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.tsNext Steps
Push
Sync your schema directly to the database
Migrate
Generate and apply migration files
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.
See the CLI reference for non-interactive and JSON output options.