zanith

Configuration

All configuration options for createZanith, database adapters, and connection management.

Two configuration paths

Zanith supports two ways to configure the client. The typed configpasses models as TypeScript objects for full type inference. The file configloads schemas from .zn files at runtime.

Typed config (recommended)

Pass your models directly. TypeScript infers all field types automatically —db.user.findMany() returns fully typed results with zero generation.

TStyped config
import { createZanith } from 'zanith';
import { PgAdapter } from 'zanith/adapters/pg';
import { User, Post, Profile } from './schema';
import { Role, PostStatus } from './enums';
 
const db = await createZanith({
  // Models as a record — keys become db.user, db.post, etc.
  models: { User, Post, Profile },
 
  // Enums registered in the schema graph
  enums: [Role, PostStatus],
 
  // Database connection
  adapter: new PgAdapter({
    connectionString: process.env.DATABASE_URL,
  }),
});

File config (.zn schemas)

Load schemas from .zn files. Use a path or glob pattern. Type safety requires the optional type generator for this path.

TSfile config
const db = await createZanith({
  schema: './schema/**/*.zn',    // glob pattern
  adapter: new PgAdapter({
    connectionString: process.env.DATABASE_URL,
  }),
  baseDir: process.cwd(),        // optional: resolve paths relative to this
});

PgAdapter (node-postgres)

The most widely used PostgreSQL driver for Node.js. Install with npm install pg.

TSpg adapter options
import { PgAdapter } from 'zanith/adapters/pg';
 
const adapter = new PgAdapter({
  // Option 1: Connection string (recommended)
  connectionString: 'postgresql://user:password@host:5432/database',
 
  // Option 2: Individual fields
  host: 'localhost',
  port: 5432,
  database: 'myapp',
  user: 'myuser',
  password: 'mypassword',
 
  // Pool configuration (optional)
  pool: {
    max: 20,                    // max concurrent connections (default: 10)
    idleTimeoutMillis: 30000,   // close idle connections after 30s
    connectionTimeoutMillis: 5000, // timeout when acquiring a connection
  },
});

PostgresJsAdapter (postgres.js)

A modern, fast alternative driver. Install with npm install postgres.

TSpostgres.js adapter
import { PostgresJsAdapter } from 'zanith/adapters/postgres';
 
const adapter = new PostgresJsAdapter({
  connectionString: 'postgresql://user:password@host:5432/database',
});

Custom adapter

Implement the DatabaseAdapter interface to use any PostgreSQL driver or connection pooler (like PgBouncer):

TScustom adapter
import type {
  DatabaseAdapter,
  QueryResult,
  TransactionClient,
  CompiledQuery,
} from 'zanith';
 
class MyCustomAdapter implements DatabaseAdapter {
  async connect(): Promise<void> {
    // Initialize your connection pool
  }
 
  async disconnect(): Promise<void> {
    // Close all connections
  }
 
  async execute<T>(query: CompiledQuery): Promise<QueryResult<T>> {
    // Execute { sql: string, params: unknown[] }
    // Return { rows: T[], rowCount: number }
  }
 
  async executeRaw<T>(sql: string, params?: unknown[]): Promise<QueryResult<T>> {
    // Execute raw SQL string
  }
 
  async transaction<T>(fn: (tx: TransactionClient) => Promise<T>): Promise<T> {
    // BEGIN, run fn(tx), COMMIT or ROLLBACK
  }
}

Environment variables

Zanith doesn't read environment variables directly — you pass them through your adapter configuration. A common pattern:

TS
// .env
DATABASE_URL=postgresql://user:pass@localhost:5432/myapp
 
// app.ts
const db = await createZanith({
  models: { User, Post },
  adapter: new PgAdapter({
    connectionString: process.env.DATABASE_URL!,
  }),
});