Shared Contracts & Types
Relevant source files
The following files were used as context for generating this wiki page:
The packages/shared module serves as the single source of truth for data structures, validation schemas, and interface contracts across the KamehaDB ecosystem. It ensures that the desktop frontend and the Node sidecar backend maintain a consistent understanding of connection profiles, database metadata, and application state.
By centralizing these definitions, KamehaDB prevents data shape drift and enforces strict validation via Zod, which is utilized for both runtime checks and TypeScript type inference.
Sources: AGENTS.md:121-127, PLAN.md:112-117
Data Flow and Architecture
The shared contracts define the boundaries between the React-based desktop application and the Hono-based sidecar. When the desktop app makes a request, it uses schemas from the shared package to validate inputs, and the sidecar uses the same schemas to process and respond to data.
This diagram illustrates how the shared package governs the interaction between the two primary application components.
Sources: AGENTS.md:130-136, PLAN.md:135-143
Connection Profiles
Connection profiles are the primary data structure for managing database credentials and settings. They support multiple database engines and include validation logic to ensure required fields (like passwords for PostgreSQL or connection strings for MongoDB) are present.
Supported Database Engines
KamehaDB supports a variety of SQL and NoSQL engines, categorized by the DbKind type.
| Engine | DbKind Value | Support Level |
|---|---|---|
| PostgreSQL | postgres | Full (Stats, Schema, AI) |
| MySQL | mysql | Full (Schema, AI) |
| SQLite | sqlite | Full (Local file-based) |
| MongoDB | mongodb | Dedicated Adapter |
| Redis | redis | Dedicated Adapter |
| Qdrant | qdrant | Vector Search Adapter |
Sources: packages/shared/src/index.ts:6, README.md:10-18, CHANGELOG.md:17-25
Validation Schema
The ConnectionProfileSchema ensures that metadata like createdAt, updatedAt, and readonly status are consistently tracked.
export const ConnectionProfileSchema = z.object({
id: z.string(),
name: z.string().min(1),
kind: z.enum(['postgres', 'sqlite', 'mysql', 'redis', 'mongodb', 'qdrant']),
host: z.string().optional(),
port: z.number().int().positive().optional(),
database: z.string().optional(),
username: z.string().optional(),
ssl: z.boolean().optional(),
filePath: z.string().optional(),
readonly: z.boolean().optional().default(true),
color: z.string().optional(),
createdAt: z.string(),
updatedAt: z.string(),
});
Sources: packages/shared/src/index.ts:9-24
Database Adapter Contracts
KamehaDB uses a set of TypeScript interfaces to normalize how different database engines interact with the system. These adapters handle metadata retrieval, query execution, and engine-specific statistics.
SqlAdapter Interface
The SqlAdapter is the primary contract for relational databases (PostgreSQL, MySQL, SQLite).
| Method | Return Type | Description |
|---|---|---|
testConnection() | Promise<TestConnectionResult> | Validates connectivity |
listTables(schema?) | Promise<TableInfo[]> | Retrieves tables in a schema |
previewRows(input) | Promise<QueryResult> | Fetches a paginated row sample |
runQuery(input) | Promise<QueryResult> | Executes arbitrary SQL |
searchSchema(input) | Promise<SchemaSearchMatch[]> | Server-side fuzzy search |
Sources: packages/shared/src/index.ts:133-149, CHANGELOG.md:46-47
Adapter Relationship Hierarchy
Each engine type has a dedicated interface to account for its unique operational requirements, such as Redis key scanning or MongoDB aggregation pipelines.
Sources: packages/shared/src/index.ts:133-289
Application State Management
The shared types define how the workspace is structured, including the various tab types available to the user.
Workspace Tabs
The WorkspaceTab type is a discriminated union that allows the UI to render the correct view based on the tab's type property.
table: Standard SQL table browsing.query: Monaco-based SQL editor.mongo/mongo-query: MongoDB collection browsing and aggregation.qdrant/qdrant-search: Vector database exploration.graph: Schema visualization via ER diagrams.
Sources: packages/shared/src/index.ts:365-408, PLAN.md:196-205
SQL Safety Guard
The shared module includes a isQuerySafe utility and associated constants to prevent destructive operations when a connection is in read-only mode.
export const DESTRUCTIVE_KEYWORDS = [
'DROP', 'TRUNCATE', 'ALTER', 'CREATE',
'INSERT', 'UPDATE', 'DELETE', 'MERGE',
'GRANT', 'REVOKE',
];
export const SAFE_KEYWORDS = ['SELECT', 'WITH', 'SHOW', 'DESCRIBE', 'EXPLAIN'];
This utility uses regular expressions to scan normalized SQL strings for keywords that are prohibited in read-only environments.
Sources: packages/shared/src/index.ts:430-466
Conclusion
The shared contracts in KamehaDB provide a robust foundation for the application's local-first architecture. By enforcing strict schemas and consistent interfaces, the project ensures that both SQL and NoSQL databases can be managed through a unified, type-safe interface while maintaining security through built-in query safety checks.
Sources: README.md:5-9, AGENTS.md:121-127