💾 データベースドライバー

データベースドライバーは NodeBlocks サービスを MongoDB に接続します。SDK サービスで使用する接続設定とコレクションアクセスを抽象化します。

---

🎯 概要

NodeBlocks のデータベースドライバーは、設定済みの MongoDB 接続を作成するファクトリー関数です。SDK には現在 1 つの MongoDB ドライバーが含まれます。独自の永続化アダプターについては、カスタムデータストアの使用 を参照してください。

import { drivers } from '@nodeblocks/backend-sdk';
import type { MongoClientOptions } from 'mongodb';

const { getMongoClient, withMongo } = drivers;

MongoClientOptions は mongodb パッケージからインポートします。SDK からは再エクスポートされません。

---

📊 getMongoClient と withMongo の比較

関数	connect() を呼び出すか	認証
getMongoClient	いいえ（遅延接続。最初の操作時に接続）	ヘルパーは認証情報を追加しません。接続文字列または MongoClientOptions.auth を使用してください。
withMongo	はい（即時接続。client.connect() を待機）	クライアントに auth: { username, password } を設定します。

---

📋 利用可能なデータベースドライバー

MongoDB ドライバー

MongoDB ドライバーは、NodeBlocks サービスで使用する設定済み MongoDB データベースインスタンスを作成します。

getMongoClient

指定した接続 URL とデータベース名で MongoDB の Db インスタンスを作成します。これは同期ファクトリーのため await は不要です。connect() は明示的に呼び出しません。MongoDB ドライバーは最初の操作時に遅延接続します。

パラメーター:

パラメーター	型	説明
url	string	MongoDB 接続文字列（例：mongodb://localhost:27017）
dbName	string	MongoDB インスタンス内のデータベース名
options?	MongoClientOptions	mongodb パッケージの任意クライアントオプション（既定値：{ timeoutMS: 30000 }）

戻り値: データベース操作を行う MongoDB の Db インスタンス

ライフサイクルに関する注意: getMongoClient は内部で MongoClient を作成しますが、返すのは Db 参照だけで、クライアント自体は公開しません。複数コレクションを使うアプリでは、自身で管理する共有クライアントを使うか、サービスドキュメントの例のようにコレクションごとに withMongo を使用してください。

使用例:

import { drivers } from '@nodeblocks/backend-sdk';

const { getMongoClient } = drivers;

const db = getMongoClient(
  process.env.MONGODB_URI || 'mongodb://localhost:27017',
  process.env.MONGODB_DB_NAME || 'myapp'
);

// Access collections
const usersCollection = db.collection('users');
const postsCollection = db.collection('posts');

カスタムオプションの例:

import { drivers } from '@nodeblocks/backend-sdk';
import type { MongoClientOptions } from 'mongodb';

const { getMongoClient } = drivers;

const db = getMongoClient(
  'mongodb+srv://username:password@cluster.mongodb.net/myapp',
  'myapp',
  { timeoutMS: 10000 } satisfies MongoClientOptions
);

withMongo

自動コレクションアクセスを備えた、認証済み MongoDB 接続を作成するカリー化ユーティリティです。getMongoClient と異なり、コレクションを返す前に client.connect() を呼び出します。

パラメーター:

パラメーター	型	説明
dbUrl	string	MongoDB 接続 URL
dbName	string	接続先データベース名
dbUser	string	認証用ユーザー名
dbPassword	string	認証用パスワード
collectionName	string	アクセスするコレクション名
options?	MongoClientOptions	mongodb パッケージの任意クライアントオプション（既定値：{ timeoutMS: 30000 }）。カリー化シグネチャには含まれません。5 つの位置引数を単一の呼び出しで渡す場合のみ指定してください。

戻り値: 要求されたコレクションを含む Promise<{ [collectionName]: Collection<Document> }> オブジェクト

ライフサイクルに関する注意: 完全に適用された withMongo(...) の呼び出しごとに新しい MongoClient を作成し、connect() を待機してコレクションだけを返します。クライアントは終了処理のために公開されません。カリー化ファクトリーが再利用するのは URL、データベース、認証情報の束縛のみです。await connectToMyApp('users') を呼ぶたびに独自の接続を開きます。複数コレクションを使うアプリでは、自身で管理する 1 つの共有クライアントを使うか、withMongo 呼び出しごとに 1 接続を受け入れてください。

使用例:

import { drivers } from '@nodeblocks/backend-sdk';

const { withMongo } = drivers;

// Full application — get users collection
const { users } = await withMongo(
  'mongodb://localhost:27017/?authSource=admin',
  'myapp',
  'admin',
  'password',
  'users'
);
// Returns: { users: Collection<Document> }

// Reusable factory — URL, database, and credentials applied once
const connectToMyApp = withMongo('mongodb://localhost:27017/?authSource=admin', 'myapp', 'admin', 'password');
const { users: usersCol } = await connectToMyApp('users');
const { orders } = await connectToMyApp('orders');

// Partial factory — URL and database only
const connectWithAuth = withMongo('mongodb://localhost:27017/?authSource=admin', 'myapp');
const { posts } = await connectWithAuth('admin', 'password', 'posts');

// With custom options (all 5 positional args + options in one call)
const { users: usersWithOptions } = await withMongo(
  'mongodb://localhost:27017/?authSource=admin',
  'myapp',
  'admin',
  'password',
  'users',
  { timeoutMS: 10000 }
);

オプションのマージ動作:

動作	詳細
既定オプション	options を省略した場合は { timeoutMS: 30000 }
認証の上書き	withMongo は options を展開した後で auth: { username, password } を設定します。options の auth はカリー化された認証情報で上書きされます。
カリー化 options	options は第 6 引数で、Ramda のカリー化チェーンには含まれません。5 つの位置引数を単一呼び出しで渡す場合のみ指定してください。

エラー動作:

結果	動作
接続成功	{ [collectionName]: Collection<Document> } に解決されます。
client.connect() 失敗	Promise は接続エラーで拒否され、db() と collection() は呼び出されません。

---

🔧 データベースドライバーの使用

サービスでの使用

データストアパラメーターを通じて、データベースコレクションをサービスへ渡します。

import { services, drivers } from '@nodeblocks/backend-sdk';

const { identitiesService } = services;
const { withMongo } = drivers;

const connectToDatabase = withMongo(
  'mongodb://localhost:27017/?authSource=admin',
  'dev',
  'user',
  'password'
);

identitiesService(
  { ...(await connectToDatabase('identities')) },
  {
    authSecrets: {
      authEncSecret: process.env.AUTH_ENC_SECRET!,
      authSignSecret: process.env.AUTH_SIGN_SECRET!,
    },
  }
);

完全な Express 配線と必要なデータストアは、アイデンティティサービス を参照してください。

---

🔗 関連ドキュメント

• ドライバー概要 — ドライバーエクスポートの完全な一覧
• カスタムデータストアの使用 — 独自データベースドライバーの実装方法