Introduction & Getting Started

Relevant source files

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

• README.md
• PLAN.md
• AGENTS.md
• packages/shared/src/index.ts
• package.json

KamehaDB is a local-first, cross-platform database GUI designed to provide developers with a secure and efficient way to manage various database engines. It features a built-in AI assistant for query generation and explanation, schema browsing, and visual ER diagrams. The application is built using a "sidecar" architecture, where a desktop frontend communicates with a local Node.js server to perform database operations, ensuring that credentials and metadata remain strictly on the user's local machine.

Sources: README.md:1-12, PLAN.md:5-13, AGENTS.md:7-13

System Architecture

KamehaDB utilizes a multi-process architecture consisting of a Tauri-based desktop application and a Node.js sidecar server. This separation ensures that the frontend remains responsive while the sidecar handles heavy database drivers and persistent connections.

The diagram shows the local-first data flow where the UI communicates only with the local sidecar.
Sources: AGENTS.md:20-25, PLAN.md:120-135

Core Components

Component	Responsibility	Technology Stack
Desktop App	User interface, workspace management, and Tauri shell.	Tauri v2, React 19, Vite, Tailwind v4
Sidecar Server	Database adapters, connection pooling, and metadata persistence.	Hono, better-sqlite3, Database Drivers
Shared Package	Source of truth for Zod schemas and TypeScript contracts.	TypeScript, Zod
Metadata Store	Local storage for connection profiles and AI settings.	SQLite (kamehadb.db)

Sources: AGENTS.md:20-27, README.md:112-119, PLAN.md:43-65

Workspace Setup

KamehaDB uses a pnpm workspace to manage its internal packages and applications. The landing page is managed separately via npm.

Project Layout

├── apps/
│   ├── desktop/          # Frontend UI (React + Tauri)
│   └── sidecar/          # Backend Server (Node.js)
├── packages/
│   ├── shared/           # Zod schemas, types, and contracts
│   └── ui/               # Shared UI primitives
├── landing/              # Marketing site (Managed via npm)

Sources: AGENTS.md:20-27, README.md:95-104

Prerequisites

• Node.js: Version 18+ is required.
• pnpm: Used for the main workspace.
• Rust/Cargo: Required for building the Tauri desktop bundle.
• Docker: Optional, used for local development databases.

Sources: README.md:70-75, PLAN.md:104-105, layout.tsx:112

Getting Started

To initialize the development environment and run the application locally, follow these steps:

1. Install Dependencies: Use pnpm at the root to install workspace dependencies.

   pnpm install
   

2. Launch Dev Databases: Start the included Docker Compose stack for testing.

   docker compose up -d
   

3. Run Application: Start both the sidecar and the desktop app concurrently.

   pnpm dev
   

Sources: README.md:40-48, package.json:7-13, AGENTS.md:38-46

Local Connection Defaults

For the docker-compose.yml environment, the following defaults are provided for initial testing:

Engine	Port	Username	Password	Database
PostgreSQL	5432	kameha	kameha	kamehadb
MySQL	3306	kameha	kameha	kamehadb
MariaDB	3307	kameha	kameha	kamehadb
Redis	6379	—	—	—

Sources: README.md:60-67, AGENTS.md:144-150

Connection & Security Model

KamehaDB prioritizes security by keeping all sensitive data local. Connection profiles are validated using Zod schemas defined in the shared package.

Security Implementation

• Sidecar Binding: The sidecar server binds exclusively to 127.0.0.1 to prevent external access.
• Secret Storage: Credentials can be stored securely using OS-native keychains (macOS Keychain, Windows Credential Manager).
• Read-Only Mode: By default, connections are set to readonly: true to prevent accidental data modification.

Sources: PLAN.md:275-285, AGENTS.md:113-118, shared/src/index.ts:25-30

Connection Schema

Connection profiles are defined by the ConnectionProfileSchema.

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

Sources: shared/src/index.ts:13-27

Summary

KamehaDB provides a robust, local-first platform for database management, combining standard GUI features with modern AI capabilities. By strictly separating the frontend from the database drivers via a sidecar and enforcing local-only data persistence, it offers a secure alternative to cloud-based database clients.

Sources: PLAN.md:5-13, README.md:1-12