kandev/docs/db.md

Database Configuration

Kandev supports two database backends: SQLite (default) and PostgreSQL.

See configuration.md for the full backend configuration reference (every YAML key + env var). This page focuses on database-specific settings.

SQLite (default)

SQLite requires no external services and works out of the box.

Environment variables

Variable	Required	Default	Description
KANDEV_HOME_DIR	No	~/.kandev	Kandev root directory - contains data/ (DB), tasks/, worktrees/, repos/, sessions/, and lsp-servers/
KANDEV_DATABASE_DRIVER	No	sqlite	Database driver
KANDEV_DATABASE_PATH	No	$KANDEV_HOME_DIR/data/kandev.db	Path to the SQLite database file (override)

Config file (config.yaml)

homeDir: ""  # empty = resolve from KANDEV_HOME_DIR or ~/.kandev
database:
  driver: sqlite
  path: ""   # empty = $homeDir/data/kandev.db

No additional setup is needed - the database file is created automatically on first run.

PostgreSQL

1. Create the database

CREATE USER kandev WITH PASSWORD 'your-password';
CREATE DATABASE kandev OWNER kandev;

2. Configure Kandev

Environment variables

Variable	Required	Default	Description
KANDEV_DATABASE_DRIVER	Yes	sqlite	Set to postgres
KANDEV_DATABASE_HOST	No	localhost	PostgreSQL host
KANDEV_DATABASE_PORT	No	5432	PostgreSQL port
KANDEV_DATABASE_USER	Yes	kandev	Database user
KANDEV_DATABASE_PASSWORD	Usually	(empty)	Database password - required unless your Postgres allows passwordless auth
KANDEV_DATABASE_DBNAME	Yes	kandev	Database name
KANDEV_DATABASE_SSLMODE	No	disable	SSL mode (disable, require, verify-ca, verify-full)
KANDEV_DATABASE_MAXCONNS	No	25	Maximum open connections
KANDEV_DATABASE_MINCONNS	No	5	Minimum idle connections

Config file (config.yaml)

database:
  driver: postgres
  host: localhost
  port: 5432
  user: kandev
  password: your-password
  dbName: kandev
  sslMode: disable
  maxConns: 25
  minConns: 5

3. Run

KANDEV_DATABASE_DRIVER=postgres \
KANDEV_DATABASE_PASSWORD=your-password \
kandev

Tables are created automatically on first run - no manual migrations needed.