Databases

Add managed database instances to your test environment with automatic provisioning and seed scripts.

Required fields

Field	Type	Description
`type`	`"DATABASE"`	Item type
`name`	string	Unique name (1-63 chars). Used as DNS hostname for service connections.
`database`	enum	`"postgres"`, `"mysql"`, `"mongodb"`, or `"redis"`

Optional fields

Field	Type	Default	Description
`description`	string	—	Human-readable description (max 500 chars)
`image`	string	—	Custom Docker image, overriding the engine default (e.g. `"getlago/postgres-partman:15.0-alpine"`). Mutually exclusive with `version`.
`version`	string	per engine	Database image version tag (e.g. `"16"` for postgres:16). Mutually exclusive with `image`. See defaults in engine details below.
`dbName`	string	`dokkimi`	Database/schema name
`dbUser`	string	`dokkimi`	Database username
`dbPassword`	string	`dokkimi`	Database password
`initFilePath`	string	—	Relative path to a single init script
`initFilePaths`	string[]	—	Relative paths to multiple init scripts (executed in order). Use one or the other, not both.
`minCpu`	number	—	Minimum CPU cores
`minMemory`	number	—	Minimum memory in MB
`maxCpu`	number	—	Maximum CPU cores
`maxMemory`	number	—	Maximum memory in MB
`stage`	integer	`0`	Deployment stage — controls bootup order

Engine details

Engine	Default version	Default image	Port	Default connection string
`postgres`	`15`	postgres:15	5432	`postgresql://dokkimi:dokkimi@{name}:5432/dokkimi`
`mysql`	`8`	mysql:8	3306	`mysql://dokkimi:dokkimi@{name}:3306/dokkimi`
`mongodb`	`7`	mongo:7	27017	`mongodb://dokkimi:dokkimi@{name}:27017/dokkimi?authSource=admin`
`redis`	`7`	redis:7-alpine	6379	`redis://:dokkimi@{name}:6379`

Use the version field to pin a specific database version (e.g. "version": "16" produces postgres:16). The version string is used verbatim as the image tag — for Redis, that means "version": "7" produces redis:7 (Debian-based); use "7-alpine" for the smaller Alpine variant.

Use the image field when you need a custom or extended database image (e.g. Postgres with pg_partman). When image is set, Dokkimi uses it directly instead of constructing the image from the engine and version:

{
  "type": "DATABASE",
  "name": "lago-postgres",
  "database": "postgres",
  "image": "getlago/postgres-partman:15.0-alpine",
  "initFilePath": "../init-files/schema.sql"
}

Examples

PostgreSQL

{
  "type": "DATABASE",
  "name": "postgres-db",
  "database": "postgres",
  "dbName": "myapp",
  "dbUser": "appuser",
  "dbPassword": "secret",
  "initFilePath": "../init-files/schema.sql"
}

MySQL

{
  "type": "DATABASE",
  "name": "mysql-db",
  "database": "mysql",
  "initFilePaths": ["../init-files/schema.sql", "../init-files/seed.sql"]
}

MongoDB

{
  "type": "DATABASE",
  "name": "mongo-db",
  "database": "mongodb",
  "initFilePath": "../init-files/init.js"
}

Redis

{
  "type": "DATABASE",
  "name": "redis-cache",
  "database": "redis"
}

Connection strings

Use the database item's name as the hostname. The connection string format varies by engine. With the defaults (dbUser: dokkimi, dbPassword: dokkimi, dbName: dokkimi):

PostgreSQL

postgresql://dokkimi:dokkimi@postgres-db:5432/dokkimi

MySQL

mysql://dokkimi:dokkimi@mysql-db:3306/dokkimi

MongoDB

mongodb://dokkimi:dokkimi@mongo-db:27017/dokkimi?authSource=admin

MongoDB requires ?authSource=admin. Dokkimi creates MongoDB users as root users that authenticate against the admin database. Without this parameter, authentication will fail.

Redis

redis://:dokkimi@redis-cache:6379

Note the ://:password@ format — Redis has no username, just a password.

If you customize dbUser, dbPassword, or dbName, substitute those values in the connection string accordingly.

Init script readiness

For MongoDB, Dokkimi guarantees that all init scripts have fully executed before tests begin. It injects a small sentinel script that runs after your init files, and the database is only marked as ready once the sentinel is confirmed. This eliminates flaky failures caused by tests starting before seeded data is available.

Reserved database name: The dokkimi_internal database is reserved for Dokkimi's internal readiness checks. Do not use this name in your init scripts or application code.

Query interception and logging

Every DATABASE item is paired with a DB proxy sidecar — a transparent proxy that intercepts all database queries at the wire protocol level. This means every SQL query, MongoDB operation, or Redis command your services execute is captured and logged automatically, without any changes to your application code.

You can inspect all captured queries after a run with dokkimi inspect, which shows every query alongside the HTTP traffic and console logs. This gives you full visibility into what your services actually did to the database during the test — not just what the API returned.

This is particularly valuable for debugging: when a test fails, you can see the exact queries that ran, in order, and trace the issue to a specific database interaction rather than guessing from HTTP responses alone.

DATABASE vs SERVICE. Infrastructure that needs query-level interception and logging should use the DATABASE item type. If you need a data store that Dokkimi doesn't support natively (like Elasticsearch or DynamoDB), you can run it as a SERVICE — it works the same way, you just won't get automatic query logging.

Connecting services to databases

Pass the connection string to your service via environment variables:

{
  "type": "SERVICE",
  "name": "my-service",
  "port": 3000,
  "healthCheck": "/health",
  "env": [
    { "name": "DATABASE_URL", "value": "postgresql://dokkimi:dokkimi@postgres-db:5432/dokkimi" },
    { "name": "REDIS_URL", "value": "redis://:dokkimi@redis-cache:6379" },
    { "name": "MONGO_URL", "value": "mongodb://dokkimi:dokkimi@mongo-db:27017/dokkimi?authSource=admin" }
  ]
}

← Services Mocks →