spice-couchbase 2.0.60 → 2.0.62

package/src/index.auto-optimize.test.js

@@ -0,0 +1,393 @@
+"use strict";
+
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const path = require("node:path");
+const vm = require("node:vm");
+const { test } = require("node:test");
+const { buildCoveringIndex, buildCoveringIndexDefinition } = require("./utility");
+
+const keyspace = { bucket: "saturn", scope: "test", collection: "users" };
+const lookupQuery = "SELECT name, email FROM users WHERE status = 'active'";
+
+function existingIndex(index_key, overrides = {}) {
+  return { name: "legacy_covering_index", using: "gsi", state: "online", index_key, ...overrides };
+}
+
+function executionScope(indexes = [], { inventoryError, inventoryResponse, plan } = {}) {
+  const calls = [];
+  return {
+    calls,
+    async query(statement, options) {
+      calls.push({ statement, options });
+      if (statement.startsWith("EXPLAIN ")) {
+        return { rows: [plan || { "#operator": "Fetch" }] };
+      }
+      if (statement.includes("FROM system:indexes")) {
+        if (inventoryError) throw inventoryError;
+        return inventoryResponse === undefined ? { rows: indexes } : inventoryResponse;
+      }
+      return { rows: [] };
+    },
+  };
+}
+
+function createStatements(scope) {
+  return scope.calls.filter(({ statement }) => statement.startsWith("CREATE INDEX "));
+}
+
+// Isolate optimizer state and time without connecting to Couchbase or sleeping.
+// Each load is a fresh module: its own seen-set, cooldown and policy.
+function loadDriver(durationMs, env = {}) {
+  let tick = BigInt(0);
+  const module = { exports: {} };
+  vm.runInNewContext(fs.readFileSync(path.join(__dirname, "index.js"), "utf8"), {
+    require,
+    module,
+    console,
+    process: {
+      env,
+      hrtime: {
+        bigint: () => {
+          const current = tick;
+          tick += BigInt(durationMs) * BigInt(1000000);
+          return current;
+        },
+      },
+    },
+  });
+  return module.exports;
+}
+
+function instanceOf(Database) {
+  const db = Object.create(Database.prototype);
+  db.bucket = "saturn";
+  db.scope_name = "test";
+  db.collection_name = "users";
+  db.cluster = { query: async () => ({ rows: [] }) };
+  return db;
+}
+
+// Opted in wholesale: per-resource resolution has its own tests further down.
+function createDatabase(durationMs, env = {}) {
+  const db = instanceOf(loadDriver(durationMs, env));
+  db.auto_optimize = true;
+  return db;
+}
+
+test("auto-optimization only starts above the default 3-second threshold", async () => {
+  for (const duration of [1001, 2999, 3000, 3001]) {
+    const db = createDatabase(duration);
+    let optimizations = 0;
+    db.optimize = async () => { optimizations += 1; };
+    await db.query("SELECT name FROM users WHERE status = 'active'");
+    assert.equal(optimizations, duration > 3000 ? 1 : 0, `${duration}ms`);
+  }
+});
+
+test("the explicit slow-query threshold override remains supported", async () => {
+  const db = createDatabase(5001, { SPICE_COUCHBASE_SLOW_QUERY_MS: "5000" });
+  let optimizations = 0;
+  db.optimize = async () => { optimizations += 1; };
+  await db.query("SELECT name FROM users WHERE status = 'active'");
+  assert.equal(optimizations, 1);
+});
+
+test("Fetch plans for full-document projections never create indexes", async () => {
+  for (const projection of ["*", "users.*", "`users`.*", "(`users`).*, META(`users`).id AS id"]) {
+    const db = createDatabase(0);
+    const statements = [];
+    const query = `SELECT ${projection} FROM users WHERE status = 'active' ORDER BY created_at DESC`;
+    await db.optimize(query, {
+      query: async (statement) => {
+        statements.push(statement);
+        return { rows: [{ "#operator": "Fetch" }] };
+      },
+    });
+    assert.deepEqual(statements, [`EXPLAIN ${query}`]);
+  }
+});
+
+test("Fetch plans for explicit fields still create a covering index", async () => {
+  const db = createDatabase(0);
+  const scope = executionScope();
+  await db.optimize("SELECT name FROM users WHERE status = 'active'", scope);
+  assert.equal(scope.calls.length, 3);
+  assert.match(scope.calls[1].statement, /FROM system:indexes/);
+  assert.equal(JSON.stringify(scope.calls[1].options.parameters), JSON.stringify(keyspace));
+  assert.match(scope.calls[2].statement, /^CREATE INDEX `adv_covered_/);
+  assert.match(scope.calls[2].statement, /`status`, `name`/);
+});
+
+test("reordered selected columns and changed literals generate identical DDL", () => {
+  const original = buildCoveringIndex(lookupQuery, keyspace);
+  const reordered = buildCoveringIndex("SELECT email, name FROM users WHERE status = 'pending'", keyspace);
+  assert.equal(original, reordered);
+});
+
+test("adding explicit ascending order cannot rename an identical definition", () => {
+  const base = "SELECT status, created_at FROM users WHERE status = 'pending'";
+  assert.equal(buildCoveringIndex(base, keyspace), buildCoveringIndex(`${base} ORDER BY created_at ASC`, keyspace));
+});
+
+test("genuinely different access-key order and direction keep distinct definitions", () => {
+  const base = "SELECT name, email FROM users WHERE status = 'active'";
+  const asc = buildCoveringIndex(`${base} ORDER BY name, email`, keyspace);
+  const desc = buildCoveringIndex(`${base} ORDER BY name DESC, email`, keyspace);
+  const reordered = buildCoveringIndex(`${base} ORDER BY email, name`, keyspace);
+  assert.notEqual(asc, desc);
+  assert.notEqual(asc, reordered);
+  assert.notEqual(asc.match(/adv_covered_\w+/)[0], reordered.match(/adv_covered_\w+/)[0]);
+});
+
+test("case-distinct document fields are not collapsed", () => {
+  const statement = buildCoveringIndex("SELECT Name, name, Status, status FROM users ORDER BY Name DESC", keyspace);
+  assert.match(statement, /`Name` DESC/);
+  assert.match(statement, /`name`/);
+  assert.match(statement, /`Status`/);
+  assert.match(statement, /`status`/);
+  assert.doesNotMatch(statement, /`name` DESC/);
+});
+
+for (const state of ["online", "deferred", "pending", "building", "offline"]) {
+  test(`an existing ${state} index with reordered projection keys prevents creation`, async () => {
+    const scope = executionScope([
+      existingIndex(["`deleted` INCLUDE MISSING", "`status`", "`name`", "`email`"], { state }),
+    ]);
+    await createDatabase(0).optimize(lookupQuery, scope);
+    assert.equal(scope.calls.length, 2);
+    assert.equal(createStatements(scope).length, 0);
+  });
+}
+
+test("a wider existing index covers a projection subset without another index", async () => {
+  const scope = executionScope([
+    existingIndex(["`deleted` INCLUDE MISSING", "`status`", "`name`", "`phone`", "`email` DESC"]),
+  ]);
+  await createDatabase(0).optimize(lookupQuery, scope);
+  assert.equal(createStatements(scope).length, 0);
+});
+
+test("catalog key formatting, explicit ASC and attribute order are normalized", async () => {
+  for (const leadingKey of ["((`deleted`)) ASC INCLUDE MISSING", "deleted INCLUDE MISSING ASC"]) {
+    const scope = executionScope([
+      existingIndex([leadingKey, "(status) ASC", "`name`", "email ASC"]),
+    ]);
+    await createDatabase(0).optimize(lookupQuery, scope);
+    assert.equal(createStatements(scope).length, 0, leadingKey);
+  }
+});
+
+const incompatibleIndexes = [
+  ["missing a projection field", existingIndex(["`deleted` INCLUDE MISSING", "`status`", "`name`"])],
+  ["different access prefix", existingIndex(["`deleted` INCLUDE MISSING", "`name`", "`status`", "`email`"])],
+  ["missing-leading-key exclusion", existingIndex(["`deleted`", "`status`", "`name`", "`email`"])],
+  ["case-distinct field", existingIndex(["`deleted` INCLUDE MISSING", "`status`", "`Name`", "`email`"])],
+  ["expression instead of the field", existingIndex(["`deleted` INCLUDE MISSING", "`status`", "LOWER(`name`)", "`email`"])],
+  ["array key", existingIndex(["`deleted` INCLUDE MISSING", "`status`", "`name`", "`email`", "DISTINCT ARRAY v FOR v IN tags END"])],
+  ["partial index", existingIndex(["`deleted` INCLUDE MISSING", "`status`", "`name`", "`email`"], { condition: "(`status` = 'pending')" })],
+  ["primary index", existingIndex([], { is_primary: true })],
+];
+for (const [reason, index] of incompatibleIndexes) {
+  test(`does not mistake ${reason} for a compatible covering index`, async () => {
+    const scope = executionScope([index]);
+    await createDatabase(0).optimize(lookupQuery, scope);
+    assert.equal(createStatements(scope).length, 1);
+  });
+}
+
+test("existing opposite sort direction does not satisfy the requested sort", async () => {
+  const query = `${lookupQuery} ORDER BY created_at DESC`;
+  const scope = executionScope([
+    existingIndex(["`deleted` INCLUDE MISSING", "`status`", "`created_at`", "`name`", "`email`"]),
+  ]);
+  await createDatabase(0).optimize(query, scope);
+  assert.equal(createStatements(scope).length, 1);
+  assert.match(createStatements(scope)[0].statement, /`created_at` DESC/);
+});
+
+test("same generated name is never recreated even if its keys are unavailable", async () => {
+  const candidate = buildCoveringIndexDefinition(lookupQuery, keyspace);
+  const scope = executionScope([{ name: candidate.name, state: "building" }]);
+  await createDatabase(0).optimize(lookupQuery, scope);
+  assert.equal(createStatements(scope).length, 0);
+});
+
+test("catalog failure or incomplete results prevent creation and trigger cooldown", async () => {
+  for (const options of [
+    { inventoryError: new Error("query service unavailable") },
+    { inventoryResponse: {} },
+    { inventoryResponse: { rows: [], meta: { warnings: [{ message: "partial inventory" }] } } },
+  ]) {
+    const db = createDatabase(3001);
+    const scope = executionScope([], options);
+    await db.optimize(lookupQuery, scope);
+    assert.equal(createStatements(scope).length, 0);
+    let retries = 0;
+    db.optimize = async () => { retries++; };
+    await db.query("SELECT email FROM users WHERE status = 'pending'");
+    assert.equal(retries, 0);
+  }
+});
+
+test("already-covered plans need neither an inventory lookup nor creation", async () => {
+  const scope = executionScope([], { plan: { "#operator": "IndexScan3" } });
+  await createDatabase(0).optimize(lookupQuery, scope);
+  assert.equal(scope.calls.length, 1);
+});
+
+test("a default collection uses default names in its inventory lookup", async () => {
+  const db = createDatabase(0);
+  db.scope_name = undefined;
+  db.collection_name = undefined;
+  const scope = executionScope();
+  await db.optimize("SELECT name FROM saturn WHERE status = 'active'", scope);
+  assert.equal(JSON.stringify(scope.calls[1].options.parameters), JSON.stringify({
+    bucket: "saturn", scope: "_default", collection: "_default",
+  }));
+  assert.match(createStatements(scope)[0].statement, /`saturn`\.`_default`\.`_default`/);
+});
+
+// ---- Per-resource opt-in for auto cover indexing ----
+
+// Nothing decided at instance level: resolution falls through to the call,
+// the application policy and the static lists.
+function createUnconfiguredDatabase(env = {}) {
+  return instanceOf(loadDriver(3001, env));
+}
+
+async function optimizationsFor(db, statement, ...queryArgs) {
+  let optimizations = 0;
+  db.optimize = async () => { optimizations += 1; };
+  await db.query(statement, ...queryArgs);
+  return optimizations;
+}
+
+const slowLookup = "SELECT name FROM users WHERE status = 'active'";
+const EVERY_RESOURCE = { SPICE_COUCHBASE_OPTIMIZE_RESOURCES: "*" };
+
+test("no resource is auto-indexed unless something opts it in", async () => {
+  assert.equal(await optimizationsFor(createUnconfiguredDatabase(), slowLookup), 0);
+  assert.equal(await optimizationsFor(
+    createUnconfiguredDatabase({ SPICE_COUCHBASE_OPTIMIZE_RESOURCES: "" }), slowLookup), 0);
+});
+
+test("SPICE_COUCHBASE_OPTIMIZE_RESOURCES enables the instance's collection, case-insensitively", async () => {
+  const env = { SPICE_COUCHBASE_OPTIMIZE_RESOURCES: " Users ,audit_log,, `sessions` " };
+  assert.equal(await optimizationsFor(createUnconfiguredDatabase(env), slowLookup), 1);
+
+  const sessions = createUnconfiguredDatabase(env);
+  sessions.collection_name = "sessions";
+  assert.equal(await optimizationsFor(sessions, "SELECT id FROM sessions"), 1);
+
+  const orders = createUnconfiguredDatabase(env);
+  orders.collection_name = "orders";
+  assert.equal(await optimizationsFor(orders, "SELECT total FROM orders WHERE status = 'paid'"), 0);
+});
+
+test("a wildcard restores auto indexing for every resource", async () => {
+  const db = createUnconfiguredDatabase(EVERY_RESOURCE);
+  db.collection_name = "anything";
+  assert.equal(await optimizationsFor(db, "SELECT a FROM anything WHERE b = 1"), 1);
+});
+
+test("legacy bucket mode resolves the resource from the type literal the driver adds", async () => {
+  const env = { SPICE_COUCHBASE_OPTIMIZE_RESOURCES: "audit_log" };
+  for (const [type, expected] of [["audit_log", 1], ["users", 0]]) {
+    const db = createUnconfiguredDatabase(env);
+    db.collection_name = "_default";
+    db.scope_name = "_default";
+    assert.equal(await optimizationsFor(db,
+      `SELECT actor FROM \`saturn\` WHERE type = '${type}' AND deleted = false`), expected, type);
+  }
+});
+
+test("a fully qualified or aliased FROM keyspace matches on its last segment", async () => {
+  const env = { SPICE_COUCHBASE_OPTIMIZE_RESOURCES: "logs" };
+  for (const statement of [
+    "SELECT level FROM `default`:`saturn`.`app`.`logs` WHERE level = 'error'",
+    "SELECT l.level FROM saturn.app.logs AS l WHERE l.level = 'error'",
+    "SELECT u.name FROM users AS u JOIN `logs` AS l ON l.user_id = META(u).id",
+  ]) {
+    const db = createUnconfiguredDatabase(env);
+    db.collection_name = "_default";
+    assert.equal(await optimizationsFor(db, statement), 1, statement);
+  }
+});
+
+test("connection or constructor lists work without the environment variable", async () => {
+  const db = createUnconfiguredDatabase();
+  db.enabled_resources = new Set(["users"]);
+  assert.equal(await optimizationsFor(db, slowLookup), 1);
+});
+
+test("an explicit instance setting overrides every resource list", async () => {
+  const on = createUnconfiguredDatabase();
+  on.auto_optimize = true;
+  assert.equal(await optimizationsFor(on, slowLookup), 1);
+
+  const off = createUnconfiguredDatabase(EVERY_RESOURCE);
+  off.auto_optimize = false;
+  assert.equal(await optimizationsFor(off, slowLookup), 0);
+});
+
+test("a single call can opt in or out through query options", async () => {
+  assert.equal(await optimizationsFor(createUnconfiguredDatabase(), slowLookup, { auto_optimize: true }), 1);
+  assert.equal(await optimizationsFor(createUnconfiguredDatabase(EVERY_RESOURCE), slowLookup, { auto_optimize: false }), 0);
+  assert.equal(await optimizationsFor(createUnconfiguredDatabase(EVERY_RESOURCE), slowLookup, "cluster", { optimize: false }), 0);
+  // The scan-consistency shorthand is not an opt-in or opt-out.
+  assert.equal(await optimizationsFor(createUnconfiguredDatabase(EVERY_RESOURCE), slowLookup, "cluster", true), 1);
+  assert.equal(await optimizationsFor(createUnconfiguredDatabase(), slowLookup, "cluster", true), 0);
+});
+
+test("an application policy decides per resource and sees the statement context", async () => {
+  const Database = loadDriver(3001);
+  const seen = [];
+  Database.setAutoOptimizePolicy((resource, context) => {
+    seen.push([resource, context]);
+    return resource === "users";
+  });
+  assert.equal(Database.getAutoOptimizePolicy().length, 2);
+
+  const users = instanceOf(Database);
+  users.connection_name = "default";
+  assert.equal(await optimizationsFor(users, slowLookup), 1);
+  // Objects cross the vm boundary, so compare by value rather than prototype.
+  assert.equal(JSON.stringify(seen[0]), JSON.stringify(["users", { query: slowLookup, connection: "default", collection: "users" }]));
+
+  const orders = instanceOf(Database);
+  orders.collection_name = "orders";
+  assert.equal(await optimizationsFor(orders, "SELECT total FROM orders WHERE status = 'paid'"), 0);
+});
+
+test("a policy that returns undefined defers to the static lists", async () => {
+  for (const [env, expected] of [[{ SPICE_COUCHBASE_OPTIMIZE_RESOURCES: "users" }, 1], [{}, 0]]) {
+    const Database = loadDriver(3001, env);
+    Database.setAutoOptimizePolicy(() => undefined);
+    assert.equal(await optimizationsFor(instanceOf(Database), slowLookup), expected);
+  }
+});
+
+test("an explicit policy refusal wins over the wildcard, and a throwing policy counts as a refusal", async () => {
+  for (const policy of [() => false, () => { throw new Error("settings unavailable"); }]) {
+    const Database = loadDriver(3001, EVERY_RESOURCE);
+    Database.setAutoOptimizePolicy(policy);
+    assert.equal(await optimizationsFor(instanceOf(Database), slowLookup), 0);
+  }
+});
+
+test("the policy can be cleared and must be a function", async () => {
+  const Database = loadDriver(3001, EVERY_RESOURCE);
+  Database.setAutoOptimizePolicy(() => false);
+  Database.setAutoOptimizePolicy(null);
+  assert.equal(Database.getAutoOptimizePolicy(), null);
+  assert.equal(await optimizationsFor(instanceOf(Database), slowLookup), 1);
+  assert.throws(() => Database.setAutoOptimizePolicy("users"), { name: "TypeError" });
+});
+
+test("a declined statement is not remembered as already optimised", async () => {
+  const db = createUnconfiguredDatabase();
+  assert.equal(await optimizationsFor(db, slowLookup), 0);
+  db.auto_optimize = true;
+  assert.equal(await optimizationsFor(db, slowLookup), 1);
+});

package/src/index.js

@@ -4,6 +4,7 @@ let _ = require("lodash");
 let couchbase = require("couchbase");
 const { ConflictResolutionType } = require("couchbase");
 const { QueryScanConsistency } = require("couchbase");
+const { parseResourceList, extractStatementResources } = require("./utility");
 
 if (!Promise.allSettled) {
   Promise.allSettled = (promises) =>
@@ -25,12 +26,12 @@ if (!Promise.allSettled) {
 // Couchbase lookupIn has a limit of 16 operations per call
 const LOOKUP_IN_MAX_SPECS = 16;
 
-// Auto-optimisation guard rails. `query()` fires `optimize()` (an EXPLAIN plus
-// a possible CREATE INDEX) for any statement slower than SLOW_QUERY_MS. When
+// Auto-optimisation guard rails. `query()` fires `optimize()` (an EXPLAIN,
+// index inventory check, and possible CREATE INDEX) above SLOW_QUERY_MS. When
 // the cluster is degraded every statement is slow, so without limits each
 // query spawned two more heavy ones and deepened the outage. These caps make it
 // a bounded, once-per-statement background task that backs off on failure.
-const SLOW_QUERY_MS = Number(process.env.SPICE_COUCHBASE_SLOW_QUERY_MS || 1000);
+const SLOW_QUERY_MS = Number(process.env.SPICE_COUCHBASE_SLOW_QUERY_MS || 3000);
 const AUTO_OPTIMIZE_ENABLED = !["0", "false", "no", "off"].includes(
   String(process.env.SPICE_COUCHBASE_AUTO_OPTIMIZE ?? "true")
     .trim()
@@ -50,6 +51,37 @@ const optimizeState = {
   seen: new Set(),
   cooldownUntil: 0,
 };
+// Auto cover indexing is opt-in per resource. A resource is the collection a
+// Database instance serves (scoped deployments) or the `type = '...'` literal
+// legacy bucket mode adds to every statement; raw statements also count their
+// FROM / JOIN keyspaces. Names are case-insensitive. A slow statement is
+// optimised when, in order of precedence:
+//   1. the call says so:        query_options.auto_optimize (true / false)
+//   2. the instance says so:    constructor option or connection config
+//                               `auto_optimize` (true / false)
+//   3. the application policy:  Database.setAutoOptimizePolicy(fn), where
+//                               fn(resource, context) returns true / false, or
+//                               undefined to defer to the static lists
+//   4. a static list names a resource it touches: comma-separated
+//      SPICE_COUCHBASE_OPTIMIZE_RESOURCES (`*` = every resource, which is the
+//      pre-2.0.62 behaviour), or connection config / constructor option
+//      `auto_optimize_resources`.
+const OPTIMIZE_ENABLED_RESOURCES = parseResourceList(
+  process.env.SPICE_COUCHBASE_OPTIMIZE_RESOURCES,
+);
+let autoOptimizePolicy = null;
+
+function requestedAutoOptimize(query_options) {
+  if (
+    !query_options ||
+    typeof query_options !== "object" ||
+    Array.isArray(query_options)
+  ) {
+    return undefined;
+  }
+  const value = query_options.auto_optimize ?? query_options.optimize;
+  return typeof value === "boolean" ? value : undefined;
+}
 
 function shouldOptimize(query) {
   if (!AUTO_OPTIMIZE_ENABLED) return false;
@@ -126,6 +158,8 @@ module.exports = class Database {
       scope,
       query_scope = "cluster",
       auto_create_collection,
+      auto_optimize,
+      auto_optimize_resources,
     } = {},
   ) {
     if (connection) {
@@ -181,7 +215,94 @@ module.exports = class Database {
       this.use_bucket_name =
         spice.config.database.connections[this.connection_name].scope ==
         undefined;
+
+      // Auto cover indexing. See OPTIMIZE_ENABLED_RESOURCES for precedence.
+      const configured_auto_optimize =
+        auto_optimize ?? this.db_config.auto_optimize;
+      this.auto_optimize =
+        typeof configured_auto_optimize === "boolean"
+          ? configured_auto_optimize
+          : undefined;
+      this.enabled_resources = parseResourceList([
+        ...parseResourceList(this.db_config.auto_optimize_resources),
+        ...parseResourceList(auto_optimize_resources),
+      ]);
+    }
+  }
+
+  /**
+   * Lets the application decide per resource whether slow statements may
+   * create covering indexes, e.g. from a per-resource setting an operator
+   * toggles at runtime. `policy(resource, { query, connection, collection })`
+   * returns true or false, or undefined to defer to the static lists. It is
+   * synchronous because it runs on the query path. Pass null to clear.
+   */
+  static setAutoOptimizePolicy(policy) {
+    if (
+      policy !== null &&
+      policy !== undefined &&
+      typeof policy !== "function"
+    ) {
+      throw new TypeError("Auto-optimize policy must be a function or null");
     }
+    autoOptimizePolicy = policy || null;
+  }
+
+  static getAutoOptimizePolicy() {
+    return autoOptimizePolicy;
+  }
+
+  /**
+   * Resources a statement touches, plus this instance's collection: that is
+   * the keyspace `optimize()` would create the index on.
+   */
+  statementResources(query) {
+    const resources = extractStatementResources(query);
+    if (this.collection_name && this.collection_name !== "_default") {
+      resources.add(String(this.collection_name).toLowerCase());
+    }
+    return resources;
+  }
+
+  /**
+   * True when a slow statement may create a covering index. See
+   * OPTIMIZE_ENABLED_RESOURCES for the order of precedence.
+   */
+  shouldAutoOptimize(query, query_options = {}) {
+    const requested = requestedAutoOptimize(query_options);
+    if (requested !== undefined) return requested;
+    if (typeof this.auto_optimize === "boolean") return this.auto_optimize;
+
+    const resources = this.statementResources(query);
+    if (typeof autoOptimizePolicy === "function" && resources.size > 0) {
+      let deferred = false;
+      for (const resource of resources) {
+        let verdict;
+        try {
+          verdict = autoOptimizePolicy(resource, {
+            query,
+            connection: this.connection_name,
+            collection: this.collection_name,
+          });
+        } catch (e) {
+          // A broken policy must not create indexes nobody asked for.
+          verdict = false;
+        }
+        if (verdict === true) return true;
+        if (verdict === undefined || verdict === null) deferred = true;
+      }
+      if (!deferred) return false;
+    }
+
+    const enabled = new Set([
+      ...OPTIMIZE_ENABLED_RESOURCES,
+      ...(this.enabled_resources || []),
+    ]);
+    if (enabled.has("*")) return true;
+    for (const resource of resources) {
+      if (enabled.has(resource)) return true;
+    }
+    return false;
   }
 
   setGlobalConnectionObject(collection) {
@@ -856,7 +977,10 @@ module.exports = class Database {
   async optimize(query, exec_scope) {
     optimizeState.inFlight += 1;
     try {
-      const { buildCoveringIndex } = require("./utility");
+      const {
+        buildCoveringIndexDefinition,
+        indexSatisfiesCoveringDefinition,
+      } = require("./utility");
 
       // 1. Run EXPLAIN to get the query plan
       const explainQuery = `EXPLAIN ${query}`;
@@ -870,16 +994,48 @@ module.exports = class Database {
       }
 
       // 3. Build covering index from the query
-      const indexStatement = buildCoveringIndex(query, {
+      const candidate = buildCoveringIndexDefinition(query, {
         bucket: this.bucket,
         scope: this.scope_name,
         collection: this.collection_name,
       });
 
-      // 4. Execute the index creation if we got a valid statement
-      if (indexStatement) {
-        await exec_scope.query(indexStatement);
+      if (!candidate) return;
+
+      // EXPLAIN only describes the chosen plan. An equivalent or wider index
+      // may already exist under an older name, or still be deferred/building.
+      // Include both catalog representations of the default collection.
+      const indexResponse = await exec_scope.query(
+        `SELECT RAW i FROM system:indexes AS i
+         WHERE i.namespace_id = 'default'
+           AND ((i.bucket_id = $bucket AND i.scope_id = $scope AND i.keyspace_id = $collection)
+             OR ($scope = '_default' AND $collection = '_default'
+               AND i.bucket_id IS MISSING AND i.scope_id IS MISSING AND i.keyspace_id = $bucket))`,
+        {
+          parameters: {
+            bucket: candidate.bucket,
+            scope: candidate.scope,
+            collection: candidate.collection,
+          },
+        },
+      );
+      // A failed or incomplete inventory is not evidence that no index exists.
+      if (
+        !Array.isArray(indexResponse?.rows) ||
+        indexResponse?.meta?.warnings?.length
+      ) {
+        throw new Error("Cannot verify existing indexes before auto-optimization");
       }
+      if (indexResponse.rows.some((index) =>
+        index.name === candidate.name ||
+        indexSatisfiesCoveringDefinition(index, candidate),
+      )) {
+        return;
+      }
+
+      // Identical definitions use the same name across processes. Couchbase's
+      // per-keyspace name uniqueness also prevents a concurrent duplicate.
+      await exec_scope.query(candidate.statement);
     } catch (e) {
       // A failure here (timeout, index already exists, cluster busy) almost
       // always means the cluster is struggling. Stop adding EXPLAIN and
@@ -921,6 +1077,7 @@ module.exports = class Database {
     // declared at the top of this file. Never awaited, never allowed to reject.
     if (
       durationInMilliseconds > SLOW_QUERY_MS &&
+      this.shouldAutoOptimize(sanitizedQuery, query_options) &&
       shouldOptimize(sanitizedQuery)
     ) {
       this.optimize(sanitizedQuery, exec_scope).catch(() => {});