.reylo.yaml

The keys of Reylo's project file

Configure Reylo in a .reylo.yaml (or .reylo.yml) file beside package.json. Every key is optional:

.reylo.yaml
# the dev database Reylo reads your schema from (the default)
direct_url: ${DATABASE_URL}
# the .env files Reylo reads (the default)
env: [.env.local, .env]
# a parameter whose type cannot be inferred is an error (the default)
allow_untyped_params: false
# a Postgres array column holds one dimension (the default)
allow_nested_arrays: false
# a comment naming each query's file, for your database's monitoring (the default)
sqlcommenter: true
# the directory of Reylo's files: schema.sql, the migrations and its cache (the default)
dir: reylo

The package.json it sits beside is the nearest one at or above the directory Reylo runs in, short of your home directory: one in the home directory itself is passed over, and reylo migrate init starts no project there.

direct_url

The dev database Reylo reads your schema from. It defaults to DATABASE_URL, and its scheme names the dialect:

.env
# or postgresql://
DATABASE_URL=postgres://localhost:5432/app
# or mariadb://
DATABASE_URL=mysql://root@localhost:3306/app
# or sqlite:; the path starts at package.json
DATABASE_URL=file:./app.db

Point it at a direct connection, not a pooler: describing a query through a pooler in transaction mode, such as PgBouncer's, can fail. You can interpolate other variables from your environment to construct a connection string.

.reylo.yaml
# the default is ${DATABASE_URL}
direct_url: postgres://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:5432/app

A variable can fall back, as in a shell, when it is unset or empty:

.reylo.yaml
direct_url: ${BUILD_DATABASE_URL:-${DATABASE_URL}}

To keep a password out of every file, $(…) runs a command, such as a password manager's or a cloud's token command, and puts what it prints in its place. Reylo runs it once per editor session or build, and again when the database refuses the login, as when a token expires.

.reylo.yaml
# or $(aws rds generate-db-auth-token …) for a short-lived token
direct_url: postgres://app:$(op read op://dev/db/password)@db:5432/app

A type check or a build reads this database, so in CI and on your host it needs your migrations applied. The database a query runs on is the client you pass to .run(), so the two can differ.

A script that runs against production is typed on your dev database, so its types hold only where the two schemas agree. To type it on the database it runs on:

DATABASE_URL="$PRODUCTION_URL" node --import reylo/register report.ts

TLS

The type check reads TLS settings from the URL in direct_url:

.env
# postgres: encrypted, no certificate check
DATABASE_URL=postgres://…/app?sslmode=require
# postgres: the certificate and host checked
DATABASE_URL=postgres://…/app?sslmode=verify-full
# mysql: encrypted, no certificate check
DATABASE_URL=mysql://…/app?ssl-mode=REQUIRED
# mysql: the certificate and host checked
DATABASE_URL=mysql://…/app?ssl-mode=VERIFY_IDENTITY
  • With no setting, a Postgres connection is encrypted where the server offers it, and a MySQL connection isn't.
  • Postgres also reads sslrootcert, sslcert, sslkey and channel_binding, as libpq does, and node-postgres's ssl=true.
  • MySQL also reads mysql2's ssl setting, as JSON with rejectUnauthorized, ca, cert and key, and Prisma's sslaccept=strict.
  • A certificate is also checked against the certificates NODE_EXTRA_CA_CERTS names, as Node checks it.

env

The .env files Reylo reads, relative to .reylo.yaml. The first file that sets a variable wins, and the environment wins over every file.

.reylo.yaml
# the default is [.env.local, .env]
env: [.env.development, .env]

Reylo reads them as dotenv does. A # outside quotes starts a comment, so quote a value that holds one:

.env
# or mysql://… or sqlite:./path/to/your.db, etc
DATABASE_URL="postgres://app:pa#ss@localhost:5432/app" # the dev database

allow_untyped_params

Whether a parameter whose type cannot be inferred may stay unknown.

By default it's an error that says to cast it.

.reylo.yaml
# the default is false
allow_untyped_params: true

allow_nested_arrays

Whether a Postgres array column may hold nested arrays.

Postgres doesn't track an array's dimensions, so by default Reylo types an array column with one, and .run() throws on a value of more. With this set, the column is typed at any depth, as NestedArray<T>, and nothing is refused.

.reylo.yaml
# the default is false
allow_nested_arrays: true

sqlcommenter

Each query Reylo sends ends with a comment that names its file, in sqlcommenter's format, so database monitoring that reads it, such as Datadog's and PlanetScale's, groups your queries by file. On SQLite the comment opens the query instead, since SQLite would write it into the name of a last column with no alias. The query's .sql leaves it out. Set sqlcommenter: false to leave it off what Reylo sends too.

.reylo.yaml
# the default is true
sqlcommenter: false
What Postgres receives for queries/get_user.sql, by default
select id, name, email from users where id = $1::int /*file='queries%2Fget_user.sql'*/

dir

The directory beside .reylo.yaml that holds Reylo's files: the schema.sql, migrations/ and reylo.lock of migrations, which you commit, and its cache in .cache/, which keeps itself out of git.

.reylo.yaml
# the default is reylo
dir: db

shadow_url

The server where migrations build their shadow databases, for a database whose own server refuses create database:

.reylo.yaml
# the default is the database's own server
shadow_url: ${SHADOW_URL}
Released under the MIT License. Copyright © 2026 Colin McDonnell.

On this page