@forgekit/db

@forgekit/db provides edge-optimized connection pools, replication replica routing, and type-safe transaction handlers.

Core Initialization

Configure @forgekit/db directly:

import { ForgeApp } from '@forgekit/core';
import { db } from '@forgekit/db';

const app = new ForgeApp();

app.use(
	db({
		url: process.env.DATABASE_URL,
		poolSize: 15,
		replicas: [{ url: process.env.DATABASE_REPLICA_URL_1, weight: 1 }]
	})
);

Type-Safe Transactions

To prevent connection leakages, transactions use auto-releasing callbacks:

const result = await app.db.transaction(async (tx) => {
	// Update balance query
	await tx.execute('UPDATE accounts SET balance = balance - ? WHERE id = ?', [100, 'acc_123']);

	// Insert transaction history log
	return await tx.execute('INSERT INTO transactions (id, amount, account_id) VALUES (?, ?, ?)', [
		'tx_999',
		100,
		'acc_123'
	]);
});

Replica Routing

ForgeKit automatically splits read/write traffic:

• app.db.write(...) or .transaction(...) routes queries to the Primary connection.
• app.db.read(...) routes queries randomly to read replicas depending on their weights, minimizing database CPU overhead.