mcpField
T
tidb-sql

tidb-sql

github.com/pingcapデータ・データベース2767 回インストール10 週間前に更新
リポジトリ

tidb-sql について

tidb-sqlは、TiDBの互換性制約を踏まえたSQL作成とトラブルシューティングのためのスキルです。エンジンとバージョンの確認、MySQLとの互換性検証、TiDB固有の診断方法を案内します。

主な機能

  1. 01TiDBのエンジンとバージョン確認
  2. 02TiDB向けの安全なSQL作成
  3. 03MySQL SQLの互換性確認
  4. 04EXPLAINによるクエリ診断
  5. 05TiDB機能リファレンスの参照

活用シーン

  1. 01TiDBデータベース向けSQLの作成
  2. 02既存のMySQLクエリのTiDB対応
  3. 03遅いSQLや失敗するSQLの調査

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/pingcap/agent-rules --skill tidb-sql

インストール後、Claude Code で/tidb-sqlを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
auto-random.md
explain.md
flashback.md
full-text-search.md
mysql-compatibility-notes.md
tidb-cloud-ssl.md
transactions.md
vector.md
scripts/
render_dot_png.sh

詳細

TiDB SQL（MySQL 互換性重視）

目標: デフォルトで TiDB 上で正しく動作する SQL を生成し、「MySQL では動作するが TiDB では壊れる」構文を避けること。

ワークフロー（毎回使用します）

  1. 対象エンジンとバージョンを特定します:
    • SELECT VERSION(); を実行します。
    • 結果に TiDB が含まれる場合、TiDB として扱い、バージョンを解析します（Vector / Foreign Key などの機能ゲートに必要です）。
    • TiDB Cloud に接続する場合、クライアントが証明書 + 本人確認を伴う SSL を有効にしていることを確認します（skills/tidb-sql/references/tidb-cloud-ssl.md を参照）。
  2. リクエストが依存する場合は、機能について 2 つの簡単な質問をします:
    • 「TiFlash はありますか？」（ベクトルインデックスに必要です）
    • 「これは Full-Text Search がサポートされているリージョンの TiDB Cloud Starter/Essential ですか？」（可用性は限定的です）
  3. TiDB で安全なデフォルトを使用して SQL を生成します:
    • サポートされていない MySQL 機能（プロシージャ/トリガー/イベント/UDF/GEOMETRY/SPATIAL など）を避けます。
    • ビューは読み取り専用として扱います。
    • 主キーの変更はマイグレーション/再構築作業として扱います。
  4. ユーザーが MySQL の SQL を提供した場合、互換性チェックを行います:
    • サポートされていない機能を TiDB の代替手段に置き換えます。
    • 動作の違いとバージョンの前提条件を明示的に指摘します。
  5. SQL が遅い、または予期せず失敗する場合、TiDB ネイティブの診断を使用します:
    • 構造化プランとオペレータツリーには EXPLAIN FORMAT = "tidb_json" を使用します。
    • estRows と actRows を比較するには EXPLAIN ANALYZE を使用します（クエリを実行します）。
    • プランがおかしい場合は、ANALYZE TABLE ... で統計を更新することを検討します。

重要な違い（覚えておいてください）

  • Vector: TiDB は VECTOR / VECTOR(D) 型とベクトル関数/インデックスをサポートしていますが、MySQL はサポートしていません。
  • GEOMETRY/SPATIAL なし: GEOMETRY、空間関数、SPATIAL インデックスを避けます。
  • プロシージャ / 関数 / トリガー / イベントなし: ロジックをアプリケーション層または外部スケジューラに移します。
  • Full-Text Search（TiDB の機能）: 利用可能な場合は TiDB の Full-Text Search SQL を使用します。MySQL の FULLTEXT がどこでも動作すると想定しないでください。
  • ビューは読み取り専用: ビューに対する UPDATE/INSERT/DELETE は行いません。
  • 外部キー: TiDB v6.6.0 以降でサポートされています。それ以外の場合は、FK の強制に依存しないでください。
  • 主キーの変更は制限されています: PK の変更には「新規テーブルの作成 + バックフィル + スワップ」を想定してください。
  • AUTO_RANDOM: 書き込みホットスポットを避けるため、適切な場合は AUTO_INCREMENT よりも AUTO_RANDOM を優先します。
  • トランザクション: TiDB は悲観的モードと楽観的モードをサポートしています。楽観的モードの COMMIT 失敗はアプリケーションロジックで処理してください。

以下のリファレンスを使用します（このスキル内）

  • skills/tidb-sql/references/vector.md - VECTOR 型、関数、ベクトルインデックスの DDL、クエリパターン。
  • skills/tidb-sql/references/full-text-search.md - Full-Text Search SQL のパターンと可用性に関する注意点。
  • skills/tidb-sql/references/auto-random.md - AUTO_RANDOM のルール、DDL パターン、制限事項。
  • skills/tidb-sql/references/transactions.md - 悲観的モードと楽観的モード、およびセッション/グローバルノブ。
  • skills/tidb-sql/references/mysql-compatibility-notes.md - SQL を壊すことが多いその他の「MySQL vs TiDB」の違い。
  • skills/tidb-sql/references/explain.md - EXPLAIN / EXPLAIN ANALYZE の使用方法、tidb_json および dot 形式。
  • skills/tidb-sql/references/flashback.md - FLASHBACK TABLE/DATABASE および FLASHBACK CLUSTER のリカバリプレイブック。
  • skills/tidb-sql/references/tidb-cloud-ssl.md - TiDB Cloud の SSL 検証要件とクライアントフラグ。

コメント

Markdown 対応