feat!: unify query builder execution

Author: bernard-ng

bun.lock

@@ -1,5 +1,20 @@
 # @ngandu-dev/database
 
+## 3.0.2
+
+### Changed
+
+- Replaced duplicated query models, binding enums, SQL builders, and platform exceptions with compatibility re-exports from `@ngandu-dev/query-builder`.
+- Made `Connection` and `AbstractPlatform` explicitly implement the standalone query-builder contracts.
+- Expanded `@ngandu-dev/database/query` to expose the canonical query model and expression symbols.
+- Added `ConnectedQueryBuilder`, a compatibility façade that extends the standalone builder while delegating all execution and fetch operations to `Connection`.
+- Allowed `Connection#executeQuery()` and `Connection#executeStatement()` to execute standalone query-builder instances after resolving the active database platform.
+
+### Fixed
+
+- Fixed array expansion when bindings originate from the standalone query-builder package.
+- Unified DB2, MySQL, and SQL Server locking behavior across the standalone and database-backed query surfaces.
+
 ## 2.0.0
 
 ### Changed

packages/database/CHANGELOG.md

@@ -54,6 +54,10 @@ const users = await connection
 
 Detailed guides are available in [`docs/`](docs), including configuration, transactions, platforms, portability, types, and schema support.
 
+`connection.createQueryBuilder()` returns a connected builder. It has the same construction API as `@ngandu-dev/query-builder`, plus the legacy execution and fetch helpers. Those helpers are thin delegates: `Connection` remains the only component that connects, resolves the database platform, binds parameters, executes SQL, and converts driver errors.
+
+For construction without a connection, import `StandaloneQueryBuilder` from `@ngandu-dev/database/query` or import `QueryBuilder` directly from `@ngandu-dev/query-builder`.
+
 ## Development
 
 From the monorepo root:

packages/database/README.md

@@ -14,6 +14,29 @@ const conn = DriverManager.getConnection({ driver: "mysql2", pool });
 const qb = conn.createQueryBuilder();
 ```
 
+Builder Variants
+----------------
+
+`conn.createQueryBuilder()` returns a connected builder for application code. It
+extends the standalone builder and preserves the legacy execution and fetch API,
+but delegates every database operation to `Connection`. There is only one
+connection, parameter-binding, execution, and error-conversion implementation.
+
+For SQL construction without I/O, use the standalone variant:
+
+```ts
+import { StandaloneQueryBuilder } from "@ngandu-dev/database/query";
+
+const query = new StandaloneQueryBuilder()
+  .select("id", "email")
+  .from("users");
+
+console.log(query.getSQL());
+```
+
+The standalone builder has no execution or fetch methods. It can also be
+imported as `QueryBuilder` from `@ngandu-dev/query-builder`.
+
 Security: Preventing SQL Injection
 ----------------------------------
 
@@ -260,6 +283,13 @@ Execution API
 - `fetchAllAssociativeIndexed()` (async)
 - `fetchFirstColumn()` (async)
 
+These methods exist only on the connected builder returned by
+`Connection#createQueryBuilder()`. They delegate to `Connection`, which first
+connects and resolves any server-version-dependent platform before compiling
+and executing the query. Calling synchronous `getSQL()` directly on such a
+builder requires the connection platform to already be available; execution
+methods resolve it automatically.
+
 Not Implemented
 ---------------
 

packages/database/docs/query-builder.md

@@ -1,6 +1,6 @@
 {
   "name": "@ngandu-dev/database",
-  "version": "2.0.0",
+  "version": "3.0.2",
   "description": "A TypeScript database abstraction layer inspired by Doctrine DBAL.",
   "license": "MIT",
   "author": "Bernard Ngandu <bernard@ngandu.dev>",
@@ -145,7 +145,7 @@
     "sql-server"
   ],
   "dependencies": {
-    "@ngandu-dev/query-builder": "^2.0.0",
+    "@ngandu-dev/query-builder": "^3.0.2",
     "semver": "^7.7.4"
   },
   "peerDependencies": {

packages/database/package.json

@@ -0,0 +1,95 @@
+import {
+  ArrayParameterType as BuilderArrayParameterType,
+  ConflictResolutionMode as BuilderConflictResolutionMode,
+  DB2Platform as BuilderDB2Platform,
+  DefaultSelectSQLBuilder as BuilderDefaultSelectSQLBuilder,
+  MySQL80Platform as BuilderMySQL80Platform,
+  MySQLPlatform as BuilderMySQLPlatform,
+  NotSupported as BuilderNotSupported,
+  ParameterType as BuilderParameterType,
+  SelectQuery as BuilderSelectQuery,
+  SQLServerPlatform as BuilderSQLServerPlatform,
+  UnionType as BuilderUnionType,
+  QueryBuilder,
+} from "@ngandu-dev/query-builder";
+
+import { ArrayParameterType } from "../../array-parameter-type";
+import { ExpandArrayParameters } from "../../expand-array-parameters";
+import { ParameterType } from "../../parameter-type";
+import { DB2Platform } from "../../platforms/db2-platform";
+import { NotSupported } from "../../platforms/exception/not-supported";
+import { MySQLPlatform } from "../../platforms/mysql-platform";
+import { MySQL80Platform } from "../../platforms/mysql80-platform";
+import { SQLServerPlatform } from "../../platforms/sqlserver-platform";
+import { ConflictResolutionMode } from "../../query/for-update/conflict-resolution-mode";
+import { SelectQuery } from "../../query/select-query";
+import { UnionType } from "../../query/union-type";
+import { DefaultSelectSQLBuilder } from "../../sql/builder/default-select-sql-builder";
+import { Parser } from "../../sql/parser";
+
+const buildLockedSelect = (
+  platform: ConstructorParameters<typeof QueryBuilder>[0],
+  mode: BuilderConflictResolutionMode = BuilderConflictResolutionMode.ORDINARY,
+): string => new QueryBuilder(platform).select("*").from("items").forUpdate(mode).getSQL();
+
+describe("query-builder package contract", () => {
+  it("uses one canonical set of public query and binding symbols", () => {
+    expect(ArrayParameterType).toBe(BuilderArrayParameterType);
+    expect(ParameterType).toBe(BuilderParameterType);
+    expect(ConflictResolutionMode).toBe(BuilderConflictResolutionMode);
+    expect(UnionType).toBe(BuilderUnionType);
+    expect(SelectQuery).toBe(BuilderSelectQuery);
+    expect(DefaultSelectSQLBuilder).toBe(BuilderDefaultSelectSQLBuilder);
+    expect(NotSupported).toBe(BuilderNotSupported);
+  });
+
+  it("expands arrays created with the standalone package binding enum", () => {
+    const visitor = new ExpandArrayParameters(
+      { ids: [1, 2, 3] },
+      { ids: BuilderArrayParameterType.INTEGER },
+    );
+
+    new Parser().parse("id IN (:ids)", visitor);
+
+    expect(visitor.getSQL()).toBe("id IN (?, ?, ?)");
+    expect(visitor.getParameters()).toEqual([1, 2, 3]);
+    expect(visitor.getTypes()).toEqual([
+      ParameterType.INTEGER,
+      ParameterType.INTEGER,
+      ParameterType.INTEGER,
+    ]);
+  });
+
+  it("generates identical DB2 locking SQL through both platform surfaces", () => {
+    expect(buildLockedSelect(new BuilderDB2Platform())).toBe(buildLockedSelect(new DB2Platform()));
+    expect(buildLockedSelect(new DB2Platform())).toBe(
+      "SELECT * FROM items WITH RR USE AND KEEP UPDATE LOCKS",
+    );
+
+    expect(() =>
+      buildLockedSelect(new BuilderDB2Platform(), BuilderConflictResolutionMode.SKIP_LOCKED),
+    ).toThrow(BuilderNotSupported);
+  });
+
+  it("generates identical SQL Server locking SQL through both platform surfaces", () => {
+    expect(buildLockedSelect(new BuilderSQLServerPlatform())).toBe(
+      buildLockedSelect(new SQLServerPlatform()),
+    );
+    expect(
+      buildLockedSelect(new BuilderSQLServerPlatform(), BuilderConflictResolutionMode.SKIP_LOCKED),
+    ).toBe("SELECT * FROM items WITH (UPDLOCK, ROWLOCK, READPAST)");
+  });
+
+  it("keeps version-aware MySQL locking behavior aligned", () => {
+    expect(() =>
+      buildLockedSelect(new BuilderMySQLPlatform(), BuilderConflictResolutionMode.SKIP_LOCKED),
+    ).toThrow(BuilderNotSupported);
+    expect(() =>
+      buildLockedSelect(new MySQLPlatform(), BuilderConflictResolutionMode.SKIP_LOCKED),
+    ).toThrow(BuilderNotSupported);
+
+    expect(
+      buildLockedSelect(new BuilderMySQL80Platform(), BuilderConflictResolutionMode.SKIP_LOCKED),
+    ).toBe(buildLockedSelect(new MySQL80Platform(), BuilderConflictResolutionMode.SKIP_LOCKED));
+  });
+});

packages/database/src/__tests__/query/query-builder-contract.test.ts

@@ -13,6 +13,7 @@ import type { Connection as DriverConnection } from "../../driver/connection";
 import { DriverException } from "../../exception/driver-exception";
 import { ParameterType } from "../../parameter-type";
 import { MySQLPlatform } from "../../platforms/mysql-platform";
+import { MySQL80Platform } from "../../platforms/mysql80-platform";
 import type { QueryParameters, QueryParameterTypes } from "../../query";
 import { NonUniqueAlias } from "../../query/exception/non-unique-alias";
 import { UnknownAlias } from "../../query/exception/unknown-alias";
@@ -29,6 +30,7 @@ import { Union } from "../../query/union";
 import { UnionQuery } from "../../query/union-query";
 import { UnionType } from "../../query/union-type";
 import { Result } from "../../result";
+import type { ServerVersionProvider } from "../../server-version-provider";
 
 describe("Query API surface parity", () => {
   it("adds SelectQuery getters and distinct flag accessor", () => {
@@ -121,14 +123,17 @@ class NoopExceptionConverter implements ExceptionConverter {
 }
 
 class NoopDriverConnection implements DriverConnection {
+  public readonly queries: string[] = [];
+
   public async prepare(_sql: string) {
     return {
       bindValue: () => undefined,
       execute: async () => new ArrayResult([], [], 0),
     };
   }
 
-  public async query(_sql: string) {
+  public async query(sql: string) {
+    this.queries.push(sql);
     return new ArrayResult([], [], 0);
   }
 
@@ -174,11 +179,28 @@ class NoopDriver implements Driver {
     return this.exceptionConverter;
   }
 
-  public getDatabasePlatform(): MySQLPlatform {
+  public getDatabasePlatform(
+    _versionProvider: ServerVersionProvider,
+  ): MySQLPlatform | Promise<MySQLPlatform> {
     return new MySQLPlatform();
   }
 }
 
+class LazyPlatformDriver extends NoopDriver {
+  public readonly connection = new NoopDriverConnection();
+
+  public override async connect(_params: Record<string, unknown>): Promise<DriverConnection> {
+    return this.connection;
+  }
+
+  public override async getDatabasePlatform(
+    versionProvider: ServerVersionProvider,
+  ): Promise<MySQLPlatform> {
+    await versionProvider.getServerVersion();
+    return new MySQL80Platform();
+  }
+}
+
 class SpyExecutionConnection extends Connection {
   public readonly queryCalls: Array<{
     params: QueryParameters;
@@ -205,19 +227,33 @@ class SpyExecutionConnection extends Connection {
   }
 
   public override async executeQuery(
-    sql: string,
+    queryOrSql: QueryBuilder | string,
     params: QueryParameters = [],
     types: QueryParameterTypes = [],
   ): Promise<Result> {
+    const sql =
+      typeof queryOrSql === "string" ? queryOrSql : queryOrSql.getSQL(this.getDatabasePlatform());
+    if (typeof queryOrSql !== "string") {
+      params = queryOrSql.getParameters();
+      types = queryOrSql.getParameterTypes();
+    }
+
     this.queryCalls.push({ params, sql, types });
     return new Result(new ArrayResult([...this.queryRows]), this);
   }
 
   public override async executeStatement(
-    sql: string,
+    queryOrSql: QueryBuilder | string,
     params: QueryParameters = [],
     types: QueryParameterTypes = [],
   ): Promise<number> {
+    const sql =
+      typeof queryOrSql === "string" ? queryOrSql : queryOrSql.getSQL(this.getDatabasePlatform());
+    if (typeof queryOrSql !== "string") {
+      params = queryOrSql.getParameters();
+      types = queryOrSql.getParameterTypes();
+    }
+
     this.statementCalls.push({ params, sql, types });
     return this.statementResult;
   }
@@ -1105,6 +1141,19 @@ describe("QueryBuilder", () => {
     ]);
   });
 
+  it("should resolve an asynchronous platform before executing a connected builder", async () => {
+    const driver = new LazyPlatformDriver();
+    const connection = new Connection({}, driver);
+    const qb = connection.createQueryBuilder();
+
+    qb.select("u.id").from("users", "u").forUpdate(ConflictResolutionMode.SKIP_LOCKED);
+
+    await qb.executeQuery();
+
+    expect(connection.getDatabasePlatform()).toBeInstanceOf(MySQL80Platform);
+    expect(driver.connection.queries).toEqual(["SELECT u.id FROM users u FOR UPDATE SKIP LOCKED"]);
+  });
+
   it("should fetch associative through connection", async () => {
     const connection = new SpyExecutionConnection({
       queryRows: [{ id: 1, name: "Alice" }],

packages/database/src/__tests__/query/query-builder.test.ts

@@ -1,23 +1 @@
-import { ParameterType } from "./parameter-type";
-
-export enum ArrayParameterType {
-  INTEGER = "ARRAY_INTEGER",
-  STRING = "ARRAY_STRING",
-  ASCII = "ARRAY_ASCII",
-  BINARY = "ARRAY_BINARY",
-}
-
-export namespace ArrayParameterType {
-  export function toElementParameterType(type: ArrayParameterType): ParameterType {
-    switch (type) {
-      case ArrayParameterType.INTEGER:
-        return ParameterType.INTEGER;
-      case ArrayParameterType.STRING:
-        return ParameterType.STRING;
-      case ArrayParameterType.ASCII:
-        return ParameterType.ASCII;
-      case ArrayParameterType.BINARY:
-        return ParameterType.BINARY;
-    }
-  }
-}
+export { ArrayParameterType } from "@ngandu-dev/query-builder";