Skip to content
Cyoda Documentation
Settings

database configuration

cyoda-go version 0.6.2

config.database

Section titled “config.database”

NAME

Section titled “NAME”

config.database — storage backend selection and per-backend connection settings.

SYNOPSIS

Section titled “SYNOPSIS”

Select the backend with CYODA_STORAGE_BACKEND. Configure the chosen backend via its per-backend variables (CYODA_SQLITE_* or CYODA_POSTGRES_*). The memory backend requires no additional configuration.

OPTIONS

Section titled “OPTIONS”

Backend selection

Section titled “Backend selection”
  • CYODA_STORAGE_BACKEND — storage backend to use: sqlite, postgres, or memory (bare default: memory; cyoda init writes CYODA_STORAGE_BACKEND=sqlite to ~/.config/cyoda/cyoda.env, so the effective default after cyoda init is sqlite)

SQLite backend (CYODA_SQLITE_*)

Section titled “SQLite backend (CYODA_SQLITE_*)”

Used when CYODA_STORAGE_BACKEND=sqlite.

  • CYODA_SQLITE_PATH — path to the SQLite database file (default: ~/.local/share/cyoda/cyoda.db on Linux/macOS XDG; %LocalAppData%\cyoda\cyoda.db on Windows)
  • CYODA_SQLITE_AUTO_MIGRATE — run embedded SQL migrations on startup (default: true)
  • CYODA_SQLITE_BUSY_TIMEOUT — busy timeout for lock contention (default: 5s)
  • CYODA_SQLITE_CACHE_SIZE — SQLite page cache size in KiB (default: 64000)
  • CYODA_SQLITE_SEARCH_SCAN_LIMIT — max rows scanned per search query (default: 100000)

The prefix CYODA_SQLITE_ is used to namespace all SQLite configuration variables.

PostgreSQL backend (CYODA_POSTGRES_*)

Section titled “PostgreSQL backend (CYODA_POSTGRES_*)”

Used when CYODA_STORAGE_BACKEND=postgres.

  • CYODA_POSTGRES_URL — PostgreSQL connection string, e.g. postgres://user:pass@host/db (required when using postgres backend)
  • CYODA_POSTGRES_URL_FILE — file path for CYODA_POSTGRES_URL (takes precedence)
  • CYODA_POSTGRES_MAX_CONNS — maximum pool connections (default: 25)
  • CYODA_POSTGRES_MIN_CONNS — minimum pool connections (default: 5)
  • CYODA_POSTGRES_MAX_CONN_IDLE_TIME — max idle time before closing a connection (default: 5m)
  • CYODA_POSTGRES_AUTO_MIGRATE — run embedded SQL migrations on startup (default: true)

The prefix CYODA_POSTGRES_ is used to namespace all PostgreSQL configuration variables.

Memory backend

Section titled “Memory backend”

Used when CYODA_STORAGE_BACKEND=memory. No additional configuration needed. Data is not persisted across restarts. Suitable for development and testing only.

EXAMPLES

Section titled “EXAMPLES”

SQLite (default after cyoda init):

CYODA_STORAGE_BACKEND=sqlite
CYODA_SQLITE_PATH=/var/data/cyoda.db
CYODA_SQLITE_AUTO_MIGRATE=true

PostgreSQL:

CYODA_STORAGE_BACKEND=postgres
CYODA_POSTGRES_URL=postgres://cyoda:secret@localhost:5432/cyoda
CYODA_POSTGRES_MAX_CONNS=50

In-memory (tests/dev):

CYODA_STORAGE_BACKEND=memory

SEE ALSO

Section titled “SEE ALSO”
  • config
  • run

See also

Section titled “See also”
  • cyoda help config — Environment variables beat default values. The _FILE suffix variant takes precedence over the plain variable when both are set — for example, CYODA_POSTGRES_URL_FILE=/etc/secrets/db-url wins over CYODA_POSTGRES_URL. There are no command-line flags for configuration values; env vars are the sole configuration surface.
  • cyoda help run — cyoda-go is a single-process, multi-tenant REST and gRPC API server. It starts in serving mode when invoked with no subcommand. All configuration is via environment variables with a CYODA_ prefix. The binary, Docker image, and Helm chart run the same binary; only the environment configuration differs across run modes.

Raw formats

Section titled “Raw formats”