# .reylo.yaml

> "The keys of Reylo's project file: the database Reylo reads your schema from, the .env files it reads, and the checks you can loosen."

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`:

```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:

**Postgres**, `.env`:

```sh
# or postgresql://
DATABASE_URL=postgres://localhost:5432/app
```

**MySQL**, `.env`:

```sh
# or mariadb://
DATABASE_URL=mysql://root@localhost:3306/app
```

**SQLite**, `.env`:

```sh
# 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`:

```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`:

```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`:

```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:

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

### TLS

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

`.env`:

```sh
# 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`:

```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`:

```sh
# 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](https://reylo.dev/inference#a-parameter-nothing-types) may stay `unknown`.

By default it's an error that says to [cast it](https://reylo.dev/inference#casts).

`.reylo.yaml`:

```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`:

```yaml
# the default is false
allow_nested_arrays: true
```

## `sqlcommenter`

Each query Reylo sends ends with a comment that names its file, in [sqlcommenter](https://google.github.io/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`](https://reylo.dev/typescript#sql) leaves it out. Set `sqlcommenter: false` to leave it off what Reylo sends too.

`.reylo.yaml`:

```yaml
# the default is true
sqlcommenter: false
```

**What Postgres receives for queries/get_user.sql, by default**:

```sql
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](https://reylo.dev/migrate/docs), which you commit, and its cache in `.cache/`, which keeps itself out of git.

`.reylo.yaml`:

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

## `shadow_url`

The server where [migrations](https://reylo.dev/migrate/docs) build their shadow databases, for a database whose own server refuses `create database`:

`.reylo.yaml`:

```yaml
# the default is the database's own server
shadow_url: ${SHADOW_URL}
```
