alibabacloud-polardbx-sql

PolarDB-X SQL（MySQL 互換性に重点）

PolarDB-X 2.0 Enterprise Edition（Distributed Edition）の AUTO モードデータベース向けに SQL を作成、レビュー、適応し、「MySQL では動作するのに PolarDB-X では失敗する」という問題を回避します。

アーキテクチャ：PolarDB-X 2.0 Enterprise Edition（CN コンピュートノード + DN ストレージノード + GMS メタデータサービス + CDC ログノード）+ AUTO モードデータベース

対象範囲：

• PolarDB-X 2.0 Enterprise Edition（Distributed Edition とも呼ばれます）+ AUTO モードデータベース

対象外：

• PolarDB-X 1.0（DRDS 1.0）
• PolarDB-X 2.0 Standard Edition
• PolarDB-X 2.0 Enterprise Edition の DRDS モードデータベース

AUTO モードと DRDS モードの主な違いは、AUTO モードではパーティションの定義に MySQL 互換の PARTITION BY 構文を使用する一方、DRDS モードでは従来の dbpartition/tbpartition 構文を使用することです。次のコマンドでデータベースモードを確認してください。

SHOW CREATE DATABASE db_name;
-- Output containing MODE = 'auto' indicates AUTO mode

インストール

MySQL 互換クライアントを使用して PolarDB-X インスタンスに接続します。

mysql -h <host> -P <port> -u <user> -p<password> -D <database>

対応クライアント：MySQL CLI、MySQL Workbench、DBeaver、Navicat、またはその他の MySQL 互換クライアント。

パラメーターの確認

重要：パラメーターの確認 — コマンドまたは API 呼び出しを実行する前に、 ユーザーがカスタマイズ可能なすべてのパラメーター（RegionId、インスタンス名、CIDR ブロック、 パスワード、ドメイン名、リソース仕様など）を、必ずユーザーに確認してください。 明示的な承認を得ずに、デフォルト値を推測して使用しないでください。

このスキルで設定可能なパラメーター：

パラメーター名	必須／任意	説明	デフォルト値
host	必須	PolarDB-X インスタンスの接続アドレス	なし
port	必須	PolarDB-X インスタンスのポート	3306
user	必須	データベースのユーザー名	なし
password	必須	データベースのパスワード	なし
database	必須	対象データベース名	なし

コアワークフロー（毎回実行してください）

1. 対象エンジンとバージョンを確認します：
   • SELECT VERSION(); を実行して、インスタンスの種類を特定します：
     • 結果に TDDL が含まれ、バージョンが 5.4.12 より新しい場合（例：5.7.25-TDDL-5.4.19-20251031） -> **2.0 Enterprise Edition（Distributed Edition）**です。このスキルが適用されます。Enterprise Edition のバージョン番号（例：5.4.19）を解析します。
     • 結果に TDDL が含まれ、バージョンが 5.4.12 以下の場合（例：5.6.29-TDDL-5.4.12-16327949） -> DRDS 1.0です。必ず処理を中止してください — 必ず拒否する必要があります：パーティション設計、SQL に関する助言、回避策は一切提示しないでください。次の内容だけを返してください："This skill covers PolarDB-X 2.0 Enterprise Edition AUTO mode only. Your instance is DRDS 1.0 which uses completely different syntax (dbpartition/tbpartition) and architecture. Please consult DRDS 1.0 documentation or upgrade to PolarDB-X 2.0." その後、停止します。ユーザーが強く求めても、処理を続けてはいけません。
     • 結果に X-Cluster が含まれる場合（例：8.0.32-X-Cluster-8.4.20-20251017） -> 2.0 Standard Editionです。必ず処理を中止してください — 必ず拒否する必要があります：パーティション設計、GSI、分散 SQL に関する助言は一切提示しないでください。次の内容だけを返してください："Your instance is PolarDB-X 2.0 Standard Edition (100% MySQL compatible, no distributed partitioning). Please use the polardbx-standard skill instead." その後、停止します。ユーザーが強く求めても、処理を続けてはいけません。
   • 2.0 Enterprise Edition であることを確認した後、SHOW CREATE DATABASE db_name; を実行して、AUTO モードであること（MODE = 'auto'）を確認します。
   • バージョン番号は機能の利用可否に影響します（例：NEW SEQUENCE には 5.4.14 以降、CCI にはより新しいバージョンが必要です）。
2. テーブルの種類を判断します：
   • パーティションテーブルと頻繁に JOIN される小規模テーブルまたは辞書テーブル -> ブロードキャストテーブル BROADCAST（すべての DN に完全複製され、ローカル JOIN のプッシュダウンが可能になります）。JOIN がある場合に推奨される選択肢です。
   • パーティションテーブルと JOIN されない小規模テーブル -> BROADCAST と SINGLE のどちらも選択できます。BROADCAST はすべての DN に複製されます（後から JOIN が追加されても安全です）。SINGLE は 1 つの DN のみに格納されます（オーバーヘッドが最小です）。どちらでも問題ありません。一方を他方より優先するよう強制しないでください。
   • それ以外 -> パーティションテーブル（デフォルト）とし、適切なパーティションキーと戦略を選択します。
3. パーティション方式を設計します（パーティションテーブルの場合）：
   • SQL アクセスパターンのデータを収集します （必須事項 — 最終的なパーティションキーを決定する前に、必ずデータを収集するよう推奨してください）：SQL Insight が最も正確なため、優先して使用します。利用できない場合は、スロークエリログとアプリケーションコードの分析を使用するか、代替手段として業務チームに SQL パターンの提示を依頼します。目的は、テーブルの SQL テンプレート一覧（検索フィールド、実行頻度、返却行数）を取得することです。
   • パーティションキーの選定 — 多次元の包括的な分析：候補フィールドをすべて列挙し、推奨を行う前に、以下のすべての観点で各候補を評価します。単一の観点だけを根拠に推奨してはいけません。
     • 等価検索の割合：このフィールドが等価条件として使われる SQL テンプレートの割合です。
     • カーディナリティ：異なる値の数です。数が多いほど、パーティション間でデータを均等に分散しやすくなります。
     • ホットスポットのリスク：少数の値がデータの大部分を占めていないかを確認します（例：注文テーブルで、一部の buyer_id は数百万行を占める一方、ほかの buyer_id の行数は少ない場合があります）。
     • 主キー／一意キーの状態：PK／UK は本質的に最も高いカーディナリティを持ち、ホットスポットのリスクがありません。
     • セマンティック分析：テーブルの種類とフィールドの意味からクエリパターンを推測します。たとえば注文テーブルの order_id は、ユーザーが buyer_id による検索しか挙げていなくても、注文詳細の検索、ステータス確認、決済コールバックなどで頻繁に検索されることが確実です。 最適なパーティションキーは、すべての観点を総合して高い評価を得た候補です。パーティションキー以外のフィールドに対する高頻度クエリは、GSI を作成することで最適化できます。典型例：注文テーブルでは、パーティションキーに order_id（PK、最も高いカーディナリティ、ホットスポットなし、意味的にも検索頻度が高い）を使用し、buyer_id（buyer による検索の割合は高いものの、一部の buyer がはるかに多くの注文を生成する偏りのリスクがある）に GSI を作成します。
   • GSI の選定：書き込み量に応じて戦略を決定します。書き込み量が少ないテーブルでは、GSI を自由に作成できます。パーティションキー以外の高頻度検索フィールドには GSI を作成します。カーディナリティが低いフィールドや時刻フィールドは GSI に適していません。常にほかのフィールドと組み合わせて使われ、単独では使われないフィールドには、単独の GSI は不要です。GSI の種類：返却行数が少ない場合は通常の GSI、1 対多の場合は Clustered GSI、一意制約には UGSI を使用します。GSI の構文には PARTITION BY KEY(...) PARTITIONS N を必ず含めてください — 完全な構文については gsi.md を参照してください。
   • パーティションアルゴリズム：ワークロードの約 90％では、単一レベルの HASH／KEY を使用します。注文タイプの多次元クエリには CO_HASH、時間ベースのデータクリーンアップには HASH+RANGE、マルチテナントには LIST+HASH を使用します。単一カラムの場合、HASH と KEY は同等です。
   • パーティション数：ほとんどのワークロードには 256 が適しています。DN ノード数の数倍にする必要があります。1 パーティションあたりの行数は 1 億未満に保ちます。
   • 移行ワークフロー（単一テーブルをパーティションテーブルにするための 3 段階の方法）：（1）まず一意性を維持したまま、パーティション数が 1 のパーティションテーブルに変換します -> （2）必要な GSI／UGSI を作成します -> （3）目標のパーティション数に変更します。詳細については partition-design-best-practice.md を参照してください。
4. SQL を生成する際は、PolarDB-X の安全なデフォルト設定を使用します：
   • サポートされていない MySQL 機能（ストアドプロシージャ／トリガー／EVENT／SPATIAL など）は避けます。
   • MySQL の AUTO_INCREMENT 主キーによる書き込みホットスポットの代わりに、KEY または HASH パーティショニングを使用します。
   • パーティションキー以外のフィールドによる検索が必要な場合は、グローバルセカンダリインデックス（GSI）の作成を検討します。
5. ユーザーから MySQL SQL が提供された場合は、互換性を確認します：
   • サポートされていない機能を置き換え、PolarDB-X での代替手段を提示します。
   • 動作の違いとバージョン要件を明確に示します。
6. SQL が遅い場合やエラーが発生した場合は、PolarDB-X の診断ツールを使用します：
   • EXPLAIN で論理実行計画を確認します。
   • EXPLAIN EXECUTE で、DN にプッシュダウンされる物理実行計画を確認します。
   • EXPLAIN SHARDING でシャードスキャンの詳細を確認し、全シャードスキャンが発生していないか調べます。
   • EXPLAIN ANALYZE で実際に実行し、実行時の統計情報を収集します。

主な違いのクイックリファレンス

• 3 種類のテーブル：単一テーブル（SINGLE）、ブロードキャストテーブル（BROADCAST）、パーティションテーブル（デフォルト）があります。データ量とアクセスパターンに応じて選択します。
• パーティションテーブル：KEY/HASH/RANGE/LIST/RANGE COLUMNS/LIST COLUMNS/CO_HASH とサブパーティションに対応しています（49 種類の組み合わせ）。
• 主キーとユニークキー：グローバル（一意性をグローバルに保証）またはローカル（パーティション内で一意）に分類されます。単一テーブル、ブロードキャストテーブル、自動パーティションテーブルは常にグローバルです。手動パーティションテーブルでは、パーティション列が PK/UK 列の一部であればグローバル、そうでなければローカルとなります（データ重複や DDL 失敗のリスクがあります）。重要な原則：グローバルな一意性を自然に保証できるよう、既存の PK/UK 列からパーティションキーを選択してください。パーティション列を追加するために、ユーザーの既存の主キー定義を変更してはいけません。
• グローバルセカンダリインデックス GSI：パーティションキー以外の列を使ったクエリでフルシャードスキャンが発生する問題を解決し、GSI／UGSI／クラスタ化 GSI の各タイプに対応します。重要：GSI では独自の PARTITION BY 句を指定する必要があります。通常の MySQL インデックスではなく、独立してパーティション化されたテーブルです。正しい構文：

  -- ✅ Correct: GSI with PARTITION BY clause
  GLOBAL INDEX g_i_seller(seller_id) PARTITION BY KEY(seller_id) PARTITIONS 16
  CLUSTERED INDEX cg_i_buyer(buyer_id) PARTITION BY KEY(buyer_id) PARTITIONS 16
  -- ❌ Wrong: Missing PARTITION BY (this is NOT MySQL INDEX syntax)
  GLOBAL INDEX gsi_seller(seller_id)
  

  従来型のパーティション設計 — 注文テーブル：候補は order_id（PK）と buyer_id です。総合的に分析すると、order_id はカーディナリティが最も高く（行ごとに一意）、ホットスポットのリスクがゼロで、PK であり、意味上もクエリ頻度が高い（注文詳細／ステータス／支払いの参照）列です。一方、buyer_id は購入者の軸でのクエリ比率が高いものの、分布に偏りが生じる可能性があります（一部の購入者は注文数が大幅に多くなります）。結論：order_id をパーティションキーにし、buyer_id にクラスタ化 GSI を設定します。
• クラスタ化カラムナインデックス CCI：行指向と列指向を組み合わせたストレージです。CLUSTERED COLUMNAR INDEX により OLAP 分析クエリを高速化します。
• シーケンス：グローバルに一意なシーケンスです。デフォルトのタイプは NEW SEQUENCE（5.4.14+）で、AUTO_INCREMENT の分散型の代替手段です。
• 分散トランザクション：TSO グローバルクロック + MVCC + 2PC に基づき、デフォルトで強整合性を実現します。単一シャードのトランザクションは自動的にローカルトランザクションに最適化されます。
• テーブルグループ：同じパーティションルールを持つテーブルを同じテーブルグループにバインドし、JOIN 計算のプッシュダウンを可能にして、シャード間のデータシャッフルを回避します。
• TTL テーブル：時間列に基づいてコールドデータを自動的に期限切れにし、クリーンアップします。CCI と組み合わせて、ホットデータとコールドデータを分離できます。
• サポートされない MySQL 機能：ストアドプロシージャ／トリガー／EVENT／SPATIAL／GEOMETRY／LOAD XML／HANDLER など。
• STRAIGHT_JOIN／NATURAL JOIN はサポートされません：代わりに標準の JOIN 構文を使用してください。
• := 代入演算子はサポートされません：ロジックをアプリケーション層に移してください。
• HAVING／JOIN ON 句ではサブクエリを使用できません：サブクエリを JOIN または CTE に書き換えてください。

ベストプラクティス

1. 適切なテーブルタイプを選択する：パーティション分割テーブルと結合する小規模なテーブルや辞書テーブルには、ブロードキャストテーブルを使用してください。パーティション分割テーブルと結合しない小規模なテーブルでは、BROADCAST と SINGLE のどちらも使用できます。それ以外には、パーティション分割テーブルを使用してください。
2. 包括的かつ多次元的に分析してパーティションキーを選択する：まず SQL アクセスパターンのデータを収集するよう、常に推奨してください（SQL Insight が推奨されます）。候補となる各フィールドについて、すべての観点（等価検索の比率、カーディナリティ、ホットスポットのリスク、PK/UK かどうか、フィールドの意味）を分析し、すべての観点を総合して最も評価の高い候補を選んでください。単一の観点だけで判断してはいけません。テーブルやフィールドの意味からクエリパターンを推測することも忘れないでください（例：注文テーブルの order_id は、注文の詳細、ステータス確認、決済コールバックで頻繁に検索されることが確実です）。
3. PK/UK 列をパーティションキーとして優先する：パーティションキーを選ぶ際は、既存のプライマリキーまたはユニークキーの列から選ぶことを優先してください。これにより、スキーマを変更せずに PK/UK を Global（グローバルに一意）にできます。パーティション列を追加するために、ユーザーの既存のプライマリキー定義を変更してはいけません。PK 列がパーティションキーとして適さない場合（例：ビジネス上の意味を持たない自動採番 ID）、ほかのビジネス列をパーティションキーとして選択しても問題ありません。この場合、PK は Local（パーティション内でのみ一意）になります。Local PK のリスクをユーザーに説明し、自動採番／Sequence の仕組みでパーティション間の PK 重複を回避できるようにしてください。
4. GSI を適切に作成する：書き込み量に基づいて GSI 戦略を決定してください。返される行数が少ない場合は通常の GSI、1 対多の場合は Clustered GSI、一意性制約には UGSI を使用してください。比率の低い SQL に対して GSI を作成してはいけません。INSPECT INDEX を使用して、冗長な GSI を定期的に整理してください。すべての GSI には独自の PARTITION BY KEY(...) PARTITIONS N 句が必要です。PARTITION BY を付けずに GLOBAL INDEX idx(col) とだけ記述してはいけません。
5. 256 パーティションを使用する：256 パーティションは大半のワークロードに適しており、DN ノード数の数倍にする必要があります。
6. 単一テーブルをパーティション分割テーブルにする際は、3 段階の方法を使用する：一意性を保ったまま、まず 1 パーティションに変換し、次に GSI/UGSI を作成し、最後に目標のパーティション数に変更してください。これにより、一意性制約が失われる期間を回避できます。
7. 比率の低い SQL にパーティションキーへのヒットを無理強いしない：パーティション設計は現実的に行ってください。低 QPS のクロスシャードクエリは全体的なコストが限られるため、すべてのクエリフィールドに GSI を作成してはいけません。
8. JOIN を最適化するためにテーブルグループを使用する：頻繁に結合するテーブルを、同じパーティションルールで同じテーブルグループにバインドしてください。
9. サポート対象外の MySQL 構文を避ける：ストアドプロシージャ、トリガー、EVENT、SPATIAL、NATURAL JOIN、:= などは使用しないでください。
10. HAVING/JOIN ON 内のサブクエリを避ける：JOIN または CTE に書き換えてください。
11. 診断には EXPLAIN コマンドを使用する：SQL のパフォーマンス問題には、EXPLAIN SHARDING と EXPLAIN ANALYZE を優先してください。
12. Online DDL の前に長時間トランザクションを確認する：MDL ロック待ちを避けるため、DDL の実行前に長時間トランザクションがないか確認してください。
13. コールドデータの管理に TTL テーブルを使用する：時間属性を持つ大規模テーブルには、期限切れデータを自動的にクリーンアップする TTL テーブルを使用してください。
14. 効率的なページングには Keyset ページングを使用する：深いページングでの LIMIT M, N は避けてください（コストは O(M+N) で、分散システムではさらに大きくなります）。各バッチの最後の行のソート値を記録し、次のバッチの WHERE 条件として使用してください。ソート列に重複があり得る場合は、(sort_column, id) のタプル比較を使用してください。ソート列には適切な複合インデックスを設定してください。
15. Range パーティション分割テーブルでは自動パーティション追加を使用する：PolarDB-X では、自動パーティション事前作成の設定に、独自の ALTER TABLE ... MODIFY TTL SET 構文（TTL_EXPR、TTL_PART_INTERVAL、ARCHIVE_TYPE、ARCHIVE_TABLE_PRE_ALLOCATE などの複数のパラメーターを含む）を使用します。この構文は標準 SQL ではなく、推測できません。自動パーティション追加の設定を生成する前に、正確な SQL 構文を必ず references/auto-add-range-parts.md で確認してください。バージョン 5.4.20 以降が必要です。

参考リンク

参照先	説明
references/create-table.md	CREATE TABLE 構文、テーブルの種類（単一／ブロードキャスト／パーティション分割）、パーティション戦略、セカンダリパーティション、パーティション管理
references/partition-design-best-practice.md	パーティション設計のベストプラクティス：パーティションキー／GSI／アルゴリズム／件数の選定、3 段階の移行、詳細な例
references/primary-key-unique-key.md	主キーと一意キーのグローバル／ローカル分類、ルール、リスク、推奨事項
references/gsi.md	グローバルセカンダリインデックス GSI／UGSI／クラスター化 GSI の作成、クエリ、制限事項
references/cci.md	クラスター化カラムナーインデックス CCI の作成、使用方法、適用シナリオ
references/sequence.md	シーケンスの種類（NEW／GROUP／SIMPLE／TIME）、作成方法と使用方法
references/transactions.md	分散トランザクションモデル、分離レベル、考慮事項
references/mysql-compatibility-notes.md	MySQL と PolarDB-X の互換性の違いと開発上の制限事項
references/explain.md	EXPLAIN コマンドの各種形式と実行計画の診断
references/ttl-table.md	TTL テーブルの定義、コールドデータのアーカイブ、クリーンアップのスケジュール設定
references/online-ddl.md	オンライン DDL の評価、ロックフリー実行戦略、長時間トランザクションの確認、DMS のロックフリー変更
references/pagination-best-practice.md	効率的なページネーション：キセットページネーション、シャードごとの走査、インデックス要件、Java の例
references/auto-add-range-parts.md	レンジパーティションの自動追加：TTL ベースのパーティション事前作成、第 1／第 2 レベルの設定、管理コマンド
references/cli-installation-guide.md	Alibaba Cloud CLI のインストールガイド