drizzle-zero

Drizzle-zero supports many-to-many relationships via junction tables. You can configure them using either a Simple or Extended format in your drizzle-zero.config.ts.

Simple Configuration

Use this when you have a standard junction table. The format is [junction_table, target_table].

Extended Configuration

Use this for complex scenarios like self-referential relationships. You must explicitly map the sourceField, destTable, and destField.

Example of Extended Configuration (Self-referential):

export default drizzleZeroConfig(drizzleSchema, {
  tables: {
    user: { id: true, name: true },
    friendship: { requestingId: true, acceptingId: true },
  },
  manyToMany: {
    user: {
      friends: [
        {
          sourceField: ['id'],
          destTable: 'friendship',
          destField: ['requestingId'],
        },
        {
          sourceField: ['acceptingId'],
          destTable: 'user',
          destField: ['id'],
        },
      ],
    },
  },
});

// Simple format example
export default drizzleZeroConfig(drizzleSchema, {
  tables: {
    user: { id: true, name: true },
    usersToGroup: { userId: true, groupId: true },
    group: { id: true, name: true },
  },
  manyToMany: {
    user: {
      groups: ['usersToGroup', 'group'],
    },
  },
});

Use the drizzle-zero generate CLI command to convert your Drizzle ORM schema into a Zero schema.

Requirements:

• You must have an existing Drizzle schema.
• The Drizzle schema must be included in your tsconfig for type resolution to work, otherwise you will encounter a Failed to find type definitions error.
• By default, the CLI looks for a Drizzle Kit config at drizzle.config.ts in the current directory. This must be a single TS file (not a folder/glob).

Common CLI Flags:

• -s, --schema <input-file>: Path to your Drizzle schema file.
• -k, --drizzle-kit-config <input-file>: Path to your drizzle.config.ts file.
• -o, --output <output-file>: Custom path for the generated schema (default is zero-schema.gen.ts).
• -f, --format: Use Prettier to format the generated output.
• -t, --tsconfig <tsconfig-file>: Specify a custom tsconfig file.
• -j, --js-file-extension: Manually override .js extension behavior for imports.
• -c, --config <input-file>: Path to a custom drizzle-zero.config.ts file.

Output Control Flags:

• --skip-types: Skip generating table Row[] type exports.
• --skip-builder: Skip generating the query createBuilder export.
• --skip-declare: Skip generating the module augmentation for default types in Zero.
• --enable-legacy-mutators: Enable legacy CRUD mutators.
• --enable-legacy-queries: Enable legacy CRUD queries.
• --suppress-defaults-warning: Hide warnings for columns using database defaults (.default() or .defaultFn()).

{
  "scripts": {
    "generate": "drizzle-zero generate --format",
    "postinstall": "npm generate"
  }
}

Create a drizzle-zero.config.ts file to selectively include specific tables and columns in your Zero schema. This is useful for the "expand/migrate/contract" pattern.

Important Notes:

• The config file must be included in your tsconfig for type resolution to work.
• All tables/columns must be defined in the config, but you can set them to false to exclude them.
• For column names, use the JavaScript field name (e.g., authorId), not the database column name (e.g., author_id).
• For large schemas, the config file may struggle with types; in those cases, use the default CLI behavior without a config file.

Configuration Options:

• tables: An object mapping table names to their included columns or false to exclude the table.
• casing: Specify a casing style (e.g., "snake_case") to match your Drizzle configuration.

import {drizzleZeroConfig} from 'drizzle-zero';
import * as drizzleSchema from './drizzle-schema';

export default drizzleZeroConfig(drizzleSchema, {
  tables: {
    users: {
      id: true,
      name: true,
      email: true,
    },
    posts: {
      id: true,
      content: true,
      authorId: true,
    },
  },
  // casing: "snake_case",
});

When setting up drizzle-zero, you can automatically locate your Drizzle schema files by pointing to your drizzle-kit configuration file. This allows drizzle-zero to inherit settings like casing directly from your existing Drizzle Kit setup.

drizzle-zero supports two ways to find your schema:

1. Direct Path: Provide a specific path to your Drizzle schema file using drizzleSchemaPath.
2. Drizzle Kit Config: Provide a path to your drizzle-kit.config.ts (or similar) using drizzleKitConfigPath. The utility will then parse the config to find the schema and casing properties.

Important Constraints:

• The schema property in your Drizzle Kit config must be a single string path, not an array. drizzle-zero requires a single file to ensure imports work correctly.
• If you encounter errors loading the config, ensure your package.json includes "type": "module" if you are using ESM.

The columns parameter in createZeroTableBuilder allows you to control which Drizzle columns are exposed to the Zero client and how they are typed.

Configuration Options:

• boolean:
  • true: Includes the column using default mapping.
  • false: Excludes the column from the Zero schema.
• ColumnBuilder: Provides a custom mapping for the column. This is used to override the type, optionality, or provide a custom schema.
• undefined (default): If columns is not provided, all primary keys and columns explicitly marked as true (or columns with server defaults/not-null constraints depending on internal logic) are processed. Note that if columns is an object, any column not explicitly listed as true or a ColumnBuilder will be excluded (unless it is a primary key).

Example: Partial Column Inclusion

const zeroTable = createZeroTableBuilder('users', usersTable, {
  id: true, // Include as is
  email: true, // Include as is
  bio: zeroString().optional(), // Custom mapping
  password_hash: false, // Explicitly exclude
});

export type ColumnsConfig<TTable extends Table> =
  | boolean
  | Partial<{
      readonly [KColumn in ColumnNames<TTable>]:
        | boolean
        | ColumnBuilder<...>;
    }>;

To set up drizzle-zero, use the drizzleZeroConfig function. This function takes your existing Drizzle schema and a configuration object to define which tables are exposed and how complex relationships like many-to-many are handled.

Common configuration keys include:

• tables: An object mapping table names to boolean values. Setting a table to true enables it for drizzle-zero. Setting allTypes: true can be used to include all types.
• manyToMany: An object used to define custom many-to-many relationship logic for specific tables.
• testSerialPk, testUuidPk, etc.: Boolean flags used for testing various primary key types.

import {drizzleZeroConfig} from 'drizzle-zero';
import * as drizzleSchema from '../db/drizzle/schema';

export const schema = drizzleZeroConfig(drizzleSchema, {
  tables: {
    user: true,
    project: true,
    // ... other tables
  },
  manyToMany: {
    // custom relationship definitions
  },
});

Use createZeroTableBuilder to transform a Drizzle ORM table definition into a Zero schema definition. This function handles mapping Drizzle column types to Zero types, identifying primary keys, and managing column inclusion/exclusion.

Key Features:

• Automatic Type Mapping: Automatically maps Drizzle types (string, number, boolean, json, etc.) to their Zero equivalents.
• Primary Key Detection: Automatically identifies primary keys from the Drizzle table. If no primary key is found, it throws an error.
• Column Filtering: You can specify which columns to include in the Zero schema using the columns configuration.
• Casing Support: Supports camelCase or snake_case for the Zero schema table name via the casing option.
• Server Default Warnings: Warns you if a column uses a database default, as the Zero client cannot use these defaults directly (you should use mutators instead).

Parameters:

• tableName: The name of the table in the Zero schema.
• table: The Drizzle table instance.
• columns (optional): Configuration for column inclusion and custom mapping.
• debug (optional): Enables debug logging.
• casing (optional): 'camelCase' | 'snake_case'.
• suppressDefaultsWarning (optional): If true, hides warnings about database-side default values.

import { createZeroTableBuilder } from 'drizzle-zero';
import { myDrizzleTable } from './schema';

const zeroTable = createZeroTableBuilder(
  'my_table',
  myDrizzleTable,
  {
    // Only include specific columns
    id: true,
    name: true,
    // Customize a column with a ColumnBuilder
    description: zeroString().optional(),
  }
);