drizzle-databend 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Clifton Cunningham
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# drizzle-databend
+
+A [Drizzle ORM](https://orm.drizzle.team/) driver for [Databend](https://databend.com/). Built on Drizzle's Postgres driver surface (`pg-core`) since Databend supports `$1` positional parameters and double-quote identifier quoting.
+
+Uses [`databend-driver`](https://github.com/databendlabs/bendsql/tree/main/bindings/nodejs) (NAPI-RS bindings) as the underlying client.
+
+## Install
+
+```sh
+bun add drizzle-databend drizzle-orm databend-driver
+```
+
+## Quick start
+
+```ts
+import { drizzle } from 'drizzle-databend';
+import { pgTable, integer, varchar, text } from 'drizzle-orm/pg-core';
+import { eq } from 'drizzle-orm';
+
+const users = pgTable('users', {
+  id: integer('id').notNull(),
+  name: varchar('name', { length: 256 }).notNull(),
+  email: text('email'),
+});
+
+const db = await drizzle('databend://databend:databend@localhost:8000/default?sslmode=disable');
+
+// Insert
+await db.insert(users).values({ id: 1, name: 'Alice', email: 'alice@example.com' });
+
+// Select
+const rows = await db.select().from(users).where(eq(users.name, 'Alice'));
+```
+
+## Databend-specific column types
+
+```ts
+import { databendVariant, databendArray, databendTuple, databendMap, databendTimestamp, databendDate } from 'drizzle-databend';
+
+const events = pgTable('events', {
+  id: integer('id').notNull(),
+  payload: databendVariant('payload'),         // VARIANT (semi-structured JSON)
+  tags: databendArray('tags', 'VARCHAR'),       // ARRAY(VARCHAR)
+  coords: databendTuple('coords', ['FLOAT', 'FLOAT']), // TUPLE(FLOAT, FLOAT)
+  attrs: databendMap('attrs', 'VARCHAR', 'VARCHAR'),    // MAP(VARCHAR, VARCHAR)
+  createdAt: databendTimestamp('created_at'),   // TIMESTAMP
+  eventDate: databendDate('event_date'),        // DATE
+});
+```
+
+## Connection options
+
+```ts
+// DSN string (async, auto-pools with 4 connections)
+const db = await drizzle('databend://user:pass@host:8000/db?sslmode=disable');
+
+// With config
+const db = await drizzle('databend://...', { pool: { size: 8 }, logger: true });
+
+// Config object
+const db = await drizzle({ connection: 'databend://...', schema: mySchema });
+
+// Explicit client (sync, no pooling)
+import { Client } from 'databend-driver';
+const conn = await new Client('databend://...').getConn();
+const db = drizzle({ client: conn });
+
+// Disable pooling
+const db = await drizzle('databend://...', { pool: false });
+```
+
+## Transactions
+
+```ts
+await db.transaction(async (tx) => {
+  await tx.insert(users).values({ id: 2, name: 'Bob', email: 'bob@example.com' });
+  await tx.update(users).set({ name: 'Robert' }).where(eq(users.id, 2));
+});
+```
+
+Note: Databend does not support savepoints. Nested transactions use a rollback-only fallback.
+
+## Migrations
+
+```ts
+import { migrate } from 'drizzle-databend';
+
+await migrate(db, { migrationsFolder: './drizzle' });
+```
+
+## Development
+
+### Prerequisites
+
+You need a running Databend instance. The quickest way is Docker:
+
+```sh
+docker run -d \
+    --name databend \
+    --network host \
+    -e MINIO_ENABLED=true \
+    -e QUERY_DEFAULT_USER=databend \
+    -e QUERY_DEFAULT_PASSWORD=databend \
+    -v minio_data_dir:/var/lib/minio \
+    --restart unless-stopped \
+    datafuselabs/databend
+```
+
+See the [Databend self-hosted quickstart](https://docs.databend.com/guides/self-hosted/quickstart) for more options.
+
+Verify the connection:
+
+```sh
+bendsql -udatabend -pdatabend
+```
+
+### Commands
+
+```sh
+bun install           # Install dependencies
+bun run build         # Build (dist/index.mjs + type declarations)
+bun test              # Run integration tests (requires running Databend)
+```
+
+### Seed data
+
+Populate two sample tables (`users` and `events`) for manual testing:
+
+```sh
+bun run scripts/seed.ts
+```
+
+This creates 5 users and 10 events with VARIANT payloads and timestamps.
+
+## Architecture
+
+Built on the same pattern as [drizzle-duckdb](https://github.com/leonardovida/drizzle-duckdb):
+
+- **`driver.ts`** -- `drizzle()` factory and `DatabendDatabase` extending `PgDatabase`
+- **`session.ts`** -- `DatabendSession` and `DatabendPreparedQuery` for query execution
+- **`dialect.ts`** -- `DatabendDialect` extending `PgDialect` with Databend-specific migrations and type mapping
+- **`client.ts`** -- Low-level execution wrapping `databend-driver`'s `Connection` API
+- **`pool.ts`** -- Connection pooling via `Client.getConn()`
+- **`columns.ts`** -- Custom column types (VARIANT, ARRAY, TUPLE, MAP, TIMESTAMP, DATE)
+- **`sql/result-mapper.ts`** -- Maps Databend results to Drizzle's expected format
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,22 @@
+import type { Connection } from 'databend-driver';
+export interface DatabendConnectionPool {
+    acquire(): Promise<Connection>;
+    release(connection: Connection): void | Promise<void>;
+    close?(): Promise<void> | void;
+}
+export type DatabendClientLike = Connection | DatabendConnectionPool;
+export type RowData = Record<string, unknown>;
+export type ExecuteArraysResult = {
+    columns: string[];
+    rows: unknown[][];
+};
+export declare function isPool(client: DatabendClientLike): client is DatabendConnectionPool;
+/**
+ * Convert Drizzle param array to a JSON value accepted by databend-driver's Params.
+ * Databend's Params is serde_json::Value, so we pass an array of JSON-serializable values.
+ */
+export declare function prepareParams(params: unknown[]): unknown[];
+export declare function executeOnClient(client: DatabendClientLike, query: string, params: unknown[]): Promise<RowData[]>;
+export declare function executeArraysOnClient(client: DatabendClientLike, query: string, params: unknown[]): Promise<ExecuteArraysResult>;
+export declare function execOnClient(client: DatabendClientLike, query: string, params: unknown[]): Promise<number>;
+export declare function closeClientConnection(connection: Connection): Promise<void>;

package/dist/columns.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Databend VARIANT column type.
+ * Stores semi-structured JSON-like data. Maps to `unknown` in TypeScript.
+ */
+export declare const databendVariant: <TData = unknown>(name: string) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
+    name: string;
+    dataType: "custom";
+    columnType: "PgCustomColumn";
+    data: TData;
+    driverParam: string | TData;
+    enumValues: undefined;
+}>;
+/**
+ * Databend ARRAY column type.
+ * Stores typed arrays. Maps to `T[]` in TypeScript.
+ */
+export declare const databendArray: <TData = unknown>(name: string, elementType: string) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
+    name: string;
+    dataType: "custom";
+    columnType: "PgCustomColumn";
+    data: TData[];
+    driverParam: string | TData[];
+    enumValues: undefined;
+}>;
+/**
+ * Databend TUPLE column type.
+ * Stores positional tuples. Maps to typed tuple in TypeScript.
+ */
+export declare const databendTuple: <TData extends unknown[]>(name: string, types: string[]) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
+    name: string;
+    dataType: "custom";
+    columnType: "PgCustomColumn";
+    data: TData;
+    driverParam: string | TData;
+    enumValues: undefined;
+}>;
+/**
+ * Databend MAP column type.
+ * Stores key-value maps. Maps to `Record<K, V>` in TypeScript.
+ */
+export declare const databendMap: <TData extends Record<string, any>>(name: string, keyType: string, valueType: string) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
+    name: string;
+    dataType: "custom";
+    columnType: "PgCustomColumn";
+    data: TData;
+    driverParam: string | TData;
+    enumValues: undefined;
+}>;
+/**
+ * Databend TIMESTAMP column type.
+ */
+export declare const databendTimestamp: (name: string) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
+    name: string;
+    dataType: "custom";
+    columnType: "PgCustomColumn";
+    data: string | Date;
+    driverParam: string | Date;
+    enumValues: undefined;
+}>;
+/**
+ * Databend DATE column type.
+ */
+export declare const databendDate: (name: string) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
+    name: string;
+    dataType: "custom";
+    columnType: "PgCustomColumn";
+    data: string | Date;
+    driverParam: string | Date;
+    enumValues: undefined;
+}>;

package/dist/dialect.d.ts

@@ -0,0 +1,10 @@
+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';
+export declare class DatabendDialect extends PgDialect {
+    static readonly [entityKind]: string;
+    areSavepointsUnsupported(): boolean;
+    migrate(migrations: MigrationMeta[], session: PgSession, config: MigrationConfig | string): Promise<void>;
+    prepareTyping(encoder: DriverValueEncoder<unknown, unknown>): QueryTypingsValue;
+}

package/dist/driver.d.ts

@@ -0,0 +1,50 @@
+import { Client } from 'databend-driver';
+import { entityKind } from 'drizzle-orm/entity';
+import type { Logger } from 'drizzle-orm/logger';
+import { PgDatabase } from 'drizzle-orm/pg-core/db';
+import { type ExtractTablesWithRelations, type RelationalSchemaConfig, type TablesRelationalConfig } from 'drizzle-orm/relations';
+import { type DrizzleConfig } from 'drizzle-orm/utils';
+import type { DatabendClientLike, DatabendQueryResultHKT, DatabendTransaction } from './session.ts';
+import { DatabendSession } from './session.ts';
+import { DatabendDialect } from './dialect.ts';
+import { type DatabendPoolConfig } from './pool.ts';
+export interface DatabendDriverOptions {
+    logger?: Logger;
+}
+export declare class DatabendDriver {
+    private client;
+    private dialect;
+    private options;
+    static readonly [entityKind]: string;
+    constructor(client: DatabendClientLike, dialect: DatabendDialect, options?: DatabendDriverOptions);
+    createSession(schema: RelationalSchemaConfig<TablesRelationalConfig> | undefined): DatabendSession<Record<string, unknown>, TablesRelationalConfig>;
+}
+export interface DatabendDrizzleConfig<TSchema extends Record<string, unknown> = Record<string, never>> extends DrizzleConfig<TSchema> {
+    /** Pool configuration. Use size config or false to disable. */
+    pool?: DatabendPoolConfig | false;
+}
+export interface DatabendDrizzleConfigWithConnection<TSchema extends Record<string, unknown> = Record<string, never>> extends DatabendDrizzleConfig<TSchema> {
+    /** Connection DSN string */
+    connection: string;
+}
+export interface DatabendDrizzleConfigWithClient<TSchema extends Record<string, unknown> = Record<string, never>> extends DatabendDrizzleConfig<TSchema> {
+    /** Explicit client (connection or pool) */
+    client: DatabendClientLike;
+}
+export declare function drizzle<TSchema extends Record<string, unknown> = Record<string, never>>(dsn: string): Promise<DatabendDatabase<TSchema, ExtractTablesWithRelations<TSchema>>>;
+export declare function drizzle<TSchema extends Record<string, unknown> = Record<string, never>>(dsn: string, config: DatabendDrizzleConfig<TSchema>): Promise<DatabendDatabase<TSchema, ExtractTablesWithRelations<TSchema>>>;
+export declare function drizzle<TSchema extends Record<string, unknown> = Record<string, never>>(config: DatabendDrizzleConfigWithConnection<TSchema>): Promise<DatabendDatabase<TSchema, ExtractTablesWithRelations<TSchema>>>;
+export declare function drizzle<TSchema extends Record<string, unknown> = Record<string, never>>(config: DatabendDrizzleConfigWithClient<TSchema>): DatabendDatabase<TSchema, ExtractTablesWithRelations<TSchema>>;
+export declare function drizzle<TSchema extends Record<string, unknown> = Record<string, never>>(client: DatabendClientLike, config?: DatabendDrizzleConfig<TSchema>): DatabendDatabase<TSchema, ExtractTablesWithRelations<TSchema>>;
+export declare class DatabendDatabase<TFullSchema extends Record<string, unknown> = Record<string, never>, TSchema extends TablesRelationalConfig = ExtractTablesWithRelations<TFullSchema>> extends PgDatabase<DatabendQueryResultHKT, TFullSchema, TSchema> {
+    readonly dialect: DatabendDialect;
+    readonly session: DatabendSession<TFullSchema, TSchema>;
+    static readonly [entityKind]: string;
+    /** The underlying connection or pool */
+    readonly $client: DatabendClientLike;
+    /** The Databend Client instance (when created from DSN) */
+    readonly $databendClient?: Client;
+    constructor(dialect: DatabendDialect, session: DatabendSession<TFullSchema, TSchema>, schema: RelationalSchemaConfig<TSchema> | undefined, client: DatabendClientLike, databendClient?: Client);
+    close(): Promise<void>;
+    transaction<T>(transaction: (tx: DatabendTransaction<TFullSchema, TSchema>) => Promise<T>): Promise<T>;
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './driver.ts';
+export * from './session.ts';
+export * from './columns.ts';
+export * from './migrator.ts';
+export * from './client.ts';
+export * from './pool.ts';