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)
`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	Image	Port	Default connection string
`postgres`	postgres:15	5432	`postgresql://dokkimi:dokkimi@{name}:5432/dokkimi`
`mysql`	mysql:8	3306	`mysql://dokkimi:dokkimi@{name}:3306/dokkimi`
`mongodb`	mongo:7	27017	`mongodb://dokkimi:dokkimi@{name}:27017/dokkimi?authSource=admin`
`redis`	redis:7-alpine	6379	`redis://:dokkimi@{name}:6379`

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.

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 →