ペルソナ: あなたは、安全で明示的かつ可観測性の高いデータベースコードを書く Go バックエンドエンジニアです。SQL を一流の言語として扱い、ORM や魔法は使わず、データ整合性の問題をアプリケーションの境界で捉えます。

モード:

• Write モード — 新しいリポジトリ関数、クエリヘルパー、またはトランザクションラッパーを生成する場合: スキルのシーケンシャル手順に従い、新しいコードを生成する前に背景エージェントを起動して、コードベース内の既存のクエリパターンと命名規則をグレップします。
• Review/debug モード — 既存のデータベースコードを監査またはデバッグする場合: サブエージェントを使用して、ビジネスロジックを読むのと並行して、rows.Close() の欠落、パラメータ化されていないクエリ、コンテキスト伝播の欠落、エラーチェックの欠落をスキャンします。

コミュニティデフォルト。 samber/cc-skills-golang@golang-database スキルを明示的に置き換える企業スキルが優先されます。

Go データベースのベストプラクティス

Go の database/sql はデータベースアクセスに堅牢な基礎を提供します。その上で sqlx または pgx を使用してエルゴノミクスを実現します — ORM は決して使用しません。

sqlx または pgx を使用する場合は、ライブラリの公式ドキュメントとコード例を参照して、現在の API シグネチャを確認してください。

ベストプラクティスの要約

1. ORM ではなく sqlx または pgx を使用する — ORM は SQL を隠し、予測不可能なクエリを生成し、デバッグを難しくします
2. クエリは必ずパラメータ化プレースホルダを使用する — ユーザー入力を SQL 文字列に連結してはいけません
3. コンテキストはすべてのデータベース操作に渡す必要がある — *Context メソッドバリアント (QueryContext, ExecContext, GetContext) を使用します
4. sql.ErrNoRows は明示的に処理する必要がある — errors.Is を使用して「見つからない」と実際のエラーを区別します
5. 反復後は Rows を必ずクローズする — QueryContext 呼び出しの直後に defer rows.Close() を使用します
6. 行を返さないステートメントに db.Query を決して使用しない — Query は *Rows を返しており、クローズする必要があります。忘れるとコネクションがプールにリークします。代わりに db.Exec を使用してください
7. マルチステートメント操作にはトランザクションを使用する — BeginTxx/Commit でと関連する書き込みをラップします
8. データを変更するために読み取っている場合は SELECT ... FOR UPDATE を使用する — レース条件を防止します
9. デフォルトの READ COMMITTED では不十分な場合は、カスタム分離レベルを設定する (例: 財務操作の場合は serializable)
10. NULLable カラムを処理する — ポインタフィールド (*string, *int) または sql.NullXxx タイプを使用します
11. コネクションプールは設定する必要がある — SetMaxOpenConns, SetMaxIdleConns, SetConnMaxLifetime, SetConnMaxIdleTime
12. マイグレーションに外部ツールを使用する — golang-migrate または Flyway、手書きまたは AI 生成のマイグレーション SQL は決して使用しません
13. バッチ操作を合理的なサイズで行う — 行ごとではなく (ラウンドトリップが多すぎる)、一度に数百万ではなく (ロックとメモリ)
14. データベススキーマを作成または変更しない — おもちゃのデータでは正しく見えるスキーマでも、実際の本番負荷下ではホットスポット、ロック競合、またはインデックスの欠落を作成できます。スキーマ設計には、AI が持たないデータ量、アクセスパターン、本番制約の理解が必要です
15. 隠れた SQL 機能を避ける — アプリケーションコード内でトリガー、ビュー、マテリアライズドビュー、ストアドプロシージャ、または行レベルセキュリティに依存しないでください。それらは見えない副作用を生成し、デバッグを不可能にします。SQL を明示的かつ可視的に Go に保つだけで、テストとバージョン管理ができます

ライブラリ選択

ライブラリ	最適な用途	構造体スキャン	PostgreSQL 固有
database/sql	移植性、最小限の依存関係	手動 Scan	いいえ
sqlx	マルチデータベースプロジェクト	StructScan	いいえ
pgx	PostgreSQL (30-50% 高速)	pgx.RowToStructByName	はい (COPY, LISTEN, 配列)
GORM/ent	避ける	魔法	抽象化

ORM ではない理由:

• 予測不可能なクエリ生成 — コード内で見ることができない N+1 問題
• 魔法フック・コールバック (BeforeCreate, AfterUpdate) はデバッグを難しくします
• スキーママイグレーションがアプリケーションコードに結合されている
• ORM API を学ぶことは SQL を学ぶよりも難しく、抽象化がリークします

パラメータ化クエリ

// ✗ VERY BAD — SQL インジェクション脆弱性
query := fmt.Sprintf("SELECT * FROM users WHERE email = '%s'", email)

// ✓ Good — パラメータ化 (PostgreSQL)
var user User
err := db.GetContext(ctx, &user, "SELECT id, name, email FROM users WHERE email = $1", email)

// ✓ Good — パラメータ化 (MySQL)
err := db.GetContext(ctx, &user, "SELECT id, name, email FROM users WHERE email = ?", email)

動的 IN 句

query, args, err := sqlx.In("SELECT * FROM users WHERE id IN (?)", ids)
if err != nil {
    return fmt.Errorf("building IN clause: %w", err)
}
query = db.Rebind(query) // adjust placeholders for your driver
err = db.SelectContext(ctx, &users, query, args...)

動的カラム名

ユーザー入力からカラム名を補間しないでください。許可リストを使用します:

allowed := map[string]bool{"name": true, "email": true, "created_at": true}
if !allowed[sortCol] {
    return fmt.Errorf("invalid sort column: %s", sortCol)
}
query := fmt.Sprintf("SELECT id, name, email FROM users ORDER BY %s", sortCol)

インジェクション防止パターンの詳細については、samber/cc-skills-golang@golang-security スキルを参照してください。

構造体スキャンと NULLable カラム

sqlx の場合は db:"column_name" タグ、pgx の場合は pgx.CollectRows と pgx.RowToStructByName を使用します。NULLable カラムはポインタフィールド (*string, *time.Time) で処理します。これらはスキャンと JSON マーシャリングの両方で機能します。すべてのアプローチの例については、Scanning Reference を参照してください。

エラーハンドリング

func GetUser(id string) (*User, error) {
    var user User

    err := db.GetContext(ctx, &user, "SELECT id, name FROM users WHERE id = $1", id)
    if err != nil {
        if errors.Is(err, sql.ErrNoRows) {
            return nil, ErrUserNotFound // ドメインエラーに変換
        }
        return nil, fmt.Errorf("querying user %s: %w", id, err)
    }

    return &user, nil
}

または:

func GetUser(id string) (u *User, exists bool, err error) {
    var user User

    err := db.GetContext(ctx, &user, "SELECT id, name FROM users WHERE id = $1", id)
    if err != nil {
        if errors.Is(err, sql.ErrNoRows) {
            return nil, false, nil // 「ユーザーなし」は技術的なエラーではなく、ドメインエラーです
        }
        return nil, false, fmt.Errorf("querying user %s: %w", id, err)
    }

    return &user, true, nil
}

常に rows をクローズする

rows, err := db.QueryContext(ctx, "SELECT id, name FROM users")
if err != nil {
    return fmt.Errorf("querying users: %w", err)
}
defer rows.Close() // コネクションリークを防止

for rows.Next() {
    // ...
}
if err := rows.Err(); err != nil { // 反復後は常にチェック
    return fmt.Errorf("iterating users: %w", err)
}

一般的なデータベースエラーパターン

エラー	検出方法	アクション
行が見つからない	errors.Is(err, sql.ErrNoRows)	ドメインエラーを返す
ユニーク制約	ドライバ固有のエラーコードをチェック	競合エラーを返す
コネクション拒否	err != nil on db.PingContext	早期に失敗、ログ、バックオフで再試行
シリアライゼーション失敗	PostgreSQL エラーコード 40001	トランザクション全体を再試行
コンテキストがキャンセルされた	errors.Is(err, context.Canceled)	処理を停止、伝播

コンテキスト伝播

常に *Context メソッドバリアントを使用して、デッドラインとキャンセルを伝播させます:

// ✗ Bad — コンテキストなし、クライアントが切断されても完了するまでクエリが実行される
db.Query("SELECT ...")

// ✓ Good — コンテキストのキャンセルとタイムアウトを尊重
db.QueryContext(ctx, "SELECT ...")

コンテキストパターンの詳細については、samber/cc-skills-golang@golang-context スキルを参照してください。

トランザクション、分離レベル、ロック

トランザクションパターン、分離レベル、SELECT FOR UPDATE、ロックバリアントについては、Transactions を参照してください。

コネクションプール

db.SetMaxOpenConns(25)              // 総コネクション数を制限
db.SetMaxIdleConns(10)              // ウォームコネクションを準備
db.SetConnMaxLifetime(5 * time.Minute)  // 古いコネクションをリサイクル
db.SetConnMaxIdleTime(1 * time.Minute)  // アイドルコネクションをより早くクローズ

サイジングガイダンスと式については、Database Performance を参照してください。

マイグレーション

外部マイグレーションツールを使用してください。スキーマ変更には、データ量、既存のインデックス、外部キー、本番制約を理解した人間による確認が必要です。

推奨ツール:

• golang-migrate — CLI + Go ライブラリ、すべての主要なデータベースをサポート
• Flyway — JVM ベース、エンタープライズ環境で広く使用
• Atlas — モダン、宣言的スキーマ管理

マイグレーション SQL は人間によって作成・確認され、ソースコントロールにバージョン管理され、CI/CD パイプラインを通じて適用されるべきです。

隠れた SQL 機能を避ける

アプリケーションコード内でトリガー、ビュー、マテリアライズドビュー、ストアドプロシージャ、または行レベルセキュリティに依存しないでください。それらは見えない副作用を生成し、デバッグを不可能にします。SQL を明示的かつ可視的に Go に保ち、テストとバージョン管理ができるようにしてください。

スキーマ作成

このスキルはスキーマ作成をカバーしていません。 AI 生成スキーマはしばしば微妙に間違っています — インデックスの欠落、不正なカラムタイプ、悪い正規化、または制約の欠落です。スキーマ設計には、データ量、アクセスパターン、クエリプロファイル、ビジネス制約の理解が必要です。専用のデータベースツーリングと人間のレビューを使用してください。

ディープダイブ

• Transactions — トランザクション境界、分離レベル、デッドロック防止、SELECT FOR UPDATE
• Testing Database Code — モック接続、コンテナを使用した統合テスト、フィクスチャ、スキーマセットアップ/ティアダウン
• Database Performance — コネクションプールサイジング、バッチ処理、インデックス戦略、クエリ最適化
• Struct Scanning — 構造体タグ、NULLable カラム処理、JSON マーシャリングパターン

クロスリファレンス

• → samber/cc-skills-golang@golang-security スキルで SQL インジェクション防止パターンを参照
• → samber/cc-skills-golang@golang-context スキルでデータベース操作へのコンテキスト伝播を参照
• → samber/cc-skills-golang@golang-error-handling スキルでデータベースエラーラップパターンを参照
• → samber/cc-skills-golang@golang-testing スキルでデータベース統合テストパターンを参照

参考資料

• database/sql tutorial
• sqlx
• pgx
• golang-migrate