How to choose a database engine

SQLite is the default (ADR 0011). It needs no server and works in tests out of the box. Use MySQL (also for MariaDB servers, ADR 0012) or PostgreSQL when you deploy to a shared server.

Pick the engine with the environment, so the same code runs everywhere:

import { databaseFromEnv, defineDatabaseConfig } from '@samveys/database'

export default defineDatabaseConfig({
  default: 'main',
  connections: { main: databaseFromEnv() },
})

# development and tests: nothing to set → SQLite at storage/app.db
DB_CONNECTION=mysql    DATABASE_URL=mysql://app:secret@db:3306/app      # MySQL or MariaDB
DATABASE_URL=postgres://app:secret@db:5432/app                          # the scheme picks PostgreSQL

To use a server engine, install its client library in the app: pnpm add mysql2 or pnpm add pg. An app that only uses SQLite never loads either library.

To check that every engine behaves the same for your app, run your own tests against each engine in CI. The framework's own suites do the same: SVS_REQUIRE_DOCKER=1 pnpm test runs MySQL 8.4, MariaDB 11.4 and PostgreSQL 17 in containers.