Skip to content
VibORM
Esc
↑↓navigate↵open⌘Jpreview
On this page

Configuration

Configure VibORM with viborm.config.ts for CLI commands like push and migrate

Config File

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

import { defineConfig } from "viborm/config";
import { client } from "./src/db";

export default defineConfig({
  client,
});

The client is created in your application code:

import { createClient } from "viborm/pglite";
import { user, post } from "./schema";

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

Configuration Options

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 for an example and Resolving Changes for the callback’s methods.

Database Drivers

VibORM ships a driver per database library (viborm/pg, viborm/postgres, viborm/sqlite3, viborm/pglite, and more) — see 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:

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"),
  },
});

Schema Export

Your schema file should export all your models:

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:

import { createClient } from "viborm/pg";
import { user, post } from "./schema";

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

Environment Variables

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

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.

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:

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

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",
});
import { defineConfig } from "viborm/config";
import { client } from "./src/db";

export default defineConfig({
  client,
  migrations: { dir: "./migrations" },
});
import { createClient } from "viborm/pglite";
import { user, post } from "./schema";

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

export const client = createClient({
  schema: { user, post },
  databaseUrl: process.env.DATABASE_URL,
});
import { defineConfig } from "viborm/config";
import { client } from "./src/db.dev";

export default defineConfig({ client });
import { defineConfig } from "viborm/config";
import { client } from "./src/db.prod";

export default defineConfig({ client });
# Development
pnpm exec viborm push --config viborm.config.dev.ts

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

Next Steps

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.

See the CLI reference for non-interactive and JSON output options.

Was this page helpful?