Service drivers

The driver set is closed. A declaration naming a driver outside it is refused with unknown_service_driver, listing the drivers Onebox can run and directing you to a daemon workload.

That is deliberate: inventing an image from a name produces a container that starts and stores nothing durable.

The runtime and connection tables are generated from the private driver catalogue. The guidance and limitations below remain deliberately authored in the generator: they are product explanations, not facts the catalogue can prove.

Runtime catalogue

Driver	Image repository	Port	Data path	URL scheme	Health check
clickhouse	clickhouse/clickhouse-server	8123	/var/lib/clickhouse	http	available
mariadb	mariadb	3306	/var/lib/mysql	mysql	available
meilisearch	getmeili/meilisearch	7700	/meili_data	http	available
minio	minio/minio	9000	/data	s3	available
mongodb	mongo	27017	/data/db	mongodb	available
mysql	mysql	3306	/var/lib/mysql	mysql	available
nats	nats	4222	/data	nats	none
postgres	postgres	5432	/var/lib/postgresql/data	postgres	available
rabbitmq	rabbitmq	5672	/var/lib/rabbitmq	amqp	available
redis	redis	6379	/data	redis	available
valkey	valkey/valkey	6379	/data	redis	available

Connection contract

Driver	Typical use	Connection parts
clickhouse	Analytical database	url host port user password database
mariadb	Relational database	url host port user password database
meilisearch	Search	url host port password
minio	S3-compatible object storage	url host port user password
mongodb	Document database	url host port user password database
mysql	Relational database	url host port user password database
nats	Messaging, JetStream	url host port password
postgres	Relational database	url host port user password database
rabbitmq	Message broker	url host port user password
redis	Cache, queue	url host port user password
valkey	Cache, queue	url host port user password

A part the driver does not have — a database on a cache — is omitted rather than written empty. Every driver has a password part; redis and valkey have a user part because Redis 6+ authenticates the built-in default user, and a URL with an empty username fails AUTH outright.

nats has no health check

Its image carries no shell to run a probe in, so the driver declares none. A needs on it resolves to started rather than healthy, and writing condition: healthy against it is refused at load time rather than left to hang on the target. Every other driver has one.

Its server is also started without authentication. The password part is written into the connection file like any other, but nothing on the nats side checks it.

What a declaration gets you

services:
  postgres: 17

The image, a durable volume, a health check (every driver but nats), a credential generated on the target, and the connection details your application reads.

• The service outlives every release. Its own Compose project; no deploy and no rollback stops it or removes its volume.
• The credential is generated on the server, once. Not in your project, the generated runtime, or the digest. Never rotated by a re-apply.
• The version binds into the release digest, so a database upgrade under an untouched application cannot pass unnoticed.

Settings are driver-validated

services:
  postgres:
    version: 17
    settings:
      max_connections: 200

A setting is applied through the mechanism its driver actually reads. One the driver has no way to apply is refused with service_settings_unsupported, rather than silently ignored.

Known limitations

mongodb runs a standalone server, not a replica set

Change streams and multi-document transactions need a replica set. An application using either will connect, authenticate, and then fail — Rocket.Chat reports The $changeStream stage is only supported on replica sets.

Onebox does not configure a replica set, so an application that needs one wants a daemon workload it owns. This is a limitation of the driver rather than of the contract, and it is stated here because the failure appears in the application’s logs rather than in anything Onebox says.

Only postgres is backed up

postgres is the one driver with an executable backup contract: declaring backup on it gives a continuous off-host archive and point-in-time recovery. Every other driver declares policy_qualified: false, so a backup policy on it is refused at ob validate rather than accepted and left to do nothing — and its data lives only on this host until you copy it off yourself.

Onebox also refuses a major version change a driver cannot perform in place, rather than replacing the container and leaving the data intact and unreachable.

For postgres, declaring backup changes this — see Shipped vs proposed.

Anything else

Run it as a daemon workload and you own it: the image, the credential, the volumes, the backup. See Add a database for the comparison.