---
title: Configuration
description: Configure VibORM with viborm.config.ts for CLI commands like push and migrate
icon: settings
---


## Config File

Create a `viborm.config.ts` file in your project root:

```ts title="viborm.config.ts"
import { defineConfig } from "viborm/config";
import { client } from "./src/db";

export default defineConfig({
  client,
});
```

The client is created in your application code:

```ts title="src/db.ts"
import { createClient } from "viborm/pglite";
import { user, post } from "./schema";

export const client = createClient({ schema: { user, post }, dataDir: "./data" });
```

:::info[File Names]
VibORM automatically discovers config files in this order:
- `viborm.config.ts`
- `viborm.config.mts`
- `viborm.config.js`
- `viborm.config.mjs`

You can also specify a custom path with `--config ./path/to/config.ts`.
:::

## Configuration Options

```ts
interface VibORMConfig {
  /** VibORM client instance (required) */
  client: VibORMClient;

  /** Migration configuration */
  migrations?: {
    /** Estate directory (default: "./migrations") */
    dir?: string;
    /** Exact physical table scope; include junctions and rename destinations. */
    tables?: readonly string[];
    /** Rename, destructive-change and enum-value decisions for CLI planning. */
    resolve?: ResolveCallback;
    /** Estate storage writer. Defaults to filesystem storage at `dir`. */
    storage?: MigrationStorageWriter;
  };
}
```

| Option | Type | Required | Default | Description |
|--------|------|----------|---------|-------------|
| `client` | `VibORMClient` | Yes | - | VibORM client instance |
| `migrations.dir` | `string` | No | `"./migrations"` | Estate directory |
| `migrations.tables` | `readonly string[]` | No | Every table in the namespace | Tables `push` and `migrate` manage, by physical name |
| `migrations.resolve` | `ResolveCallback` | No | None | Decisions for `push` and `migrate generate` |
| `migrations.storage` | `MigrationStorageWriter` | No | Filesystem writer at `dir` | Estate storage writer |

`tables` lists exact physical table names, junction tables included. Without
it, the CLI manages every table in the namespace. A `migrate` estate freezes
the list into its identity, so name both the old and the new table before
publishing a rename. `resolve` receives each possible rename, destructive change
and enum-value removal that `push` or `migrate generate` plans, and a change it
leaves undecided refuses the plan. Without `resolve`, `push` refuses a possible
rename or an enum-value removal, and runs a destructive change only with
`--accept-data-loss`. See
[Managed tables and CLI decisions](/docs/migration/push#managed-tables-and-cli-decisions)
for an example and [Resolving Changes](/docs/migration/push#resolving-changes)
for the callback's methods.

:::info[CLI Override]
`--dir` overrides `migrations.dir`.
:::

## Database Drivers

VibORM ships a driver per database library (`viborm/pg`, `viborm/postgres`, `viborm/sqlite3`, `viborm/pglite`, and more) — see [Drivers](/docs/drivers) for the full list and their options.

## Migration Storage

By default, VibORM uses filesystem storage for migration files. You can configure the storage driver explicitly:

```ts title="viborm.config.ts"
import { defineConfig } from "viborm/config";
import { createFsStorageWriter } from "viborm/migrations/storage/fs";
import { client } from "./src/db";

export default defineConfig({
  client,
  migrations: {
    storage: createFsStorageWriter("./migrations"),
  },
});
```

:::info[Storage Priority]
If `migrations.storage` is set, the CLI uses it. Otherwise it creates a
filesystem writer at `--dir`, then `migrations.dir`, then `./migrations`.
:::

## Schema Export

Your schema file should export all your models:

```ts title="src/schema.ts"
import { s } from "viborm";

// Define enums with explicit names for reuse
export const Status = s.enum(["PENDING", "ACTIVE", "INACTIVE"]).name("status");

// Define models
export const user = s.model({
  id: s.string().id(),
  name: s.string(),
  email: s.string().unique(),
  status: Status.default("PENDING"),
  posts: s.toMany(() => post),
});

export const post = s.model({
  id: s.string().id(),
  title: s.string(),
  content: s.string().nullable(),
  authorId: s.string(),
  author: s.toOne(() => user).fields("authorId").references("id"),
});
```

Then import it when creating your client:

```ts title="src/db.ts"
import { createClient } from "viborm/pg";
import { user, post } from "./schema";

export const client = createClient({
  schema: { user, post },
  databaseUrl: process.env.DATABASE_URL,
});
```

:::info[Model-only schema]
`createClient` takes an object containing only model definitions. When a module
also exports enums or utilities, import its models explicitly. The CLI's schema
loader filters module exports; client construction reports a named schema error
for non-model entries.
:::

## Environment Variables

Keep sensitive configuration in the environment. The `src/db.ts` above already
reads its connection string from `process.env.DATABASE_URL`:

```bash title=".env"
DATABASE_URL=postgresql://user:password@localhost:5432/mydb
```

If a URL isn't enough, every driver also accepts an `options` object with library-specific settings (host, port, ssl, pool size, ...) — see [Drivers](/docs/drivers).

Each driver's `createClient` refuses a key it does not read with a
`ClientInitializationError` that names the key. For example `viborm/sqlite3`
takes its database file as `dataDir`, so `databaseUrl` there is refused instead
of silently opening an in-memory database.

## Running the CLI

The CLI automatically loads your config file:

```bash
# Using the installed CLI on Node.js
pnpm exec viborm push

# Using npm
npx viborm push

# With custom config path
pnpm exec viborm push --config ./config/viborm.config.ts
```

## Multiple Environments

For different environments, you can use environment variables or multiple config files:

**Environment Variables**

```ts title="src/db.ts"
import { createClient } from "viborm/pg";
import { user, post } from "./schema";

const isProduction = process.env.NODE_ENV === "production";

export const client = createClient({
  schema: { user, post },
  databaseUrl: isProduction
    ? process.env.DATABASE_URL
    : "postgresql://localhost:5432/mydb_dev",
});
```

```ts title="viborm.config.ts"
import { defineConfig } from "viborm/config";
import { client } from "./src/db";

export default defineConfig({
  client,
  migrations: { dir: "./migrations" },
});
```

**Multiple Configs**

```ts title="src/db.dev.ts"
import { createClient } from "viborm/pglite";
import { user, post } from "./schema";

export const client = createClient({ schema: { user, post }, dataDir: "./data" });
```

```ts title="src/db.prod.ts"
import { createClient } from "viborm/pg";
import { user, post } from "./schema";

export const client = createClient({
  schema: { user, post },
  databaseUrl: process.env.DATABASE_URL,
});
```

```ts title="viborm.config.dev.ts"
import { defineConfig } from "viborm/config";
import { client } from "./src/db.dev";

export default defineConfig({ client });
```

```ts title="viborm.config.prod.ts"
import { defineConfig } from "viborm/config";
import { client } from "./src/db.prod";

export default defineConfig({ client });
```

```bash
# Development
pnpm exec viborm push --config viborm.config.dev.ts

# Production
pnpm exec viborm push --config viborm.config.prod.ts
```

## Next Steps

**[Push](/docs/migration/push)**

Sync your schema directly to the database

**[Migrate](/docs/migration/migrate)**

Generate and apply migration files

**[Schema](/docs/schema)**

Learn how to define your schema


## Prevalidated schemas

`createClient({ schema, driver, skipSchemaValidation: true })` is for a schema
validated by `viborm check` in the same build or CI revision. It skips repeat
schema-definition checks; it does not disable operation input validation,
provider result parsing, or relation resolution. Do not enable it for a schema
that is assembled dynamically from unchecked input. The default is `false`.

## Batched `findUnique`

`createClient({ schema, driver, findUniqueBatching: true })` answers the
`findUnique` calls issued in the same tick with one read over their keys, the
GraphQL N+1 case. The default is `false`: the merged read runs in the first
call's async context, so leave it off where a driver or a trace reads the
caller's `AsyncLocalStorage` and one client serves several requests. See
[Batching concurrent calls](/docs/client/find-unique#batching-concurrent-calls).

See the [CLI reference](/docs/cli) for non-interactive and JSON output options.
