Running databases in Docker

Every engine prorm supports can be run locally in a container, which is how the
integration tests get their databases. Each guide starts the engine, waits for
it correctly (readiness is where most flaky setups go wrong), connects prorm
to it, and tears it down.

The short path

The repository ships a compose file covering the SQL engines the test suite
uses:

$ npm run test:db:up            # postgres, mysql, mariadb, mssql, oracle, cockroachdb, clickhouse
$ npm run test:integration
$ npm run test:db:down

Oracle's image is large and slow (1-2 minutes even with a healthcheck). Skip it
with npm run test:db:up:no-oracle.

--wait in those scripts blocks until every service reports healthy, which is
what makes them usable in CI.

SQL engines

These are SQL dialects: models, migrations and the query builder all work.

PostgreSQL — PostgreSQL 16 on port 5432; pg_isready readiness, extensions, TLS for managed hosts.

MySQL — MySQL 8.0 on 3306; the auth-plugin flag and strict mode.

MariaDB — MariaDB 11 on 3307, so it runs beside MySQL; system-versioned tables.

CockroachDB — single node on 26257 (SQL) and 8080 (UI); retryable transactions.

ClickHouse — HTTP on 8123; what an analytical store does differently.

NoSQL stores

MongoDB — port 27017; a one-node replica set for transactions and change streams.

Redis — port 6379; persistence, and Redis as a model cache.

Cassandra — port 9042; a slow-starting JVM, heap caps and CQL's rules.

Elasticsearch — port 9200; heap size, security, refresh.

Neo4j — Bolt on 7687, browser on 7474; the password rule.

These use the NoSqlStore interface rather than a SQL Dialect — no models,
no DDL. See the store index.

Runtimes

Bun — the built-in bun:sqlite, no native build; networked engines on a shared network.

Deno — npm compatibility and explicit permissions.

Two things that cause most of the trouble

Do not sleep — poll. Every engine opens its port before it can serve
queries, so sleep 5 && connect fails intermittently and passes just often
enough to look fine. Each guide gives the right readiness check.

With Compose, a healthcheck plus docker compose up --wait (or depends_on: condition: service_healthy) runs the loop for you; every guide includes a docker-compose.yml with one.

127.0.0.1 inside a container is that container. When your application
also runs in Docker, put both on a shared network and address the database by
its container name. The Bun guide shows
the pattern.

Dialects — per-engine SQL behaviour

Stores — the NoSQL adapters

Connection pooling

Running databases in Docker

The short path#

SQL engines#

NoSQL stores#

Runtimes#

Two things that cause most of the trouble#

Related reading#

The short path

SQL engines

NoSQL stores

Runtimes

Two things that cause most of the trouble

Related reading