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)
`version`	string	per engine	Database image version tag (e.g. `"16"` for postgres:16). 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

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.

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.

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 →