drizzle-databend 0.1.13 → 0.1.15

package/README.md

@@ -1,23 +1,33 @@
 # 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.
+> This driver was created to power [drizzle-cube](https://try.drizzle-cube.dev) (an embeddable semantic layer built on Drizzle) and [drizby](https://github.com/cliftonc/drizby) (an open source BI platform built on drizzle-cube). It enables both projects to query Databend natively via Drizzle ORM.
+
+A [Drizzle ORM](https://orm.drizzle.team/) driver for [Databend](https://databend.com/). Built on a standalone `databend-core` dialect module with `?` 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.
 
+### Parameter binding
+
+Queries are sent with `?` placeholders and a separate parameter array. On Databend
+server `> 1.2.900` with `databend-driver >= 0.34.0`, parameters are bound **server-side**
+via the `/v1/query` `params` field, so values are never interpolated into the SQL text.
+Against older servers the driver transparently falls back to client-side interpolation
+using its own SQL-standard escaping. Either way the driver owns escaping; this adapter no
+longer pre-escapes values. `databend-driver >= 0.34.0` is required.
+
 ## Install
 
 ```sh
-bun add drizzle-databend drizzle-orm databend-driver
+npm install 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 { drizzle, databendTable, integer, varchar, text } from 'drizzle-databend';
 import { eq } from 'drizzle-orm';
 
-const users = pgTable('users', {
+const users = databendTable('users', {
   id: integer('id').notNull(),
   name: varchar('name', { length: 256 }).notNull(),
   email: text('email'),
@@ -35,9 +45,18 @@ 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', {
+import {
+  databendTable,
+  databendVariant,
+  databendArray,
+  databendTuple,
+  databendMap,
+  databendTimestamp,
+  databendDate,
+  integer,
+} from 'drizzle-databend';
+
+const events = databendTable('events', {
   id: integer('id').notNull(),
   payload: databendVariant('payload'),         // VARIANT (semi-structured JSON)
   tags: databendArray('tags', 'VARCHAR'),       // ARRAY(VARCHAR)
@@ -117,32 +136,28 @@ 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)
+npm install           # Install dependencies
+npm run build         # Build (dist/index.mjs + type declarations)
+npm run typecheck     # Type-check with tsc
+npm run lint          # Lint with biome
+npm test              # Run all 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
+- **`src/databend-core/`** -- Standalone dialect module (ported from drizzle-orm's gel-core)
+  - `dialect.ts` -- SQL generation with `?` params and `"` identifier quoting
+  - `session.ts` -- Abstract session, prepared query, and transaction base classes
+  - `db.ts` -- `DatabendDatabase` with select/insert/update/delete/execute/CTE support
+  - `table.ts` -- `databendTable()` table definition function
+  - `columns/` -- Column type builders (integer, varchar, boolean, timestamp, etc.)
+  - `query-builders/` -- SELECT, INSERT, UPDATE, DELETE query builders
+- **`src/driver.ts`** -- `drizzle()` factory, connection management, pool creation
+- **`src/session.ts`** -- Concrete session with databend-driver query execution
+- **`src/client.ts`** -- Low-level execution wrapping `databend-driver`'s `Connection` API
+- **`src/pool.ts`** -- Connection pooling via `Client.getConn()`
+- **`src/columns.ts`** -- Custom column types (VARIANT, ARRAY, TUPLE, MAP, TIMESTAMP, DATE)
+- **`src/sql/result-mapper.ts`** -- Maps Databend results to Drizzle's expected format
 
 ## License
 

package/dist/client.d.ts

@@ -13,11 +13,16 @@ export type ExecuteArraysResult = {
 };
 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.
+ * Convert a Drizzle param array into the JSON values databend-driver binds to `?`
+ * placeholders. Databend's Params is a serde_json::Value, so we pass an array of
+ * JSON-serializable values.
  *
- * The databend-driver does client-side parameter substitution with no string escaping,
- * so we must pre-escape single quotes here (SQL standard '' escaping).
+ * As of databend-driver 0.34.0 the driver binds parameters server-side (or, against
+ * older servers, interpolates them with its own SQL-standard '' escaping). Either way
+ * the driver owns escaping, so we must NOT pre-escape here - doing so would corrupt
+ * values via double-escaping. Our only job is to coerce JS types the JSON params array
+ * cannot carry verbatim (bigint, Date, structured values) into a form the server binds
+ * to the target column.
  */
 export declare function prepareParams(params: unknown[], typings?: QueryTypingsValue[]): unknown[];
 export declare function executeOnClient(client: DatabendClientLike, query: string, params: unknown[], typings?: QueryTypingsValue[]): Promise<RowData[]>;

package/dist/databend-core/db.d.ts

@@ -11,7 +11,7 @@ export declare class DatabendDatabase {
     query: any;
     constructor(dialect: any, session: any, schema?: any);
     $with(alias: string): {
-        as(qb: any): WithSubquery<string, Record<string, unknown>>;
+        as(qb: any): WithSubquery<string, any>;
     };
     $count(source: any, filters?: any): DatabendCountBuilder;
     with(...queries: any[]): {

package/dist/databend-core/dialect.d.ts

@@ -8,7 +8,7 @@ export declare class DatabendDialect {
     constructor(config?: any);
     migrate(migrations: MigrationMeta[], session: any, config: MigrationConfig | string): Promise<void>;
     escapeName(name: string): string;
-    escapeParam(num: number): string;
+    escapeParam(_num: number): string;
     escapeString(str: string): string;
     buildWithCTE(queries: any[] | undefined): SQL<unknown> | undefined;
     buildDeleteQuery({ table, where, withList }: any): SQL<unknown>;

package/dist/databend-core/query-builders/query-builder.d.ts

@@ -7,7 +7,7 @@ export declare class QueryBuilder {
     dialectConfig: any;
     constructor(dialect?: any);
     $with(alias: string): {
-        as(qb: any): WithSubquery<string, Record<string, unknown>>;
+        as(qb: any): WithSubquery<string, any>;
     };
     with(...queries: any[]): {
         select: (fields?: any) => DatabendSelectBuilder;

package/dist/databend-core/query-builders/select.d.ts

@@ -45,7 +45,7 @@ declare class DatabendSelectQueryBuilderBase extends TypedQueryBuilder<any, any>
     /** @internal */
     getSQL(): any;
     toSQL(): any;
-    as(alias: string): Subquery<string, Record<string, unknown>>;
+    as(alias: string): Subquery<string, any>;
     /** @internal */
     getSelectedFields(): any;
     $dynamic(): this;

package/dist/index.mjs

@@ -5,17 +5,18 @@ function isPool(client) {
 function prepareParams(params, typings) {
   return params.map((param, i) => {
     if (param === void 0) return null;
-    if (param instanceof Date) return param.toISOString().replace(/'/g, "''");
+    if (param === null) return null;
+    if (param instanceof Date) return param.toISOString();
     if (typeof param === "bigint") return param.toString();
     if (typeof param === "string") {
       const typing = typings?.[i];
       if (typing === "decimal" && /^-?\d+(\.\d+)?([eE][+-]?\d+)?$/.test(param)) {
         return Number(param);
       }
-      return param.replace(/'/g, "''");
+      return param;
     }
-    if (typeof param === "object" && param !== null) {
-      return JSON.stringify(param).replace(/'/g, "''");
+    if (typeof param === "object") {
+      return JSON.stringify(param);
     }
     return param;
   });
@@ -963,8 +964,8 @@ var DatabendDialect = class {
   escapeName(name) {
     return `"${name}"`;
   }
-  escapeParam(num) {
-    return `$${num + 1}`;
+  escapeParam(_num) {
+    return "?";
   }
   escapeString(str) {
     return `'${str.replace(/'/g, "''")}'`;
@@ -2952,6 +2953,12 @@ import {
   is as is10,
   SQL as SQL8
 } from "drizzle-orm";
+function getFieldSql(field) {
+  const f = field;
+  if (f.sql instanceof SQL8) return f.sql;
+  if (f._?.sql instanceof SQL8) return f._.sql;
+  throw new Error("Cannot extract SQL from field");
+}
 function toDecoderInput(decoder, value) {
   void decoder;
   return value;
@@ -3002,11 +3009,12 @@ function mapResultRow(columns, row, joinsNotNullableMap) {
       } else if (is10(field, SQL8)) {
         decoder = field.decoder;
       } else {
-        const col = field.sql.queryChunks.find((chunk) => is10(chunk, Column3));
+        const fieldSql = getFieldSql(field);
+        const col = fieldSql.queryChunks.find((chunk) => is10(chunk, Column3));
         if (is10(col, DatabendCustomColumn)) {
           decoder = col;
         } else {
-          decoder = field.sql.decoder;
+          decoder = fieldSql.decoder;
         }
       }
       let node = acc;

package/package.json

@@ -3,7 +3,7 @@
   "module": "./dist/index.mjs",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "A drizzle ORM driver for use with Databend. Based on drizzle's Postgres driver surface.",
   "type": "module",
   "scripts": {
@@ -17,8 +17,8 @@
     "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
-    "databend-driver": ">=0.33.0",
-    "drizzle-orm": "^0.40.0"
+    "databend-driver": ">=0.34.0",
+    "drizzle-orm": ">=0.40.0"
   },
   "peerDependenciesMeta": {
     "databend-driver": {
@@ -28,8 +28,8 @@
   "devDependencies": {
     "@biomejs/biome": "^2.4.7",
     "@types/node": "^25.5.0",
-    "databend-driver": "^0.33.6",
-    "drizzle-orm": "0.40.0",
+    "databend-driver": "^0.34.0",
+    "drizzle-orm": "0.45.0",
     "esbuild": "^0.25.0",
     "typescript": "^5.8.2",
     "vitest": "^1.6.0"

package/src/client.ts

@@ -19,27 +19,40 @@ export function isPool(
 }
 
 /**
- * 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.
+ * Convert a Drizzle param array into the JSON values databend-driver binds to `?`
+ * placeholders. Databend's Params is a serde_json::Value, so we pass an array of
+ * JSON-serializable values.
  *
- * The databend-driver does client-side parameter substitution with no string escaping,
- * so we must pre-escape single quotes here (SQL standard '' escaping).
+ * As of databend-driver 0.34.0 the driver binds parameters server-side (or, against
+ * older servers, interpolates them with its own SQL-standard '' escaping). Either way
+ * the driver owns escaping, so we must NOT pre-escape here - doing so would corrupt
+ * values via double-escaping. Our only job is to coerce JS types the JSON params array
+ * cannot carry verbatim (bigint, Date, structured values) into a form the server binds
+ * to the target column.
  */
 export function prepareParams(params: unknown[], typings?: QueryTypingsValue[]): unknown[] {
   return params.map((param, i) => {
     if (param === undefined) return null;
-    if (param instanceof Date) return param.toISOString().replace(/'/g, "''");
+    if (param === null) return null;
+    // JSON has no Date type: send an ISO string for the server to bind to TIMESTAMP.
+    if (param instanceof Date) return param.toISOString();
+    // JSON cannot carry a bigint: send it as a string for the server to parse.
     if (typeof param === 'bigint') return param.toString();
     if (typeof param === 'string') {
+      // Drizzle hands decimal/numeric values over as strings. Coerce them to a JS number
+      // so the server binds a numeric value rather than a string for numeric columns.
       const typing = typings?.[i];
       if (typing === 'decimal' && /^-?\d+(\.\d+)?([eE][+-]?\d+)?$/.test(param)) {
         return Number(param);
       }
-      return param.replace(/'/g, "''");
+      return param;
     }
-    if (typeof param === 'object' && param !== null) {
-      return JSON.stringify(param).replace(/'/g, "''");
+    // VARIANT / ARRAY / MAP / TUPLE: serialize structured values to a JSON string, which
+    // the server parses into the semi-structured column type.
+    if (typeof param === 'object') {
+      return JSON.stringify(param);
     }
+    // number / boolean pass through unchanged.
     return param;
   });
 }

package/src/databend-core/dialect.ts

@@ -97,8 +97,12 @@ export class DatabendDialect {
     return `"${name}"`;
   }
 
-  escapeParam(num: number): string {
-    return `$${num + 1}`;
+  escapeParam(_num: number): string {
+    // Emit `?` rather than `$N`. Databend reads `$N` as a column-position reference
+    // (stage column refs), which forces the driver onto its client-side interpolation
+    // fallback. `?` parses as a placeholder and is bound server-side, positionally, in
+    // encounter order - which matches how Drizzle appends one param per placeholder.
+    return '?';
   }
 
   escapeString(str: string): string {

package/src/sql/result-mapper.ts

@@ -6,6 +6,7 @@ import {
   is,
   type SelectedFieldsOrdered,
   SQL,
+  Subquery,
 } from 'drizzle-orm';
 import { DatabendCustomColumn } from '../databend-core/columns/custom.ts';
 import { DatabendDate } from '../databend-core/columns/date.ts';
@@ -15,6 +16,14 @@ type SQLInternal<T = unknown> = SQL<T> & {
   decoder: DriverValueDecoder<T, any>;
 };
 
+/** Extract SQL from Aliased (has .sql) or Subquery (has _.sql) */
+function getFieldSql(field: unknown): SQL {
+  const f = field as any;
+  if (f.sql instanceof SQL) return f.sql;
+  if (f._?.sql instanceof SQL) return f._.sql;
+  throw new Error('Cannot extract SQL from field');
+}
+
 type DecoderInput<TDecoder extends DriverValueDecoder<unknown, unknown>> =
   Parameters<TDecoder['mapFromDriverValue']>[0];
 
@@ -113,12 +122,13 @@ export function mapResultRow<TResult>(
       } else if (is(field, SQL)) {
         decoder = (field as SQLInternal).decoder;
       } else {
-        const col = field.sql.queryChunks.find((chunk) => is(chunk, Column));
+        const fieldSql = getFieldSql(field);
+        const col = fieldSql.queryChunks.find((chunk) => is(chunk, Column));
 
         if (is(col, DatabendCustomColumn)) {
           decoder = col;
         } else {
-          decoder = (field.sql as SQLInternal).decoder;
+          decoder = (fieldSql as SQLInternal).decoder;
         }
       }
       let node = acc;