Database Adapters Structure
Relevant source files
The following files were used as context for generating this wiki page:
The Database Adapters in KamehaDB serve as a bridge between the Node.js sidecar API and various supported database engines, including PostgreSQL, MySQL, SQLite, MongoDB, Redis, and Qdrant. They provide a unified interface for metadata extraction, query execution, and data previewing, ensuring that the desktop application can interact with different database types through a consistent set of API contracts.
These adapters are primarily located within the apps/sidecar/src/adapters/ directory and implement contracts defined in the @kamehadb/shared package. This architecture enables local-first database management where credentials and query execution remain entirely on the user's machine.
Sources: AGENTS.md:12-14, PLAN.md:209-223, packages/shared/src/index.ts:117-133
Adapter Architecture and Interface Design
The architecture relies on TypeScript interfaces (contracts) that define the required capabilities for each database type. The system distinguishes between relational SQL engines, NoSQL document stores (MongoDB), and key-value stores (Redis).
Core Interface Contracts
| Interface | Purpose | Target Databases |
|---|---|---|
SqlAdapter | Standard SQL operations, metadata, and schema browsing. | PostgreSQL, MySQL, SQLite |
MongoAdapter | Document-based operations, aggregation, and collection stats. | MongoDB |
RedisAdapter | Key scanning, TTL lookups, and command execution. | Redis |
QdrantAdapter | Vector search, point management, and collection stats. | Qdrant |
Sources: packages/shared/src/index.ts:117, packages/shared/src/index.ts:187, packages/shared/src/index.ts:228, packages/shared/src/index.ts:316
Data Flow Overview
The following diagram illustrates the lifecycle of a database request from the UI through the adapter layer.
The sidecar serves as an intermediary that normalizes raw driver outputs into standard TypeScript types like QueryResult or TableInfo.
Sources: PLAN.md:162-171, AGENTS.md:123-131
Implementation of SQL Adapters
SQL adapters for PostgreSQL and MySQL implement the SqlAdapter interface. They use connection pooling to manage resources and perform direct queries against system catalogs (like information_schema) to retrieve metadata.
PostgreSQL Adapter
The PostgreSQL adapter utilizes the pg driver. It includes advanced functionality for retrieving database statistics, such as index usage, bloat percentages, and active backend connections.
- Key Functions:
createPostgresAdapter,getTableStats,getIndexStats,getActiveConnections. - Metadata Source:
information_schema.tables,information_schema.columns,pg_stat_user_tables,pg_stat_activity.
Sources: apps/sidecar/src/adapters/postgres.ts:108, apps/sidecar/src/adapters/postgres.ts:402, apps/sidecar/src/adapters/postgres.ts:446
MySQL Adapter
The MySQL adapter uses mysql2/promise. It implements similar schema-browsing logic but adapted for MySQL's specific syntax (e.g., using backticks for escaping and INFORMATION_SCHEMA.STATISTICS for indexes).
- Key Functions:
createMysqlAdapter,listTables,getTableColumns. - Metadata Source:
INFORMATION_SCHEMA.COLUMNS,INFORMATION_SCHEMA.SCHEMATA.
Sources: apps/sidecar/src/adapters/mysql.ts:45, apps/sidecar/src/adapters/mysql.ts:88, apps/sidecar/src/adapters/mysql.ts:101
MongoDB Adapter Structure
The MongoAdapter deviates from the SQL contract to support document-oriented operations. It handles BSON serialization, aggregation pipelines, and collection-level statistics.
The MongoDB implementation includes a serializeDocument helper to convert BSON types like ObjectId and Date into strings/ISODates for JSON compatibility.
Sources: apps/sidecar/src/adapters/mongodb.ts:15-28, packages/shared/src/index.ts:228-245
Query Safety and Execution
A critical component shared by SQL adapters is the isQuerySafe utility. This provides a guardrail when connections are marked as readonly.
Destructive Keyword Filtering
Adapters check queries against a list of destructive keywords to prevent accidental data loss in read-only mode.
| Category | Keywords |
|---|---|
| Safe | SELECT, WITH, SHOW, DESCRIBE, EXPLAIN |
| Destructive | DROP, TRUNCATE, ALTER, CREATE, INSERT, UPDATE, DELETE, MERGE, GRANT, REVOKE |
Sources: packages/shared/src/index.ts:413-433, PLAN.md:417-422
SQL Result Normalization
All SQL adapters return a QueryResult object, which standardizes rows and column metadata across different drivers.
export type QueryResult = {
columns: QueryColumn[];
rows: Record<string, unknown>[];
rowCount: number;
durationMs: number;
truncated: boolean;
};
Sources: packages/shared/src/index.ts:63-69
Summary
The database adapter structure in KamehaDB provides a modular and type-safe way to support multiple database engines. By abstracting driver-specific logic behind clear interfaces like SqlAdapter and MongoAdapter, the project ensures that high-level features—such as the AI SQL generator and schema browser—can function uniformly across PostgreSQL, MySQL, and NoSQL databases. The use of a Node.js sidecar allows these adapters to perform heavy-duty database operations locally, maintaining the project's "local-first" security posture.