tablestudioapp/plugins

TableStudio を介したデータベース操作

TableStudio はユーザーの Mac 上のデータベースアプリです。その MCP ツールは、認証情報なしで保存済みの接続にアクセスでき、生の psql セッションにはない安全機構（実際の行に対する正確な書き込みのドライラン、使い捨てのサンドボックスコピー、ユーザーが変更を承認するレビューインボックス）を備えています。psql、mysql、sqlite3、または独自接続を開くスクリプトの代わりに、これらのツールを使用してください。

以下のツール名は TableStudio のものです。お使いのクライアントはこれらにプレフィックスを付けて表示する場合があります（Claude Code では mcp__plugin_tablestudio_tablestudio__list_connections）。ツールが遅延読み込みされる場合は、最初の呼び出しの前にその名前でツールを読み込んでください。

1. 何をする前に、正しいデータベースを見つける

セッションの データベースコンテキスト ノート（TableStudio プラグインから提供されます）は、通常、リポジトリの各データベース設定の背後にある TableStudio 接続を、その ID と環境とともに示しています。その ID を connection_id として使用します。ノートには、TableStudio のツールが利用できない場合と、その対処方法も記載されています。

ノートがない場合、またはノートに名前がないデータベースの場合は、次の手順を実行します。

1. list_connections を呼び出します。各接続には、ユーザーが TableStudio に伝えた情報が含まれている場合があります。
   • project: 接続が属するプロジェクト。作業中のリポジトリとプロジェクトが一致する接続を優先します。
   • environment: development、staging、production のいずれか。存在しない場合は未タグ付け（development ではありません）。
   • read_only: TableStudio がこの接続への書き込みを拒否します。Staging は引き続き機能します。
   • location: local（この Mac）、remote、sandbox（使い捨てコピー。実験しても安全）のいずれか。
   • agent_writes: direct は execute_query がそこに書き込めることを意味します（書き込みがオンの場合）。review は、すべての変更が stage_migration を通じてユーザーが適用するためのものになることを意味します。これは TableStudio が決定します。ユーザーが development または staging とタグ付けしていない production およびリモートデータベースは review です。
   • notes: データベースの規則（ソフトデリート、金額のセント単位、命名規則など）に関するユーザーのメモ。これに従ってください。
2. 最初にプロジェクトを照合し、次に host、port、database をプロジェクト独自の設定（.env、config）と照合して確認します。
3. 2つの接続がユーザーの意図するものと一致する可能性がある場合、またはデータベースが本番環境かどうか判断できない場合は、ユーザーに問い合わせてください。推測しないでください。

次に、以下の手順を実行します。

• 読み取り以上のことを計画する前に、describe_capabilities を 1 回呼び出します。これにより、直接書き込み、ステージング、サンドボックスが現在許可されているかどうかと、各設定の名前がわかります。拒否されてから制限を知るのではなく、これに基づいて計画を立ててください。
• agent_writes: review（本番環境、またはリモートかつ未タグ付け）の場合、直接書き込むことは絶対に避けてください。変更はレビュー用にステージングします。TableStudio はそのような接続への直接書き込みを拒否するため、最初からステージングを計画してください。
• SQL を書く前に engine（postgres、mysql、sqlite、d1、clickhouse）を確認し、その方言で記述してください。
• TableStudio に保存されていないデータベースには、そのツールを介してアクセスできません。ユーザーに TableStudio でデータベースを追加するよう依頼してください。チャットでパスワードを要求しないでください。
• データベースに到達できないために呼び出しが失敗した場合は、connection_status を呼び出してください。ローカルサーバーが停止していると表示された場合は、提供された instance_id を使用して start_local_database を呼び出してください。

2. 読み取りと調査

• 名前を推測する代わりに検索してください。search_schema は名前の一部からテーブルとカラムを見つけ、get_table_ddl は完全な構造、インデックス、外部キー、referenced_by を提供します。
• execute_query で読み取りを実行します。必要なカラムを選択し、フィルタリング、集計、LIMIT を行ってください。結果には上限があります（max_rows、デフォルト 200）。そのため、truncated の結果は全体を表していません。
• 読み取りは、本番環境でも読み取り専用トランザクション内で 30 秒の制限付きで実行されます。関数を介してもデータを変更できません。ただし、負荷を軽減するために、大きな本番テーブルではインデックス付きカラムでフィルタリングするか、count(*) の代わりに database_overview の行数見積もりを使用してください。
• データバグ: まずデータ内で再現します。問題のある行を見つけ、その数を数え、いつ発生したかを特定します（min(created_at)）。次に、それらを書き込むコードを読みます。そのバグを証明するクエリをユーザーに示します。コードを修正し、行の修復が必要な場合は、それがデータ変更です（セクション 3）。
• 秘密情報、パスワード、接続文字列を SQL、コード、ドキュメント、チャットに決して貼り付けないでください。接続文字列が属する唯一の場所は、プロジェクトの gitignore された env ファイル（ローカルデータベース用）です（ローカルデータベースのスキルで get_connection_url をカバーしています）。

3. データの変更（INSERT、UPDATE、DELETE）

PostgreSQL の場合:

1. ステートメントを作成し、preflight_statement を呼び出します。verdict（looks_fine、review、would_fail）、dry_run.rows（変更される行の正確な数、読み取り専用）、他のテーブルへのカスケード、失敗の原因となる条件が取得できます。
2. プレーンな言葉で何を行うかをユーザーに伝えます。「これにより invoices の 142 行が更新されます。カスケードは発生しません。」 verdict が would_fail の場合は、最初にステートメントを修正します。review の場合は、その理由を説明します。
3. 次に、以下のいずれかを実行します。
   • agent_writes: direct かつ直接書き込みが許可されている場合: dry_run.rows に設定した expected_rows を指定して execute_query を呼び出します。正確にその数の行が変更された場合のみコミットし、それ以外の場合はロールバックします。リモートの PostgreSQL データベースでは、TableStudio は expected_rows なしでのデータ変更を拒否します。
   • agent_writes: review、書き込みが許可されていない場合、またはユーザーが最初に確認すべきものの場合: 明確な title、SQL、およびドライランカウントを含む rationale（例：「... で見つかった 142 件の重複請求書を無効にします」）を指定して stage_migration を呼び出します。これは TableStudio の Agent Center のユーザーのレビューキューに送られ、実行はされません。

その他のエンジン ではドライランはありません。まず同じ WHERE 句で SELECT count(*) を実行し、件数を報告してから、同じ実行またはステージングのルールに従います。

重要なデータベース（大量の DELETE、DROP、TRUNCATE）に対して破壊的な操作を行う前に、サンドボックスが有効な場合は create_restore_point を呼び出し、その旨をユーザーに伝えます。

4. スキーマの変更

リポジトリがマイグレーションツールを使用している場合（Prisma、Drizzle、Rails、Django、Alembic、Laravel、Supabase、Knex、Ecto、TypeORM、Wrangler D1、またはプレーンな番号付き SQL ファイル。プラグインが検出した場合、セッションコンテキストにその名前が表示されます）、変更はそのツールに属します。

1. そのツールの方法で変更を行います。スキーマを編集してマイグレーションを生成するか、マイグレーションファイルを記述します。
2. ツールの開発コマンドを使用して、ローカル開発 データベースに適用します。
3. 実データに対して確認します（下記参照）。
4. 他の場所への適用は、ユーザーの通常のデプロイプロセスに委ねます。自分で本番環境に対してツールのデプロイコマンドを実行しないでください。

マイグレーションツールがスキーマを所有している場合に ALTER TABLE を直接実行すると、ツールの履歴とデータベースの同期が取れなくなり、次のデプロイで問題が発生します。

マイグレーションツールがない場合、またはユーザーが既存のデータベースに一度限りの変更を依頼した場合:

1. まず get_table_ddl でテーブルを読み取ります。何かを削除または名前変更する前に、referenced_by を確認します。
2. コピーで試します。create_sandbox（data: none（スキーマのみ）、sample（実際の行の一部））を作成し、サンドボックスの接続で execute_query を使用して DDL を実行し、意図したとおりに動作するか確認します。
3. compare_schemas で差分を表示します（source_connection_id をサンドボックス、target_connection_id を実際のデータベースに設定）。
4. 実際の接続で stage_migration を使用して提案します。ユーザーが TableStudio から適用します。

実データに対するマイグレーションの確認

ローカルデータベースで成功するマイグレーションでも、実際の行が存在する環境では失敗したり、アプリケーションをロックしたりする可能性があります。マイグレーションが完了したと判断する前に、デプロイ先のデータベース（通常はステージングまたは本番環境。セッションノートまたは list_connections から判別）に対して読み取り専用で確認します。

1. 変更する各テーブルの get_table_ddl を取得します。行数、インデックス、参照情報を確認します。

2. 追加する各制約について、それを破る行を見つける SELECT を execute_query で実行します。

   • NOT NULL: SELECT count(*) FROM t WHERE col IS NULL
   • UNIQUE: SELECT col, count(*) FROM t GROUP BY col HAVING count(*) > 1 LIMIT 20
   • 外部キー: 親が存在しない子行（LEFT JOIN … WHERE parent.id IS NULL）
   • CHECK、またはより狭い型や長さ: 新しい範囲外の行

   いずれかの行が存在する場合、デプロイは失敗します。マイグレーションにバックフィルまたはクリーンアップのステップを追加し、その旨を伝えます。

3. PostgreSQL では、大きなテーブルをロックまたは書き換えるステップ（下記参照）にフラグを立て、安全なパターンに切り替えます。

4. 変更が複雑な場合は、その接続から data: "sample" で create_sandbox を作成し、サンドボックスでマイグレーションの SQL を execute_query で実行し、次に compare_schemas を実行して、実際にコピーでテストします。

確認した内容と結果をユーザーに伝えます（「orders.status には 120 万行中 NULL が 0 件であるため、SET NOT NULL は安全です」）。これらはすべて読み取り専用です。マイグレーションをローカル開発データベース以外に適用しないでください。

PostgreSQL のロック

• 大規模でビジーなテーブルにインデックスを作成する場合: CREATE INDEX CONCURRENTLY を使用します。これはトランザクション内で実行できないため、そのステートメントを BEGIN … COMMIT でラップしないでください。
• 揮発性のデフォルト値を持つ NOT NULL カラムの追加、カラム型の変更、外部キーの追加は、テーブルの書き換えやロックを引き起こす可能性があります。そのことを rationale に記載し、安全なステップに分割することを検討してください（カラムを NULL 許容で追加し、バッチでバックフィルし、その後 SET NOT NULL を実行する。外部キーを NOT VALID で追加し、その後 VALIDATE CONSTRAINT を実行する）。
• schema_issues は、各問題に対して lock_impact を含む修正 SQL を返します。修正を提案する前にこれを読んでください。

5. 何かをステージングした後

• その変更が TableStudio でユーザーのレビューを待っており、実行されていない ことを伝え、結果から review_url をリンクとして提供します。このリンクを開くと、変更の影響（影響を受ける行、ロック、失敗する可能性のあるもの）、変更後のスキーマの図、元に戻す計画が表示されたレビューが表示されます。ステージングされた変更が適用されたとは決して言わないでください。
• ユーザーが変更を依頼した場合、list_staged_migrations は status: changes_requested とそのメモを review_feedback に表示します。同じ migration_id で update_staged_migration を使用して修正し、2 番目のコピーをステージングするのではなく、再度確認できる状態になったことをユーザーに伝えます。取り下げるには、remove_staged_migration を使用します。
• list_staged_migrations は、ユーザーが変更を適用、無視、または失敗したかも示します。

ユーザーが保留中の変更について尋ねた場合（「何をステージングした？」「マイグレーションは実行された？」）、このリポジトリの接続に対して list_staged_migrations を呼び出します。保留中 のものを最初に、新しい順に報告します。タイトル、接続、ステージング日時、review_url、およびその内容とリスクレベル（大きなテーブルをロックまたは書き換えるか、データを削除するか、WHERE 句がないか）を 1 行で説明します。次に、changes requested があるもの（ユーザーのメモ付き）、failed したもの（エラー付き）を報告します。ユーザーが TableStudio の Agent Center で適用、差し戻し、または無視できること、自分では適用できないことを明確に伝えます。

6. TableStudio が拒否した場合

• 設定を指定した拒否（例：書き込みがオフ）は、ユーザーの選択です。どの設定で許可されるかを伝え、代わりに変更をステージングすることを提案し、そこで停止します。回避策を探してはいけません。
• TableStudio のツールがまったく利用できない場合、セッションノートにその理由が記載されています：アプリが閉じている、MCP サーバーがオフ（設定→MCP）、またはクライアントがまだ接続されていない。ノートが示す修正方法を伝えてください。Claude Code では、TableStudio が開いている状態で /mcp を使用してユーザーが再接続できます。
• blocked: production_review_required または review_required という拒否は、その接続がレビュー経由でのみ変更を受け付けることを意味します。ステージングしてください。dry_run_required は、最初に preflight_statement を実行し、expected_rows を渡すことを意味します。side_effect_function は、ステートメントがトランザクション外で動作するものを呼び出すことを意味します。代わりにユーザーに SQL を表示してください。
• プラグインのシェルガードは、本番環境に書き込むシェルコマンドをブロックします。ブロックは、回避するものではなく、上記の手順を使用するためのシグナルとして扱ってください。
• TableStudio を介して行ったすべての操作は、Agent Center でユーザーに表示され、この会話ごとにグループ化されます。