.claude/skills/connection-pooling/SKILL.md

Connection Pooling

概要

このスキルは、データベース接続管理の設計と実装に関する 知識を提供します。特にサーバーレス環境（Turso）での libSQL接続管理とEmbedded Replicasに焦点を当てています。

主要な価値:

• サーバーレス環境での安定した接続
• Embedded Replicasによるローカル↔クラウド同期
• 高負荷時のパフォーマンス維持
• 接続リソースの効率的な利用

対象ユーザー:

• .claude/​agents/​dba-mgr.mdエージェント
• バックエンド開発者
• DevOpsエンジニア
• SREチーム

リソース構造

connection-pooling/
├── SKILL.md                                    # 本ファイル
├── resources/
│   ├── pool-sizing-guide.md                   # プールサイジング
│   ├── serverless-connections.md              # サーバーレス接続
│   └── error-handling.md                      # エラーハンドリング
├── scripts/
│   └── check-connections.mjs                  # 接続状態確認
└── templates/
    └── drizzle-config-template.ts             # Drizzle設定テンプレート

コマンドリファレンス

リソース読み取り

# プールサイジング
cat .claude/​skills/​connection-pooling/​resources/​pool-sizing-guide.md

# サーバーレス接続
cat .claude/​skills/​connection-pooling/​resources/​serverless-connections.md

# エラーハンドリング
cat .claude/​skills/​connection-pooling/​resources/​error-handling.md

スクリプト実行

# 接続状態確認
node .claude/​skills/​connection-pooling/​scripts/​check-connections.mjs

いつ使うか

シナリオ1: 新規プロジェクトセットアップ

状況: 新しいプロジェクトでDB接続を設定する

適用条件:

• データベースサービスが決定済み
• 想定負荷が見積もられている
• 実行環境が決まっている

期待される成果: 最適な接続プール設定

シナリオ2: 接続エラーの解決

状況: 「too many connections」などのエラーが発生

適用条件:

• エラーの発生パターンが把握できている
• 現在の設定が確認できる
• 接続数の監視ができる

期待される成果: 安定した接続設定

シナリオ3: サーバーレス移行

状況: サーバーレス環境への移行で接続管理を見直す

適用条件:

• サーバーレスプラットフォームが決定
• 接続パターンが理解されている
• Embedded Replicasの使用を検討している

期待される成果: サーバーレス対応の接続設定

ワークフロー

Phase 1: 要件分析

目的: 接続要件を明確化する

ステップ:

1. 環境の確認:

   • サーバーレス vs 常駐サーバー
   • Turso Cloud / Embedded Replicas / Self-hosted
   • ワーカー数・インスタンス数

2. 負荷の見積もり:

   • 同時リクエスト数
   • クエリの実行時間
   • ピーク時の負荷

判断基準:

• 実行環境が明確か？
• 負荷の見積もりがあるか？
• Embedded Replicasの使用を検討したか？

リソース: resources/​serverless-connections.md

Phase 2: 接続設計

目的: 適切な接続設定を決定する

ステップ:

1. 接続設定の実装:

   // Turso接続設定
   const config = {
     url: process.env.TURSO_DATABASE_URL,
     authToken: process.env.TURSO_AUTH_TOKEN,
   };
   

2. Embedded Replicas設定:

   const client = createClient({
     url: "file:local.db", // ローカルレプリカ
     syncUrl: process.env.TURSO_DATABASE_URL,
     authToken: process.env.TURSO_AUTH_TOKEN,
     syncInterval: 60, // 60秒ごとに同期
   });
   

判断基準:

• 接続URLとトークンは設定されているか？
• Embedded Replicasの使用を検討したか？
• 同期間隔は適切か？
• リトライ設定があるか？

リソース: resources/​pool-sizing-guide.md

Phase 3: エラーハンドリング

目的: 接続エラーに対する回復力を確保する

ステップ:

1. リトライ戦略:

   • 指数バックオフ
   • 最大リトライ回数
   • リトライ可能なエラーの定義

2. サーキットブレーカー:

   • 連続失敗時のオープン
   • 回復試行間隔
   • 半開状態の管理

判断基準:

• リトライ戦略が実装されているか？
• タイムアウトが設定されているか？
• エラーログが記録されるか？

リソース: resources/​error-handling.md

Phase 4: 監視

目的: 接続状態を継続的に監視する

ステップ:

1. メトリクスの収集:

   • アクティブ接続数
   • 待機中の接続
   • 接続エラー率

2. アラート設定:

   • 接続枯渇の警告
   • エラー率の閾値
   • レイテンシの監視

判断基準:

• 接続数の監視があるか？
• アラートが設定されているか？
• ダッシュボードがあるか？

核心概念

接続プールの基本

アプリケーション
    │
    ├── リクエスト1 ──→ [接続1]
    ├── リクエスト2 ──→ [接続2]  ←── 接続プール
    ├── リクエスト3 ──→ [接続3]       (再利用)
    └── リクエスト4 ──→ [待機...]
                           │
                           ▼
                      データベース

プールモード

サーバーレス特有の課題

Lambda/​Edge Function
    │
    ├── コールドスタート → 新規接続
    │                      (オーバーヘッド)
    ├── ウォームスタート → 既存接続再利用
    │                      (高速)
    └── スケールアウト → 接続爆発のリスク
                          (プーラーで制御)

ベストプラクティス

すべきこと

1. 適切な接続方式を選択する:

   • Turso Cloud: HTTPSベースの接続
   • Embedded Replicas: ローカルファイル + クラウド同期
   • Self-hosted: libSQL Server

2. 接続を適切にリリースする:

   try {
     const result = await client.execute("SELECT * FROM users");
     return result;
   } finally {
     // libSQLクライアントは自動的に接続を管理
     // Embedded Replicasの場合は定期的に同期
   }
   

3. 同期設定を最適化する:

   const config = {
     syncInterval: 60, // 同期間隔（秒）
     syncOnWrite: true, // 書き込み時に同期
     readYourWrites: true, // 自分の書き込みを即座に読み取り
   };
   

避けるべきこと

1. 接続のリーク:

   • ❌ 接続を閉じ忘れる
   • ✅ try-finallyで確実にリリース

2. 不適切な同期設定:

   • ❌ 同期間隔が短すぎる（ネットワーク負荷）
   • ✅ アプリケーション要件に応じた適切な間隔

3. Embedded Replicasの未活用:

   • ❌ サーバーレス環境で常にリモート接続
   • ✅ Embedded Replicasでローカル読み取り + クラウド同期

トラブルシューティング

問題1: 同期エラー

症状: Embedded Replicasの同期が失敗

原因:

• ネットワーク接続の問題
• 認証トークンの期限切れ
• 同期URLの設定ミス

解決策:

// 同期状態の確認
const syncStatus = await client.sync();
console.log("Sync completed:", syncStatus);

// 手動で強制同期
await client.sync();

// 同期エラーのハンドリング
client.on("sync-error", (error) => {
  console.error("Sync failed:", error);
  // リトライロジック
});

問題2: 接続タイムアウト

症状: Tursoへの接続がタイムアウト

原因:

• ネットワーク遅延
• 認証トークンの問題
• リージョンが遠い

解決策:

// Embedded Replicasを使用してローカル接続
const client = createClient({
  url: "file:local.db",
  syncUrl: process.env.TURSO_DATABASE_URL,
  authToken: process.env.TURSO_AUTH_TOKEN,
});

// リトライ戦略
const retryConfig = {
  retries: 3,
  factor: 2,
  minTimeout: 1000,
  maxTimeout: 5000,
};

問題3: コールドスタートの遅延

症状: Lambda/​Edgeの初回リクエストが遅い

原因:

• リモートDB接続の確立
• HTTPS通信のオーバーヘッド
• 認証処理

解決策:

• Embedded Replicasの使用（ローカルファイルアクセス）
• Provisioned Concurrencyの使用
• クライアントインスタンスのキャッシング

関連スキル

• .claude/​skills/​query-performance-tuning/​SKILL.md (.claude/​skills/​query-performance-tuning/​SKILL.md): クエリ最適化
• .claude/​skills/​backup-recovery/​SKILL.md (.claude/​skills/​backup-recovery/​SKILL.md): バックアップ戦略

メトリクス

接続プール健全性指標

変更履歴

参考文献

• Turso Documentation: https://docs.turso.tech/
• libSQL: https://github.com/tursodatabase/libsql
• Embedded Replicas: https://docs.turso.tech/features/embedded-replicas