turbo-operations

Turbo パイプラインの運用

Turbo パイプラインを実行するためのライフサイクルコマンド、監視、エラーリファレンスです。これは参照用です。動作しなくなったパイプラインを対話形式でトラブルシューティングするには、/turbo-doctor を使用してください。新しいパイプラインを構築するには、/turbo-builder を使用してください。

パイプラインの状態

状態	説明
running	パイプラインがデータを処理中です
starting	パイプラインを初期化中です
paused	パイプラインは一時停止中です（レプリカ数は 0）
stopped	パイプラインは実行されていません（手動停止）
error	パイプラインでエラーが発生しました
completed	ジョブモードのパイプラインが範囲の処理を完了しました

ストリーミングモードとジョブモードのライフサイクル

操作	ストリーミングパイプライン	ジョブモードのパイプライン（job: true）
一覧表示	running／paused と表示されます	running／completed と表示されます
一時停止	対応しています	対応していません
再開	対応しています	対応していません
再起動	対応しています	対応していません。削除してから適用してください
削除	対応しています	対応しています（完了から約 1 時間後に自動クリーンアップ）
適用	インプレースで更新します	先に削除してから再適用する必要があります

ジョブモードのパイプラインのライフサイクル

ジョブモードのパイプライン（job: true）は、1 回限りのバッチ処理です。

1. 開始 — start_at から end_block までのデータを処理します
2. 実行 — 範囲が限定されたデータを処理します
3. 完了 — 範囲の処理が完了すると自動的に停止します
4. 自動クリーンアップ — 完了から約 1 時間後に自動的に削除されます

一時停止、再開、再起動はできません。再デプロイする前に削除する必要があります。

ライフサイクルコマンド

パイプラインを一覧表示する

goldsky turbo list

パイプラインを一時停止する

削除せずに処理を一時的に停止します。後で再開できるよう、すべての状態を保持します。

goldsky turbo pause <pipeline-name>

パイプラインを再開する

一時停止中のパイプラインを再開します。再開できるのは paused 状態のパイプラインだけです。

goldsky turbo resume <pipeline-name>

パイプラインを再起動する

実行中または一時停止中のパイプラインのポッド再起動を実行します。

goldsky turbo restart <pipeline-name>
# To clear all checkpoints and reprocess from the beginning:
goldsky turbo restart <pipeline-name> --clear-state

パイプラインを削除する

パイプラインを完全に削除します。すべてのチェックポイントが失われます。シンクにすでに書き込まれたデータは保持されます。

goldsky turbo delete <pipeline-name>

削除して再作成する（新規開始）

goldsky turbo delete my-pipeline
goldsky turbo apply my-pipeline.yaml

チェックポイントの動作

• パイプラインを削除すると、そのチェックポイントは完全に削除されます
• 同じ名前で再作成すると、チェックポイントを復元せずに新規開始します
• チェックポイントを保持するには、削除して再作成する代わりに apply を使って更新してください
• チェックポイントの状態はソース名にひも付いています。ソース名を変更すると、そのチェックポイントはリセットされます
• チェックポイントの状態はパイプライン名にひも付いています。パイプライン名を変更すると、すべてのチェックポイントがリセットされます

監視コマンド

操作	コマンド
パイプラインを一覧表示する	goldsky turbo list
ライブデータを表示する	goldsky turbo inspect <name> -p
特定のノードを調べる	goldsky turbo inspect <name> -n <node> -p
ログを表示する	goldsky turbo logs <name>
ログを追跡する	goldsky turbo logs <name> --follow
タイムスタンプ付きでログを表示する	goldsky turbo logs <name> --timestamps
末尾の N 行を表示する	goldsky turbo logs <name> --tail N
N 秒前以降のログを表示する	goldsky turbo logs <name> --since N

goldsky turbo inspect のフラグ

フラグ	短縮形	説明
--print	-p	レコードを stdout に出力します
--topology-node-keys	-n	フィルターするノードキー（例：transform 名）をカンマ区切りで指定します
--buffer-size	-b	バッファーに保持するレコードの最大数（デフォルト：10000）

常に -p を使用してください。提案するすべての inspect コマンドに必ず含めてください。

ログ分析スクリプト

パイプラインのログをすばやく分析するには、ヘルパースクリプトを使用してください。

./scripts/analyze-logs.sh <pipeline-name>
./scripts/analyze-logs.sh <pipeline-name> --tail 100

このスクリプトは一般的なエラーパターンをチェックし、推奨事項とともに検出結果を報告します。

一般的なエラーパターン

詳しいエラーパターンと解決方法は data/error-patterns.json にあります。

エラーパターン	考えられる原因	修正方法
connection refused	データベースに到達できない	ネットワーク／ファイアウォールの設定を確認します
authentication failed	認証情報が正しくない	正しい認証情報でシークレットを更新します
secret not found	シークレットがない	goldsky secret create でシークレットを作成します
SQL syntax error	transform の SQL が無効	YAML の SQL を修正して再デプロイします
duplicate key	主キーの衝突	transform で主キーが一意になるようにします
script transform error	TypeScript のランタイムエラー	スクリプトのロジック、null の処理、戻り値の型を確認します
dynamic_table error	バックエンドへの接続の問題	dynamic table のシークレット／テーブルが存在することを確認します
WASM execution failed	サンドボックス内でスクリプトがクラッシュ	スクリプトをデバッグし、undefined へのアクセスを確認します
handler timeout	外部 HTTP エンドポイントの応答が遅い	timeout_ms を増やすか、ハンドラーのエンドポイントを修正します

スクリプト transform の問題

問題	修正方法
undefined のプロパティへのアクセス	null チェックを追加します：input.field ?? ''
戻り値の型が誤っている	返されるオブジェクトが schema と完全に一致することを確認します
戻り値のフィールドが不足している	返されるオブジェクトにすべての schema フィールドが含まれている必要があります
invoke is not a function	スクリプトで function invoke(data) を定義していることを確認します
BigInt エラー	数値リテラルを直接使わず、BigInt() コンストラクターを使用します

Dynamic Table の問題

問題	修正方法
テーブルが見つからない	デプロイ前に PostgreSQL でテーブルを作成します
チェックで一致するものがない	バッキングテーブルにデータが存在することを確認します
データが古い	postgres バックエンドの場合、行が実際に存在することを確認します
メモリの逼迫	大きな in_memory テーブルは postgres バックエンドに切り替えます

トラブルシューティングのクイックリファレンス

症状	考えられる原因	簡単な解決方法
データが流れてこない	start_at: latest	新しいデータを待つか、earliestを使用します
認証に失敗する	認証情報が間違っている	正しいパスワードでシークレットを更新します
接続が拒否される	ネットワーク／ファイアウォール	ホストを確認し、Goldsky の IP を許可リストに追加します
ストレージの上限を超えた	Neon の無料枠（512MB）	プランをアップグレードするか、データを削除します
SQL エラー	変換構文が正しくない	まず YAML を検証します
パイプラインが見つからない	名前が一致しない	goldsky turbo listを実行して名前を確認します
権限が拒否される	ロールの権限が不十分	プロジェクトのロールが Editor または Admin か確認します
pipeline already exists	ジョブモードの古い設定	先に削除してから、再適用します
ジョブを一時停止／再開できない	ジョブモードの制限	ジョブパイプラインは一時停止／再開に対応していません
ジョブを再起動できない	ジョブモードの制限	削除してから再適用してください
inspect に接続できない	パイプラインが実行されていない	goldsky turbo listでステータスを確認します
ログが空	パイプラインが起動したばかり	データを待つか、start_atを確認します
TUI の接続が切れる	パイプラインが中断された	30 分以内に自動再接続されます。ステータスを確認してください

関連項目

• /turbo-doctor — パイプラインの問題を対話形式で診断するスキル
• /turbo-builder — 新しいパイプラインを構築してデプロイします
• /turbo-pipelines — YAML 設定とアーキテクチャのリファレンス