@leonardovida-md/drizzle-neo-duckdb 1.0.0

package/src/columns.ts

@@ -0,0 +1,429 @@
+import { sql, type SQL } from 'drizzle-orm';
+import type { SQLWrapper } from 'drizzle-orm/sql/sql';
+import { customType } from 'drizzle-orm/pg-core';
+
+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';
+
+type BoolColType = 'BOOLEAN' | 'BOOL';
+
+type BlobColType = 'BLOB' | 'BYTEA' | 'VARBINARY';
+
+type DateColType =
+  | 'DATE'
+  | 'TIME'
+  | 'TIMETZ'
+  | 'TIMESTAMP'
+  | 'DATETIME'
+  | 'TIMESTAMPTZ'
+  | 'TIMESTAMP_MS'
+  | 'TIMESTAMP_S';
+
+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;
+
+function coerceArrayString(value: string): unknown[] | undefined {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return [];
+  }
+  if (trimmed.startsWith('[')) {
+    try {
+      return JSON.parse(trimmed) as unknown[];
+    } catch {
+      return undefined;
+    }
+  }
+  if (trimmed.startsWith('{') && trimmed.endsWith('}')) {
+    try {
+      const json = trimmed.replace(/{/g, '[').replace(/}/g, ']');
+      return JSON.parse(json) as unknown[];
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+function formatLiteral(value: unknown, typeHint?: string): string {
+  if (value === null || value === undefined) {
+    return 'NULL';
+  }
+
+  const upperType = typeHint?.toUpperCase() ?? '';
+  if (value instanceof Date) {
+    return `'${value.toISOString()}'`;
+  }
+
+  if (typeof value === 'number' || typeof value === 'bigint') {
+    return value.toString();
+  }
+
+  if (typeof value === 'boolean') {
+    return value ? 'TRUE' : 'FALSE';
+  }
+
+  const str =
+    typeof value === 'string' ? value : JSON.stringify(value) ?? String(value);
+
+  const escaped = str.replace(/'/g, "''");
+  // Simple quoting based on hint.
+  if (
+    upperType.includes('CHAR') ||
+    upperType.includes('TEXT') ||
+    upperType.includes('STRING') ||
+    upperType.includes('VARCHAR')
+  ) {
+    return `'${escaped}'`;
+  }
+
+  return `'${escaped}'`;
+}
+
+function buildListLiteral(values: unknown[], elementType?: string): SQL {
+  if (values.length === 0) {
+    return sql`[]`;
+  }
+  const chunks = values.map((v) =>
+    typeof v === 'object' && !Array.isArray(v)
+      ? sql`${v as SQLWrapper}`
+      : sql.raw(formatLiteral(v, elementType))
+  );
+  return sql`list_value(${sql.join(chunks, sql.raw(', '))})`;
+}
+
+function buildStructLiteral(
+  value: Record<string, unknown>,
+  schema?: Record<string, Primitive>
+): SQL {
+  const parts = Object.entries(value).map(([key, val]) => {
+    const typeHint = schema?.[key];
+    if (Array.isArray(val)) {
+      const inner =
+        typeof typeHint === 'string' && typeHint.endsWith('[]')
+          ? typeHint.slice(0, -2)
+          : undefined;
+
+      return sql`${sql.identifier(key)} := ${buildListLiteral(val, inner)}`;
+    }
+    return sql`${sql.identifier(key)} := ${val}`;
+  });
+  return sql`struct_pack(${sql.join(parts, sql.raw(', '))})`;
+}
+
+function buildMapLiteral(value: Record<string, unknown>, valueType?: string): SQL {
+  const keys = Object.keys(value);
+  const vals = Object.values(value);
+  const keyList = buildListLiteral(keys, 'TEXT');
+  const valList = buildListLiteral(
+    vals,
+    valueType?.endsWith('[]') ? valueType.slice(0, -2) : valueType
+  );
+  return sql`map(${keyList}, ${valList})`;
+}
+
+export const duckDbList = <TData = unknown>(
+  name: string,
+  elementType: AnyColType
+) =>
+  customType<{ data: TData[]; driverData: SQL | unknown[] | string }>({
+    dataType() {
+      return `${elementType}[]`;
+    },
+    toDriver(value: TData[]) {
+      return buildListLiteral(value, elementType);
+    },
+    fromDriver(value: unknown[] | string | SQL): TData[] {
+      if (Array.isArray(value)) {
+        return value as TData[];
+      }
+      if (typeof value === 'string') {
+        const parsed = coerceArrayString(value);
+        if (parsed) {
+          return parsed as TData[];
+        }
+      }
+      return [] as TData[];
+    },
+  })(name);
+
+export const duckDbArray = <TData = unknown>(
+  name: string,
+  elementType: AnyColType,
+  fixedLength?: number
+) =>
+  customType<{ data: TData[]; driverData: SQL | unknown[] | string }>({
+    dataType() {
+      return fixedLength
+        ? `${elementType}[${fixedLength}]`
+        : `${elementType}[]`;
+    },
+    toDriver(value: TData[]) {
+      return buildListLiteral(value, elementType);
+    },
+    fromDriver(value: unknown[] | string | SQL): TData[] {
+      if (Array.isArray(value)) {
+        return value as TData[];
+      }
+      if (typeof value === 'string') {
+        const parsed = coerceArrayString(value);
+        if (parsed) {
+          return parsed as TData[];
+        }
+      }
+      return [] as TData[];
+    },
+  })(name);
+
+export const duckDbMap = <TData extends Record<string, any>>(
+  name: string,
+  valueType: AnyColType | ListColType | ArrayColType
+) =>
+  customType<{ data: TData; driverData: TData }>({
+  dataType() {
+      return `MAP (STRING, ${valueType})`;
+    },
+    toDriver(value: TData) {
+      return buildMapLiteral(value, valueType);
+    },
+    fromDriver(value: TData): TData {
+      return value;
+    },
+  })(name);
+
+export const duckDbStruct = <TData extends Record<string, any>>(
+  name: string,
+  schema: Record<string, Primitive>
+) =>
+  customType<{ data: TData; driverData: TData }>({
+    dataType() {
+      const fields = Object.entries(schema).map(
+        ([key, type]) => `${key} ${type}`
+      );
+
+      return `STRUCT (${fields.join(', ')})`;
+    },
+    toDriver(value: TData) {
+      return buildStructLiteral(value, schema);
+    },
+    fromDriver(value: TData | string): TData {
+      if (typeof value === 'string') {
+        try {
+          return JSON.parse(value) as TData;
+        } catch {
+          return value as unknown as TData;
+        }
+      }
+      return value;
+    },
+  })(name);
+
+export const duckDbJson = <TData = unknown>(name: string) =>
+  customType<{ data: TData; driverData: SQL | string }>({
+    dataType() {
+      return 'JSON';
+    },
+    toDriver(value: TData) {
+      if (typeof value === 'string') {
+        return value;
+      }
+      if (
+        value !== null &&
+        typeof value === 'object' &&
+        'queryChunks' in (value as Record<string, unknown>)
+      ) {
+        return value as unknown as SQL;
+      }
+      return JSON.stringify(value ?? null);
+    },
+    fromDriver(value: SQL | string) {
+      if (typeof value !== 'string') {
+        return value as unknown as TData;
+      }
+      const trimmed = value.trim();
+      if (!trimmed) {
+        return value as unknown as TData;
+      }
+      try {
+        return JSON.parse(trimmed) as TData;
+      } catch {
+        return value as unknown as TData;
+      }
+    },
+  })(name);
+
+export const duckDbBlob = customType<{
+  data: Buffer;
+  default: false;
+}>({
+  dataType() {
+    return 'BLOB';
+  },
+  toDriver(value: Buffer) {
+    const hexString = value.toString('hex');
+    return sql`from_hex(${hexString})`;
+  },
+});
+
+export const duckDbInet = (name: string) =>
+  customType<{ data: string; driverData: string }>({
+    dataType() {
+      return 'INET';
+    },
+    toDriver(value: string) {
+      return value;
+    },
+  })(name);
+
+export const duckDbInterval = (name: string) =>
+  customType<{ data: string; driverData: string }>({
+    dataType() {
+      return 'INTERVAL';
+    },
+    toDriver(value: string) {
+      return value;
+    },
+  })(name);
+
+type TimestampMode = 'date' | 'string';
+
+interface TimestampOptions {
+  withTimezone?: boolean;
+  mode?: TimestampMode;
+  precision?: number;
+}
+
+export const duckDbTimestamp = (
+  name: string,
+  options: TimestampOptions = {}
+) =>
+  customType<{
+    data: Date | string;
+    driverData: SQL | string | Date;
+  }>({
+    dataType() {
+      if (options.withTimezone) {
+        return 'TIMESTAMPTZ';
+      }
+      const precision = options.precision ? `(${options.precision})` : '';
+      return `TIMESTAMP${precision}`;
+    },
+    toDriver(value: Date | string) {
+      const iso = value instanceof Date ? value.toISOString() : value;
+      const normalized = iso.replace('T', ' ').replace('Z', '+00');
+      const typeKeyword = options.withTimezone ? 'TIMESTAMPTZ' : 'TIMESTAMP';
+      return sql.raw(`${typeKeyword} '${normalized}'`);
+    },
+    fromDriver(value: Date | string | SQL) {
+      if (options.mode === 'string') {
+        if (value instanceof Date) {
+          return value.toISOString().replace('T', ' ').replace('Z', '+00');
+        }
+        return typeof value === 'string' ? value : value.toString();
+      }
+      if (value instanceof Date) {
+        return value;
+      }
+      const stringValue =
+        typeof value === 'string' ? value : value.toString();
+      const hasOffset =
+        stringValue.endsWith('Z') ||
+        /[+-]\d{2}:?\d{2}$/.test(stringValue);
+      const normalized = hasOffset
+        ? stringValue.replace(' ', 'T')
+        : `${stringValue.replace(' ', 'T')}Z`;
+      return new Date(normalized);
+    },
+  })(name);
+
+export const duckDbDate = (name: string) =>
+  customType<{ data: string | Date; driverData: string | Date }>({
+    dataType() {
+      return 'DATE';
+    },
+    toDriver(value: string | Date) {
+      return value;
+    },
+    fromDriver(value: string | Date) {
+        const str =
+          value instanceof Date
+            ? value.toISOString().slice(0, 10)
+            : value;
+        return str;
+    },
+  })(name);
+
+export const duckDbTime = (name: string) =>
+  customType<{ data: string; driverData: string | bigint }>({
+    dataType() {
+      return 'TIME';
+    },
+    toDriver(value: string) {
+      return value;
+    },
+    fromDriver(value: string | bigint) {
+      if (typeof value === 'bigint') {
+        const totalMillis = Number(value) / 1000;
+        const date = new Date(totalMillis);
+        return date.toISOString().split('T')[1]!.replace('Z', '');
+      }
+      return value;
+    },
+  })(name);
+
+function toListValue(values: (unknown | SQLWrapper)[]): SQL {
+  return buildListLiteral(values);
+}
+
+export function duckDbArrayContains(
+  column: SQLWrapper,
+  values: unknown[] | SQLWrapper
+): SQL {
+  const rhs = Array.isArray(values) ? toListValue(values) : values;
+  return sql`array_has_all(${column}, ${rhs})`;
+}
+
+export function duckDbArrayContained(
+  column: SQLWrapper,
+  values: unknown[] | SQLWrapper
+): SQL {
+  const rhs = Array.isArray(values) ? toListValue(values) : values;
+  return sql`array_has_all(${rhs}, ${column})`;
+}
+
+export function duckDbArrayOverlaps(
+  column: SQLWrapper,
+  values: unknown[] | SQLWrapper
+): SQL {
+  const rhs = Array.isArray(values) ? toListValue(values) : values;
+  return sql`array_has_any(${column}, ${rhs})`;
+}

package/src/dialect.ts

@@ -0,0 +1,136 @@
+import { entityKind, is } from 'drizzle-orm/entity';
+import type { MigrationConfig, MigrationMeta } from 'drizzle-orm/migrator';
+import {
+  PgDate,
+  PgDateString,
+  PgDialect,
+  PgJson,
+  PgJsonb,
+  PgNumeric,
+  PgSession,
+  PgTime,
+  PgTimestamp,
+  PgTimestampString,
+  PgUUID,
+} from 'drizzle-orm/pg-core';
+import {
+  sql,
+  type DriverValueEncoder,
+  type QueryTypingsValue,
+} from 'drizzle-orm';
+
+export class DuckDBDialect extends PgDialect {
+  static readonly [entityKind]: string = 'DuckDBPgDialect';
+  private hasPgJsonColumn = false;
+
+  assertNoPgJsonColumns(): void {
+    if (this.hasPgJsonColumn) {
+      throw new Error(
+        'Pg JSON/JSONB columns are not supported in DuckDB. Replace them with duckDbJson() to use DuckDB’s native JSON type.'
+      );
+    }
+  }
+
+  override async migrate(
+    migrations: MigrationMeta[],
+    session: PgSession,
+    config: MigrationConfig | string
+  ): Promise<void> {
+    const migrationConfig: MigrationConfig =
+      typeof config === 'string' ? { migrationsFolder: config } : config;
+
+    const migrationsSchema = migrationConfig.migrationsSchema ?? 'drizzle';
+    const migrationsTable =
+      migrationConfig.migrationsTable ?? '__drizzle_migrations';
+    const migrationsSequence = `${migrationsTable}_id_seq`;
+    const legacySequence = 'migrations_pk_seq';
+
+    const escapeIdentifier = (value: string) => value.replace(/"/g, '""');
+    const sequenceLiteral = `"${escapeIdentifier(
+      migrationsSchema
+    )}"."${escapeIdentifier(migrationsSequence)}"`;
+
+    const migrationTableCreate = sql`
+      CREATE TABLE IF NOT EXISTS ${sql.identifier(migrationsSchema)}.${sql.identifier(
+      migrationsTable
+    )} (
+        id integer PRIMARY KEY default nextval('${sql.raw(sequenceLiteral)}'),
+        hash text NOT NULL,
+        created_at bigint
+      )
+    `;
+
+    await session.execute(
+      sql`CREATE SCHEMA IF NOT EXISTS ${sql.identifier(migrationsSchema)}`
+    );
+    await session.execute(
+      sql`CREATE SEQUENCE IF NOT EXISTS ${sql.identifier(
+        migrationsSchema
+      )}.${sql.identifier(migrationsSequence)}`
+    );
+    if (legacySequence !== migrationsSequence) {
+      await session.execute(
+        sql`CREATE SEQUENCE IF NOT EXISTS ${sql.identifier(
+          migrationsSchema
+        )}.${sql.identifier(legacySequence)}`
+      );
+    }
+    await session.execute(migrationTableCreate);
+
+    const dbMigrations = await session.all<{
+      id: number;
+      hash: string;
+      created_at: string;
+    }>(
+      sql`select id, hash, created_at from ${sql.identifier(
+        migrationsSchema
+      )}.${sql.identifier(migrationsTable)} order by created_at desc limit 1`
+    );
+
+    const lastDbMigration = dbMigrations[0];
+
+    await session.transaction(async (tx) => {
+      for await (const migration of migrations) {
+        if (
+          !lastDbMigration ||
+          Number(lastDbMigration.created_at) < migration.folderMillis
+        ) {
+          for (const stmt of migration.sql) {
+            await tx.execute(sql.raw(stmt));
+          }
+
+          await tx.execute(
+            sql`insert into ${sql.identifier(
+              migrationsSchema
+            )}.${sql.identifier(
+              migrationsTable
+            )} ("hash", "created_at") values(${migration.hash}, ${
+              migration.folderMillis
+            })`
+          );
+        }
+      }
+    });
+  }
+
+  override prepareTyping(
+    encoder: DriverValueEncoder<unknown, unknown>
+  ): QueryTypingsValue {
+    if (is(encoder, PgJsonb) || is(encoder, PgJson)) {
+      this.hasPgJsonColumn = true;
+      return 'none';
+    } else if (is(encoder, PgNumeric)) {
+      return 'decimal';
+    } else if (is(encoder, PgTime)) {
+      return 'time';
+    } else if (is(encoder, PgTimestamp) || is(encoder, PgTimestampString)) {
+      return 'timestamp';
+    } else if (is(encoder, PgDate) || is(encoder, PgDateString)) {
+      return 'date';
+    } else if (is(encoder, PgUUID)) {
+      return 'uuid';
+    } else {
+      return 'none';
+    }
+  }
+}

package/src/driver.ts

@@ -0,0 +1,131 @@
+import { entityKind } from 'drizzle-orm/entity';
+import type { Logger } from 'drizzle-orm/logger';
+import { DefaultLogger } from 'drizzle-orm/logger';
+import { PgDatabase } from 'drizzle-orm/pg-core/db';
+import type { SelectedFields } from 'drizzle-orm/pg-core/query-builders';
+import type { PgSession } from 'drizzle-orm/pg-core';
+import {
+  createTableRelationsHelpers,
+  extractTablesRelationalConfig,
+  type ExtractTablesWithRelations,
+  type RelationalSchemaConfig,
+  type TablesRelationalConfig,
+} from 'drizzle-orm/relations';
+import { type DrizzleConfig } from 'drizzle-orm/utils';
+import type {
+  DuckDBClientLike,
+  DuckDBQueryResultHKT,
+  DuckDBTransaction,
+} from './session.ts';
+import { DuckDBSession } from './session.ts';
+import { DuckDBDialect } from './dialect.ts';
+import { DuckDBSelectBuilder } from './select-builder.ts';
+import { aliasFields } from './sql/selection.ts';
+
+export interface PgDriverOptions {
+  logger?: Logger;
+  rewriteArrays?: boolean;
+  rejectStringArrayLiterals?: boolean;
+}
+
+export class DuckDBDriver {
+  static readonly [entityKind]: string = 'DuckDBDriver';
+
+  constructor(
+    private client: DuckDBClientLike,
+    private dialect: DuckDBDialect,
+    private options: PgDriverOptions = {}
+  ) {}
+
+  createSession(
+    schema: RelationalSchemaConfig<TablesRelationalConfig> | undefined
+  ): DuckDBSession<Record<string, unknown>, TablesRelationalConfig> {
+    return new DuckDBSession(this.client, this.dialect, schema, {
+      logger: this.options.logger,
+      rewriteArrays: this.options.rewriteArrays,
+      rejectStringArrayLiterals: this.options.rejectStringArrayLiterals,
+    });
+  }
+}
+
+export interface DuckDBDrizzleConfig<
+  TSchema extends Record<string, unknown> = Record<string, never>
+> extends DrizzleConfig<TSchema> {
+  rewriteArrays?: boolean;
+  rejectStringArrayLiterals?: boolean;
+}
+
+export function drizzle<
+  TSchema extends Record<string, unknown> = Record<string, never>
+>(
+  client: DuckDBClientLike,
+  config: DuckDBDrizzleConfig<TSchema> = {}
+): DuckDBDatabase<TSchema, ExtractTablesWithRelations<TSchema>> {
+  const dialect = new DuckDBDialect();
+
+  const logger =
+    config.logger === true ? new DefaultLogger() : config.logger || undefined;
+
+  let schema: RelationalSchemaConfig<TablesRelationalConfig> | undefined;
+
+  if (config.schema) {
+    const tablesConfig = extractTablesRelationalConfig(
+      config.schema,
+      createTableRelationsHelpers
+    );
+    schema = {
+      fullSchema: config.schema,
+      schema: tablesConfig.tables,
+      tableNamesMap: tablesConfig.tableNamesMap,
+    };
+  }
+
+  const driver = new DuckDBDriver(client, dialect, {
+    logger,
+    rewriteArrays: config.rewriteArrays,
+    rejectStringArrayLiterals: config.rejectStringArrayLiterals,
+  });
+  const session = driver.createSession(schema);
+
+  return new DuckDBDatabase(dialect, session, schema) as DuckDBDatabase<
+    TSchema,
+    ExtractTablesWithRelations<TSchema>
+  >;
+}
+
+export class DuckDBDatabase<
+  TFullSchema extends Record<string, unknown> = Record<string, never>,
+  TSchema extends TablesRelationalConfig = ExtractTablesWithRelations<TFullSchema>
+> extends PgDatabase<DuckDBQueryResultHKT, TFullSchema, TSchema> {
+  static readonly [entityKind]: string = 'DuckDBDatabase';
+
+  constructor(
+    readonly dialect: DuckDBDialect,
+    readonly session: DuckDBSession<TFullSchema, TSchema>,
+    schema: RelationalSchemaConfig<TSchema> | undefined
+  ) {
+    super(dialect, session, schema);
+  }
+
+  select(): DuckDBSelectBuilder<undefined>;
+  select<TSelection extends SelectedFields>(
+    fields: TSelection
+  ): DuckDBSelectBuilder<TSelection>;
+  select(fields?: SelectedFields): DuckDBSelectBuilder<
+    SelectedFields | undefined
+  > {
+    const selectedFields = fields ? aliasFields(fields) : undefined;
+
+    return new DuckDBSelectBuilder({
+      fields: selectedFields ?? undefined,
+      session: this.session as unknown as PgSession<DuckDBQueryResultHKT>,
+      dialect: this.dialect,
+    });
+  }
+
+  override async transaction<T>(
+    transaction: (tx: DuckDBTransaction<TFullSchema, TSchema>) => Promise<T>
+  ): Promise<T> {
+    return await this.session.transaction<T>(transaction);
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './driver.ts';
+export * from './session.ts';
+export * from './columns.ts';
+export * from './migrator.ts';
+export * from './introspect.ts';