spice-couchbase 2.0.63 → 2.0.65

package/src/index.index-management.test.js

@@ -0,0 +1,232 @@
+"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 {
+  statementShape,
+  planIndexNames,
+  usesManagedIndex,
+  renderIndexKey,
+  BASE_INDEX,
+} = require("./utility");
+
+// Same isolation as index.auto-optimize.test.js: a fresh module per load, so
+// the seen-set, cooldown and handler never leak between tests.
+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 recordingCluster(rowsFor = () => []) {
+  const calls = [];
+  return {
+    calls,
+    async query(statement, options) {
+      calls.push({ statement, options });
+      return { rows: rowsFor(statement), meta: {} };
+    },
+  };
+}
+
+function createDatabase(Database, cluster) {
+  const db = Object.create(Database.prototype);
+  db.bucket = "saturn";
+  db.scope_name = "test";
+  db.collection_name = "users";
+  db.db_config = { bucket: "saturn" };
+  db.auto_optimize = true;
+  db.cluster = cluster;
+  db.scope = cluster;
+  return db;
+}
+
+const KEYSPACE = "default:`saturn`.`test`.`users`";
+
+test("statement shapes ignore literal values and IN list lengths", () => {
+  assert.equal(
+    statementShape("SELECT * FROM `users` WHERE email = 'a@b.c' AND age > 30 AND id IN ['x', 'y']"),
+    statementShape("SELECT * FROM `users` WHERE email = \"d@e.f\" AND age > 7 AND id IN ['z']"),
+  );
+});
+
+test("managed indexes are recognised in a plan, the base fallback is not", () => {
+  const plan = (index) => ({ "#operator": "Sequence", "~children": [{ "#operator": "IndexScan3", index }] });
+  assert.deepEqual(planIndexNames(plan("ix_sort_1a2b3c_9f0e")), ["ix_sort_1a2b3c_9f0e"]);
+  assert.equal(usesManagedIndex(plan("ix_sort_1a2b3c_9f0e")), true);
+  assert.equal(usesManagedIndex(plan("ix_base")), false);
+  assert.equal(usesManagedIndex(plan("adv_covered_1a3952f8")), false);
+});
+
+test("index keys render direction and INCLUDE MISSING", () => {
+  assert.deepEqual(BASE_INDEX.keys.map(renderIndexKey), ["`created_at` DESC INCLUDE MISSING", "`deleted`"]);
+  assert.equal(renderIndexKey("`name`"), "`name`");
+  assert.throws(() => renderIndexKey({}), TypeError);
+});
+
+test("createIndex is idempotent, deferred by default and fully qualified", async () => {
+  const cluster = recordingCluster();
+  const db = createDatabase(loadDriver(0), cluster);
+  await db.createIndex({
+    name: "ix_sort_1a2b3c_9f0e",
+    keys: [{ expr: "`priority`", desc: true, include_missing: true }, { expr: "IFMISSINGORNULL(`due_at`, {})" }],
+    where: "IFMISSING(`deleted`, false) = false",
+    num_replica: 1,
+  });
+  assert.equal(
+    cluster.calls[0].statement,
+    `CREATE INDEX IF NOT EXISTS \`ix_sort_1a2b3c_9f0e\` ON ${KEYSPACE}` +
+      "(`priority` DESC INCLUDE MISSING, IFMISSINGORNULL(`due_at`, {})) " +
+      'WHERE IFMISSING(`deleted`, false) = false WITH {"defer_build":true,"num_replica":1}',
+  );
+});
+
+test("build, drop and primary drop target the collection", async () => {
+  const cluster = recordingCluster();
+  const db = createDatabase(loadDriver(0), cluster);
+  await db.buildIndexes(["ix_a", "ix_b", "ix_a"]);
+  await db.dropIndex("ix_a");
+  await db.dropPrimaryIndex();
+  assert.deepEqual(cluster.calls.map(({ statement }) => statement), [
+    `BUILD INDEX ON ${KEYSPACE}(\`ix_a\`, \`ix_b\`)`,
+    `DROP INDEX IF EXISTS \`ix_a\` ON ${KEYSPACE}`,
+    `DROP PRIMARY INDEX IF EXISTS ON ${KEYSPACE}`,
+  ]);
+  assert.equal(await db.buildIndexes([]), null);
+});
+
+test("a partial index inventory is an error, not an empty list", async () => {
+  const Database = loadDriver(0);
+  const db = createDatabase(Database, {
+    async query() {
+      return { rows: [], meta: { warnings: [{ msg: "partial" }] } };
+    },
+  });
+  await assert.rejects(() => db.listIndexes(), /index inventory/);
+});
+
+test("the client context id reaches the SDK options", async () => {
+  const cluster = recordingCluster();
+  const db = createDatabase(loadDriver(0), cluster);
+  await db.query("SELECT 1", "cluster", { client_context_id: "scheduler.due" });
+  assert.equal(cluster.calls[0].options.clientContextId, "scheduler.due");
+});
+
+function scanTimeout() {
+  const error = new Error("Index scan timed out");
+  error.cause = { first_error_code: 12015, first_error_message: "Index scan timed out" };
+  return error;
+}
+
+test("an expired scan_wait reruns without waiting only when the caller allows it", async () => {
+  const Database = loadDriver(0);
+  const attempts = [];
+  const cluster = {
+    async query(statement, options) {
+      attempts.push(options);
+      if (attempts.length === 1) throw scanTimeout();
+      return { rows: [{ ok: true }] };
+    },
+  };
+  const db = createDatabase(Database, cluster);
+  const response = await db.query("SELECT 1", "cluster", {
+    scan_consistency: "request_plus",
+    scan_wait: 2000,
+    scan_wait_fallback: true,
+  });
+  assert.deepEqual(response.rows, [{ ok: true }]);
+  assert.equal(attempts.length, 2);
+  assert.equal(attempts[1].scanWait, undefined);
+  assert.notEqual(attempts[1].scanConsistency, attempts[0].scanConsistency);
+});
+
+test("without the fallback an expired scan_wait is an error", async () => {
+  const Database = loadDriver(0);
+  const db = createDatabase(Database, {
+    async query() {
+      throw scanTimeout();
+    },
+  });
+  await assert.rejects(
+    () => db.query("SELECT 1", "cluster", { scan_consistency: "request_plus", scan_wait: 2000 }),
+    /Index scan timed out/,
+  );
+});
+
+test("with a handler installed, slow statements are handed off once per shape and never indexed here", async () => {
+  const Database = loadDriver(5000);
+  const cluster = recordingCluster((statement) =>
+    statement.startsWith("EXPLAIN ") ? [{ "#operator": "IndexScan3", index: "ix_base" }] : [],
+  );
+  const db = createDatabase(Database, cluster);
+  const reports = [];
+  Database.setSlowStatementHandler(async (report) => reports.push(report));
+  let legacy = 0;
+  db.optimize = async () => { legacy += 1; };
+
+  await db.query("SELECT name FROM users WHERE email = 'a@b.c'");
+  await db.query("SELECT name FROM users WHERE email = 'd@e.f'");
+  await new Promise((resolve) => setImmediate(resolve));
+
+  assert.equal(reports.length, 1);
+  assert.equal(reports[0].shape, "SELECT name FROM users WHERE email = ?");
+  assert.equal(reports[0].collection, "users");
+  assert.equal(legacy, 0);
+  assert.equal(cluster.calls.some(({ statement }) => statement.startsWith("CREATE ")), false);
+});
+
+test("a slow statement already served by a managed index is not reported", async () => {
+  const Database = loadDriver(5000);
+  const cluster = recordingCluster((statement) =>
+    statement.startsWith("EXPLAIN ") ? [{ "#operator": "IndexScan3", index: "ix_sort_1a2b3c_9f0e" }] : [],
+  );
+  const db = createDatabase(Database, cluster);
+  const reports = [];
+  Database.setSlowStatementHandler(async (report) => reports.push(report));
+  await db.query("SELECT name FROM users ORDER BY priority DESC");
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.equal(reports.length, 0);
+});
+
+test("without a handler the legacy covering-index path still runs", async () => {
+  const Database = loadDriver(5000);
+  const db = createDatabase(Database, recordingCluster());
+  let legacy = 0;
+  db.optimize = async () => { legacy += 1; };
+  await db.query("SELECT name FROM users WHERE status = 'active'");
+  assert.equal(legacy, 1);
+});
+
+test("a new collection gets the base index instead of a primary index when asked", async () => {
+  const Database = loadDriver(0);
+  const cluster = recordingCluster();
+  const db = createDatabase(Database, cluster);
+  db.db_config.primary_index = false;
+  db.checkGlobelConnectionObject = () => false;
+  db.collectionExists = async () => false;
+  db.createCollection = async () => {};
+  db.wait = async () => {};
+  let primary = 0;
+  db.createPrimaryIndex = async () => { primary += 1; };
+  await db.upsertCollection();
+  assert.equal(primary, 0);
+  assert.match(cluster.calls[0].statement, /^CREATE INDEX IF NOT EXISTS `ix_base` ON .*\(`created_at` DESC INCLUDE MISSING, `deleted`\) WITH \{"defer_build":false\}$/);
+});

package/src/index.js

@@ -4,7 +4,15 @@ let _ = require("lodash");
 let couchbase = require("couchbase");
 const { ConflictResolutionType } = require("couchbase");
 const { QueryScanConsistency } = require("couchbase");
-const { parseResourceList, extractStatementResources } = require("./utility");
+const {
+  parseResourceList,
+  extractStatementResources,
+  statementShape,
+  usesManagedIndex,
+  renderIndexKey,
+  BASE_INDEX,
+  MANAGED_INDEX_NAME,
+} = require("./utility");
 const { createHealthMonitor, openHandles } = require("./connectionHealth");
 
 if (!Promise.allSettled) {
@@ -71,6 +79,11 @@ const OPTIMIZE_ENABLED_RESOURCES = parseResourceList(
   process.env.SPICE_COUCHBASE_OPTIMIZE_RESOURCES,
 );
 let autoOptimizePolicy = null;
+// When the application installs a handler, slow statements are handed to it
+// instead of creating indexes here: it owns every index decision, with its
+// own key rules, caps and build windows. Without one, the legacy covering
+// index path below still runs, so other applications keep their behaviour.
+let slowStatementHandler = null;
 
 // One health monitor per process, shared by every copy of this module that
 // ends up loaded. See connectionHealth.js.
@@ -168,9 +181,39 @@ function buildQueryOptions(queryOptions = {}) {
     options.scanWait = numericScanWait;
   }
 
+  // Reported as clientContextID in system:completed_requests, which is how a
+  // slow statement is traced back to the route or job that ran it.
+  const clientContextId =
+    queryOptions.clientContextId ?? queryOptions.client_context_id;
+  if (clientContextId !== undefined && clientContextId !== null && clientContextId !== "") {
+    options.clientContextId = String(clientContextId).slice(0, 64);
+  }
+
   return options;
 }
 
+function wantsScanWaitFallback(query_options) {
+  return (
+    query_options &&
+    typeof query_options === "object" &&
+    (query_options.scan_wait_fallback === true ||
+      query_options.scanWaitFallback === true)
+  );
+}
+
+// The query service reports an expired scan_wait as an index scan timeout
+// (12015), which is a query error, not a connectivity timeout.
+function isScanWaitExpired(error) {
+  const code =
+    error?.cause?.first_error_code ?? error?.context?.first_error_code;
+  const message =
+    error?.cause?.first_error_message ||
+    error?.context?.first_error_message ||
+    error?.message ||
+    "";
+  return code === 12015 || /index scan timed out|scan.{0,20}timed? ?out/i.test(message);
+}
+
 module.exports = class Database {
   constructor(
     connection,
@@ -398,6 +441,38 @@ module.exports = class Database {
     return autoOptimizePolicy;
   }
 
+  /**
+   * Hands slow statements to the application instead of creating covering
+   * indexes here. `handler({ statement, shape, plan, resources, connection,
+   * bucket, scope, collection, duration_ms })` runs in the background, once
+   * per statement shape, after the resource opt-in policy has allowed it and
+   * only when the plan is not already served by a managed index. Pass null to
+   * restore the legacy behaviour.
+   */
+  static setSlowStatementHandler(handler) {
+    if (
+      handler !== null &&
+      handler !== undefined &&
+      typeof handler !== "function"
+    ) {
+      throw new TypeError("Slow statement handler must be a function or null");
+    }
+    slowStatementHandler = handler || null;
+  }
+
+  static getSlowStatementHandler() {
+    return slowStatementHandler;
+  }
+
+  /** The fallback index every collection gets in place of a primary index. */
+  static get BASE_INDEX() {
+    return BASE_INDEX;
+  }
+
+  static get MANAGED_INDEX_NAME() {
+    return MANAGED_INDEX_NAME;
+  }
+
   /**
    * Resources a statement touches, plus this instance's collection: that is
    * the keyspace `optimize()` would create the index on.
@@ -543,7 +618,19 @@ module.exports = class Database {
         if (!collection_exists) {
           await this.createCollection(this.collection_name, this.scope_name);
           await this.wait(2000);
-          await this.createPrimaryIndex(this.scope_name, this.collection_name);
+          // `primary_index: false` on the connection replaces the primary
+          // index with the base secondary index. A new collection is empty,
+          // so building it straight away costs nothing.
+          if (this.db_config?.primary_index === false) {
+            await this.createIndex({
+              ...BASE_INDEX,
+              defer_build: false,
+              collection: this.collection_name,
+              scope: this.scope_name,
+            });
+          } else {
+            await this.createPrimaryIndex(this.scope_name, this.collection_name);
+          }
         }
       }
     } catch (e) {
@@ -656,6 +743,121 @@ module.exports = class Database {
     }
   }
 
+  // Index management. Every statement here is DDL or a catalog read against a
+  // fully qualified keyspace, run at cluster level and outside `query()` so a
+  // slow build never feeds back into the slow-statement path.
+
+  async runDdl(statement, options = {}) {
+    return this.observe(this.cluster.query(statement, options));
+  }
+
+  /**
+   * Every index on a collection, from system:indexes, including the legacy
+   * catalog form of the default collection. Rows carry name, index_key,
+   * condition, state, is_primary, using.
+   */
+  async listIndexes({
+    collection = this.collection_name,
+    scope = this.scope_name,
+  } = {}) {
+    const response = await this.runDdl(
+      `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: this.db_config.bucket,
+          scope,
+          collection,
+        },
+      },
+    );
+    // A failed or partial inventory is not evidence that no index exists.
+    if (!Array.isArray(response?.rows) || response?.meta?.warnings?.length) {
+      throw new Error(`Cannot read the index inventory for ${scope}.${collection}`);
+    }
+    return response.rows;
+  }
+
+  /**
+   * `CREATE INDEX IF NOT EXISTS`. Deferred by default so several indexes on
+   * one collection can be built together with `buildIndexes`, in one pass
+   * over the data.
+   */
+  async createIndex({
+    name,
+    keys,
+    where,
+    defer_build = true,
+    num_replica,
+    collection = this.collection_name,
+    scope = this.scope_name,
+  } = {}) {
+    if (!name || !Array.isArray(keys) || keys.length === 0) {
+      throw new TypeError("createIndex needs a name and at least one key");
+    }
+    const withClause = { defer_build: Boolean(defer_build) };
+    if (Number.isInteger(num_replica) && num_replica >= 0) {
+      withClause.num_replica = num_replica;
+    }
+    const statement =
+      `CREATE INDEX IF NOT EXISTS ${this.quoteIdentifier(name)} ` +
+      `ON ${this.collectionPath(scope, collection)}(${keys.map(renderIndexKey).join(", ")})` +
+      (where ? ` WHERE ${where}` : "") +
+      ` WITH ${JSON.stringify(withClause)}`;
+    await this.runDdl(statement);
+    return statement;
+  }
+
+  /** Builds deferred indexes on one collection together. */
+  async buildIndexes(names, {
+    collection = this.collection_name,
+    scope = this.scope_name,
+  } = {}) {
+    const list = [...new Set(names || [])];
+    if (list.length === 0) return null;
+    const statement =
+      `BUILD INDEX ON ${this.collectionPath(scope, collection)}` +
+      `(${list.map((name) => this.quoteIdentifier(name)).join(", ")})`;
+    await this.runDdl(statement);
+    return statement;
+  }
+
+  async dropIndex(name, {
+    collection = this.collection_name,
+    scope = this.scope_name,
+  } = {}) {
+    const statement =
+      `DROP INDEX IF EXISTS ${this.quoteIdentifier(name)} ON ${this.collectionPath(scope, collection)}`;
+    await this.runDdl(statement);
+    return statement;
+  }
+
+  async dropPrimaryIndex({
+    collection = this.collection_name,
+    scope = this.scope_name,
+  } = {}) {
+    const statement = `DROP PRIMARY INDEX IF EXISTS ON ${this.collectionPath(scope, collection)}`;
+    await this.runDdl(statement);
+    return statement;
+  }
+
+  /** The plan for a statement, resolved in this instance's scope by default. */
+  async explain(statement, query_scope = this.use_bucket_name ? "cluster" : "scope") {
+    const exec_scope = query_scope === "cluster" ? this.cluster : this.scope;
+    const response = await this.observe(exec_scope.query(`EXPLAIN ${statement}`));
+    return response?.rows?.[0];
+  }
+
+  /** Couchbase's own index advice for a statement (the ADVISE statement). */
+  async advise(statement, query_scope = this.use_bucket_name ? "cluster" : "scope") {
+    const exec_scope = query_scope === "cluster" ? this.cluster : this.scope;
+    const response = await this.observe(exec_scope.query(`ADVISE ${statement}`));
+    return response?.rows?.[0];
+  }
+
   async get(doc_id, { columns = [] } = {}) {
     try {
       const useLookupIn = columns.length > 0;
@@ -1209,9 +1411,31 @@ module.exports = class Database {
     // Start time
     let startTime = process.hrtime.bigint();
     const options = buildQueryOptions(query_options);
-    let response = await this.observe(
-      exec_scope.query(sanitizedQuery, options),
-    );
+    let response;
+    try {
+      response = await this.observe(exec_scope.query(sanitizedQuery, options));
+    } catch (error) {
+      // `scan_wait_fallback`: a request_plus read that could not get a fresh
+      // index snapshot within `scan_wait` runs once more without waiting, for
+      // callers that prefer a slightly stale answer to an error.
+      if (
+        !wantsScanWaitFallback(query_options) ||
+        options.scanConsistency !== QueryScanConsistency.RequestPlus ||
+        options.scanWait === undefined ||
+        !isScanWaitExpired(error)
+      ) {
+        throw error;
+      }
+      console.warn(
+        `[spice-couchbase] index not current within ${options.scanWait}ms; reading without waiting`,
+      );
+      response = await this.observe(
+        exec_scope.query(sanitizedQuery, {
+          ..._.omit(options, ["scanWait"]),
+          scanConsistency: QueryScanConsistency.NotBounded,
+        }),
+      );
+    }
     // End time
     let endTime = process.hrtime.bigint();
     // Calculate duration in microseconds
@@ -1220,11 +1444,49 @@ 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.shouldAutoOptimize(sanitizedQuery, query_options)
     ) {
-      this.optimize(sanitizedQuery, exec_scope).catch(() => {});
+      if (slowStatementHandler) {
+        if (shouldOptimize(statementShape(sanitizedQuery))) {
+          this.reportSlowStatement(
+            sanitizedQuery,
+            exec_scope,
+            Number(durationInMilliseconds),
+          ).catch(() => {});
+        }
+      } else if (shouldOptimize(sanitizedQuery)) {
+        this.optimize(sanitizedQuery, exec_scope).catch(() => {});
+      }
     }
     return response;
   }
+
+  /**
+   * Hands a slow statement to the application's handler, unless its plan is
+   * already served by a managed index. Runs under the same in-flight and
+   * cooldown guard rails as `optimize()`.
+   */
+  async reportSlowStatement(query, exec_scope, duration_ms) {
+    optimizeState.inFlight += 1;
+    try {
+      const explainResponse = await exec_scope.query(`EXPLAIN ${query}`);
+      const plan = explainResponse?.rows?.[0];
+      if (usesManagedIndex(plan)) return;
+      await slowStatementHandler({
+        statement: query,
+        shape: statementShape(query),
+        plan,
+        resources: [...this.statementResources(query)],
+        connection: this.connection_name,
+        bucket: this.bucket,
+        scope: this.scope_name,
+        collection: this.collection_name,
+        duration_ms,
+      });
+    } catch (e) {
+      optimizeState.cooldownUntil = Date.now() + OPTIMIZE_FAILURE_COOLDOWN_MS;
+    } finally {
+      optimizeState.inFlight -= 1;
+    }
+  }
 };

package/src/utility.js

@@ -519,7 +519,85 @@ function extractStatementResources(query) {
   return names;
 }
 
+// Names the application's index manager owns. A statement whose plan already
+// scans one of these is being served by a deliberate index, so the slow-query
+// path leaves it alone. `ix_base` is the per-collection fallback and does not
+// count: a statement that only finds the fallback is exactly what to report.
+const MANAGED_INDEX_NAME = /^ix_(sort|eq|agg|core|obs)_[0-9a-f]{6}_[0-9a-f]{4}$/;
+
+// Replaces the primary index on every collection: usable by any statement
+// because the leading key includes MISSING, and ordered for the default list
+// sort (`created_at DESC`).
+const BASE_INDEX = Object.freeze({
+  name: "ix_base",
+  keys: Object.freeze([
+    Object.freeze({ expr: "`created_at`", desc: true, include_missing: true }),
+    Object.freeze({ expr: "`deleted`" }),
+  ]),
+});
+
+/**
+ * The statement with its literals replaced by `?`, so one query shape is
+ * examined once however many values it runs with. IN lists collapse to `[?]`.
+ * @param {string} query
+ * @returns {string}
+ */
+function statementShape(query) {
+  return String(query ?? "")
+    .replace(/'(?:[^'\\]|\\.|'')*'/g, "?")
+    .replace(/"(?:[^"\\]|\\.)*"/g, "?")
+    .replace(/\b\d+(?:\.\d+)?\b/g, "?")
+    .replace(/\[\s*\?(?:\s*,\s*\?)*\s*\]/g, "[?]")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * Names of the indexes an EXPLAIN plan scans.
+ * @param {object} plan
+ * @returns {string[]}
+ */
+function planIndexNames(plan) {
+  const names = new Set();
+  const visit = (node) => {
+    if (!node || typeof node !== "object") return;
+    if (Array.isArray(node)) {
+      node.forEach(visit);
+      return;
+    }
+    if (/Scan/.test(String(node["#operator"] || "")) && typeof node.index === "string") {
+      names.add(node.index);
+    }
+    Object.values(node).forEach(visit);
+  };
+  visit(plan);
+  return [...names];
+}
+
+function usesManagedIndex(plan) {
+  return planIndexNames(plan).some((name) => MANAGED_INDEX_NAME.test(name));
+}
+
+/**
+ * Renders one index key. Accepts a ready string or `{ expr, desc, include_missing }`.
+ * @param {string|{expr: string, desc?: boolean, include_missing?: boolean}} key
+ * @returns {string}
+ */
+function renderIndexKey(key) {
+  if (typeof key === "string") return key;
+  if (!key || typeof key.expr !== "string" || !key.expr.trim()) {
+    throw new TypeError("An index key needs an expression");
+  }
+  return `${key.expr}${key.desc ? " DESC" : ""}${key.include_missing ? " INCLUDE MISSING" : ""}`;
+}
+
 module.exports = {
+  MANAGED_INDEX_NAME,
+  BASE_INDEX,
+  statementShape,
+  planIndexNames,
+  usesManagedIndex,
+  renderIndexKey,
   buildCoveringIndex,
   buildCoveringIndexDefinition,
   indexSatisfiesCoveringDefinition,