@kysera/dialects 0.8.2 → 0.8.3

package/dist/index.d.ts

@@ -19,12 +19,54 @@ interface ConnectionConfig {
     password?: string | undefined;
     ssl?: boolean | undefined;
 }
+/**
+ * Options for schema-aware database operations.
+ *
+ * @example
+ * // PostgreSQL: Query tables in a specific schema
+ * await adapter.tableExists(db, 'users', { schema: 'auth' })
+ *
+ * @example
+ * // Multi-tenant: Query tables in tenant-specific schema
+ * await adapter.getTables(db, { schema: `tenant_${tenantId}` })
+ */
+interface SchemaOptions {
+    /**
+     * Schema name for the operation.
+     *
+     * - PostgreSQL: Defaults to 'public' if not specified
+     * - MySQL: Uses DATABASE() (schema = database in MySQL)
+     * - SQLite: Not supported (single schema only)
+     * - MSSQL: Defaults to 'dbo' if not specified
+     */
+    schema?: string;
+}
+/**
+ * Configuration options for creating dialect adapters
+ */
+interface DialectAdapterOptions {
+    /**
+     * Default schema for all operations.
+     * Can be overridden per-call via SchemaOptions.
+     *
+     * - PostgreSQL: Defaults to 'public'
+     * - MySQL: Uses current database
+     * - SQLite: Not applicable
+     * - MSSQL: Defaults to 'dbo'
+     */
+    defaultSchema?: string;
+}
 /**
  * Interface for dialect-specific operations
  */
 interface DialectAdapter {
     /** The dialect this adapter handles */
     readonly dialect: Dialect;
+    /**
+     * Default schema for this adapter.
+     * Used when SchemaOptions.schema is not specified.
+     */
+    readonly defaultSchema: string;
     /** Get default port for this dialect */
     getDefaultPort(): number | null;
     /** Get SQL expression for current timestamp */
@@ -39,22 +81,69 @@ interface DialectAdapter {
     isForeignKeyError(error: unknown): boolean;
     /** Check if error is a not-null constraint violation */
     isNotNullError(error: unknown): boolean;
-    /** Check if a table exists in the database */
-    tableExists(db: Kysely<any>, tableName: string): Promise<boolean>;
-    /** Get column names for a table */
-    getTableColumns(db: Kysely<any>, tableName: string): Promise<string[]>;
-    /** Get all tables in the database */
-    getTables(db: Kysely<any>): Promise<string[]>;
+    /**
+     * Check if a table exists in the database
+     *
+     * @param db - Kysely database instance
+     * @param tableName - Name of the table to check
+     * @param options - Optional schema configuration
+     * @returns true if table exists, false otherwise
+     *
+     * @example
+     * // Check in default schema (public)
+     * await adapter.tableExists(db, 'users')
+     *
+     * @example
+     * // Check in specific schema
+     * await adapter.tableExists(db, 'users', { schema: 'auth' })
+     */
+    tableExists(db: Kysely<any>, tableName: string, options?: SchemaOptions): Promise<boolean>;
+    /**
+     * Get column names for a table
+     *
+     * @param db - Kysely database instance
+     * @param tableName - Name of the table
+     * @param options - Optional schema configuration
+     * @returns Array of column names
+     *
+     * @example
+     * const columns = await adapter.getTableColumns(db, 'users', { schema: 'auth' })
+     * // ['id', 'email', 'password_hash', 'created_at']
+     */
+    getTableColumns(db: Kysely<any>, tableName: string, options?: SchemaOptions): Promise<string[]>;
+    /**
+     * Get all tables in the database/schema
+     *
+     * @param db - Kysely database instance
+     * @param options - Optional schema configuration
+     * @returns Array of table names
+     *
+     * @example
+     * // Get tables in auth schema
+     * const tables = await adapter.getTables(db, { schema: 'auth' })
+     * // ['users', 'sessions', 'tokens']
+     */
+    getTables(db: Kysely<any>, options?: SchemaOptions): Promise<string[]>;
     /** Get database size in bytes */
     getDatabaseSize(db: Kysely<any>, databaseName?: string): Promise<number>;
     /**
      * Truncate a single table
+     *
+     * @param db - Kysely database instance
+     * @param tableName - Name of the table to truncate
+     * @param options - Optional schema configuration
      * @returns true if table was truncated, false if table does not exist
      * @throws Error for other database errors
      */
-    truncateTable(db: Kysely<any>, tableName: string): Promise<boolean>;
-    /** Truncate all tables (for testing) */
-    truncateAllTables(db: Kysely<any>, exclude?: string[]): Promise<void>;
+    truncateTable(db: Kysely<any>, tableName: string, options?: SchemaOptions): Promise<boolean>;
+    /**
+     * Truncate all tables in the database/schema (for testing)
+     *
+     * @param db - Kysely database instance
+     * @param exclude - Array of table names to exclude
+     * @param options - Optional schema configuration
+     */
+    truncateAllTables(db: Kysely<any>, exclude?: string[], options?: SchemaOptions): Promise<void>;
 }
 /**
  * Error object shape for database error detection
@@ -62,43 +151,29 @@ interface DialectAdapter {
 interface DatabaseErrorLike {
     message?: string;
     code?: string;
+    /** Error number (used by MSSQL for error codes like 2627, 547, 515) */
+    number?: number;
 }
 
 /**
- * Dialect Adapter Factory
- */
-
-/**
- * Get a dialect adapter for the specified dialect
- *
- * @example
- * const adapter = getAdapter('postgres');
- * console.log(adapter.getDefaultPort()); // 5432
- */
-declare function getAdapter(dialect: Dialect): DialectAdapter;
-/**
- * Create a new dialect adapter instance
- *
- * @example
- * const adapter = createDialectAdapter('mysql');
- */
-declare function createDialectAdapter(dialect: Dialect): DialectAdapter;
-/**
- * Register a custom dialect adapter
+ * PostgreSQL Dialect Adapter
  *
- * @example
- * registerAdapter(customAdapter);
+ * Supports PostgreSQL 12+ with full schema support for multi-tenant
+ * and modular database architectures.
  */
-declare function registerAdapter(adapter: DialectAdapter): void;
 
 /**
- * PostgreSQL Dialect Adapter
+ * PostgreSQL-specific adapter options
  */
-
+interface PostgresAdapterOptions extends DialectAdapterOptions {
+    /** Logger instance for error reporting */
+    logger?: KyseraLogger;
+}
 declare class PostgresAdapter implements DialectAdapter {
     readonly dialect: "postgres";
+    readonly defaultSchema: string;
     private logger;
-    constructor(logger?: KyseraLogger);
+    constructor(options?: PostgresAdapterOptions);
     getDefaultPort(): number;
     getCurrentTimestamp(): string;
     escapeIdentifier(identifier: string): string;
@@ -106,23 +181,241 @@ declare class PostgresAdapter implements DialectAdapter {
     isUniqueConstraintError(error: unknown): boolean;
     isForeignKeyError(error: unknown): boolean;
     isNotNullError(error: unknown): boolean;
-    tableExists(db: Kysely<any>, tableName: string): Promise<boolean>;
-    getTableColumns(db: Kysely<any>, tableName: string): Promise<string[]>;
-    getTables(db: Kysely<any>): Promise<string[]>;
+    /**
+     * Resolve the schema to use for an operation.
+     * Uses the shared resolveSchema utility from helpers.ts.
+     */
+    private resolveSchema;
+    tableExists(db: Kysely<any>, tableName: string, options?: SchemaOptions): Promise<boolean>;
+    getTableColumns(db: Kysely<any>, tableName: string, options?: SchemaOptions): Promise<string[]>;
+    getTables(db: Kysely<any>, options?: SchemaOptions): Promise<string[]>;
     getDatabaseSize(db: Kysely<any>, databaseName?: string): Promise<number>;
-    truncateTable(db: Kysely<any>, tableName: string): Promise<boolean>;
-    truncateAllTables(db: Kysely<any>, exclude?: string[]): Promise<void>;
+    truncateTable(db: Kysely<any>, tableName: string, options?: SchemaOptions): Promise<boolean>;
+    truncateAllTables(db: Kysely<any>, exclude?: string[], options?: SchemaOptions): Promise<void>;
+    /**
+     * Check if a schema exists in the database
+     *
+     * @param db - Kysely database instance
+     * @param schemaName - Name of the schema to check
+     * @returns true if schema exists, false otherwise
+     *
+     * @example
+     * const exists = await adapter.schemaExists(db, 'auth')
+     */
+    schemaExists(db: Kysely<any>, schemaName: string): Promise<boolean>;
+    /**
+     * Get all schemas in the database (excluding system schemas)
+     *
+     * @param db - Kysely database instance
+     * @returns Array of schema names
+     *
+     * @example
+     * const schemas = await adapter.getSchemas(db)
+     * // ['public', 'auth', 'admin', 'tenant_1']
+     */
+    getSchemas(db: Kysely<any>): Promise<string[]>;
+    /**
+     * Create a new schema in the database
+     *
+     * @param db - Kysely database instance
+     * @param schemaName - Name of the schema to create
+     * @param options - Creation options
+     * @returns true if schema was created, false if it already exists
+     *
+     * @example
+     * await adapter.createSchema(db, 'tenant_123')
+     */
+    createSchema(db: Kysely<any>, schemaName: string, options?: {
+        ifNotExists?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Drop a schema from the database
+     *
+     * @param db - Kysely database instance
+     * @param schemaName - Name of the schema to drop
+     * @param options - Drop options
+     * @returns true if schema was dropped, false if it doesn't exist
+     *
+     * @example
+     * await adapter.dropSchema(db, 'tenant_123', { cascade: true })
+     */
+    dropSchema(db: Kysely<any>, schemaName: string, options?: {
+        ifExists?: boolean;
+        cascade?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Get detailed information about a schema
+     *
+     * @param db - Kysely database instance
+     * @param schemaName - Name of the schema
+     * @returns Schema information including table count, size, and owner
+     *
+     * @example
+     * const info = await adapter.getSchemaInfo(db, 'tenant_123')
+     * // { name: 'tenant_123', tableCount: 15, owner: 'app_user', sizeBytes: 1048576 }
+     */
+    getSchemaInfo(db: Kysely<any>, schemaName: string): Promise<{
+        name: string;
+        tableCount: number;
+        owner: string | null;
+        sizeBytes: number;
+    }>;
+    /**
+     * Get index information for all tables in a schema
+     *
+     * @param db - Kysely database instance
+     * @param options - Optional schema configuration
+     * @returns Array of index information
+     *
+     * @example
+     * const indexes = await adapter.getSchemaIndexes(db, { schema: 'auth' })
+     */
+    getSchemaIndexes(db: Kysely<any>, options?: SchemaOptions): Promise<{
+        tableName: string;
+        indexName: string;
+        indexType: string;
+        isUnique: boolean;
+        isPrimary: boolean;
+        columns: string[];
+    }[]>;
+    /**
+     * Get foreign key relationships in a schema
+     *
+     * @param db - Kysely database instance
+     * @param options - Optional schema configuration
+     * @returns Array of foreign key relationships
+     *
+     * @example
+     * const fks = await adapter.getSchemaForeignKeys(db, { schema: 'public' })
+     */
+    getSchemaForeignKeys(db: Kysely<any>, options?: SchemaOptions): Promise<{
+        constraintName: string;
+        tableName: string;
+        columnName: string;
+        referencedSchema: string;
+        referencedTable: string;
+        referencedColumn: string;
+        onDelete: string;
+        onUpdate: string;
+    }[]>;
+    /**
+     * Get the current search_path setting
+     *
+     * @param db - Kysely database instance
+     * @returns Array of schema names in the search path
+     *
+     * @example
+     * const path = await adapter.getSearchPath(db)
+     * // ['public', 'tenant_123']
+     */
+    getSearchPath(db: Kysely<any>): Promise<string[]>;
+    /**
+     * Set the search_path for the current session
+     *
+     * @param db - Kysely database instance
+     * @param schemas - Array of schema names to set in the search path
+     *
+     * @example
+     * // Set search path for multi-tenant query
+     * await adapter.setSearchPath(db, ['tenant_123', 'public'])
+     */
+    setSearchPath(db: Kysely<any>, schemas: string[]): Promise<void>;
+    /**
+     * Execute a function with a temporary search_path, then restore the original
+     *
+     * @param db - Kysely database instance
+     * @param schemas - Temporary search path
+     * @param fn - Function to execute with the temporary search path
+     * @returns The result of the function
+     *
+     * @example
+     * const result = await adapter.withSearchPath(db, ['tenant_123'], async () => {
+     *   // All queries in here will use tenant_123 schema by default
+     *   return await db.selectFrom('users').selectAll().execute()
+     * })
+     */
+    withSearchPath<T>(db: Kysely<any>, schemas: string[], fn: () => Promise<T>): Promise<T>;
+    /**
+     * Clone a schema's structure (tables, indexes, constraints) to a new schema
+     *
+     * @param db - Kysely database instance
+     * @param sourceSchema - Source schema to clone from
+     * @param targetSchema - Target schema name to create
+     * @param options - Clone options
+     * @returns true if successful
+     *
+     * @example
+     * // Clone 'template' schema to create new tenant schema
+     * await adapter.cloneSchema(db, 'template', 'tenant_456')
+     *
+     * @example
+     * // Clone with data included
+     * await adapter.cloneSchema(db, 'template', 'tenant_456', { includeData: true })
+     */
+    cloneSchema(db: Kysely<any>, sourceSchema: string, targetSchema: string, options?: {
+        includeData?: boolean;
+        excludeTables?: string[];
+    }): Promise<boolean>;
+    /**
+     * Compare two schemas and return the differences
+     *
+     * @param db - Kysely database instance
+     * @param schema1 - First schema name
+     * @param schema2 - Second schema name
+     * @returns Comparison result with tables unique to each schema
+     *
+     * @example
+     * const diff = await adapter.compareSchemas(db, 'template', 'tenant_123')
+     * // { onlyInFirst: ['archived_users'], onlyInSecond: ['custom_settings'], inBoth: ['users', 'posts'] }
+     */
+    compareSchemas(db: Kysely<any>, schema1: string, schema2: string): Promise<{
+        onlyInFirst: string[];
+        onlyInSecond: string[];
+        inBoth: string[];
+    }>;
 }
+/**
+ * Default PostgreSQL adapter instance with 'public' schema
+ */
 declare const postgresAdapter: PostgresAdapter;
+/**
+ * Create a new PostgreSQL adapter with custom configuration
+ *
+ * @param options - Adapter configuration options
+ * @returns Configured PostgresAdapter instance
+ *
+ * @example
+ * // Create adapter with custom default schema
+ * const adapter = createPostgresAdapter({ defaultSchema: 'auth' })
+ *
+ * @example
+ * // Create adapter with logger
+ * const adapter = createPostgresAdapter({
+ *   defaultSchema: 'app',
+ *   logger: myLogger
+ * })
+ */
+declare function createPostgresAdapter(options?: PostgresAdapterOptions): PostgresAdapter;
 
 /**
  * MySQL Dialect Adapter
+ *
+ * Note: In MySQL, "schema" and "database" are synonymous.
+ * The schema option maps to the current database context.
  */
 
+/**
+ * MySQL-specific adapter options
+ */
+interface MySQLAdapterOptions extends DialectAdapterOptions {
+    /** Logger instance for error reporting */
+    logger?: KyseraLogger;
+}
 declare class MySQLAdapter implements DialectAdapter {
     readonly dialect: "mysql";
+    readonly defaultSchema: string;
     private logger;
-    constructor(logger?: KyseraLogger);
+    constructor(options?: MySQLAdapterOptions);
     getDefaultPort(): number;
     getCurrentTimestamp(): string;
     escapeIdentifier(identifier: string): string;
@@ -130,23 +423,57 @@ declare class MySQLAdapter implements DialectAdapter {
     isUniqueConstraintError(error: unknown): boolean;
     isForeignKeyError(error: unknown): boolean;
     isNotNullError(error: unknown): boolean;
-    tableExists(db: Kysely<any>, tableName: string): Promise<boolean>;
-    getTableColumns(db: Kysely<any>, tableName: string): Promise<string[]>;
-    getTables(db: Kysely<any>): Promise<string[]>;
+    /**
+     * Get the schema (database) filter for queries.
+     * In MySQL, schema = database, so we use DATABASE() if not specified.
+     */
+    private getSchemaFilter;
+    tableExists(db: Kysely<any>, tableName: string, options?: SchemaOptions): Promise<boolean>;
+    getTableColumns(db: Kysely<any>, tableName: string, options?: SchemaOptions): Promise<string[]>;
+    getTables(db: Kysely<any>, options?: SchemaOptions): Promise<string[]>;
     getDatabaseSize(db: Kysely<any>, databaseName?: string): Promise<number>;
-    truncateTable(db: Kysely<any>, tableName: string): Promise<boolean>;
-    truncateAllTables(db: Kysely<any>, exclude?: string[]): Promise<void>;
+    truncateTable(db: Kysely<any>, tableName: string, options?: SchemaOptions): Promise<boolean>;
+    truncateAllTables(db: Kysely<any>, exclude?: string[], options?: SchemaOptions): Promise<void>;
 }
+/**
+ * Default MySQL adapter instance
+ */
 declare const mysqlAdapter: MySQLAdapter;
+/**
+ * Create a new MySQL adapter with custom configuration
+ *
+ * @param options - Adapter configuration options
+ * @returns Configured MySQLAdapter instance
+ *
+ * @example
+ * // Create adapter with specific database as default
+ * const adapter = createMySQLAdapter({ defaultSchema: 'my_database' })
+ */
+declare function createMySQLAdapter(options?: MySQLAdapterOptions): MySQLAdapter;
 
 /**
  * SQLite Dialect Adapter
+ *
+ * Note: SQLite does not support schemas in the same way as PostgreSQL.
+ * Each SQLite database is a single schema. The schema option is accepted
+ * for interface compatibility but is ignored for most operations.
+ *
+ * SQLite does support ATTACH DATABASE for multiple schemas, but this
+ * requires special handling and is not currently implemented.
  */
 
+/**
+ * SQLite-specific adapter options
+ */
+interface SQLiteAdapterOptions extends DialectAdapterOptions {
+    /** Logger instance for error reporting */
+    logger?: KyseraLogger;
+}
 declare class SQLiteAdapter implements DialectAdapter {
     readonly dialect: "sqlite";
+    readonly defaultSchema: string;
     private logger;
-    constructor(logger?: KyseraLogger);
+    constructor(options?: SQLiteAdapterOptions);
     getDefaultPort(): null;
     getCurrentTimestamp(): string;
     escapeIdentifier(identifier: string): string;
@@ -154,23 +481,54 @@ declare class SQLiteAdapter implements DialectAdapter {
     isUniqueConstraintError(error: unknown): boolean;
     isForeignKeyError(error: unknown): boolean;
     isNotNullError(error: unknown): boolean;
-    tableExists(db: Kysely<any>, tableName: string): Promise<boolean>;
-    getTableColumns(db: Kysely<any>, tableName: string): Promise<string[]>;
-    getTables(db: Kysely<any>): Promise<string[]>;
+    /**
+     * Resolve the schema to use. In SQLite, this is typically 'main'
+     * unless ATTACH DATABASE has been used.
+     * Uses the shared resolveSchema utility from helpers.ts.
+     */
+    private resolveSchema;
+    tableExists(db: Kysely<any>, tableName: string, options?: SchemaOptions): Promise<boolean>;
+    getTableColumns(db: Kysely<any>, tableName: string, options?: SchemaOptions): Promise<string[]>;
+    getTables(db: Kysely<any>, options?: SchemaOptions): Promise<string[]>;
     getDatabaseSize(_db: Kysely<any>, _databaseName?: string): Promise<number>;
-    truncateTable(db: Kysely<any>, tableName: string): Promise<boolean>;
-    truncateAllTables(db: Kysely<any>, exclude?: string[]): Promise<void>;
+    truncateTable(db: Kysely<any>, tableName: string, options?: SchemaOptions): Promise<boolean>;
+    truncateAllTables(db: Kysely<any>, exclude?: string[], options?: SchemaOptions): Promise<void>;
 }
+/**
+ * Default SQLite adapter instance
+ */
 declare const sqliteAdapter: SQLiteAdapter;
+/**
+ * Create a new SQLite adapter with custom configuration
+ *
+ * @param options - Adapter configuration options
+ * @returns Configured SQLiteAdapter instance
+ *
+ * @example
+ * // Create adapter (schema options have limited effect in SQLite)
+ * const adapter = createSQLiteAdapter()
+ */
+declare function createSQLiteAdapter(options?: SQLiteAdapterOptions): SQLiteAdapter;
 
 /**
  * Microsoft SQL Server Dialect Adapter
  *
  * Supports SQL Server 2017+, Azure SQL Database, and Azure SQL Edge
+ * with full schema support (default: 'dbo')
  */
 
+/**
+ * MSSQL-specific adapter options
+ */
+interface MSSQLAdapterOptions extends DialectAdapterOptions {
+    /** Logger instance for error reporting */
+    logger?: KyseraLogger;
+}
 declare class MSSQLAdapter implements DialectAdapter {
     readonly dialect: "mssql";
+    readonly defaultSchema: string;
+    private logger;
+    constructor(options?: MSSQLAdapterOptions);
     getDefaultPort(): number;
     getCurrentTimestamp(): string;
     escapeIdentifier(identifier: string): string;
@@ -178,14 +536,133 @@ declare class MSSQLAdapter implements DialectAdapter {
     isUniqueConstraintError(error: unknown): boolean;
     isForeignKeyError(error: unknown): boolean;
     isNotNullError(error: unknown): boolean;
-    tableExists(db: Kysely<any>, tableName: string): Promise<boolean>;
-    getTableColumns(db: Kysely<any>, tableName: string): Promise<string[]>;
-    getTables(db: Kysely<any>): Promise<string[]>;
+    /**
+     * Resolve the schema to use for an operation.
+     * Uses the shared resolveSchema utility from helpers.ts.
+     */
+    private resolveSchema;
+    tableExists(db: Kysely<any>, tableName: string, options?: SchemaOptions): Promise<boolean>;
+    getTableColumns(db: Kysely<any>, tableName: string, options?: SchemaOptions): Promise<string[]>;
+    getTables(db: Kysely<any>, options?: SchemaOptions): Promise<string[]>;
     getDatabaseSize(db: Kysely<any>, _databaseName?: string): Promise<number>;
-    truncateTable(db: Kysely<any>, tableName: string): Promise<boolean>;
-    truncateAllTables(db: Kysely<any>, exclude?: string[]): Promise<void>;
+    truncateTable(db: Kysely<any>, tableName: string, options?: SchemaOptions): Promise<boolean>;
+    truncateAllTables(db: Kysely<any>, exclude?: string[], options?: SchemaOptions): Promise<void>;
+    /**
+     * Check if a schema exists in the database
+     *
+     * @param db - Kysely database instance
+     * @param schemaName - Name of the schema to check
+     * @returns true if schema exists, false otherwise
+     */
+    schemaExists(db: Kysely<any>, schemaName: string): Promise<boolean>;
+    /**
+     * Get all schemas in the database (excluding system schemas)
+     *
+     * @param db - Kysely database instance
+     * @returns Array of schema names
+     */
+    getSchemas(db: Kysely<any>): Promise<string[]>;
+    /**
+     * Create a new schema in the database
+     *
+     * @param db - Kysely database instance
+     * @param schemaName - Name of the schema to create
+     * @returns true if schema was created, false if it already exists
+     */
+    createSchema(db: Kysely<any>, schemaName: string): Promise<boolean>;
+    /**
+     * Drop a schema from the database
+     *
+     * @param db - Kysely database instance
+     * @param schemaName - Name of the schema to drop
+     * @returns true if schema was dropped, false if it doesn't exist
+     */
+    dropSchema(db: Kysely<any>, schemaName: string): Promise<boolean>;
 }
+/**
+ * Default MSSQL adapter instance with 'dbo' schema
+ */
 declare const mssqlAdapter: MSSQLAdapter;
+/**
+ * Create a new MSSQL adapter with custom configuration
+ *
+ * @param options - Adapter configuration options
+ * @returns Configured MSSQLAdapter instance
+ *
+ * @example
+ * // Create adapter with custom default schema
+ * const adapter = createMSSQLAdapter({ defaultSchema: 'app' })
+ */
+declare function createMSSQLAdapter(options?: MSSQLAdapterOptions): MSSQLAdapter;
+
+/**
+ * Dialect Adapter Factory
+ */
+
+/**
+ * Get a dialect adapter for the specified dialect.
+ * Returns a shared singleton instance with default configuration.
+ *
+ * @param dialect - Database dialect
+ * @returns DialectAdapter instance
+ *
+ * @example
+ * const adapter = getAdapter('postgres')
+ * console.log(adapter.getDefaultPort()) // 5432
+ * console.log(adapter.defaultSchema)    // 'public'
+ */
+declare function getAdapter(dialect: Dialect): DialectAdapter;
+/**
+ * Adapter options by dialect type
+ */
+type AdapterOptions = {
+    dialect: 'postgres';
+    options?: PostgresAdapterOptions;
+} | {
+    dialect: 'mysql';
+    options?: MySQLAdapterOptions;
+} | {
+    dialect: 'sqlite';
+    options?: SQLiteAdapterOptions;
+} | {
+    dialect: 'mssql';
+    options?: MSSQLAdapterOptions;
+};
+/**
+ * Create a new dialect adapter instance with custom options.
+ * Use this when you need a custom default schema or logger.
+ *
+ * @param dialect - Database dialect
+ * @param options - Dialect-specific adapter options
+ * @returns New DialectAdapter instance
+ *
+ * @example
+ * // Create adapter with custom default schema
+ * const adapter = createDialectAdapter('postgres', { defaultSchema: 'auth' })
+ *
+ * @example
+ * // Create adapter with logger
+ * const adapter = createDialectAdapter('postgres', {
+ *   defaultSchema: 'app',
+ *   logger: myLogger
+ * })
+ */
+declare function createDialectAdapter(dialect: 'postgres', options?: PostgresAdapterOptions): PostgresAdapter;
+declare function createDialectAdapter(dialect: 'mysql', options?: MySQLAdapterOptions): MySQLAdapter;
+declare function createDialectAdapter(dialect: 'sqlite', options?: SQLiteAdapterOptions): SQLiteAdapter;
+declare function createDialectAdapter(dialect: 'mssql', options?: MSSQLAdapterOptions): MSSQLAdapter;
+declare function createDialectAdapter(dialect: Dialect, options?: DialectAdapterOptions): DialectAdapter;
+/**
+ * Register a custom dialect adapter.
+ * This replaces the default adapter for the given dialect.
+ *
+ * @param adapter - DialectAdapter instance to register
+ *
+ * @example
+ * const customAdapter = new PostgresAdapter({ defaultSchema: 'custom' })
+ * registerAdapter(customAdapter)
+ */
+declare function registerAdapter(adapter: DialectAdapter): void;
 
 /**
  * Connection URL utilities
@@ -225,7 +702,7 @@ declare function getDefaultPort(dialect: Dialect): number | null;
  */
 
 /**
- * Validate a SQL identifier (table name, column name, etc.)
+ * Validate a SQL identifier (table name, column name, schema name, etc.)
  *
  * @param name - The identifier to validate
  * @returns true if the identifier is valid, false otherwise
@@ -251,29 +728,263 @@ declare function validateIdentifier(name: string): boolean;
  * assertValidIdentifier('123bad', 'table name'); // throws Error: Invalid table name: 123bad
  */
 declare function assertValidIdentifier(name: string, context?: string): void;
+/**
+ * Resolve schema name with validation
+ *
+ * This is the canonical implementation used by all dialect adapters.
+ * Eliminates code duplication across PostgreSQL, MySQL, SQLite, and MSSQL adapters.
+ *
+ * @param defaultSchema - The default schema to use if not specified in options
+ * @param options - Optional schema configuration
+ * @returns The resolved and validated schema name
+ * @throws Error if the schema name is invalid
+ *
+ * @example
+ * // Use with adapter's default schema
+ * const schema = resolveSchema('public', options)
+ *
+ * @example
+ * // Multi-tenant usage
+ * const schema = resolveSchema('public', { schema: `tenant_${tenantId}` })
+ */
+declare function resolveSchema(defaultSchema: string, options?: SchemaOptions): string;
+/**
+ * Configuration for multi-tenant schema operations
+ */
+interface TenantSchemaConfig {
+    /** Prefix for tenant schema names (default: 'tenant_') */
+    prefix?: string;
+}
+/**
+ * Generate a tenant schema name from a tenant ID
+ *
+ * @param tenantId - The unique tenant identifier
+ * @param config - Optional configuration
+ * @returns The tenant schema name (validated)
+ * @throws Error if the resulting schema name is invalid
+ *
+ * @example
+ * getTenantSchemaName('123')           // 'tenant_123'
+ * getTenantSchemaName('acme')          // 'tenant_acme'
+ * getTenantSchemaName('corp', { prefix: 'org_' }) // 'org_corp'
+ */
+declare function getTenantSchemaName(tenantId: string, config?: TenantSchemaConfig): string;
+/**
+ * Extract tenant ID from a tenant schema name
+ *
+ * @param schemaName - The schema name to parse
+ * @param config - Optional configuration
+ * @returns The tenant ID if the schema matches the pattern, null otherwise
+ *
+ * @example
+ * parseTenantSchemaName('tenant_123')           // '123'
+ * parseTenantSchemaName('tenant_acme')          // 'acme'
+ * parseTenantSchemaName('public')               // null
+ * parseTenantSchemaName('org_corp', { prefix: 'org_' }) // 'corp'
+ */
+declare function parseTenantSchemaName(schemaName: string, config?: TenantSchemaConfig): string | null;
+/**
+ * Check if a schema name matches the tenant schema pattern
+ *
+ * @param schemaName - The schema name to check
+ * @param config - Optional configuration
+ * @returns true if the schema matches the tenant pattern
+ *
+ * @example
+ * isTenantSchema('tenant_123')           // true
+ * isTenantSchema('public')               // false
+ * isTenantSchema('org_corp', { prefix: 'org_' }) // true
+ */
+declare function isTenantSchema(schemaName: string, config?: TenantSchemaConfig): boolean;
+/**
+ * Filter an array of schema names to only tenant schemas
+ *
+ * @param schemas - Array of schema names
+ * @param config - Optional configuration
+ * @returns Array of tenant schema names
+ *
+ * @example
+ * filterTenantSchemas(['public', 'tenant_1', 'tenant_2', 'auth'])
+ * // ['tenant_1', 'tenant_2']
+ */
+declare function filterTenantSchemas(schemas: string[], config?: TenantSchemaConfig): string[];
+/**
+ * Extract tenant IDs from an array of schema names
+ *
+ * @param schemas - Array of schema names
+ * @param config - Optional configuration
+ * @returns Array of tenant IDs (excluding non-tenant schemas)
+ *
+ * @example
+ * extractTenantIds(['public', 'tenant_1', 'tenant_2', 'auth'])
+ * // ['1', '2']
+ */
+declare function extractTenantIds(schemas: string[], config?: TenantSchemaConfig): string[];
+/**
+ * Options for schema copying operations
+ */
+interface SchemaCopyOptions {
+    /** Include table data (default: false, structure only) */
+    includeData?: boolean;
+    /** Tables to exclude from copying */
+    excludeTables?: string[];
+    /** Tables to include (if specified, only these are copied) */
+    includeTables?: string[];
+}
+/**
+ * Create a qualified table name with schema prefix
+ *
+ * @param schema - The schema name
+ * @param tableName - The table name
+ * @param escapeIdentifierFn - Function to escape identifiers for the specific dialect
+ * @returns Fully qualified table name (e.g., "public"."users")
+ *
+ * @example
+ * qualifyTableName('auth', 'users', escapeIdentifier)
+ * // PostgreSQL: "auth"."users"
+ * // MySQL: `auth`.`users`
+ */
+declare function qualifyTableName(schema: string, tableName: string, escapeIdentifierFn: (id: string) => string): string;
+/**
+ * Error information extracted from a database error
+ */
+interface ExtractedErrorInfo {
+    /** Error code (e.g., '23505' for PostgreSQL unique constraint) */
+    code: string;
+    /** Error message in lowercase for case-insensitive matching */
+    message: string;
+    /** Original error message */
+    originalMessage: string;
+    /** Error number (for MSSQL) - undefined if not present */
+    number: number | undefined;
+}
+/**
+ * Extract error information from an unknown database error
+ *
+ * This utility normalizes error information across different database drivers,
+ * eliminating the need for repeated type assertions in each adapter.
+ *
+ * @param error - The unknown error from a database operation
+ * @returns Normalized error information
+ *
+ * @example
+ * try {
+ *   await db.insertInto('users').values(data).execute()
+ * } catch (error) {
+ *   const info = extractErrorInfo(error)
+ *   if (info.code === '23505') {
+ *     // Handle unique constraint violation
+ *   }
+ * }
+ */
+declare function extractErrorInfo(error: unknown): ExtractedErrorInfo;
+/**
+ * Error matcher configuration for a specific error type
+ */
+interface ErrorMatcherConfig {
+    /** PostgreSQL error codes */
+    codes?: string[];
+    /** MSSQL error numbers */
+    numbers?: number[];
+    /** Message substrings to match (case-insensitive) */
+    messages?: string[];
+}
+/**
+ * Create an error matcher function for a specific constraint type
+ *
+ * This factory eliminates code duplication across dialect adapters by creating
+ * reusable error detection functions.
+ *
+ * @param config - Configuration for matching the error
+ * @returns A function that checks if an error matches the configured patterns
+ *
+ * @example
+ * // Create a unique constraint error matcher for PostgreSQL
+ * const isUniqueConstraint = createErrorMatcher({
+ *   codes: ['23505'],
+ *   messages: ['unique constraint']
+ * })
+ *
+ * @example
+ * // Create a foreign key error matcher for MSSQL
+ * const isForeignKey = createErrorMatcher({
+ *   numbers: [547],
+ *   messages: ['foreign key']
+ * })
+ */
+declare function createErrorMatcher(config: ErrorMatcherConfig): (error: unknown) => boolean;
+/**
+ * Pre-built error matchers for common constraint violations
+ * These can be used directly or as reference for custom matchers
+ */
+declare const errorMatchers: {
+    readonly postgres: {
+        readonly uniqueConstraint: (error: unknown) => boolean;
+        readonly foreignKey: (error: unknown) => boolean;
+        readonly notNull: (error: unknown) => boolean;
+    };
+    readonly mysql: {
+        readonly uniqueConstraint: (error: unknown) => boolean;
+        readonly foreignKey: (error: unknown) => boolean;
+        readonly notNull: (error: unknown) => boolean;
+    };
+    readonly sqlite: {
+        readonly uniqueConstraint: (error: unknown) => boolean;
+        readonly foreignKey: (error: unknown) => boolean;
+        readonly notNull: (error: unknown) => boolean;
+    };
+    readonly mssql: {
+        readonly uniqueConstraint: (error: unknown) => boolean;
+        readonly foreignKey: (error: unknown) => boolean;
+        readonly notNull: (error: unknown) => boolean;
+    };
+};
 /**
  * Check if table exists in the database
  *
+ * @param db - Kysely database instance
+ * @param tableName - Name of the table to check
+ * @param dialect - Database dialect
+ * @param options - Optional schema configuration
+ * @returns true if table exists, false otherwise
+ *
+ * @example
+ * // Check in default schema
+ * const exists = await tableExists(db, 'users', 'postgres')
+ *
  * @example
- * const exists = await tableExists(db, 'users', 'postgres');
+ * // Check in specific schema
+ * const exists = await tableExists(db, 'users', 'postgres', { schema: 'auth' })
  */
-declare function tableExists(db: Kysely<any>, tableName: string, dialect: Dialect): Promise<boolean>;
+declare function tableExists(db: Kysely<any>, tableName: string, dialect: Dialect, options?: SchemaOptions): Promise<boolean>;
 /**
  * Get column names for a table
  *
+ * @param db - Kysely database instance
+ * @param tableName - Name of the table
+ * @param dialect - Database dialect
+ * @param options - Optional schema configuration
+ * @returns Array of column names
+ *
  * @example
- * const columns = await getTableColumns(db, 'users', 'postgres');
+ * const columns = await getTableColumns(db, 'users', 'postgres', { schema: 'auth' })
  * // ['id', 'name', 'email', 'created_at']
  */
-declare function getTableColumns(db: Kysely<any>, tableName: string, dialect: Dialect): Promise<string[]>;
+declare function getTableColumns(db: Kysely<any>, tableName: string, dialect: Dialect, options?: SchemaOptions): Promise<string[]>;
 /**
- * Get all tables in the database
+ * Get all tables in the database/schema
+ *
+ * @param db - Kysely database instance
+ * @param dialect - Database dialect
+ * @param options - Optional schema configuration
+ * @returns Array of table names
  *
  * @example
- * const tables = await getTables(db, 'postgres');
- * // ['users', 'posts', 'comments']
+ * // Get tables in auth schema
+ * const tables = await getTables(db, 'postgres', { schema: 'auth' })
+ * // ['users', 'sessions', 'tokens']
  */
-declare function getTables(db: Kysely<any>, dialect: Dialect): Promise<string[]>;
+declare function getTables(db: Kysely<any>, dialect: Dialect, options?: SchemaOptions): Promise<string[]>;
 /**
  * Escape identifier for SQL (table names, column names, etc.)
  *
@@ -338,12 +1049,17 @@ declare function isNotNullError(error: unknown, dialect: Dialect): boolean;
  */
 declare function getDatabaseSize(db: Kysely<any>, dialect: Dialect, databaseName?: string): Promise<number>;
 /**
- * Truncate all tables in the database (useful for testing)
+ * Truncate all tables in the database/schema (useful for testing)
+ *
+ * @param db - Kysely database instance
+ * @param dialect - Database dialect
+ * @param exclude - Array of table names to exclude
+ * @param options - Optional schema configuration
  *
  * @example
- * // Truncate all tables except migrations
- * await truncateAllTables(db, 'postgres', ['kysely_migrations']);
+ * // Truncate all tables in auth schema except migrations
+ * await truncateAllTables(db, 'postgres', ['kysely_migrations'], { schema: 'auth' })
  */
-declare function truncateAllTables(db: Kysely<any>, dialect: Dialect, exclude?: string[]): Promise<void>;
+declare function truncateAllTables(db: Kysely<any>, dialect: Dialect, exclude?: string[], options?: SchemaOptions): Promise<void>;
 
-export { type ConnectionConfig, type DatabaseErrorLike, type DialectAdapter, MSSQLAdapter, MySQLAdapter, PostgresAdapter, SQLiteAdapter, assertValidIdentifier, buildConnectionUrl, createDialectAdapter, escapeIdentifier, formatDate, getAdapter, getCurrentTimestamp, getDatabaseSize, getDefaultPort, getTableColumns, getTables, isForeignKeyError, isNotNullError, isUniqueConstraintError, mssqlAdapter, mysqlAdapter, parseConnectionUrl, postgresAdapter, registerAdapter, sqliteAdapter, tableExists, truncateAllTables, validateIdentifier };
+export { type AdapterOptions, type ConnectionConfig, type DatabaseErrorLike, type DialectAdapter, type DialectAdapterOptions, type ErrorMatcherConfig, type ExtractedErrorInfo, MSSQLAdapter, type MSSQLAdapterOptions, MySQLAdapter, type MySQLAdapterOptions, PostgresAdapter, type PostgresAdapterOptions, SQLiteAdapter, type SQLiteAdapterOptions, type SchemaCopyOptions, type SchemaOptions, type TenantSchemaConfig, assertValidIdentifier, buildConnectionUrl, createDialectAdapter, createErrorMatcher, createMSSQLAdapter, createMySQLAdapter, createPostgresAdapter, createSQLiteAdapter, errorMatchers, escapeIdentifier, extractErrorInfo, extractTenantIds, filterTenantSchemas, formatDate, getAdapter, getCurrentTimestamp, getDatabaseSize, getDefaultPort, getTableColumns, getTables, getTenantSchemaName, isForeignKeyError, isNotNullError, isTenantSchema, isUniqueConstraintError, mssqlAdapter, mysqlAdapter, parseConnectionUrl, parseTenantSchemaName, postgresAdapter, qualifyTableName, registerAdapter, resolveSchema, sqliteAdapter, tableExists, truncateAllTables, validateIdentifier };