tinybird-deploy

Tinybird Deployment スキル

Tinybird Cloud にオブザーバビリティのパイプとデータソースをデプロイします。

要件

• 事前確認： which -a tb && tb --version を実行します。tb が見つからない場合、または ~/.local/bin/tb ではなく pyenv／pip のシムに解決される場合は、PATH が正しくないか Forward CLI がインストールされていません。PATH を修正するか、インストール手順のドキュメントをユーザーに案内してください。インストーラーを curl でパイプ実行してはいけません。
• tb として Tinybird Forward CLI を使用します。このマシンでは ~/.local/bin/tb に解決され、tb --cloud deployment create --check をサポートしている必要があります。
• このワークフローのインストールや更新に pip install tinybird-cli を使用してはいけません。PATH 上で Classic CLI が先に見つかる場合があります。
• tb --cloud がない場合、または Tinybird がこれを Forward ワークスペースだと認識しているのに CLI が Classic の場合は、~/.local/bin が優先されるよう PATH を修正してください。Classic CLI は tb-classic としてのみ残されています。
• enter.pollinations.ai/observability からコマンドを実行します。
• 対象のワークスペースに対する WORKSPACE:DEPLOY 権限を持つトークンを TB_TOKEN に明示的に設定し、すべてのデプロイコマンドで --host を渡します。ワークスペースの選択に .tinyb や tb workspace use を使用しないでください。
• SELECT 1 が成功しても、トークンでデータソースを読み取れるとは限りません（PIPES:READ、DATASOURCES:READ、WORKSPACE:DEPLOY はそれぞれ異なります）。新しいパスでトークンを使用する前に、既知のデータソースに対する SELECT で確認してください。

ワークスペース

同じリージョン（gcp-europe-west2）にワークスペースが 2 つあります。パイプとデータソースは両方で同期を保つ必要があります。

ワークスペース	トラフィックの送信元	UI
pollinations_enter	本番ワーカーのみ	https://cloud.tinybird.co/gcp/europe-west2/pollinations_enter
pollinations_enter_staging	ステージングワーカー＋開発ワーカー＋ローカルの npm run dev	https://cloud.tinybird.co/gcp/europe-west2/pollinations_enter_staging

ワークスペースのルーティングはトークン単位です。同じリージョンのホストが両方のワークスペースに対応し、トークンによってワークスペースが選択されます。

ローカルの .tinyb は gitignore 対象であり、本番／ステージングの選択に使用してはいけません。TB_TOKEN は Enter のランタイム SOPS ファイルではなく、macOS キーチェーンから設定してください。SOPS ファイルには Worker 用の読み取り／取り込みトークンしかありません。ステージングにはステージングワークスペースのデプロイトークンを、本番には本番ワークスペースのデプロイトークンを使用します。トークンをログに出さないでください。

オペレーターのデプロイトークンは macOS キーチェーンに保存されています（SOPS の age キーと同じ方法です）。

# staging (pollinations_enter_staging)
TB_TOKEN="$(security find-generic-password -a "$USER" -s tinybird-staging-deploy -w)"
# prod (pollinations_enter)
TB_TOKEN="$(security find-generic-password -a "$USER" -s tinybird-prod-deploy -w)"

デプロイの前に、トークンがどのワークスペースを対象としているか必ず確認してください。tb --cloud --host "$TB_HOST" info を実行すると workspace_name が表示されます。

ディレクトリ構成

enter.pollinations.ai/observability/
├── datasources/       # Data source definitions (.datasource)
│   ├── generation_event_v2.datasource
│   ├── polar_event.datasource
│   ├── stripe_event.datasource
│   └── ...
└── endpoints/         # Pipe definitions (.pipe)
    ├── weekly_usage_stats.pipe
    ├── weekly_active_users.pipe
    ├── daily_stripe_revenue.pipe
    └── ...

---

コマンド

シェルセッションごとにリージョンを一度設定し、キーチェーンから ステージングのデプロイトークンを取得します。

TB_HOST="https://api.europe-west2.gcp.tinybird.co"
TB_TOKEN="$(security find-generic-password -a "$USER" -s tinybird-staging-deploy -w)"
export TB_HOST TB_TOKEN

ステップ 1：検証（ドライラン）

デプロイの前に必ず検証してください。ステージングに対して安全に実行できます。

tb --cloud --host "$TB_HOST" deployment create --check --no-allow-destructive-operations

出力例：

| status   | name                  | type     | path                                 |
|----------|-----------------------|----------|--------------------------------------|
| modified | weekly_usage_stats    | endpoint | endpoints/weekly_usage_stats.pipe    |

ステップ 2：デプロイ

検証に合格したら、まずステージングにデプロイします。deployment create --wait はステージングデプロイを作成し、準備が整うまで待機します。--auto を渡さない限り、昇格は行われません。

tb --cloud --host "$TB_HOST" deployment create --wait --no-allow-destructive-operations

ユーザーが昇格を明示的に求めない限り、--auto を渡したり deployment promote を実行したりしないでください。

本番へのデプロイも、TB_TOKEN を tinybird-prod-deploy キーチェーントークンに明示的に置き換えたうえで、同じ形式のコマンドを使用します。ただし、ステージングでの検証と確認が済んでからにしてください。#11127 が解決するまでは、両方のワークスペースへのデプロイは引き続き手動です。

ステージングと本番は別々の承認が必要です。ユーザーが先にステージングを確認したい場合があるため、1 つのコマンドにまとめて実行しないでください。ただし、指示に「ステージングと本番にデプロイ」のように両方がすでに明記されている場合は、両方の承認を得ていることになります。間で再確認を求めないでください。

ステップ 3：確認

ステージングデプロイを確認し、同じワークスペースの読み取りトークンを使ってデプロイ済みのエンドポイントをテストします。

set -o pipefail
tb --staging --cloud --host "$TB_HOST" endpoint ls
tb --cloud --host "$TB_HOST" deployment ls

TINYBIRD_TOKEN="$(SOPS_AGE_KEY=$(security find-generic-password -a "$USER" -s sops-age-key -w 2>/dev/null || true) \
  sops -d ../secrets/staging.vars.json | jq -r '.TINYBIRD_READ_TOKEN')"
curl -fsS "https://api.europe-west2.gcp.tinybird.co/v0/pipes/weekly_usage_stats.json?weeks_back=12" \
  -H "Authorization: Bearer $TINYBIRD_TOKEN" | jq -e '
    if has("error") then error(.error)
    elif (.data | type) != "array" then error("Missing data array")
    else .data | length end'

本番の確認では、staging.vars.json を prod.vars.json に置き換え、--staging は使用しないでください。

---

安全機能

フラグ	説明
--check	変更を加えずに検証します（ドライラン）
--wait	デプロイが完了するまで待機します
--no-allow-destructive-operations	データソースの削除を防止します（デフォルト）
--allow-destructive-operations	データソースを削除するには必須です
--auto	準備が整ったデプロイを自動で昇格します。明示的に依頼されない限り使用しないでください

---

よくあるタスク

新しい Pipe を追加する

1. endpoints/ に .pipe ファイルを作成します
2. ステージングに対して検証します
3. ステージングにデプロイして確認し、依頼された場合に限り本番環境にデプロイします

既存の Pipe を変更する

上記と同様に、編集し、ステージングで検証してデプロイし、確認したうえで、依頼された場合に限り本番環境にデプロイします。

UI で Pipe を表示する

• 本番環境：https://cloud.tinybird.co/gcp/europe-west2/pollinations_enter/pipes
• ステージング：https://cloud.tinybird.co/gcp/europe-west2/pollinations_enter_staging/pipes

---

トラブルシューティング

「tb: command not found」

~/.local/bin が PATH に含まれていることを確認してから、新しいシェルを開いてください。このワークフローでは、Classic CLI を pip install tinybird-cli でインストールしないでください。

「This is a Tinybird Forward workspace」／Classic CLI のエラー

which -a tb
tb --version
tb --help | rg "deployment"

tb は Forward CLI である必要があります。最初に見つかった tb のパスが /Library/Frameworks/Python.framework/... の下にある場合、PATH が誤っています。~/.local/bin/tb を使用するか、PATH を修正してください。

検証でデータソースまたは Pipe の削除が報告される

削除について調査してください。誤って欠落した定義は、ステージングから temp/ にプルして復元してください。タスク内で意図的にステージングの移行／リセットを行う場合は、ワークスペースを確認し、ルートの AGENTS.md にあるステージング破棄可能ルールに従って --allow-destructive-operations を指定して再実行してください。本番環境での削除には明示的な許可が必要です。

Pipe のタイムアウトに関する問題

weeks_back の値が大きいと Pipe がタイムアウトする場合は、以下を行ってください。

• ユーザー数の集計には uniqExact() の代わりに uniq() を使用します（約 10 倍高速です）
• CTE と JOIN のパターンを避け、単一パスのクエリを使用します
• コストの高い集計にはマテリアライズドビューを検討します

マテリアライズドビューの検証に関する問題

• Forward のマテリアライズドビューでは UNION を使用できません。同じデータソースに書き込む個別のマテリアライズド Pipe にソースを分割してください。
• deployment create --check で検証してください。古いローカルチェックだけでは不十分です。
• 一部のエンドポイント Pipe では、クエリ実行時の重複排除によって検証に失敗することがあります。可能な場合は、マテリアライズ時に重複を排除してください。

---

重要な注意事項

• 必ず --cloud を使用してください。指定しない場合、CLI は Tinybird Local を使用しようとします。
• tb push は使用しないでください。このワークフローでは非推奨です。
• tb deploy は避けてください。昇格が誤って実行されないよう、明示的な deployment create コマンドを使用してください。
• 破壊的操作：ルートの AGENTS.md にあるステージングおよび本番環境のルールに従ってください。上記のコマンドは、デフォルトで破壊的でない検証とデプロイを行います。
• observability ディレクトリから実行してください。リポジトリのルートからは実行しないでください。