spice-couchbase 2.0.61 → 2.0.62

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

@@ -94,9 +94,10 @@ function createStatements(scope) {
     return 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 createDatabase(durationMs) {
+function loadDriver(durationMs) {
   var env = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
   var tick = BigInt(0);
   var module = {
@@ -117,7 +118,11 @@ function createDatabase(durationMs) {
       }
     }
   });
-  var db = Object.create(module.exports.prototype);
+  return module.exports;
+}
+
+function instanceOf(Database) {
+  var db = Object.create(Database.prototype);
   db.bucket = "saturn";
   db.scope_name = "test";
   db.collection_name = "users";
@@ -137,6 +142,14 @@ function createDatabase(durationMs) {
     }()
   };
   return db;
+} // Opted in wholesale: per-resource resolution has its own tests further down.
+
+
+function createDatabase(durationMs) {
+  var env = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  var db = instanceOf(loadDriver(durationMs, env));
+  db.auto_optimize = true;
+  return db;
 }
 
 test("auto-optimization only starts above the default 3-second threshold",
@@ -373,4 +386,193 @@ _asyncToGenerator(function* () {
     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() {
+  var env = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  return instanceOf(loadDriver(3001, env));
+}
+
+function optimizationsFor(_x2, _x3) {
+  return _optimizationsFor.apply(this, arguments);
+}
+
+function _optimizationsFor() {
+  _optimizationsFor = _asyncToGenerator(function* (db, statement) {
+    var optimizations = 0;
+    db.optimize =
+    /*#__PURE__*/
+    _asyncToGenerator(function* () {
+      optimizations += 1;
+    });
+
+    for (var _len = arguments.length, queryArgs = new Array(_len > 2 ? _len - 2 : 0), _key = 2; _key < _len; _key++) {
+      queryArgs[_key - 2] = arguments[_key];
+    }
+
+    yield db.query(statement, ...queryArgs);
+    return optimizations;
+  });
+  return _optimizationsFor.apply(this, arguments);
+}
+
+var slowLookup = "SELECT name FROM users WHERE status = 'active'";
+var EVERY_RESOURCE = {
+  SPICE_COUCHBASE_OPTIMIZE_RESOURCES: "*"
+};
+test("no resource is auto-indexed unless something opts it in",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  assert.equal((yield optimizationsFor(createUnconfiguredDatabase(), slowLookup)), 0);
+  assert.equal((yield optimizationsFor(createUnconfiguredDatabase({
+    SPICE_COUCHBASE_OPTIMIZE_RESOURCES: ""
+  }), slowLookup)), 0);
+}));
+test("SPICE_COUCHBASE_OPTIMIZE_RESOURCES enables the instance's collection, case-insensitively",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var env = {
+    SPICE_COUCHBASE_OPTIMIZE_RESOURCES: " Users ,audit_log,, `sessions` "
+  };
+  assert.equal((yield optimizationsFor(createUnconfiguredDatabase(env), slowLookup)), 1);
+  var sessions = createUnconfiguredDatabase(env);
+  sessions.collection_name = "sessions";
+  assert.equal((yield optimizationsFor(sessions, "SELECT id FROM sessions")), 1);
+  var orders = createUnconfiguredDatabase(env);
+  orders.collection_name = "orders";
+  assert.equal((yield optimizationsFor(orders, "SELECT total FROM orders WHERE status = 'paid'")), 0);
+}));
+test("a wildcard restores auto indexing for every resource",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var db = createUnconfiguredDatabase(EVERY_RESOURCE);
+  db.collection_name = "anything";
+  assert.equal((yield optimizationsFor(db, "SELECT a FROM anything WHERE b = 1")), 1);
+}));
+test("legacy bucket mode resolves the resource from the type literal the driver adds",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var env = {
+    SPICE_COUCHBASE_OPTIMIZE_RESOURCES: "audit_log"
+  };
+
+  for (var [type, expected] of [["audit_log", 1], ["users", 0]]) {
+    var db = createUnconfiguredDatabase(env);
+    db.collection_name = "_default";
+    db.scope_name = "_default";
+    assert.equal((yield optimizationsFor(db, "SELECT actor FROM `saturn` WHERE type = '".concat(type, "' AND deleted = false"))), expected, type);
+  }
+}));
+test("a fully qualified or aliased FROM keyspace matches on its last segment",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var env = {
+    SPICE_COUCHBASE_OPTIMIZE_RESOURCES: "logs"
+  };
+
+  for (var 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"]) {
+    var db = createUnconfiguredDatabase(env);
+    db.collection_name = "_default";
+    assert.equal((yield optimizationsFor(db, statement)), 1, statement);
+  }
+}));
+test("connection or constructor lists work without the environment variable",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var db = createUnconfiguredDatabase();
+  db.enabled_resources = new Set(["users"]);
+  assert.equal((yield optimizationsFor(db, slowLookup)), 1);
+}));
+test("an explicit instance setting overrides every resource list",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var on = createUnconfiguredDatabase();
+  on.auto_optimize = true;
+  assert.equal((yield optimizationsFor(on, slowLookup)), 1);
+  var off = createUnconfiguredDatabase(EVERY_RESOURCE);
+  off.auto_optimize = false;
+  assert.equal((yield optimizationsFor(off, slowLookup)), 0);
+}));
+test("a single call can opt in or out through query options",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  assert.equal((yield optimizationsFor(createUnconfiguredDatabase(), slowLookup, {
+    auto_optimize: true
+  })), 1);
+  assert.equal((yield optimizationsFor(createUnconfiguredDatabase(EVERY_RESOURCE), slowLookup, {
+    auto_optimize: false
+  })), 0);
+  assert.equal((yield optimizationsFor(createUnconfiguredDatabase(EVERY_RESOURCE), slowLookup, "cluster", {
+    optimize: false
+  })), 0); // The scan-consistency shorthand is not an opt-in or opt-out.
+
+  assert.equal((yield optimizationsFor(createUnconfiguredDatabase(EVERY_RESOURCE), slowLookup, "cluster", true)), 1);
+  assert.equal((yield optimizationsFor(createUnconfiguredDatabase(), slowLookup, "cluster", true)), 0);
+}));
+test("an application policy decides per resource and sees the statement context",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var Database = loadDriver(3001);
+  var seen = [];
+  Database.setAutoOptimizePolicy((resource, context) => {
+    seen.push([resource, context]);
+    return resource === "users";
+  });
+  assert.equal(Database.getAutoOptimizePolicy().length, 2);
+  var users = instanceOf(Database);
+  users.connection_name = "default";
+  assert.equal((yield 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"
+  }]));
+  var orders = instanceOf(Database);
+  orders.collection_name = "orders";
+  assert.equal((yield optimizationsFor(orders, "SELECT total FROM orders WHERE status = 'paid'")), 0);
+}));
+test("a policy that returns undefined defers to the static lists",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  for (var [env, expected] of [[{
+    SPICE_COUCHBASE_OPTIMIZE_RESOURCES: "users"
+  }, 1], [{}, 0]]) {
+    var Database = loadDriver(3001, env);
+    Database.setAutoOptimizePolicy(() => undefined);
+    assert.equal((yield optimizationsFor(instanceOf(Database), slowLookup)), expected);
+  }
+}));
+test("an explicit policy refusal wins over the wildcard, and a throwing policy counts as a refusal",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  for (var policy of [() => false, () => {
+    throw new Error("settings unavailable");
+  }]) {
+    var Database = loadDriver(3001, EVERY_RESOURCE);
+    Database.setAutoOptimizePolicy(policy);
+    assert.equal((yield optimizationsFor(instanceOf(Database), slowLookup)), 0);
+  }
+}));
+test("the policy can be cleared and must be a function",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var Database = loadDriver(3001, EVERY_RESOURCE);
+  Database.setAutoOptimizePolicy(() => false);
+  Database.setAutoOptimizePolicy(null);
+  assert.equal(Database.getAutoOptimizePolicy(), null);
+  assert.equal((yield optimizationsFor(instanceOf(Database), slowLookup)), 1);
+  assert.throws(() => Database.setAutoOptimizePolicy("users"), {
+    name: "TypeError"
+  });
+}));
+test("a declined statement is not remembered as already optimised",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var db = createUnconfiguredDatabase();
+  assert.equal((yield optimizationsFor(db, slowLookup)), 0);
+  db.auto_optimize = true;
+  assert.equal((yield optimizationsFor(db, slowLookup)), 1);
 }));

package/build/index.js

@@ -24,6 +24,11 @@ var {
   QueryScanConsistency
 } = require("couchbase");
 
+var {
+  parseResourceList,
+  extractStatementResources
+} = require("./utility");
+
 if (!Promise.allSettled) {
   Promise.allSettled = promises => Promise.all(promises.map((promise, i) => promise.then(value => ({
     status: "fulfilled",
@@ -52,7 +57,35 @@ var optimizeState = {
   inFlight: 0,
   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`.
+
+var OPTIMIZE_ENABLED_RESOURCES = parseResourceList(process.env.SPICE_COUCHBASE_OPTIMIZE_RESOURCES);
+var autoOptimizePolicy = null;
+
+function requestedAutoOptimize(query_options) {
+  var _query_options$auto_o;
+
+  if (!query_options || typeof query_options !== "object" || Array.isArray(query_options)) {
+    return undefined;
+  }
+
+  var value = (_query_options$auto_o = query_options.auto_optimize) !== null && _query_options$auto_o !== void 0 ? _query_options$auto_o : query_options.optimize;
+  return typeof value === "boolean" ? value : undefined;
+}
 
 function shouldOptimize(query) {
   if (!AUTO_OPTIMIZE_ENABLED) return false;
@@ -124,7 +157,9 @@ module.exports = class Database {
       collection,
       scope,
       query_scope = "cluster",
-      auto_create_collection
+      auto_create_collection,
+      auto_optimize,
+      auto_optimize_resources
     } = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
 
     if (connection) {
@@ -163,8 +198,93 @@ module.exports = class Database {
         this.upsertCollection();
       }
 
-      this.use_bucket_name = spice.config.database.connections[this.connection_name].scope == undefined;
+      this.use_bucket_name = spice.config.database.connections[this.connection_name].scope == undefined; // Auto cover indexing. See OPTIMIZE_ENABLED_RESOURCES for precedence.
+
+      var configured_auto_optimize = auto_optimize !== null && auto_optimize !== void 0 ? 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) {
+    var 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) {
+    var query_options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+    var requested = requestedAutoOptimize(query_options);
+    if (requested !== undefined) return requested;
+    if (typeof this.auto_optimize === "boolean") return this.auto_optimize;
+    var resources = this.statementResources(query);
+
+    if (typeof autoOptimizePolicy === "function" && resources.size > 0) {
+      var deferred = false;
+
+      for (var resource of resources) {
+        var verdict = void 0;
+
+        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;
     }
+
+    var enabled = new Set([...OPTIMIZE_ENABLED_RESOURCES, ...(this.enabled_resources || [])]);
+    if (enabled.has("*")) return true;
+
+    for (var _resource of resources) {
+      if (enabled.has(_resource)) return true;
+    }
+
+    return false;
   }
 
   setGlobalConnectionObject(collection) {
@@ -993,7 +1113,7 @@ module.exports = class Database {
       var durationInMilliseconds = (endTime - startTime) / BigInt(1000000); // Optimise slow statements in the background, subject to the guard rails
       // declared at the top of this file. Never awaited, never allowed to reject.
 
-      if (durationInMilliseconds > SLOW_QUERY_MS && shouldOptimize(sanitizedQuery)) {
+      if (durationInMilliseconds > SLOW_QUERY_MS && _this20.shouldAutoOptimize(sanitizedQuery, query_options) && shouldOptimize(sanitizedQuery)) {
         _this20.optimize(sanitizedQuery, exec_scope).catch(() => {});
       }
 

package/build/utility.js

@@ -435,11 +435,76 @@ function indexSatisfiesCoveringDefinition(index, candidate) {
   var existingFields = new Set(existingKeys.map(key => key.field));
   return requiredKeys.slice(candidate.accessKeyCount).every(key => existingFields.has(key.field));
 }
+/**
+ * Normalizes an exemption list into a Set of lower-case resource names.
+ * Accepts an array, a Set, or a comma-separated string (the env var form).
+ * Surrounding whitespace and backticks are ignored; empty entries are dropped.
+ * @param {string|string[]|Set<string>} value
+ * @returns {Set<string>}
+ */
+
+
+function parseResourceList(value) {
+  var names = new Set();
+  var items = [];
+
+  if (Array.isArray(value) || value instanceof Set) {
+    items = [...value];
+  } else if (typeof value === "string") {
+    items = value.split(",");
+  }
+
+  for (var item of items) {
+    if (typeof item !== "string") continue;
+    var name = item.trim().replace(/^`+|`+$/g, "").trim().toLowerCase();
+    if (name) names.add(name);
+  }
+
+  return names;
+}
+/**
+ * Extracts the resource names a statement touches, lower-cased:
+ * - the last path segment of every FROM / JOIN keyspace, unquoted, so
+ *   `default`:`bucket`.`scope`.`users` and users both yield "users";
+ * - every `type = '...'` literal, which is how legacy bucket-mode
+ *   deployments distinguish resources that share one keyspace.
+ * Only simple identifiers are recognised; subqueries and expressions are skipped.
+ * @param {string} query
+ * @returns {Set<string>}
+ */
+
+
+function extractStatementResources(query) {
+  var names = new Set();
+  if (typeof query !== "string") return names;
+  var identifier = "(?:`(?:[^`]|``)+`|[A-Za-z_][\\w$-]*)";
+  var keyspacePattern = new RegExp("\\b(?:FROM|JOIN)\\s+(".concat(identifier, "(?:\\s*[.:]\\s*").concat(identifier, ")*)"), "gi");
+  var segmentPattern = new RegExp(identifier, "g");
+
+  for (var match of query.matchAll(keyspacePattern)) {
+    var segments = match[1].match(segmentPattern) || [];
+    var last = (segments[segments.length - 1] || "").trim();
+    var name = last.startsWith("`") ? last.slice(1, -1).replace(/``/g, "`") : last;
+    if (name) names.add(name.toLowerCase());
+  }
+
+  var typePattern = /(?:`type`|\btype)\s*=\s*'((?:[^']|'')*)'/gi;
+
+  for (var _match of query.matchAll(typePattern)) {
+    var _name = _match[1].replace(/''/g, "'").trim();
+
+    if (_name) names.add(_name.toLowerCase());
+  }
+
+  return names;
+}
 
 module.exports = {
   buildCoveringIndex,
   buildCoveringIndexDefinition,
   indexSatisfiesCoveringDefinition,
+  parseResourceList,
+  extractStatementResources,
   extractWhereFields,
   extractSelectFields,
   extractGroupByFields,

package/build/utility.test.js

@@ -8,7 +8,9 @@ var {
   extractSelectFields,
   extractGroupByFields,
   extractOrderByFields,
-  generateHash
+  generateHash,
+  parseResourceList,
+  extractStatementResources
 } = require("./utility"); // Test utilities
 
 
@@ -825,6 +827,52 @@ test("field order: WHERE -> GROUP BY -> ORDER BY -> SELECT", () => {
 
   assert.ok(createdAtIndex < emailIndex); // ORDER BY before SELECT
 }); // ============================================
+// Tests for parseResourceList / extractStatementResources
+// ============================================
+
+console.log("\n--- parseResourceList tests ---");
+test("parses a comma-separated string, trimming, unquoting and lower-casing", () => {
+  var result = parseResourceList(" Users, `Audit_Log` ,, sessions ");
+  assert.deepStrictEqual([...result].sort(), ["audit_log", "sessions", "users"]);
+});
+test("accepts arrays and Sets and ignores non-strings", () => {
+  assert.deepStrictEqual([...parseResourceList(["Users", 42, null, " logs "])].sort(), ["logs", "users"]);
+  assert.deepStrictEqual([...parseResourceList(new Set(["A", "b"]))].sort(), ["a", "b"]);
+});
+test("returns an empty set for undefined, empty or unsupported input", () => {
+  assert.strictEqual(parseResourceList(undefined).size, 0);
+  assert.strictEqual(parseResourceList("").size, 0);
+  assert.strictEqual(parseResourceList(", ,").size, 0);
+  assert.strictEqual(parseResourceList({
+    users: true
+  }).size, 0);
+});
+console.log("\n--- extractStatementResources tests ---");
+test("extracts a bare FROM keyspace", () => {
+  assert.deepStrictEqual([...extractStatementResources("SELECT name FROM users WHERE x = 1")], ["users"]);
+});
+test("extracts the last segment of a qualified or quoted keyspace", () => {
+  assert.deepStrictEqual([...extractStatementResources("SELECT name FROM `default`:`saturn`.`app`.`Users` AS u")], ["users"]);
+  assert.deepStrictEqual([...extractStatementResources("SELECT name FROM saturn.app.logs")], ["logs"]);
+});
+test("extracts JOIN keyspaces alongside FROM", () => {
+  var result = extractStatementResources("SELECT u.name FROM users AS u JOIN `orders` AS o ON o.user_id = META(u).id");
+  assert.deepStrictEqual([...result].sort(), ["orders", "users"]);
+});
+test("extracts type literals used by legacy bucket mode", () => {
+  var result = extractStatementResources("SELECT actor FROM `saturn` WHERE type = 'Audit_Log' AND deleted = false");
+  assert.deepStrictEqual([...result].sort(), ["audit_log", "saturn"]);
+  assert.ok(extractStatementResources("SELECT a FROM b WHERE `type`='x'").has("x"));
+  assert.ok(extractStatementResources("SELECT a FROM b WHERE type = 'it''s'").has("it's"));
+});
+test("does not treat META() arguments, subqueries or column names as keyspaces", () => {
+  var result = extractStatementResources("SELECT META(`users`).id AS id, from_date FROM (SELECT * FROM users) AS sub WHERE status = 'from'");
+  assert.deepStrictEqual([...result], ["users"]);
+});
+test("handles non-string input", () => {
+  assert.strictEqual(extractStatementResources(undefined).size, 0);
+  assert.strictEqual(extractStatementResources(null).size, 0);
+}); // ============================================
 // Summary
 // ============================================
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spice-couchbase",
-  "version": "2.0.61",
+  "version": "2.0.62",
   "description": "",
   "main": "build/index.js",
   "scripts": {

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

@@ -37,7 +37,8 @@ function createStatements(scope) {
 }
 
 // Isolate optimizer state and time without connecting to Couchbase or sleeping.
-function createDatabase(durationMs, env = {}) {
+// 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"), {
@@ -55,7 +56,11 @@ function createDatabase(durationMs, env = {}) {
       },
     },
   });
-  const db = Object.create(module.exports.prototype);
+  return module.exports;
+}
+
+function instanceOf(Database) {
+  const db = Object.create(Database.prototype);
   db.bucket = "saturn";
   db.scope_name = "test";
   db.collection_name = "users";
@@ -63,6 +68,13 @@ function createDatabase(durationMs, env = {}) {
   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);
@@ -235,3 +247,147 @@ test("a default collection uses default names in its inventory lookup", async ()
   }));
   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) =>
@@ -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) {
@@ -956,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(() => {});

package/src/utility.js

@@ -458,10 +458,73 @@ function indexSatisfiesCoveringDefinition(index, candidate) {
   return requiredKeys.slice(candidate.accessKeyCount).every((key) => existingFields.has(key.field));
 }
 
+/**
+ * Normalizes an exemption list into a Set of lower-case resource names.
+ * Accepts an array, a Set, or a comma-separated string (the env var form).
+ * Surrounding whitespace and backticks are ignored; empty entries are dropped.
+ * @param {string|string[]|Set<string>} value
+ * @returns {Set<string>}
+ */
+function parseResourceList(value) {
+  const names = new Set();
+  let items = [];
+  if (Array.isArray(value) || value instanceof Set) {
+    items = [...value];
+  } else if (typeof value === "string") {
+    items = value.split(",");
+  }
+  for (const item of items) {
+    if (typeof item !== "string") continue;
+    const name = item.trim().replace(/^`+|`+$/g, "").trim().toLowerCase();
+    if (name) names.add(name);
+  }
+  return names;
+}
+
+/**
+ * Extracts the resource names a statement touches, lower-cased:
+ * - the last path segment of every FROM / JOIN keyspace, unquoted, so
+ *   `default`:`bucket`.`scope`.`users` and users both yield "users";
+ * - every `type = '...'` literal, which is how legacy bucket-mode
+ *   deployments distinguish resources that share one keyspace.
+ * Only simple identifiers are recognised; subqueries and expressions are skipped.
+ * @param {string} query
+ * @returns {Set<string>}
+ */
+function extractStatementResources(query) {
+  const names = new Set();
+  if (typeof query !== "string") return names;
+
+  const identifier = "(?:`(?:[^`]|``)+`|[A-Za-z_][\\w$-]*)";
+  const keyspacePattern = new RegExp(
+    `\\b(?:FROM|JOIN)\\s+(${identifier}(?:\\s*[.:]\\s*${identifier})*)`,
+    "gi",
+  );
+  const segmentPattern = new RegExp(identifier, "g");
+  for (const match of query.matchAll(keyspacePattern)) {
+    const segments = match[1].match(segmentPattern) || [];
+    const last = (segments[segments.length - 1] || "").trim();
+    const name = last.startsWith("`")
+      ? last.slice(1, -1).replace(/``/g, "`")
+      : last;
+    if (name) names.add(name.toLowerCase());
+  }
+
+  const typePattern = /(?:`type`|\btype)\s*=\s*'((?:[^']|'')*)'/gi;
+  for (const match of query.matchAll(typePattern)) {
+    const name = match[1].replace(/''/g, "'").trim();
+    if (name) names.add(name.toLowerCase());
+  }
+
+  return names;
+}
+
 module.exports = {
   buildCoveringIndex,
   buildCoveringIndexDefinition,
   indexSatisfiesCoveringDefinition,
+  parseResourceList,
+  extractStatementResources,
   extractWhereFields,
   extractSelectFields,
   extractGroupByFields,

package/src/utility.test.js

@@ -8,6 +8,8 @@ const {
   extractGroupByFields,
   extractOrderByFields,
   generateHash,
+  parseResourceList,
+  extractStatementResources,
 } = require("./utility");
 
 // Test utilities
@@ -1046,6 +1048,73 @@ test("field order: WHERE -> GROUP BY -> ORDER BY -> SELECT", () => {
   assert.ok(createdAtIndex < emailIndex);  // ORDER BY before SELECT
 });
 
+// ============================================
+// Tests for parseResourceList / extractStatementResources
+// ============================================
+console.log("\n--- parseResourceList tests ---");
+
+test("parses a comma-separated string, trimming, unquoting and lower-casing", () => {
+  const result = parseResourceList(" Users, `Audit_Log` ,, sessions ");
+  assert.deepStrictEqual([...result].sort(), ["audit_log", "sessions", "users"]);
+});
+
+test("accepts arrays and Sets and ignores non-strings", () => {
+  assert.deepStrictEqual([...parseResourceList(["Users", 42, null, " logs "])].sort(), ["logs", "users"]);
+  assert.deepStrictEqual([...parseResourceList(new Set(["A", "b"]))].sort(), ["a", "b"]);
+});
+
+test("returns an empty set for undefined, empty or unsupported input", () => {
+  assert.strictEqual(parseResourceList(undefined).size, 0);
+  assert.strictEqual(parseResourceList("").size, 0);
+  assert.strictEqual(parseResourceList(", ,").size, 0);
+  assert.strictEqual(parseResourceList({ users: true }).size, 0);
+});
+
+console.log("\n--- extractStatementResources tests ---");
+
+test("extracts a bare FROM keyspace", () => {
+  assert.deepStrictEqual([...extractStatementResources("SELECT name FROM users WHERE x = 1")], ["users"]);
+});
+
+test("extracts the last segment of a qualified or quoted keyspace", () => {
+  assert.deepStrictEqual(
+    [...extractStatementResources("SELECT name FROM `default`:`saturn`.`app`.`Users` AS u")],
+    ["users"],
+  );
+  assert.deepStrictEqual(
+    [...extractStatementResources("SELECT name FROM saturn.app.logs")],
+    ["logs"],
+  );
+});
+
+test("extracts JOIN keyspaces alongside FROM", () => {
+  const result = extractStatementResources(
+    "SELECT u.name FROM users AS u JOIN `orders` AS o ON o.user_id = META(u).id",
+  );
+  assert.deepStrictEqual([...result].sort(), ["orders", "users"]);
+});
+
+test("extracts type literals used by legacy bucket mode", () => {
+  const result = extractStatementResources(
+    "SELECT actor FROM `saturn` WHERE type = 'Audit_Log' AND deleted = false",
+  );
+  assert.deepStrictEqual([...result].sort(), ["audit_log", "saturn"]);
+  assert.ok(extractStatementResources("SELECT a FROM b WHERE `type`='x'").has("x"));
+  assert.ok(extractStatementResources("SELECT a FROM b WHERE type = 'it''s'").has("it's"));
+});
+
+test("does not treat META() arguments, subqueries or column names as keyspaces", () => {
+  const result = extractStatementResources(
+    "SELECT META(`users`).id AS id, from_date FROM (SELECT * FROM users) AS sub WHERE status = 'from'",
+  );
+  assert.deepStrictEqual([...result], ["users"]);
+});
+
+test("handles non-string input", () => {
+  assert.strictEqual(extractStatementResources(undefined).size, 0);
+  assert.strictEqual(extractStatementResources(null).size, 0);
+});
+
 // ============================================
 // Summary
 // ============================================