supabase-postgres-best-practices

supabase-postgres-best-practices スキルの概要

supabase-postgres-best-practices スキルは、Supabase が提供する体系立った Postgres 最適化リファレンスです。一般的なコーディング向けプロンプトでは得にくい、SQL、スキーマ設計、インデックス、RLS、接続管理に関するより的確な判断材料が欲しい人に向いています。特に、パフォーマンスと正確性の両方が重要な Supabase 環境や通常の Postgres 環境で作業するデータベースエンジニア、バックエンド開発者、AI を活用したレビュー担当者に適したスキルです。

このスキルで実際にできること

supabase-postgres-best-practices は、単に「Postgres を説明してほしい」ときではなく、たとえば次のような実務で力を発揮します。

• 遅いクエリを書き直す
• 適切なインデックス設計を選ぶ
• N+1 や悪いページネーション設計を避ける
• パフォーマンスを落としすぎずに RLS の安全性を改善する
• ロック競合を減らす
• ボトルネックがクエリ、スキーマ、接続パターンのどれにあるかを切り分ける

このスキルの価値は、抽象的なアドバイスの羅列ではなく、実践的なルールファイルとして整理されており、悪い SQL と良い SQL の比較例まで含まれている点にあります。

向いているユーザーとプロジェクト

このスキルは、次のようなチームにフィットします。

• Supabase ベースのアプリを運用していて、Postgres に特化したガイダンスが欲しい
• マイグレーション、SQL 関数、ポリシー、スキーマ変更を AI と一緒にレビューしたい
• Database Engineering の作業で再現性のある最適化パターンを使いたい
• インデックス、接続プーリング、監視、クエリプランに関する具体例が必要

特に、すでにスキーマやクエリの文脈を持っていて、「とりあえずインデックスを追加」といった一般論ではなく、その状況に根ざした改善案をモデルに出してほしい場合に有効です。

通常のプロンプトより優れている理由

大きな違いは、カバー範囲の広さと優先順位づけにあります。リポジトリ内のガイダンスは 8 つのカテゴリに整理されており、重要度の高い領域、つまりクエリ性能、接続管理、セキュリティ/RLS が先に置かれています。加えて references/ 配下のファイルには、具体的な変換例、定量的な効果、トレードオフまで書かれているため、「Postgres を最適化して」のような一行指示よりも、モデルが適用しやすい材料が揃っています。

supabase-postgres-best-practices が特に強い領域

supabase-postgres-best-practices skill は、とくに次のテーマに強みがあります。

• 複合、covering、partial、不足インデックスを含むクエリのインデックス戦略
• データ型、主キー、制約、パーティショニング、外部キー用インデックスなどのスキーマ設計
• 接続上限、プーリング、prepared statements、idle timeout などの運用面
• advisory lock、短いトランザクション、デッドロック回避、SKIP LOCKED などの並行性パターン
• EXPLAIN ANALYZE、pg_stat_statements、vacuum/analyze を使った監視・診断
• JSONB インデックスや全文検索などの高度な Postgres 機能

このスキルが適さないケース

これは Postgres 管理全般を網羅したマニュアルでも、マイグレーションフレームワークでも、ベンチマークスイートでもありません。ハードウェアサイズの見積もり、WAL 設定、複雑なレプリケーション設計のような、環境依存の深いチューニングが必要なら、このスキルは DBA 向けの包括的な運用プレイブックというより、実務的なクエリ設計・スキーマ設計ガイドとして捉えるのが適切です。

supabase-postgres-best-practices スキルの使い方

supabase-postgres-best-practices のインストール方法

スキルランナーが GitHub からのリモートインストールに対応している場合は、次を使います。

npx skills add https://github.com/supabase/agent-skills --skill supabase-postgres-best-practices

環境がクローン済みリポジトリからスキルを読み込む方式なら、対象スキルの場所は次です。

skills/supabase-postgres-best-practices

SKILL.md 自体にはインストールコマンドが書かれていないため、ディレクトリベースで利用する場合は、上記のリポジトリ単位のインストール手順か、ローカルのスキルローダーの流儀に従ってください。

最初に読むべきファイル

最短で実用投入したいなら、次の順に読むのがおすすめです。

1. skills/supabase-postgres-best-practices/SKILL.md
2. skills/supabase-postgres-best-practices/AGENTS.md
3. skills/supabase-postgres-best-practices/references/_sections.md
4. 自分の課題に対応する references/*.md

README.md は主にコントリビューター向けです。スキルを拡張したい、内容を検証したいときには役立ちますが、最初の利用では優先度はそこまで高くありません。

リポジトリ全体ではなくカテゴリから入る

このスキルは、まず自分の課題をリポジトリ内のプレフィックスに対応づけてから使うと扱いやすくなります。

• query-: 遅い SQL やインデックスの問題
• conn-: serverless や高並行環境の接続問題
• security-: 権限や RLS
• schema-: テーブル・カラム設計
• lock-: 競合やキューワーカー
• data-: バッチ処理、ページネーション、upsert、N+1
• monitor-: 診断
• advanced-: JSONB や全文検索

この切り分けを先にやると、プロンプトがぶれにくくなり、モデルも適切な解決パターンに早く入れます。

良い結果を出しやすい入力

supabase-postgres-best-practices usage の質は、入力の具体性に大きく左右されます。モデルには次の情報を渡してください。

• 現在の SQL クエリまたはマイグレーション
• 関連するテーブル定義
• 行数や想定スケール
• 現在のインデックス
• レイテンシ、CPU、ロック、接続枯渇などの遅さの症状
• RLS や pooled connections など、Supabase の機能を使っているかどうか
• 「カーソル順は維持必須」「ポリシーはテナント分離を保つ必要がある」などの正しさの制約

これらがないと、概ね正しいものの浅い提案に留まりやすくなります。

曖昧な目標を強いプロンプトに変える

弱いプロンプト:

Optimize this Postgres query.

より良いプロンプト:

Use the supabase-postgres-best-practices skill to review this query for index use, data access pattern issues, and RLS impact. Explain likely bottlenecks, propose rewritten SQL, recommend exact indexes, and note tradeoffs. Context: table sizes, existing indexes, and EXPLAIN ANALYZE are below.

理想的なプロンプトの構成:

• 目的
• 現在の SQL / スキーマ / ポリシー
• ワークロードの特性
• 制約条件
• 欲しい出力形式

この形は、リファレンスファイルが改善パターンを教えている構成とよく噛み合います。

クエリ最適化向けのプロンプト例

たとえば次のように依頼できます。

Apply supabase-postgres-best-practices to this endpoint query. Check for missing composite or partial indexes, N+1 patterns, unnecessary scans, and pagination problems. If you suggest an index, explain why the predicate and sort order fit it. If EXPLAIN ANALYZE would change your confidence, say exactly what to verify.

単に “best practices” を求めるより、こうして判断を求めるほうが有効です。要約ではなく、何を変えるべきかを返しやすくなります。

スキーマと RLS レビュー向けのプロンプト例

スキーマやポリシーを見てもらうなら、次のようなプロンプトが使えます。

Use the supabase-postgres-best-practices skill to review this migration and RLS policy set. Focus on foreign-key indexing, data types, constraints, lowercase identifiers, privilege boundaries, and whether the RLS predicates will scale on large tables. Return changes in priority order with SQL examples.

このプロンプトは、リポジトリ内でも特に強い参照領域へモデルをうまく誘導できます。

タスク別・おすすめのリポジトリ読書ルート

次のファイルパスをショートカットとして使うと効率的です。

• 遅いクエリ: references/query-missing-indexes.md, references/query-composite-indexes.md, references/query-covering-indexes.md
• soft-delete やフィルタ条件つきワークロード: references/query-partial-indexes.md
• API の取りすぎや繰り返し呼び出し: references/data-n-plus-one.md, references/data-batch-inserts.md
• ページネーションの問題: references/data-pagination.md
• ワーカーキューや競合: references/lock-skip-locked.md, references/lock-short-transactions.md
• Supabase auth とポリシー性能: references/security-rls-basics.md, references/security-rls-performance.md
• 遅さの診断: references/monitor-explain-analyze.md, references/monitor-pg-stat-statements.md

supabase-postgres-best-practices for Database Engineering から実務的な価値を最短で引き出したいなら、この読み方がいちばん手堅いです。

実案件でのおすすめワークフロー

安定して使いやすい進め方は次の通りです。

1. 問題の種類を特定する
2. 対応するリファレンスファイルだけを読み込む
3. 修正案を優先順位つきで出させる
4. SQL の書き換え案と index DDL を要求する
5. EXPLAIN ANALYZE や実ワークロードのデータで検証する
6. あり得る改善を全部試すのではなく、上位 1〜2 個の変更に絞って反復する

このスキルは、広くアイデア出しをする補助役より、論点を絞ったレビューアとして使うほうが強みを発揮します。

出力品質が変わる実践的なコツ

ちょっとした使い方の違いで、出力の質がかなり変わります。

• 既存インデックスを渡して、重複提案を避ける
• サンプルの predicate や ORDER BY を含め、インデックス提案を実態に合わせる
• 書き込みが多いかを伝え、インデックス追加のトレードオフ判断を変えさせる
• RLS では実際のポリシー文を渡す。ないと性能面の助言が抽象的になりやすい
• 「priority order で返して」と指定し、重要修正を先に出させる

supabase-postgres-best-practices スキル FAQ

supabase-postgres-best-practices は Supabase ユーザー専用ですか？

いいえ。Supabase がメンテナンスしているスキルですが、内容の多くは標準的な Postgres エンジニアリングの知見です。特にクエリプランニング、インデックス、ロック、JSONB、全文検索の観点では、通常の Postgres を使っている場合でも十分役立ちます。

初心者にも向いていますか？

意欲のある初心者には役立ちますが、初心者最優先の作りではありません。例は具体的で分かりやすい一方、多くの提案は SQL を読めること、インデックスを理解していること、実行計画を検証できることを前提にしています。Postgres に不慣れなら、実際のスキーマ情報を添えたうえで、修正案と一緒に平易な説明も求めるのがよいです。

一般的な SQL プロンプトより何が優れていますか？

supabase-postgres-best-practices guide には、アンチパターン、修正済み SQL、効果の見立て、トピック別リファレンスが厳選されて入っています。そのため、特に partial index、RLS 性能、接続上限、ロックパターンのような論点では、汎用的なプロンプトより実行可能な答えが返りやすくなります。

supabase-postgres-best-practices を使わないほうがいいのはどんなときですか？

本番ベンチマーク、DBA レベルのインフラチューニング、ベンダー固有のマネージドサービス運用ガイドの代替として期待すべきではありません。また、スキーマ、クエリ、実行計画の情報を渡さなければ、実際のワークロードを正しく推定することもできません。

コード生成だけでなく、性能デバッグにも使えますか？

はい。監視系のリファレンスには EXPLAIN ANALYZE、pg_stat_statements、vacuum/analyze に関する内容が含まれているため、SQL の書き換えだけでなく、原因切り分けにも使えます。SQL を書く前にも、遅さが見えてからの分析にも役立ちます。

マイグレーションや pull request のレビューにも使えますか？

はい。これは特に相性のよい使い方のひとつです。migration SQL、schema diff、ポリシー変更、クエリコードを確認し、性能や安全性の懸念を洗い出したうえで、より Postgres に適した代替案を提案できます。

supabase-postgres-best-practices スキルをより良く使うには

スキルが判断に必要とする根拠を渡す

supabase-postgres-best-practices の出力を最も手早く改善する方法は、具体的な根拠を渡すことです。

• EXPLAIN ANALYZE
• テーブルスキーマ
• インデックス定義
• 行数
• クエリ頻度
• read/write 比率
• ポリシー定義

このスキルには強い参照資料がありますが、たとえば複合インデックスと partial index のどちらが適切かは、predicate が曖昧なままだと正確に選べません。

アドバイスの羅列ではなく、順位つきの修正案を求める

有効なプロンプト例:

Apply supabase-postgres-best-practices and return the top 3 changes by expected impact, with exact SQL and verification steps.

“review everything” と頼むより、こちらのほうが出力は良くなります。リポジトリ自体が、効果とカテゴリ優先度で整理されているためです。

トレードオフ込みで提案させる

モデルには次の観点も必ず含めるよう求めてください。

• 読み取り性能の改善見込み
• 書き込み時のオーバーヘッド
• ストレージコスト
• マイグレーションリスク
• 運用上の注意点

これは特に、追加インデックス、パーティショニング、covering index、JSONB インデックス、prepared statements の判断で重要です。

よくある失敗パターンに注意する

品質の低い出力では、次のような問題がよく見られます。

• フィルタ条件やソート条件を確認せずにインデックスを提案する
• パーティショニングを早い段階で勧めすぎる
• RLS の正しさだけを話し、RLS の性能を見ない
• デプロイ形態を考慮せずに connection pooling を勧める
• SQL を書き換えても、実行計画がどう変わるかの確認方法に触れない

こうした兆候が出たら、対象タスクを絞り込み、対応するリファレンスファイルを明示してください。

プロンプト内でリファレンスのファイル名を指定する

次のように、参照先を明示すると精度が上がりやすくなります。

Use references/query-partial-indexes.md and references/query-composite-indexes.md to decide which index strategy fits this workload.

または

Apply the guidance from references/security-rls-performance.md to these policies and explain any index support they need.

このリポジトリはモジュール単位で構成されているため、スキル全体を抽象的に呼び出すより、対象ファイルを指定したほうが良い結果になりやすいです。

最初の回答のあと、検証前提の再質問をする

初回の回答を得たあとは、次のような追質問が有効です。

• “Which recommendation has the best impact-to-risk ratio?”
• “Show the exact EXPLAIN differences I should expect.”
• “Revise the index recommendation for a write-heavy workload.”
• “Rewrite this for cursor pagination instead of offset pagination.”
• “Check whether the RLS predicate can use an index.”

こうした 2 回目以降のやり取りで、supabase-postgres-best-practices install と活用の手間が効いてきます。

Database Engineering チーム向けに出力を改善する

チーム運用では、レビュー担当者が本当に必要とする項目に合わせてプロンプトテンプレートを標準化すると効果的です。

• 影響を受けるテーブル
• 現在の SQL と提案 SQL
• ワークロード量
• レイテンシ目標
• 既存インデックス
• RLS の有無
• デプロイモデル
• 許容できるマイグレーションリスク

こうしておくと、supabase-postgres-best-practices for Database Engineering を、その場しのぎのアシスタントではなく、再現性のあるレビュー基盤として使えるようになります。

自分でスキルを拡張する場合

社内向けでも upstream への貢献でも、references/_template.md と references/_contributing.md にあるリポジトリの流儀に従うのがよいです。つまり、まず誤ったパターンを示し、そのあとで修正後の SQL を示し、さらに定量的な効果を添えること。この構成こそが、エージェントにとってこのスキルが実用的である理由のひとつです。