Getting started / Configuration

Configuration

Loam reads a single loam.config.ts at the project root. Everything below has a sensible default; most projects set three fields.

The config file#

Create the file with loam init, or write it by hand. The defineConfig helper gives you types and validates unknown keys at load time, so a typo fails fast instead of silently using a default.

// loam.config.ts
import { defineConfig } from "loam";

export default defineConfig({
  dialect: "postgres",
  url: process.env.DATABASE_URL,
  migrations: { dir: "./db/migrations", table: "_loam" },
  strict: true,
});

Environment variables are read after the file is evaluated, so process.env is safe to use here. Loam never loads a .env file for you.

Fields#

Field	Type	Default	Notes
dialect	"postgres" \| "sqlite" \| "mysql"	—	Required.
url	string	—	Connection string; required unless a `pool` is passed.
migrations.dir	string	./migrations	Relative to the config file.
migrations.table	string	_loam_migrations	Created on first run.
strict	boolean	false	Refuse to run with drift between schema and database.
timeoutMs	number	30000	Per-statement timeout.

Environments#

Pass a function instead of an object to branch on LOAM_ENV. The function runs once per CLI invocation and its return value is cached for the process. Return the same shape in every branch; Loam diffs environments at loam check time and warns when a key exists in one and not another.

Typical splits: a local SQLite file for tests, a pooled Postgres URL in production, and a read-only replica URL for loam inspect. Keep secrets out of the file itself; reference them through process.env.

Strict mode#

With strict: true, every command first compares the live database with the schema files. Any drift (a column added by hand, a missing index, a differing default) aborts the command with a diff. This is the recommended setting for CI and production; local development usually leaves it off so you can experiment in a database console.

Drift checks take about 40 ms on a 200-table schema and are cached for 60 seconds per connection string.

TypeScript#

The config file is loaded with a lightweight transpiler, so you can import shared modules and use top-level await. Path aliases from tsconfig.json are honoured. If the file throws, the CLI prints the stack with source maps and exits with code 2.

To type the config without the helper, annotate the export as LoamConfig, exported from the package root.