@duckdbfan/drizzle-duckdb 0.0.7 → 1.3.2

package/README.md

@@ -1,66 +1,353 @@
-# drizzle-duckdb
-
-## Description
-A drizzle ORM client for use with DuckDB. Based on drizzle's Postgres client. As of writing this, certain things will work, and others won't. Notably, DuckDB-specific column types such as `struct`, `list`, `array` are not implemented, but this could be done using [drizzle custom types](https://orm.drizzle.team/docs/custom-types). (This is planned to be implemented in the package later on)
-
-## Disclaimers
-- **Experimental**: This project is in an experimental stage. Certain features may be broken or not function as expected.
-- **Use at Your Own Risk**: Users should proceed with caution and use this project at their own risk.
-- **Maintenance**: This project may not be actively maintained. Updates and bug fixes are not guaranteed.
-
-## Getting Started
-1. Install dependencies:
-    ```sh
-    bun add @duckdbfan/drizzle-duckdb
-    ```
-2. Figure it out! (sorry, might flesh this out later- see tests for some examples)
-    ```typescript
-    import { Database } from 'duckdb-async';
-    import { drizzle } from '@duckdbfan/drizzle-duckdb';
-    import { DefaultLogger, sql } from 'drizzle-orm';
-    import { char, integer, pgSchema, text } from 'drizzle-orm/pg-core';
-    
-    const client = await Database.create(':memory:');
-    const db = drizzle(client, { logger: new DefaultLogger() });
-
-    const customSchema = pgSchema('custom');
-
-    await db.execute(sql`CREATE SCHEMA IF NOT EXISTS ${customSchema}`);
-
-    const citiesTable = customSchema.table('cities', {
-      id: integer('id')
-        .primaryKey()
-        .default(sql`nextval('serial_cities')`),
-      name: text('name').notNull(),
-      state: char('state', { length: 2 }),
-    });
-
-    await db.execute(sql`CREATE SEQUENCE IF NOT EXISTS serial_cities;`);
-
-    await db.execute(
-      sql`
-        create table if not exists ${citiesTable} (
-          id integer primary key default nextval('serial_cities'),
-          name text not null,
-          state char(2)
-        )
-      `
-    );
-
-    const insertedIds = await db
-      .insert(citiesTable)
-      .values([
-        { name: 'Paris', state: 'FR' },
-        { name: 'London', state: 'UK' },
-      ])
-      .returning({ id: citiesTable.id });
-
-    console.log(insertedIds);
-
-    ```
+<div align="center">
+
+# Drizzle DuckDB
+
+### DuckDB dialect for [Drizzle ORM](https://orm.drizzle.team/)
+
+[![npm version](https://img.shields.io/npm/v/@duckdbfan/drizzle-duckdb)](https://www.npmjs.com/package/@duckdbfan/drizzle-duckdb)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+[Documentation](https://leonardovida.github.io/drizzle-duckdb/) • [LLM Context](https://leonardovida.github.io/drizzle-duckdb/llms.txt) • [Examples](./example) • [Contributing](#contributing)
+
+</div>
+
+<br>
+
+**Drizzle DuckDB** brings [Drizzle ORM](https://orm.drizzle.team/) to [DuckDB](https://duckdb.org/), an in-process analytical database. You get Drizzle's type-safe query builder, automatic migrations, and full TypeScript inference while working with DuckDB's analytics engine.
+
+Works with local DuckDB files, in-memory databases, and [MotherDuck](https://motherduck.com/) cloud.
+
+> **Status:** Experimental. Core query building, migrations, and type inference work well. Some DuckDB-specific types and edge cases are still being refined.
+
+> **Note:** The main NPM package is now `@duckdbfan/drizzle-duckdb`.
+> The previous package `@leonardovida-md/drizzle-neo-duckdb` remains published but will be deprecated.
+> Updates will land in both packages through May 2, 2026.
+> After that date, only `@duckdbfan/drizzle-duckdb` will receive updates.
+
+Docs tip: every docs page has a **Markdown (raw)** button for LLM-friendly source.
+
+## Installation
+
+```bash
+bun add @duckdbfan/drizzle-duckdb @duckdb/node-api
+```
+
+```bash
+npm install @duckdbfan/drizzle-duckdb @duckdb/node-api
+```
+
+```bash
+pnpm add @duckdbfan/drizzle-duckdb @duckdb/node-api
+```
+
+Recommended client version is `@duckdb/node-api@1.4.4-r.1`, which bundles DuckDB 1.4.4.
+
+## Quick Start
+
+```typescript
+import { DuckDBInstance } from '@duckdb/node-api';
+import { drizzle } from '@duckdbfan/drizzle-duckdb';
+import { sql } from 'drizzle-orm';
+import { integer, text, pgTable } from 'drizzle-orm/pg-core';
+
+// Connect to DuckDB
+const instance = await DuckDBInstance.create(':memory:');
+const connection = await instance.connect();
+const db = drizzle(connection);
+
+// Define your schema
+const users = pgTable('users', {
+  id: integer('id').primaryKey(),
+  name: text('name').notNull(),
+  email: text('email').notNull(),
+});
+
+// Create table
+await db.execute(sql`
+  CREATE TABLE IF NOT EXISTS users (
+    id INTEGER PRIMARY KEY,
+    name TEXT NOT NULL,
+    email TEXT NOT NULL
+  )
+`);
+
+// Insert data
+await db.insert(users).values([
+  { id: 1, name: 'Alice', email: 'alice@example.com' },
+  { id: 2, name: 'Bob', email: 'bob@example.com' },
+]);
+
+// Query with full type safety
+const allUsers = await db.select().from(users);
+//    ^? { id: number; name: string; email: string }[]
+
+// Clean up
+connection.closeSync();
+```
+
+## Connecting to DuckDB
+
+### In-Memory Database
+
+```typescript
+const instance = await DuckDBInstance.create(':memory:');
+const connection = await instance.connect();
+const db = drizzle(connection);
+```
+
+### Local File
+
+```typescript
+const instance = await DuckDBInstance.create('./my-database.duckdb');
+const connection = await instance.connect();
+const db = drizzle(connection);
+```
+
+### MotherDuck Cloud
+
+```typescript
+const instance = await DuckDBInstance.create('md:', {
+  motherduck_token: process.env.MOTHERDUCK_TOKEN,
+});
+const connection = await instance.connect();
+const db = drizzle(connection);
+```
+
+### With Logging
+
+```typescript
+import { DefaultLogger } from 'drizzle-orm';
+
+const db = drizzle(connection, {
+  logger: new DefaultLogger(),
+});
+```
+
+> Tip: With connection strings (recommended), just pass the path: `const db = await drizzle(':memory:')`. Pooling is automatic.
+
+## Connection Pooling
+
+DuckDB executes one query per connection. The async `drizzle()` entrypoints create a pool automatically (default size: 4). Options:
+
+- Set pool size or MotherDuck preset: `drizzle('md:', { pool: { size: 8 } })` or `pool: 'jumbo'` / `pool: 'giga'`.
+- Disable pooling for single-connection workloads: `pool: false`.
+- Transactions pin one pooled connection for their entire lifetime; non-transactional queries still use the pool.
+- For tuning (acquire timeout, queue limits, idle/lifetime recycling), create the pool manually:
+
+```typescript
+import { DuckDBInstance } from '@duckdb/node-api';
+import {
+  createDuckDBConnectionPool,
+  drizzle,
+} from '@duckdbfan/drizzle-duckdb';
+
+const instance = await DuckDBInstance.create('md:', {
+  motherduck_token: process.env.MOTHERDUCK_TOKEN,
+});
+const pool = createDuckDBConnectionPool(instance, {
+  size: 8,
+  acquireTimeout: 20_000,
+  maxWaitingRequests: 200,
+  maxLifetimeMs: 10 * 60_000,
+  idleTimeoutMs: 60_000,
+});
+const db = drizzle(pool);
+```
+
+## Schema & Types
+
+- Use `drizzle-orm/pg-core` for schemas; DuckDB SQL is largely Postgres-compatible.
+- DuckDB-specific helpers: `duckDbList`, `duckDbArray`, `duckDbStruct`, `duckDbMap`, `duckDbJson`, `duckDbBlob`, `duckDbInet`, `duckDbInterval`, `duckDbTimestamp`, `duckDbDate`, `duckDbTime`.
+- Browser-safe imports live under `@duckdbfan/drizzle-duckdb/helpers` (introspection emits this path).
+
+See the [column types](https://leonardovida.github.io/drizzle-duckdb/api/columns) docs for full API.
+
+## Postgres Schema Compatibility
+
+Use `pgTable`, `pgSchema`, and other `drizzle-orm/pg-core` builders as you do with Postgres. The dialect keeps table definitions and relations intact while adapting queries to DuckDB.
+
+## Querying
+
+All standard Drizzle query methods work:
+
+```typescript
+// Select
+const users = await db
+  .select()
+  .from(usersTable)
+  .where(eq(usersTable.active, true));
+
+// Insert
+await db
+  .insert(usersTable)
+  .values({ name: 'Alice', email: 'alice@example.com' });
+
+// Insert with returning
+const inserted = await db
+  .insert(usersTable)
+  .values({ name: 'Bob' })
+  .returning({ id: usersTable.id });
+
+// Update
+await db
+  .update(usersTable)
+  .set({ name: 'Updated' })
+  .where(eq(usersTable.id, 1));
+
+// Delete
+await db.delete(usersTable).where(eq(usersTable.id, 1));
+```
+
+### Array Operations
+
+For DuckDB array operations, use the custom helpers instead of Postgres operators:
+
+```typescript
+import {
+  duckDbArrayContains,
+  duckDbArrayContained,
+  duckDbArrayOverlaps,
+} from '@duckdbfan/drizzle-duckdb';
+
+// Check if array contains all values
+const results = await db
+  .select()
+  .from(products)
+  .where(duckDbArrayContains(products.tags, ['electronics', 'sale']));
+
+// Check if array is contained by values
+const results = await db
+  .select()
+  .from(products)
+  .where(
+    duckDbArrayContained(products.tags, ['electronics', 'sale', 'featured'])
+  );
+
+// Check if arrays overlap
+const results = await db
+  .select()
+  .from(products)
+  .where(duckDbArrayOverlaps(products.tags, ['electronics', 'books']));
+```
+
+## Transactions
+
+```typescript
+await db.transaction(async (tx) => {
+  await tx.insert(accounts).values({ balance: 100 });
+  await tx.update(accounts).set({ balance: 50 }).where(eq(accounts.id, 1));
+});
+```
+
+> **Note:** DuckDB doesn't support `SAVEPOINT`, so nested transactions reuse the outer transaction context. Inner rollbacks will abort the entire transaction.
+
+## Migrations
+
+Apply SQL migration files using the `migrate` function:
+
+```typescript
+import { migrate } from '@duckdbfan/drizzle-duckdb';
+
+await migrate(db, { migrationsFolder: './drizzle' });
+```
+
+Migration metadata is stored in `drizzle.__drizzle_migrations` by default. See [Migrations Documentation](https://leonardovida.github.io/drizzle-duckdb/guide/migrations) for configuration options.
+
+## Schema Introspection
+
+Generate Drizzle schema from an existing DuckDB database:
+
+### CLI
+
+```bash
+bunx duckdb-introspect --url ./my-database.duckdb --out ./drizzle/schema.ts
+```
+
+### Programmatic
+
+```typescript
+import { introspect } from '@duckdbfan/drizzle-duckdb';
+
+const result = await introspect(db, {
+  schemas: ['public', 'analytics'],
+  includeViews: true,
+});
+
+console.log(result.files.schemaTs);
+```
+
+See [Introspection Documentation](https://leonardovida.github.io/drizzle-duckdb/guide/introspection) for all options.
+
+## Configuration Options
+
+```typescript
+const db = drizzle(connection, {
+  // Enable query logging
+  logger: new DefaultLogger(),
+
+  // Pool size/preset when using connection strings (default: 4). Set false to disable.
+  pool: { size: 8 },
+
+  // Throw on Postgres-style array literals like '{1,2,3}' (default: false)
+  rejectStringArrayLiterals: false,
+
+  // Pass your schema for relational queries
+  schema: mySchema,
+});
+```
+
+Postgres array operators (`@>`, `<@`, `&&`) are automatically rewritten to DuckDB's `array_has_*` functions via AST transformation.
+
+## Known Limitations
+
+This connector aims for compatibility with Drizzle's Postgres driver but has some differences:
+
+| Feature               | Status                                                                       |
+| --------------------- | ---------------------------------------------------------------------------- |
+| Basic CRUD operations | Full support                                                                 |
+| Joins and subqueries  | Full support                                                                 |
+| Transactions          | No savepoints (nested transactions reuse outer)                              |
+| JSON/JSONB columns    | Use `duckDbJson()` instead                                                   |
+| Prepared statements   | No statement caching                                                         |
+| Streaming results     | Chunked reads via `executeBatches()` / `executeArrow()`; no cursor streaming |
+| Concurrent queries    | One query per connection; use pooling for parallelism                        |
+
+See [Limitations Documentation](https://leonardovida.github.io/drizzle-duckdb/reference/limitations) for details.
+
+## Examples
+
+- **[MotherDuck NYC Taxi](./example/motherduck-nyc.ts)**: Query the built-in NYC taxi dataset from MotherDuck cloud
+- **[Analytics Dashboard](./example/analytics-dashboard.ts)**: Local in-memory analytics with DuckDB types and Parquet loading
+
+Run examples:
+
+```bash
+MOTHERDUCK_TOKEN=your_token bun example/motherduck-nyc.ts
+bun example/analytics-dashboard.ts
+```
 
 ## Contributing
-Contributions are welcome, although I may not be very responsive.
+
+Contributions are welcome! Please:
+
+1. Include tests for new features (`test/<feature>.test.ts`)
+2. Note any DuckDB-specific quirks you encounter
+3. Use a clear, imperative commit message
+
+```bash
+# Install dependencies
+bun install
+
+# Run tests
+bun test
+
+# Run tests with UI
+bun t
+
+# Build
+bun run build
+```
 
 ## License
-This project is licensed under the Apache License.
+
+[Apache-2.0](./LICENSE)

package/dist/bin/duckdb-introspect.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/client.d.ts

@@ -0,0 +1,42 @@
+import { type DuckDBConnection } from '@duckdb/node-api';
+import type { PreparedStatementCacheConfig } from './options.ts';
+export type DuckDBClientLike = DuckDBConnection | DuckDBConnectionPool;
+export type RowData = Record<string, unknown>;
+export interface DuckDBConnectionPool {
+    acquire(): Promise<DuckDBConnection>;
+    release(connection: DuckDBConnection): void | Promise<void>;
+    close?(): Promise<void> | void;
+}
+export declare function isPool(client: DuckDBClientLike): client is DuckDBConnectionPool;
+export interface ExecuteClientOptions {
+    prepareCache?: PreparedStatementCacheConfig;
+}
+export type ExecuteArraysResult = {
+    columns: string[];
+    rows: unknown[][];
+};
+export interface PrepareParamsOptions {
+    rejectStringArrayLiterals?: boolean;
+    warnOnStringArrayLiteral?: () => void;
+}
+export declare function prepareParams(params: unknown[], options?: PrepareParamsOptions): unknown[];
+export declare function closeClientConnection(connection: DuckDBConnection): Promise<void>;
+export declare function executeOnClient(client: DuckDBClientLike, query: string, params: unknown[], options?: ExecuteClientOptions): Promise<RowData[]>;
+export declare function executeArraysOnClient(client: DuckDBClientLike, query: string, params: unknown[], options?: ExecuteClientOptions): Promise<ExecuteArraysResult>;
+export interface ExecuteInBatchesOptions {
+    rowsPerChunk?: number;
+}
+export interface ExecuteBatchesRawChunk {
+    columns: string[];
+    rows: unknown[][];
+}
+/**
+ * Stream results from DuckDB in batches to avoid fully materializing rows in JS.
+ */
+export declare function executeInBatches(client: DuckDBClientLike, query: string, params: unknown[], options?: ExecuteInBatchesOptions): AsyncGenerator<RowData[], void, void>;
+export declare function executeInBatchesRaw(client: DuckDBClientLike, query: string, params: unknown[], options?: ExecuteInBatchesOptions): AsyncGenerator<ExecuteBatchesRawChunk, void, void>;
+/**
+ * Return columnar results when the underlying node-api exposes an Arrow/columnar API.
+ * Falls back to column-major JS arrays when Arrow is unavailable.
+ */
+export declare function executeArrowOnClient(client: DuckDBClientLike, query: string, params: unknown[]): Promise<unknown>;

package/dist/columns.d.ts

@@ -1,3 +1,6 @@
+import { type SQL } from 'drizzle-orm';
+import type { SQLWrapper } from 'drizzle-orm/sql/sql';
+import { type ListValueWrapper, type ArrayValueWrapper, type MapValueWrapper, type BlobValueWrapper, type JsonValueWrapper, type TimestampValueWrapper } from './value-wrappers-core.ts';
 type IntColType = 'SMALLINT' | 'INTEGER' | 'BIGINT' | 'HUGEINT' | 'USMALLINT' | 'UINTEGER' | 'UBIGINT' | 'UHUGEINT' | 'INT' | 'INT16' | 'INT32' | 'INT64' | 'INT128' | 'LONG' | 'VARINT';
 type FloatColType = 'FLOAT' | 'DOUBLE';
 type StringColType = 'STRING' | 'VARCHAR' | 'TEXT';
@@ -7,20 +10,58 @@ type DateColType = 'DATE' | 'TIME' | 'TIMETZ' | 'TIMESTAMP' | 'DATETIME' | 'TIME
 type AnyColType = IntColType | FloatColType | StringColType | BoolColType | DateColType | BlobColType;
 type ListColType = `${AnyColType}[]`;
 type ArrayColType = `${AnyColType}[${number}]`;
+type StructColType = `STRUCT (${string})`;
+type Primitive = AnyColType | ListColType | ArrayColType | StructColType;
+export declare function coerceArrayString(value: string): unknown[] | undefined;
+export declare function formatLiteral(value: unknown, typeHint?: string): string;
+export declare function buildListLiteral(values: unknown[], elementType?: string): SQL;
+export declare function buildStructLiteral(value: Record<string, unknown>, schema?: Record<string, Primitive>): SQL;
+export declare function buildMapLiteral(value: Record<string, unknown>, valueType?: string): SQL;
+export declare const duckDbList: <TData = unknown>(name: string, elementType: AnyColType) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
+    name: string;
+    dataType: "custom";
+    columnType: "PgCustomColumn";
+    data: TData[];
+    driverParam: string | ListValueWrapper | unknown[];
+    enumValues: undefined;
+}>;
+export declare const duckDbArray: <TData = unknown>(name: string, elementType: AnyColType, fixedLength?: number) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
+    name: string;
+    dataType: "custom";
+    columnType: "PgCustomColumn";
+    data: TData[];
+    driverParam: string | unknown[] | ArrayValueWrapper;
+    enumValues: undefined;
+}>;
 export declare const duckDbMap: <TData extends Record<string, any>>(name: string, valueType: AnyColType | ListColType | ArrayColType) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
     name: string;
     dataType: "custom";
     columnType: "PgCustomColumn";
     data: TData;
-    driverParam: string;
+    driverParam: MapValueWrapper | TData;
     enumValues: undefined;
 }>;
-export declare const duckDbStruct: <TData extends Record<string, any>>(name: string, schema: Record<string, AnyColType | ListColType | ArrayColType>) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
+export declare const duckDbStruct: <TData extends Record<string, any>>(name: string, schema: Record<string, Primitive>) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
     name: string;
     dataType: "custom";
     columnType: "PgCustomColumn";
     data: TData;
-    driverParam: string;
+    driverParam: TData;
+    enumValues: undefined;
+}>;
+/**
+ * JSON column type that wraps values and delays JSON.stringify() to binding time.
+ * This ensures consistent handling with other wrapped types.
+ *
+ * Note: DuckDB stores JSON as VARCHAR internally, so the final binding
+ * is always a stringified JSON value.
+ */
+export declare const duckDbJson: <TData = unknown>(name: string) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
+    name: string;
+    dataType: "custom";
+    columnType: "PgCustomColumn";
+    data: TData;
+    driverParam: string | JsonValueWrapper | SQL<unknown>;
     enumValues: undefined;
 }>;
 export declare const duckDbBlob: {
@@ -28,25 +69,75 @@ export declare const duckDbBlob: {
         name: "";
         dataType: "custom";
         columnType: "PgCustomColumn";
-        data: Buffer;
-        driverParam: unknown;
+        data: Buffer<ArrayBufferLike>;
+        driverParam: BlobValueWrapper;
         enumValues: undefined;
     }>;
     <TConfig extends Record<string, any>>(fieldConfig?: TConfig | undefined): import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
         name: "";
         dataType: "custom";
         columnType: "PgCustomColumn";
-        data: Buffer;
-        driverParam: unknown;
+        data: Buffer<ArrayBufferLike>;
+        driverParam: BlobValueWrapper;
         enumValues: undefined;
     }>;
     <TName extends string>(dbName: TName, fieldConfig?: unknown): import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
         name: TName;
         dataType: "custom";
         columnType: "PgCustomColumn";
-        data: Buffer;
-        driverParam: unknown;
+        data: Buffer<ArrayBufferLike>;
+        driverParam: BlobValueWrapper;
         enumValues: undefined;
     }>;
 };
+export declare const duckDbInet: (name: string) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
+    name: string;
+    dataType: "custom";
+    columnType: "PgCustomColumn";
+    data: string;
+    driverParam: string;
+    enumValues: undefined;
+}>;
+export declare const duckDbInterval: (name: string) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
+    name: string;
+    dataType: "custom";
+    columnType: "PgCustomColumn";
+    data: string;
+    driverParam: string;
+    enumValues: undefined;
+}>;
+type TimestampMode = 'date' | 'string';
+interface TimestampOptions {
+    withTimezone?: boolean;
+    mode?: TimestampMode;
+    precision?: number;
+    bindMode?: 'auto' | 'bind' | 'literal';
+}
+export declare const duckDbTimestamp: (name: string, options?: TimestampOptions) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
+    name: string;
+    dataType: "custom";
+    columnType: "PgCustomColumn";
+    data: string | Date;
+    driverParam: string | TimestampValueWrapper | Date | SQL<unknown>;
+    enumValues: undefined;
+}>;
+export declare const duckDbDate: (name: string) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
+    name: string;
+    dataType: "custom";
+    columnType: "PgCustomColumn";
+    data: string | Date;
+    driverParam: string | Date;
+    enumValues: undefined;
+}>;
+export declare const duckDbTime: (name: string) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
+    name: string;
+    dataType: "custom";
+    columnType: "PgCustomColumn";
+    data: string;
+    driverParam: string | bigint;
+    enumValues: undefined;
+}>;
+export declare function duckDbArrayContains(column: SQLWrapper, values: unknown[] | SQLWrapper): SQL;
+export declare function duckDbArrayContained(column: SQLWrapper, values: unknown[] | SQLWrapper): SQL;
+export declare function duckDbArrayOverlaps(column: SQLWrapper, values: unknown[] | SQLWrapper): SQL;
 export {};

package/dist/dialect.d.ts

@@ -1,9 +1,34 @@
 import { entityKind } from 'drizzle-orm/entity';
 import type { MigrationConfig, MigrationMeta } from 'drizzle-orm/migrator';
 import { PgDialect, PgSession } from 'drizzle-orm/pg-core';
-import { type DriverValueEncoder, type QueryTypingsValue } from 'drizzle-orm';
+import { SQL, type DriverValueEncoder, type QueryTypingsValue } from 'drizzle-orm';
+import type { QueryWithTypings } from 'drizzle-orm/sql/sql';
 export declare class DuckDBDialect extends PgDialect {
     static readonly [entityKind]: string;
-    migrate(migrations: MigrationMeta[], session: PgSession, config: MigrationConfig): Promise<void>;
+    private hasPgJsonColumn;
+    private savepointsSupported;
+    /**
+     * Reset the PG JSON detection flag. Should be called before preparing a new query.
+     */
+    resetPgJsonFlag(): void;
+    /**
+     * Mark that a PG JSON/JSONB column was detected during query preparation.
+     */
+    markPgJsonDetected(): void;
+    assertNoPgJsonColumns(): void;
+    /**
+     * Check if savepoints are known to be unsupported for this dialect instance.
+     */
+    areSavepointsUnsupported(): boolean;
+    /**
+     * Mark that savepoints are supported for this dialect instance.
+     */
+    markSavepointsSupported(): void;
+    /**
+     * Mark that savepoints are not supported for this dialect instance.
+     */
+    markSavepointsUnsupported(): void;
+    migrate(migrations: MigrationMeta[], session: PgSession, config: MigrationConfig | string): Promise<void>;
     prepareTyping(encoder: DriverValueEncoder<unknown, unknown>): QueryTypingsValue;
+    sqlToQuery(sqlObj: SQL, invokeSource?: 'indexes' | undefined): QueryWithTypings;
 }