@objectstack/driver-sql 7.3.0 → 7.4.1

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { QueryAST, DriverOptions } from '@objectstack/spec/data';
+import { SchemaMode, QueryAST, DriverOptions } from '@objectstack/spec/data';
 import { IDataDriver } from '@objectstack/spec/contracts';
 import knex, { Knex } from 'knex';
 
@@ -36,8 +36,15 @@ interface IntrospectedSchema {
 /**
  * SqlDriver configuration — passed directly to Knex.
  * See https://knexjs.org/guide/#configuration-options
+ *
+ * `schemaMode` (ADR-0015) is an ObjectStack-level concern, not a Knex
+ * option: it is stripped before constructing the Knex instance and gates
+ * all schema-mutating DDL. Defaults to `'managed'` when omitted, preserving
+ * legacy behaviour.
  */
-type SqlDriverConfig = Knex.Config;
+type SqlDriverConfig = Knex.Config & {
+    schemaMode?: SchemaMode;
+};
 /**
  * SQL Driver for ObjectStack.
  *
@@ -175,7 +182,21 @@ declare class SqlDriver implements IDataDriver {
         sql: string;
         bindings: any[];
     } | null;
+    /**
+     * Schema ownership mode (ADR-0015). When not `'managed'`, all
+     * schema-mutating DDL is rejected by {@link assertSchemaMutable}. The
+     * runtime injects this from `Datasource.schemaMode`; defaults to
+     * `'managed'` so existing callers are unaffected.
+     */
+    protected readonly schemaMode: SchemaMode;
     constructor(config: SqlDriverConfig);
+    /**
+     * DDL gate (ADR-0015 §5.1). Single choke-point asserting that
+     * schema-mutating DDL is only performed on a `managed` datasource.
+     * Federated datasources (`external` / `validate-only`) are guests in a
+     * database ObjectStack does not own and must never run DDL against.
+     */
+    protected assertSchemaMutable(operation: string): void;
     connect(): Promise<void>;
     checkHealth(): Promise<boolean>;
     disconnect(): Promise<void>;
@@ -280,6 +301,38 @@ declare class SqlDriver implements IDataDriver {
         name: string;
         fields?: Record<string, any>;
     }>): Promise<void>;
+    /**
+     * Build a deterministic index name for a declared index so repeated
+     * `initObjects` runs converge on the same identifier (and can detect an
+     * already-materialized index by name). Long names are hash-suffixed to
+     * stay within the 63/64-char identifier limits of Postgres/MySQL.
+     */
+    protected buildIndexName(tableName: string, fields: string[], unique: boolean): string;
+    /**
+     * Read the names of indexes that already exist on a table, per dialect.
+     * Used to make declared-index sync idempotent across repeated runs.
+     * Failures are swallowed — at worst we attempt a create and absorb the
+     * "already exists" error in `syncDeclaredIndexes`.
+     */
+    protected getExistingIndexNames(tableName: string): Promise<Set<string>>;
+    /**
+     * Materialize declared object-level indexes.
+     *
+     * - Multi-column and single-column indexes are both supported.
+     * - `unique: true` emits a UNIQUE index. NULL-distinct semantics are the
+     *   default across SQLite/Postgres/MySQL, so multiple NULL rows remain
+     *   allowed while non-NULL duplicates are rejected — matching the
+     *   convergence-on-conflict pattern the messaging pipeline relies on.
+     * - Idempotent: indexes already present (by deterministic name) are
+     *   skipped, and an "already exists" race is absorbed.
+     * - Indexes referencing a column that wasn't materialized (e.g. a virtual
+     *   `formula` field) are skipped with a warning rather than failing sync.
+     */
+    protected syncDeclaredIndexes(tableName: string, indexes: Array<{
+        name?: string;
+        fields?: string[];
+        unique?: boolean;
+    }>, physicalColumns: Set<string>): Promise<void>;
     introspectSchema(): Promise<IntrospectedSchema>;
     /** Expose the underlying Knex instance for advanced usage. */
     getKnex(): Knex;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { QueryAST, DriverOptions } from '@objectstack/spec/data';
+import { SchemaMode, QueryAST, DriverOptions } from '@objectstack/spec/data';
 import { IDataDriver } from '@objectstack/spec/contracts';
 import knex, { Knex } from 'knex';
 
@@ -36,8 +36,15 @@ interface IntrospectedSchema {
 /**
  * SqlDriver configuration — passed directly to Knex.
  * See https://knexjs.org/guide/#configuration-options
+ *
+ * `schemaMode` (ADR-0015) is an ObjectStack-level concern, not a Knex
+ * option: it is stripped before constructing the Knex instance and gates
+ * all schema-mutating DDL. Defaults to `'managed'` when omitted, preserving
+ * legacy behaviour.
  */
-type SqlDriverConfig = Knex.Config;
+type SqlDriverConfig = Knex.Config & {
+    schemaMode?: SchemaMode;
+};
 /**
  * SQL Driver for ObjectStack.
  *
@@ -175,7 +182,21 @@ declare class SqlDriver implements IDataDriver {
         sql: string;
         bindings: any[];
     } | null;
+    /**
+     * Schema ownership mode (ADR-0015). When not `'managed'`, all
+     * schema-mutating DDL is rejected by {@link assertSchemaMutable}. The
+     * runtime injects this from `Datasource.schemaMode`; defaults to
+     * `'managed'` so existing callers are unaffected.
+     */
+    protected readonly schemaMode: SchemaMode;
     constructor(config: SqlDriverConfig);
+    /**
+     * DDL gate (ADR-0015 §5.1). Single choke-point asserting that
+     * schema-mutating DDL is only performed on a `managed` datasource.
+     * Federated datasources (`external` / `validate-only`) are guests in a
+     * database ObjectStack does not own and must never run DDL against.
+     */
+    protected assertSchemaMutable(operation: string): void;
     connect(): Promise<void>;
     checkHealth(): Promise<boolean>;
     disconnect(): Promise<void>;
@@ -280,6 +301,38 @@ declare class SqlDriver implements IDataDriver {
         name: string;
         fields?: Record<string, any>;
     }>): Promise<void>;
+    /**
+     * Build a deterministic index name for a declared index so repeated
+     * `initObjects` runs converge on the same identifier (and can detect an
+     * already-materialized index by name). Long names are hash-suffixed to
+     * stay within the 63/64-char identifier limits of Postgres/MySQL.
+     */
+    protected buildIndexName(tableName: string, fields: string[], unique: boolean): string;
+    /**
+     * Read the names of indexes that already exist on a table, per dialect.
+     * Used to make declared-index sync idempotent across repeated runs.
+     * Failures are swallowed — at worst we attempt a create and absorb the
+     * "already exists" error in `syncDeclaredIndexes`.
+     */
+    protected getExistingIndexNames(tableName: string): Promise<Set<string>>;
+    /**
+     * Materialize declared object-level indexes.
+     *
+     * - Multi-column and single-column indexes are both supported.
+     * - `unique: true` emits a UNIQUE index. NULL-distinct semantics are the
+     *   default across SQLite/Postgres/MySQL, so multiple NULL rows remain
+     *   allowed while non-NULL duplicates are rejected — matching the
+     *   convergence-on-conflict pattern the messaging pipeline relies on.
+     * - Idempotent: indexes already present (by deterministic name) are
+     *   skipped, and an "already exists" race is absorbed.
+     * - Indexes referencing a column that wasn't materialized (e.g. a virtual
+     *   `formula` field) are skipped with a warning rather than failing sync.
+     */
+    protected syncDeclaredIndexes(tableName: string, indexes: Array<{
+        name?: string;
+        fields?: string[];
+        unique?: boolean;
+    }>, physicalColumns: Set<string>): Promise<void>;
     introspectSchema(): Promise<IntrospectedSchema>;
     /** Expose the underlying Knex instance for advanced usage. */
     getKnex(): Knex;

package/dist/index.js

@@ -37,8 +37,10 @@ module.exports = __toCommonJS(index_exports);
 
 // src/sql-driver.ts
 var import_system = require("@objectstack/spec/system");
+var import_shared = require("@objectstack/spec/shared");
 var import_knex = __toESM(require("knex"));
 var import_nanoid = require("nanoid");
+var import_node_crypto = require("crypto");
 var DEFAULT_ID_LENGTH = 16;
 var SEQUENCES_TABLE = "_objectstack_sequences";
 var GLOBAL_TENANT = "__global__";
@@ -95,8 +97,10 @@ var SqlDriver = class {
     this.logger = {
       warn: (msg, meta) => console.warn(msg, meta ?? "")
     };
-    this.config = config;
-    this.knex = (0, import_knex.default)(config);
+    const { schemaMode, ...knexConfig } = config;
+    this.schemaMode = schemaMode ?? "managed";
+    this.config = knexConfig;
+    this.knex = (0, import_knex.default)(knexConfig);
   }
   get supports() {
     return {
@@ -139,7 +143,9 @@ var SqlDriver = class {
       schemaSync: true,
       batchSchemaSync: false,
       migrations: false,
-      indexes: false,
+      // Object-level declared `indexes` (incl. multi-column UNIQUE) are
+      // materialized during `initObjects` — see `syncDeclaredIndexes`.
+      indexes: true,
       // Performance & Optimization
       connectionPooling: true,
       preparedStatements: true,
@@ -241,6 +247,19 @@ var SqlDriver = class {
     }
     return null;
   }
+  /**
+   * DDL gate (ADR-0015 §5.1). Single choke-point asserting that
+   * schema-mutating DDL is only performed on a `managed` datasource.
+   * Federated datasources (`external` / `validate-only`) are guests in a
+   * database ObjectStack does not own and must never run DDL against.
+   */
+  assertSchemaMutable(operation) {
+    if (this.schemaMode !== "managed") {
+      throw new import_shared.ExternalSchemaModeViolationError(
+        `DDL operation '${operation}' is forbidden: datasource schemaMode='${this.schemaMode}'. ObjectStack never mutates the schema of an external database.`
+      );
+    }
+  }
   // ===================================
   // Lifecycle
   // ===================================
@@ -779,6 +798,7 @@ var SqlDriver = class {
     await this.initObjects([{ ...objectDef, name: object }]);
   }
   async dropTable(object, _options) {
+    this.assertSchemaMutable("dropTable");
     await this.knex.schema.dropTableIfExists(object);
   }
   /**
@@ -786,6 +806,7 @@ var SqlDriver = class {
    */
   async initObjects(objects) {
     var _a, _b;
+    this.assertSchemaMutable("initObjects");
     await this.ensureDatabaseExists();
     for (const obj of objects) {
       const tableName = import_system.StorageNameMapping.resolveTableName(obj);
@@ -871,6 +892,101 @@ var SqlDriver = class {
           }
         });
       }
+      const declaredIndexes = obj.indexes;
+      if (Array.isArray(declaredIndexes) && declaredIndexes.length > 0) {
+        const colInfo = await this.knex(tableName).columnInfo();
+        const physicalColumns = new Set(Object.keys(colInfo));
+        await this.syncDeclaredIndexes(tableName, declaredIndexes, physicalColumns);
+      }
+    }
+  }
+  /**
+   * Build a deterministic index name for a declared index so repeated
+   * `initObjects` runs converge on the same identifier (and can detect an
+   * already-materialized index by name). Long names are hash-suffixed to
+   * stay within the 63/64-char identifier limits of Postgres/MySQL.
+   */
+  buildIndexName(tableName, fields, unique) {
+    const prefix = unique ? "uniq" : "idx";
+    const base = `${prefix}_${tableName}_${fields.join("_")}`;
+    const MAX = 60;
+    if (base.length <= MAX) return base;
+    const hash = (0, import_node_crypto.createHash)("sha1").update(base).digest("hex").slice(0, 8);
+    return `${`${prefix}_${tableName}`.slice(0, MAX - 9)}_${hash}`;
+  }
+  /**
+   * Read the names of indexes that already exist on a table, per dialect.
+   * Used to make declared-index sync idempotent across repeated runs.
+   * Failures are swallowed — at worst we attempt a create and absorb the
+   * "already exists" error in `syncDeclaredIndexes`.
+   */
+  async getExistingIndexNames(tableName) {
+    const names = /* @__PURE__ */ new Set();
+    try {
+      if (this.isSqlite) {
+        const safe = tableName.replace(/[^a-zA-Z0-9_]/g, "");
+        const rows = await this.knex.raw(`PRAGMA index_list(${safe})`);
+        for (const r of rows) names.add(r.name);
+      } else if (this.isPostgres) {
+        const res = await this.knex.raw(
+          `SELECT indexname FROM pg_indexes WHERE schemaname = 'public' AND tablename = ?`,
+          [tableName]
+        );
+        for (const r of res.rows) names.add(r.indexname);
+      } else if (this.isMysql) {
+        const res = await this.knex.raw(
+          `SELECT INDEX_NAME FROM information_schema.STATISTICS WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ?`,
+          [tableName]
+        );
+        for (const r of res[0]) names.add(r.INDEX_NAME);
+      }
+    } catch {
+    }
+    return names;
+  }
+  /**
+   * Materialize declared object-level indexes.
+   *
+   * - Multi-column and single-column indexes are both supported.
+   * - `unique: true` emits a UNIQUE index. NULL-distinct semantics are the
+   *   default across SQLite/Postgres/MySQL, so multiple NULL rows remain
+   *   allowed while non-NULL duplicates are rejected — matching the
+   *   convergence-on-conflict pattern the messaging pipeline relies on.
+   * - Idempotent: indexes already present (by deterministic name) are
+   *   skipped, and an "already exists" race is absorbed.
+   * - Indexes referencing a column that wasn't materialized (e.g. a virtual
+   *   `formula` field) are skipped with a warning rather than failing sync.
+   */
+  async syncDeclaredIndexes(tableName, indexes, physicalColumns) {
+    const existing = await this.getExistingIndexNames(tableName);
+    for (const idx of indexes) {
+      const fields = Array.isArray(idx?.fields) ? idx.fields.filter((f) => typeof f === "string" && f.length > 0) : [];
+      if (fields.length === 0) continue;
+      const missing = fields.filter((f) => !physicalColumns.has(f));
+      if (missing.length > 0) {
+        this.logger.warn(
+          `[sql-driver] skipping declared index on "${tableName}" \u2014 column(s) not materialized: ${missing.join(", ")}`,
+          { tableName, fields }
+        );
+        continue;
+      }
+      const unique = idx.unique === true;
+      const name = typeof idx.name === "string" && idx.name.trim() ? idx.name.trim() : this.buildIndexName(tableName, fields, unique);
+      if (existing.has(name)) continue;
+      try {
+        await this.knex.schema.alterTable(tableName, (table) => {
+          if (unique) {
+            table.unique(fields, { indexName: name });
+          } else {
+            table.index(fields, name);
+          }
+        });
+        existing.add(name);
+      } catch (e) {
+        const msg = String(e?.message ?? e);
+        if (/already exists|duplicate key name|exists/i.test(msg)) continue;
+        throw e;
+      }
     }
   }
   // ===================================