Connection & Credential Management

Relevant source files

The following files were used as context for generating this wiki page:

• apps/desktop/src/components/connection-dialog.tsx
• apps/sidecar/src/routes/connections.ts
• packages/shared/src/index.ts
• apps/desktop/src/lib/api.ts
• AGENTS.md
• PLAN.md

The Connection & Credential Management system in KamehaDB is responsible for the lifecycle of database connection profiles, including their creation, validation, secure storage, and health monitoring. It serves as the bridge between the React-based desktop UI and the local Node.js sidecar that executes database operations.

The system is designed as "local-first," where connection metadata is stored in a local SQLite database via the sidecar's metadata-store.ts, and sensitive credentials (passwords) are handled through the OS keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service) to ensure they are never exposed in plain text logs or local metadata files.

Sources: AGENTS.md:52-54, PLAN.md:144-149, PLAN.md:270-275

Architecture and Data Flow

The architecture follows a request-response pattern where the desktop frontend interacts with a local Hono server (sidecar). Connection requests are validated using Zod schemas shared across the monorepo to ensure data integrity.

Connection Profiles

Connection profiles are the primary data structure for managing database access. They support multiple engines, including PostgreSQL, MySQL, SQLite, MongoDB, Redis, and Qdrant. Each profile includes UI-specific metadata like custom colors and names.

Supported Database Engines

Engine	Default Port	Connection Method
PostgreSQL	5432	Host, Port, User, Password, SSL
MySQL	3306	Host, Port, User, Password
SQLite	N/A	Local File Path
Redis	6379	Host, Port, Optional Password
MongoDB	27017	Connection String (URI)
Qdrant	6333	Host, Port

Sources: apps/desktop/src/components/connection-dialog.tsx:57-64, packages/shared/src/index.ts:10-15, README.md:92-98

Data Model

The ConnectionProfile schema defines the structure of a saved connection.

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(),
  connectionString: z.string().optional(),
  createdAt: z.string(),
  updatedAt: z.string(),
});

Sources: packages/shared/src/index.ts:13-28

Validation and Security

The system employs several layers of security to protect database credentials and prevent accidental data destruction.

Read-Only Enforcement

By default, connections are created in readonly mode. This is enforced by a safety guard that blocks destructive SQL keywords like DROP, TRUNCATE, ALTER, DELETE, and UPDATE unless the user explicitly toggles read-only mode off.

Sources: packages/shared/src/index.ts:373-388, PLAN.md:18-20, apps/desktop/src/components/connection-dialog.tsx:327-340

Connection URL Parsing

KamehaDB includes a utility to auto-fill connection fields by parsing standard connection URIs (e.g., postgresql://user:pass@host:5432/db).

API Endpoints

The sidecar exposes a dedicated /connections router to handle profile operations.

Method	Endpoint	Description
GET	/connections	Lists all saved connection profiles.
POST	/connections	Creates a new connection profile.
PATCH	/connections/:id	Updates an existing connection profile.
DELETE	/connections/:id	Removes a connection and its credentials.
POST	/connections/test	Validates credentials without saving the profile.
GET	/connections/:id/health	Checks if an existing connection is still reachable.

Sources: apps/sidecar/src/routes/connections.ts:25-104, apps/desktop/src/lib/api.ts:40-61

Testing Connections

The connection test logic is handled server-side in the sidecar. It utilizes specific adapters for each database kind to verify connectivity and retrieve server version information.

// Example from the sidecar testing logic
connectionsRouter.post('/test', zValidator('json', TestConnectionSchema), async (c) => {
  const input = c.req.valid('json');
  // ... validation ...
  switch (input.kind) {
    case 'postgres':
      result = await testPostgresConnection(input);
      break;
    case 'mysql':
      result = await testMysqlConnection(input);
      break;
    // ... other cases ...
  }
  return c.json(result);
});

Sources: apps/sidecar/src/routes/connections.ts:106-156

Summary

The Connection & Credential Management system provides a secure, local-first foundation for KamehaDB. By utilizing shared Zod schemas, OS-level secret storage, and a robust sidecar API, it ensures that users can safely manage access to multiple database engines while maintaining strict data privacy and security defaults like mandatory read-only mode for new connections.