@objectstack/driver-sql 7.2.1 → 7.4.0

package/dist/index.mjs

@@ -1,7 +1,9 @@
 // src/sql-driver.ts
 import { StorageNameMapping } from "@objectstack/spec/system";
+import { ExternalSchemaModeViolationError } from "@objectstack/spec/shared";
 import knex from "knex";
 import { nanoid } from "nanoid";
+import { createHash } from "crypto";
 var DEFAULT_ID_LENGTH = 16;
 var SEQUENCES_TABLE = "_objectstack_sequences";
 var GLOBAL_TENANT = "__global__";
@@ -58,8 +60,10 @@ var SqlDriver = class {
     this.logger = {
       warn: (msg, meta) => console.warn(msg, meta ?? "")
     };
-    this.config = config;
-    this.knex = knex(config);
+    const { schemaMode, ...knexConfig } = config;
+    this.schemaMode = schemaMode ?? "managed";
+    this.config = knexConfig;
+    this.knex = knex(knexConfig);
   }
   get supports() {
     return {
@@ -102,7 +106,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,
@@ -204,6 +210,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 ExternalSchemaModeViolationError(
+        `DDL operation '${operation}' is forbidden: datasource schemaMode='${this.schemaMode}'. ObjectStack never mutates the schema of an external database.`
+      );
+    }
+  }
   // ===================================
   // Lifecycle
   // ===================================
@@ -742,6 +761,7 @@ var SqlDriver = class {
     await this.initObjects([{ ...objectDef, name: object }]);
   }
   async dropTable(object, _options) {
+    this.assertSchemaMutable("dropTable");
     await this.knex.schema.dropTableIfExists(object);
   }
   /**
@@ -749,6 +769,7 @@ var SqlDriver = class {
    */
   async initObjects(objects) {
     var _a, _b;
+    this.assertSchemaMutable("initObjects");
     await this.ensureDatabaseExists();
     for (const obj of objects) {
       const tableName = StorageNameMapping.resolveTableName(obj);
@@ -834,6 +855,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 = 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;
+      }
     }
   }
   // ===================================