@vibesdotdev/localdb 0.0.1

package/src/cli/commands/query/dev.localdb.query.cli-command.impl.consumer.ts

@@ -0,0 +1,69 @@
+import { existsSync } from 'node:fs';
+import { getVibesRuntime } from '@vibesdotdev/runtime';
+import type { UIContext } from '@vibesdotdev/cli/providers';
+import type { LocaldbApi } from '../../..';
+import { resolveFromCwd } from '../_shared.consumer';
+
+export default {
+	async execute(args: Record<string, unknown>, opts: Record<string, unknown>): Promise<void> {
+		const runtime = getVibesRuntime();
+		const ui = (await runtime.context('cli/ui')) as UIContext;
+		const localdb = (await runtime.context('dev/localdb')) as LocaldbApi;
+
+		const sql = typeof args.sql === 'string' ? args.sql : '';
+		const dbOpt = typeof opts.db === 'string' ? opts.db : '';
+
+		if (!sql.trim()) {
+			ui.error('Missing SQL statement');
+			process.exit(1);
+		}
+		if (!dbOpt.trim()) {
+			ui.error('Missing required option: --db <path>');
+			process.exit(1);
+		}
+
+		const fullPath = resolveFromCwd(dbOpt);
+		if (!existsSync(fullPath)) {
+			ui.error(`Database not found: ${dbOpt}`);
+			process.exit(1);
+		}
+
+		try {
+			const db = localdb.getRawDatabase(fullPath, 'localdb-query');
+			const isSelect = sql.trim().toLowerCase().startsWith('select');
+
+			if (isSelect) {
+				const results = db.query(sql).all();
+				if (opts.json) {
+					ui.json(results);
+				} else if (results.length === 0) {
+					ui.info('No results.');
+				} else {
+					ui.table(results);
+					ui.info(`(${results.length} row${results.length !== 1 ? 's' : ''})`);
+				}
+				return;
+			}
+
+			const stmt = db.prepare(sql);
+			const result = stmt.run();
+
+			const payload = {
+				changes: result.changes,
+				lastInsertRowid: result.lastInsertRowid
+			};
+
+			if (opts.json) {
+				ui.json(payload);
+			} else {
+				ui.success('Query executed successfully.');
+				ui.log(`Changes: ${payload.changes}`);
+				if (payload.lastInsertRowid)
+					ui.log(`Last Insert Row ID: ${String(payload.lastInsertRowid)}`);
+			}
+		} catch (error) {
+			ui.error(`Error executing query: ${String(error)}`);
+			process.exit(1);
+		}
+	}
+};

package/src/cli/commands/status/dev.localdb.status.cli-command.descriptor.ts

@@ -0,0 +1,20 @@
+/**
+ * Dev LocalDB Status CLI Command Descriptor
+ */
+
+import { createRuntimeAsset } from '@vibesdotdev/runtime';
+
+export default createRuntimeAsset({
+	id: 'dev.localdb.status',
+	kind: 'cli/command',
+	name: 'status',
+	description: 'Show database and migration status',
+	group: 'dev.localdb',
+	surfaces: ['cli'],
+	hardware: ['consumer'],
+	enabled: true,
+	options: [
+		{ flags: '--namespace <name>', description: 'Show status for specific namespace' },
+		{ flags: '--verbose', description: 'Show detailed migration and connection information' }
+	]
+});

package/src/cli/commands/status/dev.localdb.status.cli-command.impl.consumer.ts

@@ -0,0 +1,93 @@
+import { existsSync } from 'node:fs';
+import { getVibesRuntime } from '@vibesdotdev/runtime';
+import { requestCLIExit, type UIContext } from '@vibesdotdev/cli/providers';
+import type { LocaldbApi, MigrationRegistryApi } from '../../..';
+import { formatAgeMs, resolveDatabasePathForNamespace, resolveFromCwd } from '../_shared.consumer';
+
+export default {
+	async execute(_args: Record<string, unknown>, opts: Record<string, unknown>): Promise<void> {
+		const runtime = getVibesRuntime();
+		const ui = (await runtime.context('cli/ui')) as UIContext;
+		const localdb = (await runtime.context('dev/localdb')) as LocaldbApi;
+
+		const namespaceOpt = typeof opts.namespace === 'string' ? opts.namespace : undefined;
+		const verbose = Boolean(opts.verbose);
+
+		ui.log('\n=== LocalDB Status ===\n');
+
+		const namespaces = localdb.listNamespaces();
+		if (namespaces.length === 0) {
+			ui.info('No migration namespaces registered.');
+			return;
+		}
+
+		const namespacesToShow = namespaceOpt
+			? namespaces.filter((ns) => ns === namespaceOpt)
+			: namespaces;
+
+		if (namespacesToShow.length === 0) {
+			ui.error(`Namespace '${namespaceOpt}' not found.`);
+			ui.info(`Available namespaces: ${namespaces.join(', ')}`);
+			requestCLIExit(1);
+		}
+
+		const { migrationRegistry } =
+			(await import('../../../core/migration-registry')) as {
+				migrationRegistry: MigrationRegistryApi;
+			};
+
+		for (const ns of namespacesToShow) {
+			ui.log(`\nNamespace: ${ns}`);
+			ui.log('─'.repeat(50));
+
+			const dbPath = resolveDatabasePathForNamespace(ns);
+			if (!dbPath) {
+				ui.warn('No known database path for this namespace');
+				continue;
+			}
+
+			const fullPath = resolveFromCwd(dbPath);
+			const exists = existsSync(fullPath);
+
+			ui.log(`Database: ${dbPath}`);
+			ui.log(`Exists: ${exists ? 'yes' : 'no'}`);
+
+			if (!exists) continue;
+
+			try {
+				const db = localdb.getRawDatabase(fullPath, 'localdb-status');
+				const status = migrationRegistry.getDatabaseStatus(db, ns);
+
+				ui.log(`Schema Version: v${status.currentVersion}`);
+				ui.log(`Target Version: v${status.targetVersion}`);
+				ui.log(`Status: ${status.pendingMigrations > 0 ? 'migrations pending' : 'up to date'}`);
+
+				if (verbose && status.migrations.length > 0) {
+					ui.log('\nMigrations:');
+					for (const m of status.migrations) {
+						ui.log(`  ${m.applied ? '✓' : '○'} v${m.version}: ${m.name}`);
+					}
+				}
+			} catch (error) {
+				ui.error(`Error reading migration status: ${String(error)}`);
+			}
+		}
+
+		if (verbose) {
+			ui.log('\n\n=== Connection Pool ===\n');
+			const poolStats = localdb.getPoolStats();
+			ui.log(`Total Connections: ${poolStats.total}`);
+			ui.log(`Active: ${poolStats.active}`);
+			ui.log(`Idle: ${poolStats.idle}`);
+
+			if (poolStats.connections.length > 0) {
+				ui.log('\nConnections:');
+				for (const conn of poolStats.connections) {
+					ui.log(
+						`  • ${conn.path} (refs: ${conn.refCount}, age: ${formatAgeMs(conn.ageMs)}, consumer: ${conn.consumer})`
+					);
+				}
+			}
+		}
+	}
+};

package/src/core/connection-pool.ts

@@ -0,0 +1,240 @@
+/**
+ * SQLite Connection Pool
+ *
+ * Centralized connection management for all SQLite databases in vibes dev.
+ * Ensures only one connection per database file to prevent SQLITE_BUSY errors.
+ *
+ * Features:
+ * - Singleton pattern per database path
+ * - Automatic WAL mode and busy timeout configuration
+ * - Connection reuse across consumers
+ * - Safe cleanup on process exit
+ * - Connection statistics and monitoring
+ */
+
+import { Database } from 'bun:sqlite';
+import { getLogger } from '@vibesdotdev/logging';
+import { toErrorContext } from './error-context';
+
+const logger = getLogger('localdb:pool');
+
+export interface PooledConnection {
+	db: Database;
+	refCount: number;
+	lastUsed: number;
+	createdAt: number;
+	consumer: string; // First consumer that opened this connection
+}
+
+export interface ConnectionStats {
+	total: number;
+	active: number;
+	idle: number;
+	connections: Array<{
+		path: string;
+		refCount: number;
+		ageMs: number;
+		consumer: string;
+	}>;
+}
+
+class SQLiteConnectionPool {
+	private connections = new Map<string, PooledConnection>();
+	private cleanupInterval?: Timer;
+	private readonly STALE_THRESHOLD_MS = 30 * 60 * 1000; // 30 minutes
+	private readonly CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+
+	constructor() {
+		// Periodic cleanup of stale connections
+		this.startCleanup();
+
+		// Ensure proper cleanup on process exit
+		this.registerExitHandlers();
+	}
+
+	/**
+	 * Get or create a database connection with optimal configuration
+	 */
+	getConnection(dbPath: string, consumer = 'unknown'): Database {
+		let pooled = this.connections.get(dbPath);
+
+		if (!pooled) {
+			const db = new Database(dbPath);
+
+			// Configure for optimal concurrent access
+			this.configureDatabase(db);
+
+			pooled = {
+				db,
+				refCount: 0,
+				lastUsed: Date.now(),
+				createdAt: Date.now(),
+				consumer
+			};
+
+			this.connections.set(dbPath, pooled);
+			logger.debug(`Created connection: ${dbPath} (${consumer})`);
+		}
+
+		pooled.refCount++;
+		pooled.lastUsed = Date.now();
+
+		return pooled.db;
+	}
+
+	/**
+	 * Configure database with optimal settings for concurrent access
+	 */
+	private configureDatabase(db: Database): void {
+		// WAL mode: Readers don't block writers, writers don't block readers
+		db.exec('PRAGMA journal_mode = WAL;');
+
+		// Busy timeout: Wait up to 5 seconds for locks instead of failing immediately
+		db.exec('PRAGMA busy_timeout = 5000;');
+
+		// Foreign keys: Enable referential integrity
+		db.exec('PRAGMA foreign_keys = ON;');
+
+		// Synchronous: NORMAL is safe with WAL and much faster
+		db.exec('PRAGMA synchronous = NORMAL;');
+
+		// Temp store: Use memory for temp tables (faster)
+		db.exec('PRAGMA temp_store = MEMORY;');
+	}
+
+	/**
+	 * Release a connection (decrement reference count)
+	 * Connection remains in pool for reuse
+	 */
+	releaseConnection(dbPath: string): void {
+		const pooled = this.connections.get(dbPath);
+		if (pooled) {
+			pooled.refCount = Math.max(0, pooled.refCount - 1);
+			pooled.lastUsed = Date.now();
+		}
+	}
+
+	/**
+	 * Close a specific connection immediately
+	 * Only closes if reference count is zero (unless forced)
+	 */
+	closeConnection(dbPath: string, force = false): boolean {
+		const pooled = this.connections.get(dbPath);
+		if (!pooled) return false;
+
+		if (force || pooled.refCount === 0) {
+			try {
+				pooled.db.close();
+				this.connections.delete(dbPath);
+				// Use stderr to avoid breaking MCP stdio protocol
+				logger.debug(`[LocalDB] Closed connection: ${dbPath}`);
+				return true;
+			} catch (error) {
+				logger.error(`[LocalDB] Error closing ${dbPath}:`, toErrorContext(error));
+				return false;
+			}
+		}
+
+		return false;
+	}
+
+	/**
+	 * Clean up stale connections (unused for 30+ minutes with zero references)
+	 */
+	private cleanupStale(): void {
+		const now = Date.now();
+
+		for (const [dbPath, pooled] of this.connections.entries()) {
+			const age = now - pooled.lastUsed;
+			if (pooled.refCount === 0 && age > this.STALE_THRESHOLD_MS) {
+				this.closeConnection(dbPath, true);
+			}
+		}
+	}
+
+	/**
+	 * Start periodic cleanup
+	 */
+	private startCleanup(): void {
+		this.cleanupInterval = setInterval(() => this.cleanupStale(), this.CLEANUP_INTERVAL_MS);
+	}
+
+	/**
+	 * Stop periodic cleanup
+	 */
+	private stopCleanup(): void {
+		if (this.cleanupInterval) {
+			clearInterval(this.cleanupInterval);
+			this.cleanupInterval = undefined;
+		}
+	}
+
+	/**
+	 * Close all connections (typically on shutdown)
+	 */
+	closeAll(): void {
+		this.stopCleanup();
+
+		for (const [dbPath, pooled] of this.connections.entries()) {
+			try {
+				pooled.db.close();
+				// Use stderr to avoid breaking MCP stdio protocol
+				logger.debug(`[LocalDB] Closed connection on shutdown: ${dbPath}`);
+			} catch (error) {
+				logger.error(`[LocalDB] Error closing ${dbPath}:`, toErrorContext(error));
+			}
+		}
+
+		this.connections.clear();
+	}
+
+	/**
+	 * Get pool statistics
+	 */
+	getStats(): ConnectionStats {
+		let active = 0;
+		let idle = 0;
+		const connections: ConnectionStats['connections'] = [];
+		const now = Date.now();
+
+		for (const [path, pooled] of this.connections.entries()) {
+			if (pooled.refCount > 0) {
+				active++;
+			} else {
+				idle++;
+			}
+
+			connections.push({
+				path,
+				refCount: pooled.refCount,
+				ageMs: now - pooled.createdAt,
+				consumer: pooled.consumer
+			});
+		}
+
+		return {
+			total: this.connections.size,
+			active,
+			idle,
+			connections
+		};
+	}
+
+	/**
+	 * Register process exit handlers for cleanup
+	 */
+	private registerExitHandlers(): void {
+		process.on('beforeExit', () => this.closeAll());
+		process.on('SIGINT', () => {
+			this.closeAll();
+			process.exit(0);
+		});
+		process.on('SIGTERM', () => {
+			this.closeAll();
+			process.exit(0);
+		});
+	}
+}
+
+// Singleton instance
+export const connectionPool = new SQLiteConnectionPool();