moai-domain-database

データベースドメインのスペシャリスト

クイックリファレンス

エンタープライズデータベースの専門知識 — PostgreSQL、MongoDB、Redis、Oracle を網羅し、スケーラブルな最新アプリケーション向けの高度なデータ管理パターンと実装を紹介します。

主な機能：

• PostgreSQL：高度なリレーショナルパターン、最適化、スケーリング
• MongoDB：ドキュメントモデリング、集計、NoSQL のパフォーマンスチューニング
• Redis：インメモリキャッシュ、リアルタイム分析、分散システム
• Oracle：エンタープライズパターン、PL/SQL、パーティショニング、階層クエリ
• マルチデータベース：ハイブリッドアーキテクチャとデータ統合パターン
• パフォーマンス：クエリの最適化、インデックス戦略、スケーリング
• 運用：接続管理、マイグレーション、監視

使用する場面：

• データベーススキーマとデータモデルの設計
• キャッシュ戦略とパフォーマンス最適化の実装
• スケーラブルなデータアーキテクチャの構築
• マルチデータベースシステムの利用
• データベースクエリとパフォーマンスの最適化

---

実装ガイド

クイックスタートのワークフロー

データベーススタックの初期化：

DatabaseManager インスタンスを作成し、複数のデータベース接続を設定します。接続文字列、プールサイズ 20、クエリログの有効化を指定して PostgreSQL をセットアップします。接続文字列、データベース名、シャーディングの有効化を指定して MongoDB を設定します。接続文字列、最大接続数 50、クラスタリングの有効化を指定して Redis を設定します。統合インターフェースを使用して、すべてのデータベースタイプからプロフィールと分析データを含むユーザーデータをクエリします。

単一データベースの操作：

データベースタイプとマイグレーションファイルのパスを指定して、マイグレーションコマンドを使用し、PostgreSQL スキーマのマイグレーションを実行します。コレクション名とパイプラインの JSON ファイルを指定して、MongoDB の集計パイプラインを実行します。キーのパターンと TTL 値を指定して、Redis キャッシュをウォームアップします。

主なコンポーネント

PostgreSQL モジュール：

• 高度なスキーマ設計と制約
• 複雑なクエリの最適化とインデックス作成
• ウィンドウ関数と CTE
• パーティショニングとマテリアライズドビュー
• コネクションプーリングとパフォーマンスチューニング

MongoDB モジュール：

• ドキュメントモデリングとスキーマ設計
• 分析用の集計パイプライン
• インデックス戦略とパフォーマンス
• シャーディングとスケーリングのパターン
• データの一貫性と検証

Redis モジュール：

• 多層キャッシュ戦略
• リアルタイム分析とカウント
• 分散ロックと調整
• パブリッシュ／サブスクライブのメッセージングとストリーム
• HyperLogLog や Geo を含む高度なデータ構造

Oracle モジュール：

• 階層クエリと再帰クエリのパターン（CONNECT BY）
• PL/SQL のプロシージャ、パッケージ、バッチ処理
• パーティショニング戦略（範囲、リスト、ハッシュ、複合）
• エンタープライズ機能とステートメントキャッシュ
• LOB の処理と大規模データ処理

---

高度なパターン

マルチデータベースアーキテクチャ

ポリグロット永続化パターン：

PostgreSQL、MongoDB、Redis、Oracle への接続を初期化する DataRouter クラスを作成します。get_user_profile メソッドを実装し、PostgreSQL または Oracle から構造化されたユーザーデータを、MongoDB から柔軟なプロフィールデータを、Redis からリアルタイムのステータスを取得して、すべてのデータソースを統合します。update_user_data メソッドを実装し、構造化データの更新を PostgreSQL／Oracle に、プロフィールデータの更新を MongoDB に、リアルタイムデータの更新を Redis に振り分けた後、キャッシュを無効化します。

データ同期：

データベース間でユーザーデータを同期する DataSyncManager クラスを作成します。sync_user_data メソッドを実装し、PostgreSQL からユーザーを取得して MongoDB 用の検索ドキュメントを作成し、MongoDB の検索コレクションにアップサートし、キャッシュデータを作成して、TTL を設定した Redis キャッシュを更新します。

パフォーマンスの最適化

クエリパフォーマンスの分析：

PostgreSQL では、クエリに対して EXPLAIN ANALYZE BUFFERS を実行し、QueryAnalyzer を使用して最適化の提案を生成します。MongoDB では、AggregationOptimizer を作成して集約パイプラインを分析し、最適化します。Redis では、情報メトリクスを取得し、PerformanceAnalyzer を使用して推奨事項を生成します。

スケーリング戦略：

レプリカ接続 URL を指定して、PostgreSQL の読み取りレプリカを設定します。シャードキーとシャード数を指定して、MongoDB のシャーディングを設定します。クラスターのノード URL を指定して、Redis クラスタリングを設定します。

---

相性の良いもの

補完的なスキル：

• moai-domain-backend - API 統合とビジネスロジック
• moai-foundation-core - データベースの移行とスキーマ管理
• moai-workflow-project - データベースプロジェクトのセットアップと構成
• moai-platform-supabase - Supabase データベースの統合パターン
• moai-platform-neon - Neon データベースの統合パターン
• moai-platform-firestore - Firestore データベースの統合パターン

テクノロジーの統合：

• SQLAlchemy、Mongoose、TypeORM などの ORM と ODM
• PgBouncer と接続プールによるコネクションプーリング
• Alembic、Flyway、Data Pump などの移行ツール
• pg_stat_statements、MongoDB Atlas、Oracle AWR による監視
• Oracle 接続と PL/SQL 実行のための python-oracledb
• キャッシュの無効化と同期

---

テクノロジースタック

リレーショナルデータベース：

• プライマリデータベースとして PostgreSQL 14+
• 代替として MySQL 8.0+
• PgBouncer と SQLAlchemy によるコネクションプーリング

NoSQL データベース：

• プライマリのドキュメントストアとして MongoDB 6.0+
• ドキュメントのモデリングと検証
• 集約フレームワーク
• シャーディングとレプリケーション

インメモリデータベース：

• プライマリキャッシュとして Redis 7.0+
• 高度な機能向けの Redis Stack
• クラスタリングと高可用性
• 高度なデータ構造

エンタープライズデータベース：

• エンタープライズワークロード向けの Oracle 19c+ / 21c+
• python-oracledb（cx_Oracle の後継）
• PL/SQL プロシージャとパッケージ
• パーティショニングと高度な分析

サポートツール：

• Alembic や Flyway などの移行ツール
• Prometheus と Grafana による監視
• SQLAlchemy や Mongoose などの ORM と ODM
• 接続管理ユーティリティ

パフォーマンス機能：

• クエリの最適化と分析
• インデックス管理と戦略
• キャッシュレイヤーと無効化
• 負荷分散とフェイルオーバー

---

リソース

ステータス：本番環境対応 メンテナー：MoAI-ADK Database Team

よくある正当化

正当化	実態
「インデックスは不要です。テーブルが小さいので」	テーブルは大きくなります。1K 行では見えないインデックスの欠落が、1M 行では本番障害につながります。
「移行は後で追加します」	移行なしのスキーマ変更は再現できません。すべての変更に、元に戻せる移行スクリプトが必要です。
「このクエリは開発環境では問題なく動きます」	開発用データベースのデータセットはごく小規模です。本番環境のクエリプランは、規模が大きくなると大幅に異なります。まず EXPLAIN ANALYZE を実行してください。
「NoSQL ではスキーマ設計は不要です」	スキーマレスだからといって、設計が不要というわけではありません。ドキュメント構造の決定は、すべてのクエリとインデックスに影響します。
「列を追加するだけなら、後方互換性に問題はありません」	デフォルト値なしで NOT NULL 列を追加すると、既存の挿入処理が失敗します。列の追加には、デフォルト値または移行時のデータ補完が必要です。
「コネクションプーリングはフレームワークが処理します」	フレームワークのデフォルト設定は汎用的です。プールサイズ、タイムアウト、アイドル上限はワークロードに合わせて調整する必要があります。

危険信号

• 対応する移行ファイルがないままスキーマ変更がコミットされている
• 本番コードで、明示的な列リストではなく SELECT * を使用しているクエリがある
• WHERE、JOIN、ORDER BY 句で使用される列にインデックスがない
• 接続文字列が環境変数ではなくソースコードにハードコードされている
• トランザクションのスコープが、ユーザー向け HTTP リクエストの処理時間にわたっている（ロックが長時間保持される）
• 大規模なテーブルにアクセスする新しいクエリの EXPLAIN ANALYZE 出力がない

検証

• スキーマ変更ごとにマイグレーションファイルが存在する（マイグレーションファイルの一覧を表示）
• 頻繁にクエリされるカラムにインデックスが存在する（インデックス定義を表示）
• 代表的なデータを使って新しいクエリに対して EXPLAIN ANALYZE を実行する（出力を表示）
• 接続認証情報は環境変数から取得する
• トランザクションの範囲は最小限にし、I/O 待ちをまたがない
• バックアップと復元の手順を文書化し、テストする
• 接続プールの設定でサイズとタイムアウトを明示的に指定する

---

クラウドベンダーガイド（moai-platform-database-cloud から統合）

Neon、Supabase、Firebase Firestore のクラウドデータベースプラットフォームの選択と設定について説明します。

かんたんな選択ガイド

ニーズ	プラットフォーム
自動スケーリング対応のサーバーレス PostgreSQL	Neon
CI/CD プレビュー用のデータベースブランチ	Neon branching
エッジ対応の接続プーリング	Neon + Neon Proxy
AI/ML 向けベクトル検索（pgvector）	Supabase
マルチテナントアプリ向けの行レベルセキュリティ	Supabase RLS
リアルタイムサブスクリプション + フルスタック	Supabase
オフライン同期を備えたモバイルファースト	Firebase Firestore
クロスプラットフォーム（iOS/Android/Web）	Firebase Firestore

Neon（サーバーレス PostgreSQL）

主な機能：自動スケーリング対応のコンピューティング、ゼロまでのスケール、データベースブランチ、pg_bouncer プーリング。

セットアップ：

npm install @neondatabase/serverless
# Connection string: postgresql://user:[email protected]/dbname?sslmode=require

ブランチのワークフロー：PR ごとにブランチを作成し（neonctl branches create --name pr-123）、マイグレーションを実行してテストし、マージ時に削除します。アイドル期間中はコストがゼロです。

Supabase（PostgreSQL 16）

主な機能：pgvector、行レベルセキュリティ、リアルタイムサブスクリプション、組み込みの認証／ストレージ。

RLS ポリシーのパターン：

CREATE POLICY "users_own_data" ON items
  FOR ALL USING (auth.uid() = user_id);

pgvector による検索：SELECT * FROM embeddings ORDER BY embedding <-> $1 LIMIT 10;

Firebase Firestore（NoSQL）

主な機能：リアルタイム同期、オフラインキャッシュ、セキュリティルール、モバイル SDK。

セキュリティルールのパターン：

match /users/{userId} {
  allow read, write: if request.auth.uid == userId;
}

オフライン永続化：enableIndexedDbPersistence(db)（Web）で有効にするか、SDK のデフォルト（モバイル）を使用します。