or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-commands.mdconfiguration.mdindex.mdmysql-api.mdpostgresql-api.mdsinglestore-api.mdsqlite-api.md
tile.json

configuration.mddocs/

Configuration

Drizzle Kit configuration system provides type-safe configuration for all database operations. Configuration can be defined in a drizzle.config.ts file or passed programmatically.

Capabilities

Define Configuration

Helper function to define configuration with full TypeScript type safety and autocompletion.

/**
 * Define Drizzle Kit configuration with type safety
 * @param config - Configuration object
 * @returns The same configuration object (for type inference)
 */
function defineConfig(config: Config): Config;

Usage Example:

import { defineConfig } from 'drizzle-kit';

export default defineConfig({
  dialect: 'postgresql',
  schema: './src/schema.ts',
  out: './drizzle',
  dbCredentials: {
    url: process.env.DATABASE_URL,
  },
});

Configuration with Multiple Schema Files

import { defineConfig } from 'drizzle-kit';

export default defineConfig({
  dialect: 'mysql',
  schema: ['./src/schema/*.ts', './src/auth-schema.ts'],
  out: './migrations',
  dbCredentials: {
    host: 'localhost',
    port: 3306,
    user: 'root',
    password: 'password',
    database: 'mydb',
  },
});

Configuration with Advanced Options

import { defineConfig } from 'drizzle-kit';

export default defineConfig({
  dialect: 'postgresql',
  schema: './src/schema.ts',
  out: './drizzle',
  breakpoints: true,
  verbose: true,
  strict: true,
  casing: 'snake_case',
  tablesFilter: ['users_*', '!temp_*'],
  schemaFilter: ['public', 'custom'],
  extensionsFilters: ['postgis'],
  migrations: {
    table: 'custom_migrations',
    schema: 'drizzle',
    prefix: 'timestamp',
  },
  introspect: {
    casing: 'camel',
  },
  entities: {
    roles: {
      provider: 'supabase',
      include: ['authenticated', 'service_role'],
    },
  },
  dbCredentials: {
    url: process.env.DATABASE_URL,
  },
});

Types

Config

Main configuration type containing all options for Drizzle Kit.

type Config = {
  // Required: Database dialect
  dialect: 'postgresql' | 'mysql' | 'sqlite' | 'turso' | 'singlestore' | 'gel';

  // Schema & Output
  schema?: string | string[];  // Path(s) to schema files (glob patterns supported)
  out?: string;                // Output folder for migrations (default: './drizzle')

  // Migration Behavior
  breakpoints?: boolean;       // Enable SQL statement breakpoints (default: true)

  // Filters
  tablesFilter?: string | string[];      // Table name filters (glob patterns, supports '!' exclusion)
  schemaFilter?: string | string[];      // Schema filters (PostgreSQL only, default: ['public'])
  extensionsFilters?: 'postgis'[];       // Database extension filters

  // Output Behavior
  verbose?: boolean;           // Print all SQL statements (default: false)
  strict?: boolean;            // Always ask for confirmation (default: false)
  casing?: 'camelCase' | 'snake_case';  // Code serialization casing

  // Migrations Configuration
  migrations?: {
    table?: string;            // Custom migrations table name (default: '__drizzle_migrations')
    schema?: string;           // Custom migrations schema (PostgreSQL only, default: 'drizzle')
    prefix?: 'index' | 'timestamp' | 'supabase' | 'unix' | 'none';  // Migration file prefix (default: 'index')
  };

  // Introspection Configuration
  introspect?: {
    casing: 'camel' | 'preserve';  // Column name casing during introspection
  };

  // Entities Configuration (experimental)
  entities?: {
    roles?: boolean | {
      provider?: 'supabase' | 'neon' | string;
      exclude?: string[];
      include?: string[];
    };
  };

  // Database Connection
  dbCredentials?: PostgresCredentials | MysqlCredentials | SqliteCredentials |
                  LibSQLCredentials | SingleStoreCredentials | GelCredentials;
  driver?: 'aws-data-api' | 'd1-http' | 'expo' | 'turso' | 'pglite' | 'durable-sqlite';
};

PostgreSQL Credentials

Connection credentials for PostgreSQL databases.

type PostgresCredentials =
  // Standard connection
  | {
      host: string;
      port?: number;              // Default: 5432
      user?: string;
      password?: string;
      database: string;
      ssl?: boolean | 'require' | 'allow' | 'prefer' | 'verify-full' | ConnectionOptions;
    }
  // Connection URL
  | {
      url: string;
    }
  // AWS RDS Data API
  | {
      driver: 'aws-data-api';
      database: string;
      secretArn: string;          // AWS Secrets Manager ARN
      resourceArn: string;        // RDS cluster ARN
    }
  // PGlite embedded PostgreSQL
  | {
      driver: 'pglite';
      url: string;                // File path or ':memory:'
    };

Usage Examples:

// Standard connection
export default defineConfig({
  dialect: 'postgresql',
  dbCredentials: {
    host: 'localhost',
    port: 5432,
    user: 'postgres',
    password: 'password',
    database: 'mydb',
    ssl: false,
  },
});

// Connection URL
export default defineConfig({
  dialect: 'postgresql',
  dbCredentials: {
    url: 'postgresql://user:password@host:5432/dbname',
  },
});

// AWS RDS Data API
export default defineConfig({
  dialect: 'postgresql',
  dbCredentials: {
    driver: 'aws-data-api',
    database: 'mydb',
    secretArn: 'arn:aws:secretsmanager:region:account:secret:name',
    resourceArn: 'arn:aws:rds:region:account:cluster:name',
  },
});

// PGlite
export default defineConfig({
  dialect: 'postgresql',
  dbCredentials: {
    driver: 'pglite',
    url: './local-db',  // or ':memory:' for in-memory
  },
});

MySQL Credentials

Connection credentials for MySQL databases.

type MysqlCredentials =
  // Standard connection
  | {
      host: string;
      port?: number;              // Default: 3306
      user?: string;
      password?: string;
      database: string;
      ssl?: string | SslOptions;
    }
  // Connection URL
  | {
      url: string;
    };

interface SslOptions {
  pfx?: string;                   // PFX/PKCS12 encoded private key and certificate
  key?: string;                   // Private key in PEM format
  passphrase?: string;            // Passphrase for private key
  cert?: string;                  // Certificate chain in PEM format
  ca?: string | string[];         // CA certificates in PEM format
  crl?: string | string[];        // Certificate revocation lists
  ciphers?: string;               // Cipher suite specification
  rejectUnauthorized?: boolean;   // Verify server certificate (default: true)
}

Usage Examples:

// Standard connection
export default defineConfig({
  dialect: 'mysql',
  dbCredentials: {
    host: 'localhost',
    port: 3306,
    user: 'root',
    password: 'password',
    database: 'mydb',
  },
});

// Connection URL
export default defineConfig({
  dialect: 'mysql',
  dbCredentials: {
    url: 'mysql://user:password@host:3306/dbname',
  },
});

// With SSL
export default defineConfig({
  dialect: 'mysql',
  dbCredentials: {
    host: 'remote-host',
    database: 'mydb',
    ssl: {
      ca: '/path/to/ca-cert.pem',
      rejectUnauthorized: true,
    },
  },
});

SQLite Credentials

Connection credentials for SQLite databases.

type SqliteCredentials =
  // File-based SQLite
  | {
      url: string;                // File path or ':memory:'
    }
  // Cloudflare D1 HTTP API
  | {
      driver: 'd1-http';
      accountId: string;          // Cloudflare account ID
      databaseId: string;         // D1 database ID
      token: string;              // API token
    };

Usage Examples:

// File-based SQLite
export default defineConfig({
  dialect: 'sqlite',
  dbCredentials: {
    url: './local.db',  // or ':memory:' for in-memory
  },
});

// Cloudflare D1
export default defineConfig({
  dialect: 'sqlite',
  driver: 'd1-http',
  dbCredentials: {
    driver: 'd1-http',
    accountId: 'your-account-id',
    databaseId: 'your-database-id',
    token: process.env.CLOUDFLARE_API_TOKEN,
  },
});

LibSQL/Turso Credentials

Connection credentials for Turso (LibSQL) databases.

type LibSQLCredentials = {
  url: string;                    // Turso database URL
  authToken?: string;             // Authentication token
};

Usage Example:

export default defineConfig({
  dialect: 'turso',
  dbCredentials: {
    url: 'libsql://your-db.turso.io',
    authToken: process.env.TURSO_AUTH_TOKEN,
  },
});

SingleStore Credentials

Connection credentials for SingleStore databases.

type SingleStoreCredentials =
  // Standard connection
  | {
      host: string;
      port?: number;
      user?: string;
      password?: string;
      database: string;
      ssl?: string | SslOptions;
    }
  // Connection URL
  | {
      url: string;
    };

Usage Example:

export default defineConfig({
  dialect: 'singlestore',
  dbCredentials: {
    host: 'localhost',
    port: 3306,
    user: 'root',
    password: 'password',
    database: 'mydb',
  },
});

Gel Credentials

Connection credentials for Gel databases.

type GelCredentials =
  // Standard connection
  | {
      host: string;
      port?: number;
      user?: string;
      password?: string;
      database: string;
      tlsSecurity?: 'insecure' | 'no_host_verification' | 'strict' | 'default';
    }
  // Connection URL
  | {
      url: string;
      tlsSecurity?: 'insecure' | 'no_host_verification' | 'strict' | 'default';
    }
  // No credentials (optional)
  | undefined;

Usage Example:

export default defineConfig({
  dialect: 'gel',
  dbCredentials: {
    host: 'localhost',
    port: 5432,
    database: 'mydb',
    tlsSecurity: 'strict',
  },
});

Configuration Options

Schema Paths

The schema option accepts:

  • Single file path: './src/schema.ts'
  • Array of paths: ['./src/schema.ts', './src/auth.ts']
  • Glob patterns: './src/schema/**/*.ts'
  • Mix of all: ['./src/schema/**/*.ts', './src/special.ts']

Table Filters

The tablesFilter option uses glob patterns:

  • Include patterns: 'users_*' matches all tables starting with users_
  • Exclude patterns: '!temp_*' excludes tables starting with temp_
  • Multiple filters: ['users_*', 'posts_*', '!temp_*']

Schema Filters

The schemaFilter option (PostgreSQL only) specifies which schemas to include:

  • Single schema: 'public'
  • Multiple schemas: ['public', 'auth', 'custom']
  • Default: ['public']

Extension Filters

The extensionsFilters option excludes tables from database extensions:

  • ['postgis'] - Excludes PostGIS spatial tables

Casing Options

Serialization Casing (casing):

  • 'camelCase' - JavaScript/TypeScript style naming in generated code
  • 'snake_case' - SQL style naming in generated code

Introspection Casing (introspect.casing):

  • 'camel' - Convert database names to camelCase
  • 'preserve' - Keep original database names

Migration Prefix Options

The migrations.prefix option controls migration file naming:

  • 'index' - Sequential numbers: 0000_init.sql, 0001_add_users.sql (default)
  • 'timestamp' - Unix timestamps: 1699564800000_init.sql
  • 'supabase' - Supabase format: 20231109120000_init.sql
  • 'unix' - Unix epoch: 1699564800_init.sql
  • 'none' - No prefix: init.sql

Driver Options

The driver option is only needed for specific platforms:

  • 'aws-data-api' - AWS RDS Data API (PostgreSQL)
  • 'pglite' - PGlite embedded PostgreSQL
  • 'd1-http' - Cloudflare D1 HTTP API (SQLite)
  • 'expo' - Expo SQLite (SQLite)
  • 'turso' - Turso/LibSQL (use with dialect: 'turso')
  • 'durable-sqlite' - Cloudflare Durable Objects SQLite

For standard PostgreSQL, MySQL, and SQLite connections, no driver is needed.

Environment Variables

Configuration files commonly use environment variables for sensitive data:

import { defineConfig } from 'drizzle-kit';

export default defineConfig({
  dialect: 'postgresql',
  schema: './src/schema.ts',
  out: './drizzle',
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
});

Common environment variable patterns:

  • DATABASE_URL - Full connection string
  • DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME - Individual connection parameters
  • TURSO_AUTH_TOKEN - Turso authentication token
  • CLOUDFLARE_API_TOKEN - Cloudflare D1 API token
  • AWS_SECRET_ARN, AWS_RESOURCE_ARN - AWS RDS Data API credentials