Database setup · Kanesh

By the end of this guide, you will know which database to use and how to configure Kanesh to connect to it. Collections are stored as real SQL tables.

Before you start

For the manual Docker examples, build the local image in Getting started.
For PostgreSQL or MySQL, have a database address and credentials available to use in DATABASE_URL.
Choose one setup path below: the install script or manual configuration.

1. Choose a database

Database	Support	Good for
SQLite	Default, full	One machine, small teams, demos
PostgreSQL	Full	External PostgreSQL deployments
MySQL	Full	Existing MySQL servers

2. Configure your chosen database

Option A: install script

The script asks which database to use, or takes a flag:

Note: YOUR_KANESH_SITE is a placeholder, not a download host. No published image is available yet; use the manual source-built image below for the current preview.

curl -fsSL https://YOUR_KANESH_SITE/install.sh | sh -s -- --db postgres

Flag	Result
`--db sqlite`	One container, data in the `kanesh-data` volume
`--db postgres`	Adds a `postgres:17-alpine` service with a generated password
`--db mysql`	Adds a `mysql:8.4` service with a generated password
`--port 9000`	Publishes Kanesh on another local port
`--mcp`	Turns on the MCP endpoint

The script writes docker-compose.yml and a private .env in ./kanesh, and never overwrites an existing .env. The published image arrives with the first release; until then, build it from source as in Getting started.

Option B: manual configuration

SQLite

Nothing to configure. The file lives at DATA_DIR/kanesh.db, or set SQLITE_PATH.

docker run -p 127.0.0.1:8080:8080 -v kanesh-data:/data kanesh

PostgreSQL

docker run -p 127.0.0.1:8080:8080 -v kanesh-data:/data \
  -e DATABASE_DRIVER=postgres \
  -e DATABASE_URL="postgres://kanesh:secret@db.internal:5432/kanesh?sslmode=require" \
  kanesh

MySQL

Note: MySQL uses a go-sql-driver DSN, not a mysql:// URL. Replace the example database address and credentials with your own in either external-database command.

docker run -p 127.0.0.1:8080:8080 -v kanesh-data:/data \
  -e DATABASE_DRIVER=mysql \
  -e DATABASE_URL="kanesh:secret@tcp(db.internal:3306)/kanesh" \
  kanesh

3. Complete installation setup

Open http://127.0.0.1:8080 and claim a new installation as described in Getting started. If the database you choose cannot be reached, Kanesh stops with an error instead of silently falling back to SQLite.

Troubleshooting

Kanesh stops after selecting an external database: check the selected driver, connection address and credentials. An external database failure does not trigger a SQLite fallback.
A MySQL connection string is rejected: use the go-sql-driver DSN shown above, rather than a mysql:// URL.