durcno 1.0.0-alpha.2 → 1.0.0-alpha.4

package/README.md

@@ -1,8 +1,6 @@
 <p align="center">
-  <a href="https://npmjs.com/package/durcno" target="_blank">
-    <img src="https://img.shields.io/npm/v/durcno?style=flat&logo=npm&color=339933" alt="npm version" />
-  </a>
-  <img src="https://img.shields.io/badge/Node.js-24%2B-339933?style=flat&logo=node.js&logoColor=white" alt="Node.js 24+" />
+  <img alt="NPM Downloads" src="https://img.shields.io/npm/dw/durcno" alt="Downloads" />
+  <img src="https://img.shields.io/badge/Node.js-24%2B-339935?style=flat&logo=node.js&logoColor=white" alt="Node.js 24+" />
   <img src="https://img.shields.io/badge/PostgreSQL-14%2B-336791?style=flat&logo=postgresql&logoColor=white" alt="PostgreSQL 14+" />
   <img src="https://img.shields.io/badge/License-Apache%202.0-blue?style=flat" alt="License" />
   <img src="https://img.shields.io/badge/vitest--green?logo=vitest" alt="License" />
@@ -31,7 +29,7 @@
 ## Setup
 
 ```bash
-npm install durcno
+npm add durcno@alpha
 ```
 
 ```bash

package/dist/bin.cjs

@@ -8903,19 +8903,17 @@ function resolveConfigPath(argPath) {
   }
   return (0, import_node_path2.resolve)(process.cwd(), DURCNO_CONFIG_NAME);
 }
-async function getSetup(argPath) {
-  const absPath = resolveConfigPath(argPath);
+async function loadConfig(absPath) {
   const mod = await import(absPath);
-  const { default: setup } = mod;
-  return setup;
+  return mod.default;
 }
 
 // src/cli/commands/down.ts
 var { bgGreen, dim, cyan: cyan2, yellow: yellow2, red: red2 } = source_default;
 async function down(m, options) {
   const configPath = resolveConfigPath(options.config);
-  const { connector, config: config2 } = await getSetup(configPath);
-  config2.pool = { ...config2.pool, max: 1 };
+  const config2 = await loadConfig(configPath);
+  const { connector } = config2;
   const migrationsDir = (0, import_node_path3.resolve)(
     (0, import_node_path3.dirname)(configPath),
     config2.out || DEFAULT_MIGRATIONS_DIR
@@ -8925,7 +8923,7 @@ async function down(m, options) {
   const client = connector.getClient();
   await client.connect();
   if (await migrationsTableExists(client)) {
-    const db = (0, import_durcno2.database)({ Migrations: import_durcno2.Migrations }, { connector, config: config2 });
+    const db = (0, import_durcno2.database)({ Migrations: import_durcno2.Migrations }, config2);
     const migrations = await db.from(import_durcno2.Migrations).select();
     const migrationDirsReversed = migrationDirNames.sort().reverse();
     for (let i = 0; i < migrationDirsReversed.length; i++) {
@@ -8939,7 +8937,7 @@ async function down(m, options) {
           migrationDirName,
           isFirstMigration,
           migrationsDir,
-          { connector, config: config2 },
+          config2,
           client
         );
         if (migration.name === m) {
@@ -8954,7 +8952,7 @@ async function down(m, options) {
   await client.close();
   process.exit(0);
 }
-async function runDownMigration(migrationDirName, isFirstMigration, migrationsDirPath, setup, client) {
+async function runDownMigration(migrationDirName, isFirstMigration, migrationsDirPath, config2, client) {
   const migrationName = (0, import_node_path3.basename)(migrationDirName);
   const downPath = (0, import_node_path3.join)(migrationsDirPath, migrationName, "down.ts");
   try {
@@ -8963,31 +8961,32 @@ async function runDownMigration(migrationDirName, isFirstMigration, migrationsDi
     const options = migrationModule.options ?? {};
     const useTransaction = options.transaction ?? true;
     const execution = options.execution ?? "joined";
-    if (useTransaction) {
-      await client.query("BEGIN;");
-    }
     try {
       if (statements.length > 0) {
         if (execution === "sequential") {
+          if (useTransaction) await client.query("BEGIN;");
           for (const st of statements) {
             await client.query(st.toSQL());
           }
+          if (useTransaction) await client.query("COMMIT;");
         } else {
-          const sql = `${statements.map((st) => st.toSQL()).join("\n")}`;
+          let sql = "";
+          if (useTransaction) sql += "BEGIN;\n";
+          sql += statements.map((st) => st.toSQL()).join("\n");
+          if (useTransaction) sql += "\nCOMMIT;";
           await client.query(sql);
         }
       }
-      if (useTransaction) {
-        await client.query("COMMIT;");
-      }
     } catch (e) {
-      if (useTransaction) {
+      if (useTransaction && execution === "sequential") {
         await client.query("ROLLBACK;");
       }
       throw e;
     }
     if (!isFirstMigration) {
-      const db = (0, import_durcno2.database)({ Migrations: import_durcno2.Migrations }, setup);
+      config2.connector.pool = { ...config2.connector.pool, max: 1 };
+      config2.connector.logger = void 0;
+      const db = (0, import_durcno2.database)({ Migrations: import_durcno2.Migrations }, config2);
       await db.delete(import_durcno2.Migrations).where((0, import_durcno2.eq)(import_durcno2.Migrations.name, migrationName));
       await db.close();
     }
@@ -12234,7 +12233,7 @@ async function promptColumnRenames(prev, curr, renamedTables) {
 }
 async function generate(options) {
   const configPath = resolveConfigPath(options.config);
-  const { config: config2 } = await getSetup(configPath);
+  const config2 = await loadConfig(configPath);
   const migrationsDir = (0, import_node_path4.resolve)(
     (0, import_node_path4.dirname)(configPath),
     config2.out || DEFAULT_MIGRATIONS_DIR
@@ -12275,12 +12274,14 @@ async function generate(options) {
     ssCurrent,
     renamedTables
   );
+  const connectorMigrationOpts = config2.connector.constructor.migrationOptions;
   const migrationUpTs = generateMigration(
     ssPrevious,
     ssCurrent,
     "up",
     renamedTables,
-    renamedColumns
+    renamedColumns,
+    connectorMigrationOpts
   );
   const reverseRenamedTables = {};
   for (const [oldKey, newKey] of Object.entries(renamedTables)) {
@@ -12299,7 +12300,8 @@ async function generate(options) {
     ssPrevious,
     "down",
     reverseRenamedTables,
-    reverseRenamedColumns
+    reverseRenamedColumns,
+    connectorMigrationOpts
   );
   if (migrationUpTs === null) {
     console.log(yellow3("No changes detected. Skipping migration creation."));
@@ -12311,14 +12313,14 @@ async function generate(options) {
   (0, import_node_fs2.writeFileSync)((0, import_node_path4.resolve)(migrationDir, "up.ts"), migrationUpTs);
   (0, import_node_fs2.writeFileSync)(
     (0, import_node_path4.resolve)(migrationDir, "down.ts"),
-    migrationDnTs ?? generateNoOpMigration()
+    migrationDnTs ?? generateNoOpMigration(connectorMigrationOpts)
   );
   const migrationsRelativePath = (0, import_node_path4.relative)(process.cwd(), migrationsDir);
   console.log(
     `${bgGreen2.white.bold("[CREATED]")} ${cyan3(migrationName)} at ${cyan3(`${migrationsRelativePath}/`)}`
   );
 }
-function generateMigration(prev, curr, direction, renamedTables = {}, renamedColumns = {}) {
+function generateMigration(prev, curr, direction, renamedTables = {}, renamedColumns = {}, defaultOptions) {
   const statements = [];
   const renamedFromKeys = new Set(Object.keys(renamedTables));
   const renamedToKeys = new Set(Object.values(renamedTables));
@@ -12351,7 +12353,7 @@ function generateMigration(prev, curr, direction, renamedTables = {}, renamedCol
   for (const enumName in prev.enums) {
     if (!(enumName in curr.enums)) {
       const enm = prev.enums[enumName];
-      statements.push(`ddl.dropEnum("${enm.schema}", "${enm.name}")`);
+      statements.push(`ddl.dropType("${enm.schema}", "${enm.name}")`);
     }
   }
   for (const enumName in curr.enums) {
@@ -12359,7 +12361,7 @@ function generateMigration(prev, curr, direction, renamedTables = {}, renamedCol
       const enm = curr.enums[enumName];
       const values = enm.values.map((v) => `"${v}"`).join(", ");
       statements.push(
-        `ddl.createEnum("${enm.schema}", "${enm.name}", [${values}])`
+        `ddl.createType("${enm.schema}", "${enm.name}", { asEnum: [${values}] })`
       );
     } else {
       const prevValues = prev.enums[enumName].values;
@@ -12417,15 +12419,15 @@ function generateMigration(prev, curr, direction, renamedTables = {}, renamedCol
             }
             if (afterValue !== null) {
               statements.push(
-                `ddl.alterEnumAddValue("${enm.schema}", "${enm.name}", "${addedValue}", { after: "${afterValue}" })`
+                `ddl.alterType("${enm.schema}", "${enm.name}").addValue("${addedValue}", { after: "${afterValue}" })`
               );
             } else if (beforeValue !== null) {
               statements.push(
-                `ddl.alterEnumAddValue("${enm.schema}", "${enm.name}", "${addedValue}", { before: "${beforeValue}" })`
+                `ddl.alterType("${enm.schema}", "${enm.name}").addValue("${addedValue}", { before: "${beforeValue}" })`
               );
             } else {
               statements.push(
-                `ddl.alterEnumAddValue("${enm.schema}", "${enm.name}", "${addedValue}")`
+                `ddl.alterType("${enm.schema}", "${enm.name}").addValue("${addedValue}")`
               );
             }
           }
@@ -12524,25 +12526,25 @@ function generateMigration(prev, curr, direction, renamedTables = {}, renamedCol
   if (statements.length === 0) return null;
   return `import { type DDLStatement, ddl, type MigrationOptions } from "durcno/migration";
 
-export const options: MigrationOptions = {
-  transaction: true,
-};
+export const options: MigrationOptions = ${stringifyMigrationOpts(defaultOptions ?? { transaction: true })};
 
 export const statements: DDLStatement[] = [
   ${statements.join(",\n  ")},
 ];
 `;
 }
-function generateNoOpMigration() {
+function generateNoOpMigration(defaultOptions) {
   return `import { type DDLStatement, ddl, type MigrationOptions } from "durcno/migration";
 
-export const options: MigrationOptions = {
-  transaction: true,
-};
+export const options: MigrationOptions = ${stringifyMigrationOpts(defaultOptions ?? { transaction: true })};
 
 export const statements: DDLStatement[] = [];
 `;
 }
+function stringifyMigrationOpts(opts) {
+  if (opts.transaction === void 0) opts.transaction = true;
+  return JSON.stringify(opts, null, 2);
+}
 function generateAlterTableStmts(prevTable, currTable, tableName, curr, statements, columnRenames) {
   const alterStatements = [];
   const renamedFromCols = new Set(
@@ -12803,12 +12805,14 @@ function generateConfigFile(config2) {
   return `${envLoader}import { defineConfig } from "durcno";
 import { ${funcName} } from "durcno/connectors/${connector}";
 
-export default defineConfig(${funcName}(), {
+export default defineConfig({
   schema: "${schemaPath}",
   out: "${migrationsDir}",
-  dbCredentials: {
-    url: ${urlValue},
-  },
+  connector: ${funcName}({
+    dbCredentials: {
+      url: ${urlValue},
+    },
+  }),
 });
 `;
 }
@@ -12830,9 +12834,9 @@ function generateIndexFile(schemaPath) {
   const schemaImport = schemaPath.replace(/^db\//, "./");
   return `import { database } from "durcno";
 import * as schema from "${schemaImport}";
-import setup from "../durcno.config.ts";
+import config from "../durcno.config.ts";
 
-export const db = database(schema, setup);
+export const db = database(schema, config);
 `;
 }
 async function promptConfig() {
@@ -13001,8 +13005,8 @@ var import_durcno3 = require("durcno");
 var { bgGreen: bgGreen3, bgYellow, dim: dim3, gray: gray4, yellow: yellow5, green: green2, cyan: cyan5 } = source_default;
 async function migrate(options) {
   const configPath = resolveConfigPath(options.config);
-  const { connector, config: config2 } = await getSetup(configPath);
-  config2.pool = { ...config2.pool, max: 1 };
+  const config2 = await loadConfig(configPath);
+  const { connector } = config2;
   const migrationsDir = (0, import_node_path6.resolve)(
     (0, import_node_path6.dirname)(configPath),
     config2.out || DEFAULT_MIGRATIONS_DIR
@@ -13015,16 +13019,13 @@ async function migrate(options) {
   try {
     let previouslyApplied = [];
     if (await migrationsTableExists(client)) {
-      const db = (0, import_durcno3.database)({ Migrations: import_durcno3.Migrations }, { connector, config: config2 });
+      const db = (0, import_durcno3.database)({ Migrations: import_durcno3.Migrations }, config2);
       const records = await db.from(import_durcno3.Migrations).select();
       previouslyApplied = records.map((r) => r.name);
     }
     for (const migrationDirName of migrationDirNames.sort()) {
       if (!previouslyApplied.includes(migrationDirName)) {
-        await runUpMigration(migrationDirName, migrationsDir, client, {
-          connector,
-          config: config2
-        });
+        await runUpMigration(migrationDirName, migrationsDir, client, config2);
         appliedMigrations.push(migrationDirName);
       }
     }
@@ -13040,7 +13041,7 @@ async function migrate(options) {
           migrationFolder,
           isFirstMigration,
           migrationsDir,
-          { connector, config: config2 },
+          config2,
           client
         );
       }
@@ -13054,41 +13055,42 @@ async function migrate(options) {
   await client.close();
   process.exit(0);
 }
-async function runUpMigration(migrationDirName, migrationsDir, client, setup) {
+async function runUpMigration(migrationDirName, migrationsDir, client, config2) {
   const upPath = (0, import_node_path6.join)(migrationsDir, migrationDirName, "up.ts");
   const migrationModule = await import(upPath);
   const statements = migrationModule.statements;
   const options = migrationModule.options ?? {};
   const useTransaction = options.transaction ?? true;
   const execution = options.execution ?? "joined";
-  if (useTransaction) {
-    await client.query("BEGIN;");
-  }
   try {
     if (statements.length > 0) {
       if (execution === "sequential") {
+        if (useTransaction) await client.query("BEGIN;");
         for (const st of statements) {
           await client.query(st.toSQL());
         }
+        if (useTransaction) await client.query("COMMIT;");
       } else {
-        const sql = `${statements.map((st) => st.toSQL()).join("\n")}`;
+        let sql = "";
+        if (useTransaction) sql += "BEGIN;\n";
+        sql += statements.map((st) => st.toSQL()).join("\n");
+        if (useTransaction) sql += "\nCOMMIT;";
         await client.query(sql);
       }
     }
-    if (useTransaction) {
-      await client.query("COMMIT;");
-    }
     console.log(
       bgGreen3.white.bold("[APPLIED]") + " " + green2(`Migration ${cyan5(migrationDirName)}`) + dim3(".")
     );
-    const db = (0, import_durcno3.database)({ Migrations: import_durcno3.Migrations }, setup);
+    config2.connector.pool = { ...config2.connector.pool, max: 1 };
+    config2.connector.logger = void 0;
+    const db = (0, import_durcno3.database)({ Migrations: import_durcno3.Migrations }, config2);
     await db.insert(import_durcno3.Migrations).values({
       name: migrationDirName,
       createdAt: /* @__PURE__ */ new Date()
     });
     await db.close();
   } catch (e) {
-    if (useTransaction) {
+    if (useTransaction && execution === "sequential") {
       await client.query("ROLLBACK;");
     }
     throw e;
@@ -13106,7 +13108,7 @@ var import_node_readline = require("node:readline");
 var { cyan: cyan6, green: green3, red: red4, yellow: yellow6, gray: gray5, bgCyan, bold: bold2 } = source_default;
 async function shell(options) {
   const configPath = resolveConfigPath(options.config);
-  const { connector } = await getSetup(configPath);
+  const { connector } = await loadConfig(configPath);
   const client = connector.getClient();
   console.log(gray5("Connecting to database..."));
   await client.connect();
@@ -13352,7 +13354,7 @@ var import_migration3 = require("durcno/migration");
 var { bgGreen: bgGreen4, bgRed: bgRed2, yellow: yellow7, red: red5, green: green4, cyan: cyan7, gray: gray6 } = source_default;
 async function squash(start, end, options) {
   const configPath = resolveConfigPath(options.config);
-  const { config: config2 } = await getSetup(configPath);
+  const config2 = await loadConfig(configPath);
   const migrationsDir = (0, import_node_path7.resolve)(
     (0, import_node_path7.dirname)(configPath),
     config2.out || DEFAULT_MIGRATIONS_DIR
@@ -13459,8 +13461,8 @@ var import_durcno4 = require("durcno");
 var { dim: dim4, cyan: cyan8, yellow: yellow8, green: green5 } = source_default;
 async function status(options) {
   const configPath = resolveConfigPath(options.config);
-  const { connector, config: config2 } = await getSetup(configPath);
-  config2.pool = { ...config2.pool, max: 1 };
+  const config2 = await loadConfig(configPath);
+  const { connector } = config2;
   const migrationsDir = (0, import_node_path8.resolve)(
     (0, import_node_path8.dirname)(configPath),
     config2.out || DEFAULT_MIGRATIONS_DIR
@@ -13471,7 +13473,9 @@ async function status(options) {
     console.log(source_default.yellow("No migrations found."));
     process.exit(0);
   }
-  const db = (0, import_durcno4.database)({ Migrations: import_durcno4.Migrations }, { connector, config: config2 });
+  connector.pool = { ...connector.pool, max: 1 };
+  connector.logger = void 0;
+  const db = (0, import_durcno4.database)({ Migrations: import_durcno4.Migrations }, config2);
   const migrationsQuery = db.from(import_durcno4.Migrations).select();
   let migrations;
   const client = connector.getClient();
@@ -13504,7 +13508,7 @@ async function status(options) {
 }
 
 // src/cli/index.ts
-program.version("1.0.0-alpha.1");
+program.version("1.0.0-alpha.3");
 var Options = {
   config: ["--config <path>", "Path to the config file"]
 };

package/dist/src/columns/enum.d.mts

@@ -1,6 +1,6 @@
 import { Sql } from "../sql.mjs";
-import { Column, ColumnConfig } from "./common.mjs";
 import { Enum } from "../enumtype.mjs";
+import { Column, ColumnConfig } from "./common.mjs";
 import * as z from "zod";
 
 //#region src/columns/enum.d.ts

package/dist/src/connectors/bun.d.mts

@@ -1,4 +1,4 @@
-import { Connector } from "./common.mjs";
+import { Connector, ConnectorOptions } from "./common.mjs";
 
 //#region src/connectors/bun.d.ts
 /**
@@ -15,6 +15,6 @@ declare class BunConnector extends Connector {
   getPool(): BunPool;
 }
 /** Creates a Bun SQL connector instance. */
-declare function bun(): BunConnector;
+declare function bun(options: ConnectorOptions): BunConnector;
 //#endregion
 export { BunConnector, bun };

package/dist/src/connectors/bun.mjs

@@ -1,5 +1,5 @@
-import { $Client, $Pool, Connector } from "./common.mjs";
-import { SQL } from "bun";
+import { $Client, $Pool, Connector, getUrlFromDbCredentials } from "./common.mjs";
+import Bun from "bun";
 //#region src/connectors/bun.ts
 /**
 * Connector implementation for the Bun built-in SQL client.
@@ -12,15 +12,15 @@ import { SQL } from "bun";
 */
 var BunConnector = class extends Connector {
 	getClient() {
-		return new BunClient(this.url);
+		return new BunClient(this.options);
 	}
 	getPool() {
-		return new BunPool(this.url, this.config.pool);
+		return new BunPool(this.options);
 	}
 };
 /** Creates a Bun SQL connector instance. */
-function bun() {
-	return new BunConnector();
+function bun(options) {
+	return new BunConnector(options);
 }
 /**
 * Single-connection client wrapper for Bun's SQL API.
@@ -32,9 +32,9 @@ function bun() {
 */
 var BunClient = class extends $Client {
 	#client;
-	constructor(connectionString) {
-		super();
-		this.#client = new SQL(connectionString, { max: 1 });
+	constructor(options) {
+		super(options);
+		this.#client = new Bun.SQL(getUrlFromDbCredentials(options.dbCredentials), { max: 1 });
 		this.query = this.#client.unsafe.bind(this.#client);
 	}
 	async connect() {
@@ -57,9 +57,9 @@ var BunClient = class extends $Client {
 */
 var BunPool = class extends $Pool {
 	#pool;
-	constructor(connectionString, pool) {
-		super();
-		this.#pool = new SQL(connectionString, { max: pool?.max ?? 10 });
+	constructor(options) {
+		super(options);
+		this.#pool = new Bun.SQL(getUrlFromDbCredentials(options.dbCredentials), { max: options.pool?.max ?? 10 });
 		this.query = this.#pool.unsafe.bind(this.#pool);
 	}
 	async connect() {
@@ -72,7 +72,7 @@ var BunPool = class extends $Pool {
 		await this.#pool.end();
 	}
 	async acquireClient() {
-		return new BunPoolClient(await this.#pool.reserve());
+		return new BunPoolClient(await this.#pool.reserve(), this.options);
 	}
 };
 /**
@@ -84,8 +84,8 @@ var BunPool = class extends $Pool {
 */
 var BunPoolClient = class extends $Client {
 	#sql;
-	constructor(sql) {
-		super();
+	constructor(sql, options) {
+		super(options);
 		this.#sql = sql;
 		this.query = this.#sql.unsafe.bind(this.#sql);
 	}

package/dist/src/connectors/common.d.mts

@@ -1,6 +1,50 @@
-import { Config } from "../index.mjs";
+import { DurcnoLogger } from "../logger.mjs";
+import { Query } from "../query-builders/query.mjs";
+import { MigrationOptions } from "../migration/index.mjs";
+import { ConnectionOptions } from "node:tls";
 
 //#region src/connectors/common.d.ts
+/**
+ * Options passed to connector constructors containing database connection
+ * credentials, pool settings, and an optional logger.
+ *
+ * These options were previously part of the top-level `Config` type and are
+ * now scoped to the connector so that `Config` only contains schema/migration
+ * settings.
+ */
+type ConnectorOptions = {
+  /**
+   * Database connection credentials — either a connection URL or individual
+   * host/user/password/database fields.
+   */
+  dbCredentials: ({
+    host: string;
+    port?: number;
+    user: string;
+    password?: string;
+    database: string;
+    ssl?: boolean | "require" | "allow" | "prefer" | "verify-full" | ConnectionOptions;
+  } & {}) | {
+    url: string;
+  };
+  /**
+   * Connection pool configuration.
+   */
+  pool?: {
+    /**
+     * Maximum number of connections in the pool.
+     * @default 10
+     */
+    max?: number;
+  };
+  /**
+   * Optional logger instance for query logging.
+   * Pass a Winston logger or any object with a compatible `info()` method.
+   * When set, all executed queries will be logged at the `info` level with
+   * structured `{ sql, arguments }` metadata.
+   */
+  logger?: DurcnoLogger;
+};
 /**
  * Abstract base class for all database connectors.
  *
@@ -12,12 +56,35 @@ import { Config } from "../index.mjs";
  * @abstract
  */
 declare abstract class Connector {
-  /** The configuration object containing file paths, database credentials, client configs etc. */
-  config: Config;
-  /** The PostgreSQL connection URL derived from the configuration. */
-  url: string;
-  /** Injects the configuration and derives the connection URL. Called by `defineConfig`. */
-  _init(config: Config): void;
+  /**
+   * Default migration options applied to generated migration files for this
+   * connector. When set, the `generate` CLI command will use these values as
+   * the `options` export in the produced `up.ts` / `down.ts` files instead of
+   * the built-in defaults.
+   *
+   * @example
+   * ```typescript
+   * class MyConnector extends Connector {
+   *   static override migrationOptions: MigrationOptions = {
+   *     transaction: false,
+   *     execution: "sequential",
+   *   };
+   * }
+   * ```
+   */
+  static migrationOptions?: MigrationOptions;
+  /**
+   * The original options passed to the connector constructor.
+   * Provides full access to `dbCredentials`, `pool`, and `logger`.
+   * Note: `pool` and `logger` may be mutated on the connector instance after
+   * construction (e.g. by CLI commands); use the instance fields for current values.
+   */
+  options: ConnectorOptions;
+  /** Connection pool size override (can be mutated by CLI commands before `getPool()` is called). */
+  pool?: ConnectorOptions["pool"];
+  /** Optional logger instance for query logging. */
+  logger?: DurcnoLogger;
+  constructor(options: ConnectorOptions);
   /**
    * Creates a single-connection client.
    *
@@ -38,15 +105,19 @@ declare abstract class Connector {
   abstract getPool(): $Pool;
 }
 /**
- * Abstract base class for single-connection database clients.
+ * Abstract base class shared by {@link $Client} and {@link $Pool}.
  *
- * Implementations wrap specific PostgreSQL client libraries to provide
- * a unified interface for query execution, connection management, and
- * result parsing.
+ * Holds the common `options`, `logger`, `query`, and `execQuery` members so
+ * they only need to be defined once.
  *
  * @abstract
  */
-declare abstract class $Client {
+declare abstract class $QueryExecutor {
+  /** The connector options used to create this executor. */
+  options: ConnectorOptions;
+  /** Optional logger instance for query logging. */
+  logger?: DurcnoLogger;
+  constructor(options: ConnectorOptions);
   /**
    * Executes a SQL query with optional parameterized arguments.
    *
@@ -55,6 +126,25 @@ declare abstract class $Client {
    * @returns A promise that resolves with the query result.
    */
   query: (query: string, args?: (string | number | null)[]) => Promise<unknown>;
+  /**
+   * Executes a {@link Query} object by forwarding its sql and arguments to {@link query}.
+   * When a logger is configured, logs the SQL, arguments, and query duration after execution.
+   *
+   * @param q - The {@link Query} object to execute.
+   * @returns A promise that resolves with the raw query result.
+   */
+  execQuery(q: Query<any>): Promise<unknown>;
+}
+/**
+ * Abstract base class for single-connection database clients.
+ *
+ * Implementations wrap specific PostgreSQL client libraries to provide
+ * a unified interface for query execution, connection management, and
+ * result parsing.
+ *
+ * @abstract
+ */
+declare abstract class $Client extends $QueryExecutor {
   /**
    * Establishes a connection to the database.
    *
@@ -87,18 +177,7 @@ declare abstract class $Client {
  *
  * @abstract
  */
-declare abstract class $Pool {
-  /**
-   * Executes a SQL query with optional parameterized arguments.
-   *
-   * The pool automatically acquires a connection, executes the query,
-   * and returns the connection to the pool.
-   *
-   * @param query - The SQL query string to execute.
-   * @param args - Optional array of parameter values for parameterized queries.
-   * @returns A promise that resolves with the query result.
-   */
-  query: (query: string, args?: (string | number | null)[]) => Promise<unknown>;
+declare abstract class $Pool extends $QueryExecutor {
   /**
    * Initializes the connection pool.
    *
@@ -146,4 +225,4 @@ declare abstract class $Pool {
  */
 type QueryExecutor = $Client | $Pool;
 //#endregion
-export { $Pool, Connector, QueryExecutor };
+export { $Client, $Pool, Connector, ConnectorOptions, QueryExecutor };