@leonardovida-md/drizzle-neo-duckdb 1.0.3 → 1.1.1

package/README.md

@@ -7,7 +7,7 @@
 [![npm version](https://img.shields.io/npm/v/@leonardovida-md/drizzle-neo-duckdb)](https://www.npmjs.com/package/@leonardovida-md/drizzle-neo-duckdb)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-[Documentation](https://leonardovida-md.github.io/drizzle-neo-duckdb/) • [Examples](./example) • [Contributing](#contributing)
+[Documentation](https://leonardovida.github.io/drizzle-neo-duckdb/) • [LLM Context](https://leonardovida.github.io/drizzle-neo-duckdb/llms.txt) • [Examples](./example) • [Contributing](#contributing)
 
 </div>
 
@@ -19,6 +19,8 @@ Works with local DuckDB files, in-memory databases, and [MotherDuck](https://mot
 
 > **Status:** Experimental. Core query building, migrations, and type inference work well. Some DuckDB-specific types and edge cases are still being refined.
 
+Docs tip: every docs page has a **Markdown (raw)** button for LLM-friendly source.
+
 ## Installation
 
 ```bash
@@ -188,7 +190,20 @@ const products = pgTable('products', {
 });
 ```
 
-See [Column Types Documentation](https://leonardovida-md.github.io/drizzle-neo-duckdb/api/columns) for complete reference.
+See [Column Types Documentation](https://leonardovida.github.io/drizzle-neo-duckdb/api/columns) for complete reference.
+
+### Client-Safe Imports (schemas, drizzle-zod, trpc)
+
+When generated schemas are consumed in client bundles, import the helpers from the browser-safe subpath to avoid pulling the native DuckDB bindings:
+
+```typescript
+import {
+  duckDbJson,
+  duckDbList,
+} from '@leonardovida-md/drizzle-neo-duckdb/helpers';
+```
+
+The introspection CLI now emits this import path by default. You can still override `importBasePath` if you need the old root import.
 
 ## Querying
 
@@ -275,7 +290,7 @@ import { migrate } from '@leonardovida-md/drizzle-neo-duckdb';
 await migrate(db, { migrationsFolder: './drizzle' });
 ```
 
-Migration metadata is stored in `drizzle.__drizzle_migrations` by default. See [Migrations Documentation](https://leonardovida-md.github.io/drizzle-neo-duckdb/guide/migrations) for configuration options.
+Migration metadata is stored in `drizzle.__drizzle_migrations` by default. See [Migrations Documentation](https://leonardovida.github.io/drizzle-neo-duckdb/guide/migrations) for configuration options.
 
 ## Schema Introspection
 
@@ -300,7 +315,7 @@ const result = await introspect(db, {
 console.log(result.files.schemaTs);
 ```
 
-See [Introspection Documentation](https://leonardovida-md.github.io/drizzle-neo-duckdb/guide/introspection) for all options.
+See [Introspection Documentation](https://leonardovida.github.io/drizzle-neo-duckdb/guide/introspection) for all options.
 
 ## Configuration Options
 
@@ -333,7 +348,7 @@ This connector aims for compatibility with Drizzle's Postgres driver but has som
 | Prepared statements   | No statement caching                                       |
 | Streaming results     | Materialized by default; use `executeBatches()` for chunks |
 
-See [Limitations Documentation](https://leonardovida-md.github.io/drizzle-neo-duckdb/guide/limitations) for details.
+See [Limitations Documentation](https://leonardovida.github.io/drizzle-neo-duckdb/guide/limitations) for details.
 
 ## Examples
 

package/dist/client.d.ts

@@ -1,6 +1,12 @@
 import { type DuckDBConnection } from '@duckdb/node-api';
-export type DuckDBClientLike = DuckDBConnection;
+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 PrepareParamsOptions {
     rejectStringArrayLiterals?: boolean;
     warnOnStringArrayLiteral?: () => void;

package/dist/columns.d.ts

@@ -1,6 +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 } from './value-wrappers.ts';
+import { type ListValueWrapper, type ArrayValueWrapper, type MapValueWrapper, type BlobValueWrapper, type JsonValueWrapper } 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';
@@ -12,6 +12,11 @@ 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";

package/dist/dialect.d.ts

@@ -5,7 +5,28 @@ import { type DriverValueEncoder, type QueryTypingsValue } from 'drizzle-orm';
 export declare class DuckDBDialect extends PgDialect {
     static readonly [entityKind]: string;
     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;
 }

package/dist/driver.d.ts

@@ -1,3 +1,4 @@
+import { DuckDBInstance } from '@duckdb/node-api';
 import { entityKind } from 'drizzle-orm/entity';
 import type { Logger } from 'drizzle-orm/logger';
 import { PgDatabase } from 'drizzle-orm/pg-core/db';
@@ -10,6 +11,7 @@ import { DuckDBSession } from './session.ts';
 import { DuckDBDialect } from './dialect.ts';
 import { DuckDBSelectBuilder } from './select-builder.ts';
 import type { ExecuteInBatchesOptions, RowData } from './client.ts';
+import { type DuckDBPoolConfig, type PoolPreset } from './pool.ts';
 export interface PgDriverOptions {
     logger?: Logger;
     rewriteArrays?: boolean;
@@ -23,16 +25,46 @@ export declare class DuckDBDriver {
     constructor(client: DuckDBClientLike, dialect: DuckDBDialect, options?: PgDriverOptions);
     createSession(schema: RelationalSchemaConfig<TablesRelationalConfig> | undefined): DuckDBSession<Record<string, unknown>, TablesRelationalConfig>;
 }
+/** Connection configuration when using path-based connection */
+export interface DuckDBConnectionConfig {
+    /** Database path: ':memory:', './file.duckdb', 'md:', 'md:database' */
+    path: string;
+    /** DuckDB instance options (e.g., motherduck_token) */
+    options?: Record<string, string>;
+}
 export interface DuckDBDrizzleConfig<TSchema extends Record<string, unknown> = Record<string, never>> extends DrizzleConfig<TSchema> {
     rewriteArrays?: boolean;
     rejectStringArrayLiterals?: boolean;
+    /** Pool configuration. Use preset name, size config, or false to disable. */
+    pool?: DuckDBPoolConfig | PoolPreset | false;
+}
+export interface DuckDBDrizzleConfigWithConnection<TSchema extends Record<string, unknown> = Record<string, never>> extends DuckDBDrizzleConfig<TSchema> {
+    /** Connection string or config object */
+    connection: string | DuckDBConnectionConfig;
+}
+export interface DuckDBDrizzleConfigWithClient<TSchema extends Record<string, unknown> = Record<string, never>> extends DuckDBDrizzleConfig<TSchema> {
+    /** Explicit client (connection or pool) */
+    client: DuckDBClientLike;
 }
+export declare function drizzle<TSchema extends Record<string, unknown> = Record<string, never>>(connectionString: string): Promise<DuckDBDatabase<TSchema, ExtractTablesWithRelations<TSchema>>>;
+export declare function drizzle<TSchema extends Record<string, unknown> = Record<string, never>>(connectionString: string, config: DuckDBDrizzleConfig<TSchema>): Promise<DuckDBDatabase<TSchema, ExtractTablesWithRelations<TSchema>>>;
+export declare function drizzle<TSchema extends Record<string, unknown> = Record<string, never>>(config: DuckDBDrizzleConfigWithConnection<TSchema>): Promise<DuckDBDatabase<TSchema, ExtractTablesWithRelations<TSchema>>>;
+export declare function drizzle<TSchema extends Record<string, unknown> = Record<string, never>>(config: DuckDBDrizzleConfigWithClient<TSchema>): DuckDBDatabase<TSchema, ExtractTablesWithRelations<TSchema>>;
 export declare function drizzle<TSchema extends Record<string, unknown> = Record<string, never>>(client: DuckDBClientLike, config?: DuckDBDrizzleConfig<TSchema>): DuckDBDatabase<TSchema, ExtractTablesWithRelations<TSchema>>;
 export declare class DuckDBDatabase<TFullSchema extends Record<string, unknown> = Record<string, never>, TSchema extends TablesRelationalConfig = ExtractTablesWithRelations<TFullSchema>> extends PgDatabase<DuckDBQueryResultHKT, TFullSchema, TSchema> {
     readonly dialect: DuckDBDialect;
     readonly session: DuckDBSession<TFullSchema, TSchema>;
     static readonly [entityKind]: string;
-    constructor(dialect: DuckDBDialect, session: DuckDBSession<TFullSchema, TSchema>, schema: RelationalSchemaConfig<TSchema> | undefined);
+    /** The underlying connection or pool */
+    readonly $client: DuckDBClientLike;
+    /** The DuckDB instance (when created from connection string) */
+    readonly $instance?: DuckDBInstance;
+    constructor(dialect: DuckDBDialect, session: DuckDBSession<TFullSchema, TSchema>, schema: RelationalSchemaConfig<TSchema> | undefined, client: DuckDBClientLike, instance?: DuckDBInstance);
+    /**
+     * Close the database connection pool and instance.
+     * Should be called when shutting down the application.
+     */
+    close(): Promise<void>;
     select(): DuckDBSelectBuilder<undefined>;
     select<TSelection extends SelectedFields>(fields: TSelection): DuckDBSelectBuilder<TSelection>;
     executeBatches<T extends RowData = RowData>(query: SQL, options?: ExecuteInBatchesOptions): AsyncGenerator<T[], void, void>;