@geonosis/search 0.1.1 → 0.3.0

package/README.md

@@ -40,6 +40,11 @@ naming what it could not answer. A filter nobody declared, a value that filter n
 undeclared ordering are all refusals — because the alternative is an empty answer read as a count
 of zero, and the refusal says so.
 
+Terms with no letter or digit in them — `?!?`, a box someone hit space in — are refused too, and
+that one is the opposite failure: every row matches nothing equally, so the page that comes back is
+the whole index. `carriesATerm(terms)` is the same question asked before the refusal, for a caller
+who wants to disable a button rather than catch an exception.
+
 `DEFAULT_LIMIT` is 50 when a query names no limit.
 
 ### Pages are keyset, never offset
@@ -65,7 +70,9 @@ const index = pgFtsSearchIndex({
 })
 ```
 
-`PgFtsOptions` is `{ executor, nowMs, projections }`. The vocabulary is DERIVED from the
+`PgFtsOptions` is `{ executor, nowMs, projections, table? }`. `table` is the one the migrations were
+rendered with — `search_index` when nobody names one — because a consumer whose schema already holds
+a `search_index` should not have to drop it. The vocabulary is DERIVED from the
 projections: the kinds it can index are the kinds it will filter by, so there is no second list to
 keep in step. It answers two orderings, `relevance` (rank) and `recent` (the instant the row was
 indexed).
@@ -82,11 +89,41 @@ for the `recent` ordering, and row level security ENABLED AND FORCED with a tena
 ops-maintenance policy.
 
 The session variable names are the consumer's vocabulary and have no default (#168). The shipped
-files carry the `MIGRATION_PLACEHOLDERS` tokens — `{{tenantSetting}}` and `{{opsSetting}}` — for a
-migrator that templates. For one that does not, `searchIndexMigrations(settings)` returns the same
-DDL rendered, as `SearchMigration[]` (`{ name, statements }`), refusing a `SearchIndexSettings`
-whose names are not the `prefix.name` Postgres accepts. `DEFAULT_OPS_VALUE` is what the ops setting
-holds while the lever is pulled; `SEARCH_INDEX_TABLE` is the one table this domain owns.
+files carry the `MIGRATION_PLACEHOLDERS` tokens — `{{tenantSetting}}`, `{{opsSetting}}` and
+`{{table}}` — for a migrator that templates. For one that does not,
+`searchIndexMigrations(settings)` returns the same DDL rendered, as `SearchMigration[]`
+(`{ name, statements }`), refusing a `SearchIndexSettings` whose names are not the `prefix.name`
+Postgres accepts. `DEFAULT_OPS_VALUE` is what the ops setting holds while the lever is pulled;
+`SEARCH_INDEX_TABLE` is the default table name.
+
+`settings.table` is the table itself, and every identifier the DDL builds is derived from it — the
+primary key, the GIN index and the `recent` index — so two of these can live in one schema. Pass
+the same name to `pgFtsSearchIndex`. A name outside `letter_or_underscore` followed by letters,
+digits, underscores or `$` is refused: it is inlined into DDL inside quotes it must not be able to
+close.
+
+### What squawk says about this DDL, and why it stands
+
+Every statement squawk 2.63.0 has a finding on ships with the finding accepted in squawk's own
+syntax — the reason on its own comment line, then `-- squawk-ignore <rules>`, then the statement.
+(The reason may not share the ignore line: squawk reads everything after the rule list as another
+rule name, and then ignores nothing.) `squawk migrations/*.sql` on the shipped files is 0 issues,
+and stays 0 once they are rendered.
+
+- **`require-concurrent-index-creation`** on both `create index` statements. `CONCURRENTLY` cannot
+  run inside a transaction, and a migrator that applies a file in one — this kit's own does, and a
+  consumer's usually does — would fail on it. The index is created in the same migration as its
+  table, so it is built over no rows.
+- **`require-lock-timeout`** and **`require-statement-timeout`**, on the first index and on
+  `enable row level security`. Both values are one deployment's numbers; DDL that shipped a
+  `set lock_timeout` would impose that deployment's budget on every consumer. Set them in the
+  session that migrates.
+- **`prefer-robust-stmts`** on both `alter table` statements. The file is applied inside a
+  transaction and every statement in it is idempotent (`if not exists`, `drop policy if exists`),
+  so a run that fails part way leaves nothing behind and a rerun is a no-op.
+
+Nothing here drops anything: the only `drop` is `drop policy if exists`, which is how a policy is
+replaced, and `ban-drop-table` never fires.
 
 ## One door, and what holds it
 
@@ -116,9 +153,10 @@ the two apart from outside.
 
 The three sets, which can be run alone:
 
-- `vocabularyConformance` — a filter, a value or an ordering the index never declared is REFUSED,
-  every declared filter publishes its values, and — the control — a query inside the vocabulary is
-  answered, because an index that refused everything would pass the refusals;
+- `vocabularyConformance` — a filter, a value or an ordering the index never declared is REFUSED, a
+  query carrying no term at all is refused rather than answered with every row, every declared
+  filter publishes its values, and — the control — a query inside the vocabulary is answered,
+  because an index that refused everything would pass the refusals;
 - `derivedProjectionConformance` — findable by what was derived, invisible to what was not, one row
   per document however often it is indexed, and gone once retired;
 - `tenantIsolationConformance` — a tenant finds only its own, a read that names no tenant finds

package/dist/index.cjs

@@ -25,6 +25,7 @@ __export(index_exports, {
   MIGRATION_PLACEHOLDERS: () => MIGRATION_PLACEHOLDERS,
   SEARCH_INDEX_TABLE: () => SEARCH_INDEX_TABLE,
   SearchRefusal: () => SearchRefusal,
+  carriesATerm: () => carriesATerm,
   derivedProjectionConformance: () => derivedProjectionConformance,
   encodeCursor: () => encodeCursor,
   pgFtsSearchIndex: () => pgFtsSearchIndex,
@@ -39,8 +40,99 @@ module.exports = __toCommonJS(index_exports);
 
 // src/conformance.ts
 var import_conformance = require("@geonosis/conformance");
+
+// src/contract.ts
+var SearchRefusal = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SearchRefusal";
+  }
+};
+var NOT_ZERO = "an empty answer to this is not a count of zero \u2014 it is a question nothing could match, and it is refused rather than answered";
+var DEFAULT_LIMIT = 50;
+var TERM = /[\p{L}\p{N}]/u;
+var carriesATerm = (terms) => TERM.test(terms);
+var readSearchQuery = (vocabulary, terms, options = {}) => {
+  if (!carriesATerm(terms)) {
+    throw new SearchRefusal(
+      `"${terms}" holds no letter or digit, so there is nothing in it to match: every row this index has matches it equally, and the page that comes back is a full scan wearing the shape of a search. A caller who wants the rows themselves is asking for a listing, which is a different question`
+    );
+  }
+  const orderings = vocabulary.orderings;
+  const first = orderings[0];
+  if (first === void 0) {
+    throw new SearchRefusal(
+      "this index declares no ordering, and a page of results is a sequence: declare at least one, because unordered rows cannot be paged by their key at all"
+    );
+  }
+  const order = options.order ?? first;
+  if (!orderings.includes(order)) {
+    throw new SearchRefusal(
+      `"${order}" is not an ordering this index declares \u2014 it orders by ${[...orderings].toSorted().join(", ")}. ${NOT_ZERO}`
+    );
+  }
+  const filters = Object.entries(options.filters ?? {}).map(([name, value]) => {
+    const values = vocabulary.filters[name];
+    if (values === void 0) {
+      throw new SearchRefusal(
+        `"${name}" is not a filter this index declares \u2014 it filters by ${Object.keys(vocabulary.filters).toSorted().join(", ")}. ${NOT_ZERO}`
+      );
+    }
+    if (!values.includes(value)) {
+      throw new SearchRefusal(
+        `"${name}" takes ${[...values].toSorted().join(", ")}, and was asked for "${value}". ${NOT_ZERO}`
+      );
+    }
+    return { name, value };
+  });
+  return {
+    ...options.after === void 0 ? {} : { after: readCursor(options.after, { order, terms }) },
+    filters,
+    limit: options.limit ?? DEFAULT_LIMIT,
+    order,
+    terms
+  };
+};
+var encodeCursor = (key) => encodeURIComponent(JSON.stringify(key));
+var KEYS = ["at", "id", "kind", "order", "rank", "terms"];
+var parsed = (cursor) => {
+  let value;
+  try {
+    value = JSON.parse(decodeURIComponent(cursor));
+  } catch {
+    throw new SearchRefusal(
+      "this cursor was not minted by this index: a page is reached by the key of the row before it, and that key is not readable here"
+    );
+  }
+  if (typeof value !== "object" || value === null) {
+    throw new SearchRefusal("this cursor holds no key at all");
+  }
+  const held = value;
+  const missing = KEYS.filter((key) => held[key] === void 0);
+  if (missing.length > 0) {
+    throw new SearchRefusal(`this cursor is missing ${missing.join(", ")}`);
+  }
+  return held;
+};
+var readCursor = (cursor, asked) => {
+  const key = parsed(cursor);
+  if (key.terms !== asked.terms) {
+    throw new SearchRefusal(
+      `this cursor was minted for "${key.terms}" and the query asks "${asked.terms}": ranks are comparable only within one question, so the page after it would be another query's`
+    );
+  }
+  if (key.order !== asked.order) {
+    throw new SearchRefusal(
+      `this cursor was minted under the "${key.order}" ordering and the query asks for "${asked.order}"`
+    );
+  }
+  return key;
+};
+
+// src/conformance.ts
 var A = "tenant_conformance_a";
 var B = "tenant_conformance_b";
+var TERMLESS = "?!?";
 var twoExamples = (subject) => {
   const [first, second] = subject.examples;
   if (first === void 0 || second === void 0) {
@@ -84,7 +176,8 @@ var vocabularyConformance = (subject) => {
           A,
           (index) => (0, import_conformance.assertRefuses)(
             () => index.query(first.findableBy, { filters: { conformance_unknown: "x" } }),
-            "a filter no vocabulary declares was answered rather than refused, and the empty answer it gives reads as a count of zero"
+            "a filter no vocabulary declares was answered rather than refused, and the empty answer it gives reads as a count of zero",
+            SearchRefusal
           )
         );
       }
@@ -98,7 +191,22 @@ var vocabularyConformance = (subject) => {
             () => index.query(first.findableBy, {
               filters: { [filter.name]: "conformance_undeclared_value" }
             }),
-            `"${filter.name}" takes ${[...filter.values].toSorted().join(", ")} and answered a value outside that list: publishing filter names without their values is how a caller filters for something nothing emits and reports the empty result as a count`
+            `"${filter.name}" takes ${[...filter.values].toSorted().join(", ")} and answered a value outside that list: publishing filter names without their values is how a caller filters for something nothing emits and reports the empty result as a count`,
+            SearchRefusal
+          );
+        });
+      }
+    },
+    {
+      name: "a query with no term in it is refused rather than answered with every row",
+      run: async () => {
+        await subject.reset();
+        await subject.inTenant(A, async (index) => {
+          await index.index(first.document);
+          await (0, import_conformance.assertRefuses)(
+            () => index.query(TERMLESS),
+            `"${TERMLESS}" carries nothing to match on, and the answer to it was a page rather than a refusal: a query whose terms hold no letter or digit selects every row this index has, which is a full scan wearing the shape of a search`,
+            SearchRefusal
           );
         });
       }
@@ -110,7 +218,8 @@ var vocabularyConformance = (subject) => {
           A,
           (index) => (0, import_conformance.assertRefuses)(
             () => index.query(first.findableBy, { order: "conformance_unknown" }),
-            "an ordering nobody declared was accepted, so the rows came back in whatever order the storage felt like and the page after them is unreachable"
+            "an ordering nobody declared was accepted, so the rows came back in whatever order the storage felt like and the page after them is unreachable",
+            SearchRefusal
           )
         );
       }
@@ -252,95 +361,25 @@ var searchConformance = (subject) => [
   ...tenantIsolationConformance(subject)
 ];
 
-// src/contract.ts
-var SearchRefusal = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "SearchRefusal";
-  }
-};
-var NOT_ZERO = "an empty answer to this is not a count of zero \u2014 it is a question nothing could match, and it is refused rather than answered";
-var DEFAULT_LIMIT = 50;
-var readSearchQuery = (vocabulary, terms, options = {}) => {
-  const orderings = vocabulary.orderings;
-  const first = orderings[0];
-  if (first === void 0) {
-    throw new SearchRefusal(
-      "this index declares no ordering, and a page of results is a sequence: declare at least one, because unordered rows cannot be paged by their key at all"
-    );
-  }
-  const order = options.order ?? first;
-  if (!orderings.includes(order)) {
-    throw new SearchRefusal(
-      `"${order}" is not an ordering this index declares \u2014 it orders by ${[...orderings].toSorted().join(", ")}. ${NOT_ZERO}`
-    );
-  }
-  const filters = Object.entries(options.filters ?? {}).map(([name, value]) => {
-    const values = vocabulary.filters[name];
-    if (values === void 0) {
-      throw new SearchRefusal(
-        `"${name}" is not a filter this index declares \u2014 it filters by ${Object.keys(vocabulary.filters).toSorted().join(", ")}. ${NOT_ZERO}`
-      );
-    }
-    if (!values.includes(value)) {
-      throw new SearchRefusal(
-        `"${name}" takes ${[...values].toSorted().join(", ")}, and was asked for "${value}". ${NOT_ZERO}`
-      );
-    }
-    return { name, value };
-  });
-  return {
-    ...options.after === void 0 ? {} : { after: readCursor(options.after, { order, terms }) },
-    filters,
-    limit: options.limit ?? DEFAULT_LIMIT,
-    order,
-    terms
-  };
-};
-var encodeCursor = (key) => encodeURIComponent(JSON.stringify(key));
-var KEYS = ["at", "id", "kind", "order", "rank", "terms"];
-var parsed = (cursor) => {
-  let value;
-  try {
-    value = JSON.parse(decodeURIComponent(cursor));
-  } catch {
-    throw new SearchRefusal(
-      "this cursor was not minted by this index: a page is reached by the key of the row before it, and that key is not readable here"
-    );
-  }
-  if (typeof value !== "object" || value === null) {
-    throw new SearchRefusal("this cursor holds no key at all");
-  }
-  const held = value;
-  const missing = KEYS.filter((key) => held[key] === void 0);
-  if (missing.length > 0) {
-    throw new SearchRefusal(`this cursor is missing ${missing.join(", ")}`);
-  }
-  return held;
-};
-var readCursor = (cursor, asked) => {
-  const key = parsed(cursor);
-  if (key.terms !== asked.terms) {
-    throw new SearchRefusal(
-      `this cursor was minted for "${key.terms}" and the query asks "${asked.terms}": ranks are comparable only within one question, so the page after it would be another query's`
-    );
-  }
-  if (key.order !== asked.order) {
-    throw new SearchRefusal(
-      `this cursor was minted under the "${key.order}" ordering and the query asks for "${asked.order}"`
-    );
-  }
-  return key;
-};
-
 // src/provider/ddl.ts
 var SEARCH_INDEX_TABLE = "search_index";
 var MIGRATION_PLACEHOLDERS = {
   opsSetting: "{{opsSetting}}",
+  table: "{{table}}",
   tenantSetting: "{{tenantSetting}}"
 };
 var DEFAULT_OPS_VALUE = "on";
 var CUSTOM_SETTING = /^[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$/;
+var TABLE_NAME = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+var readTableName = (name) => {
+  const table = name ?? SEARCH_INDEX_TABLE;
+  if (!TABLE_NAME.test(table)) {
+    throw new SearchRefusal(
+      `"${table}" is not a table name this DDL can write: it is inlined into every statement inside double quotes, and a name outside \`letter_or_underscore followed by letters, digits, underscores or $\` could close them. Name the schema in the search_path rather than here`
+    );
+  }
+  return table;
+};
 var readSettings = (settings) => {
   for (const named of ["opsSetting", "tenantSetting"]) {
     const name = settings[named];
@@ -355,14 +394,30 @@ var readSettings = (settings) => {
       );
     }
   }
-  return { ...settings, opsValue: settings.opsValue ?? DEFAULT_OPS_VALUE };
+  return {
+    ...settings,
+    opsValue: settings.opsValue ?? DEFAULT_OPS_VALUE,
+    table: readTableName(settings.table)
+  };
 };
 var quoted = (identifier) => `"${identifier}"`;
 var setting = (name) => `current_setting('${name}', true)`;
 var both = (predicate) => `using (${predicate}) with check (${predicate})`;
-var table = quoted(SEARCH_INDEX_TABLE);
-var searchIndexTable = (tenantSetting) => [
-  `create table if not exists ${table} (
+var accepted = (because, rules, statement) => `-- ${because}
+-- squawk-ignore ${rules.join(", ")}
+${statement}`;
+var TIMEOUTS_BELONG_TO_THE_DEPLOYMENT = "lock_timeout and statement_timeout are one deployment\u2019s numbers, and a value written into shipped DDL imposes that deployment\u2019s budget on every consumer: set them in the session that migrates.";
+var IN_ONE_TRANSACTION = "The migrator applies this file inside a transaction, which is also why CONCURRENTLY is not available here; the index is created in the same migration as its table, over no rows.";
+var RERUNNABLE = "This file is applied inside a transaction and every statement in it is idempotent, so a run that fails part way through leaves nothing behind and a rerun is a no-op.";
+var searchIndexTable = (tenantSetting, name) => {
+  const table = quoted(name);
+  const index = (suffix, over) => accepted(
+    `${IN_ONE_TRANSACTION} ${TIMEOUTS_BELONG_TO_THE_DEPLOYMENT}`,
+    ["require-concurrent-index-creation", "require-lock-timeout", "require-statement-timeout"],
+    `create index if not exists ${quoted(`${name}_${suffix}`)} on ${table} ${over}`
+  );
+  return [
+    `create table if not exists ${table} (
   "tenant_id" text not null default ${setting(tenantSetting)},
   "kind" text not null,
   "id" text not null,
@@ -370,53 +425,69 @@ var searchIndexTable = (tenantSetting) => [
   "body" text not null,
   "indexed_at" bigint not null,
   "search" tsvector generated always as (to_tsvector('simple', regexp_replace(coalesce("title", '') || ' ' || coalesce("body", ''), '[^[:alnum:]]+', ' ', 'g'))) stored,
-  constraint "search_index_pkey" primary key ("tenant_id", "kind", "id")
+  constraint ${quoted(`${name}_pkey`)} primary key ("tenant_id", "kind", "id")
 )`,
-  `create index if not exists "search_index_search_idx" on ${table} using gin ("search")`,
-  `create index if not exists "search_index_recent_idx" on ${table} ("tenant_id", "indexed_at" desc)`
-];
-var policy = (name, as, predicate) => [
+    index("search_idx", 'using gin ("search")'),
+    index("recent_idx", '("tenant_id", "indexed_at" desc)')
+  ];
+};
+var policy = (table, name, as, predicate) => [
   `drop policy if exists ${quoted(name)} on ${table}`,
   `create policy ${quoted(name)} on ${table} as ${as} for all ${both(predicate)}`
 ];
-var searchIndexPolicies = (settings) => [
-  `alter table ${table} enable row level security`,
-  `alter table ${table} force row level security`,
-  ...policy(
-    "tenant_isolation",
-    "permissive",
-    `"tenant_id" = (select ${setting(settings.tenantSetting)})`
-  ),
-  ...policy(
-    "ops_maintenance",
-    "permissive",
-    `(select ${setting(settings.opsSetting)}) = '${settings.opsValue}'`
-  )
-];
-var renderMigrations = (settings) => [
-  { name: "0001_search_index.sql", statements: searchIndexTable(settings.tenantSetting) },
-  {
-    name: "0002_search_index_policies.sql",
-    statements: searchIndexPolicies({
-      ...settings,
-      opsValue: settings.opsValue ?? DEFAULT_OPS_VALUE
-    })
-  }
-];
+var searchIndexPolicies = (settings) => {
+  const table = quoted(settings.table);
+  return [
+    accepted(
+      `${RERUNNABLE} ${TIMEOUTS_BELONG_TO_THE_DEPLOYMENT}`,
+      ["prefer-robust-stmts", "require-lock-timeout", "require-statement-timeout"],
+      `alter table ${table} enable row level security`
+    ),
+    accepted(RERUNNABLE, ["prefer-robust-stmts"], `alter table ${table} force row level security`),
+    ...policy(
+      table,
+      "tenant_isolation",
+      "permissive",
+      `"tenant_id" = (select ${setting(settings.tenantSetting)})`
+    ),
+    ...policy(
+      table,
+      "ops_maintenance",
+      "permissive",
+      `(select ${setting(settings.opsSetting)}) = '${settings.opsValue}'`
+    )
+  ];
+};
+var renderMigrations = (settings) => {
+  const table = settings.table ?? SEARCH_INDEX_TABLE;
+  return [
+    { name: "0001_search_index.sql", statements: searchIndexTable(settings.tenantSetting, table) },
+    {
+      name: "0002_search_index_policies.sql",
+      statements: searchIndexPolicies({
+        ...settings,
+        opsValue: settings.opsValue ?? DEFAULT_OPS_VALUE,
+        table
+      })
+    }
+  ];
+};
 var searchIndexMigrations = (settings) => renderMigrations(readSettings(settings));
 
 // src/provider/pg-fts.ts
 var import_conformance2 = require("@geonosis/conformance");
 var TOKEN = /[\p{L}\p{N}]+/gu;
 var toTsQuery = (terms) => (terms.match(TOKEN) ?? []).map((token) => `${token.toLowerCase()}:*`).join(" & ");
-var table2 = `"${SEARCH_INDEX_TABLE}"`;
 var COLUMN_OF = { kind: '"kind"' };
 var ORDERINGS = ["relevance", "recent"];
 var pgFtsSearchIndex = ({
   executor,
   nowMs,
-  projections
+  projections,
+  table: named
 }) => {
+  const name = readTableName(named);
+  const table = `"${name}"`;
   const kinds = Object.keys(projections);
   const vocabulary = {
     filters: { kind: kinds },
@@ -443,7 +514,7 @@ var pgFtsSearchIndex = ({
           projection.body(document.fields),
           nowMs()
         ],
-        text: `insert into ${table2} ("kind", "id", "title", "body", "indexed_at") values ($1, $2, $3, $4, $5) on conflict on constraint "search_index_pkey" do update set "title" = excluded."title", "body" = excluded."body", "indexed_at" = excluded."indexed_at"`
+        text: `insert into ${table} ("kind", "id", "title", "body", "indexed_at") values ($1, $2, $3, $4, $5) on conflict on constraint "${name}_pkey" do update set "title" = excluded."title", "body" = excluded."body", "indexed_at" = excluded."indexed_at"`
       });
     },
     query: async (terms, options) => {
@@ -453,10 +524,9 @@ var pgFtsSearchIndex = ({
         params.push(value);
         return `$${params.length}`;
       };
-      const expression = toTsQuery(read.terms);
-      const matched = expression === "" ? void 0 : bind(expression);
-      const rank = matched === void 0 ? "0::real" : `ts_rank("search", to_tsquery('simple', ${matched}))`;
-      const where = matched === void 0 ? [] : [`"search" @@ to_tsquery('simple', ${matched})`];
+      const matched = bind(toTsQuery(read.terms));
+      const rank = `ts_rank("search", to_tsquery('simple', ${matched}))`;
+      const where = [`"search" @@ to_tsquery('simple', ${matched})`];
       for (const filter of read.filters) {
         const column = COLUMN_OF[filter.name];
         if (column === void 0) {
@@ -473,7 +543,7 @@ var pgFtsSearchIndex = ({
       }
       const answer = await executor.execute({
         params,
-        text: `select "kind", "id", "title", "indexed_at", ${rank} as "rank" from ${table2}${where.length === 0 ? "" : ` where ${where.join(" and ")}`} order by ${key} desc, "kind" desc, "id" desc limit ${bind(read.limit + 1)}`
+        text: `select "kind", "id", "title", "indexed_at", ${rank} as "rank" from ${table}${where.length === 0 ? "" : ` where ${where.join(" and ")}`} order by ${key} desc, "kind" desc, "id" desc limit ${bind(read.limit + 1)}`
       });
       const rows = (0, import_conformance2.rowsOf)(answer);
       const hits = rows.slice(0, read.limit).map((row) => ({
@@ -500,7 +570,7 @@ var pgFtsSearchIndex = ({
     retire: async (document) => {
       await executor.execute({
         params: [document.kind, document.id],
-        text: `delete from ${table2} where "kind" = $1 and "id" = $2`
+        text: `delete from ${table} where "kind" = $1 and "id" = $2`
       });
     },
     vocabulary
@@ -513,6 +583,7 @@ var pgFtsSearchIndex = ({
   MIGRATION_PLACEHOLDERS,
   SEARCH_INDEX_TABLE,
   SearchRefusal,
+  carriesATerm,
   derivedProjectionConformance,
   encodeCursor,
   pgFtsSearchIndex,

package/dist/index.d.cts

@@ -75,6 +75,8 @@ declare class SearchRefusal extends Error {
     constructor(message: string);
 }
 declare const DEFAULT_LIMIT = 50;
+/** Whether anything in these terms could be matched: a run of letters or digits, anywhere in it. */
+declare const carriesATerm: (terms: string) => boolean;
 type ReadFilter = {
     name: string;
     value: string;
@@ -178,6 +180,11 @@ type SearchIndexSettings = {
     opsSetting: string;
     /** What the ops setting holds while that lever is pulled. */
     opsValue?: string;
+    /**
+     * The table this index lives in. A consumer whose schema already holds a `search_index` names
+     * theirs here rather than dropping it (#244); every identifier the DDL builds is derived from it.
+     */
+    table?: string;
     /** What a transaction sets to name the tenant it is open for. */
     tenantSetting: string;
 };
@@ -186,9 +193,10 @@ type SearchMigration = {
     statements: string[];
 };
 declare const SEARCH_INDEX_TABLE = "search_index";
-/** The tokens the shipped `.sql` files carry where a session variable belongs. */
+/** The tokens the shipped `.sql` files carry where a consumer's own name belongs. */
 declare const MIGRATION_PLACEHOLDERS: {
     opsSetting: string;
+    table: string;
     tenantSetting: string;
 };
 declare const DEFAULT_OPS_VALUE = "on";
@@ -205,6 +213,8 @@ type PgFtsOptions<Kind extends string> = {
     /** Injected, never ambient (D-050): the composition root passes `Date.now`. */
     nowMs: () => number;
     projections: SearchProjections<Kind>;
+    /** The table the migrations were rendered with (#244). `search_index` when nobody named one. */
+    table?: string;
 };
 /**
  * Postgres full text search over an injected executor.
@@ -213,6 +223,6 @@ type PgFtsOptions<Kind extends string> = {
  * the read carries no predicate at all — the policies in this package's own migrations are what
  * answers that question, so a query that forgot its session sees nothing rather than everything.
  */
-declare const pgFtsSearchIndex: <Kind extends string>({ executor, nowMs, projections, }: PgFtsOptions<Kind>) => SearchIndex<Kind>;
+declare const pgFtsSearchIndex: <Kind extends string>({ executor, nowMs, projections, table: named, }: PgFtsOptions<Kind>) => SearchIndex<Kind>;
 
-export { DEFAULT_LIMIT, DEFAULT_OPS_VALUE, type DocumentAddress, type DocumentFields, type IndexedDocument, MIGRATION_PLACEHOLDERS, type PgFtsOptions, type ReadFilter, type ReadQuery, SEARCH_INDEX_TABLE, type SearchConformanceCase, type SearchCursor, type SearchCursorKey, type SearchExample, type SearchHit, type SearchIndex, type SearchIndexSettings, type SearchMigration, type SearchOptions, type SearchPage, type SearchProjection, type SearchProjections, SearchRefusal, type SearchSubject, type SearchVocabulary, derivedProjectionConformance, encodeCursor, pgFtsSearchIndex, readCursor, readSearchQuery, searchConformance, searchIndexMigrations, tenantIsolationConformance, vocabularyConformance };
+export { DEFAULT_LIMIT, DEFAULT_OPS_VALUE, type DocumentAddress, type DocumentFields, type IndexedDocument, MIGRATION_PLACEHOLDERS, type PgFtsOptions, type ReadFilter, type ReadQuery, SEARCH_INDEX_TABLE, type SearchConformanceCase, type SearchCursor, type SearchCursorKey, type SearchExample, type SearchHit, type SearchIndex, type SearchIndexSettings, type SearchMigration, type SearchOptions, type SearchPage, type SearchProjection, type SearchProjections, SearchRefusal, type SearchSubject, type SearchVocabulary, carriesATerm, derivedProjectionConformance, encodeCursor, pgFtsSearchIndex, readCursor, readSearchQuery, searchConformance, searchIndexMigrations, tenantIsolationConformance, vocabularyConformance };

package/dist/index.d.ts

@@ -75,6 +75,8 @@ declare class SearchRefusal extends Error {
     constructor(message: string);
 }
 declare const DEFAULT_LIMIT = 50;
+/** Whether anything in these terms could be matched: a run of letters or digits, anywhere in it. */
+declare const carriesATerm: (terms: string) => boolean;
 type ReadFilter = {
     name: string;
     value: string;
@@ -178,6 +180,11 @@ type SearchIndexSettings = {
     opsSetting: string;
     /** What the ops setting holds while that lever is pulled. */
     opsValue?: string;
+    /**
+     * The table this index lives in. A consumer whose schema already holds a `search_index` names
+     * theirs here rather than dropping it (#244); every identifier the DDL builds is derived from it.
+     */
+    table?: string;
     /** What a transaction sets to name the tenant it is open for. */
     tenantSetting: string;
 };
@@ -186,9 +193,10 @@ type SearchMigration = {
     statements: string[];
 };
 declare const SEARCH_INDEX_TABLE = "search_index";
-/** The tokens the shipped `.sql` files carry where a session variable belongs. */
+/** The tokens the shipped `.sql` files carry where a consumer's own name belongs. */
 declare const MIGRATION_PLACEHOLDERS: {
     opsSetting: string;
+    table: string;
     tenantSetting: string;
 };
 declare const DEFAULT_OPS_VALUE = "on";
@@ -205,6 +213,8 @@ type PgFtsOptions<Kind extends string> = {
     /** Injected, never ambient (D-050): the composition root passes `Date.now`. */
     nowMs: () => number;
     projections: SearchProjections<Kind>;
+    /** The table the migrations were rendered with (#244). `search_index` when nobody named one. */
+    table?: string;
 };
 /**
  * Postgres full text search over an injected executor.
@@ -213,6 +223,6 @@ type PgFtsOptions<Kind extends string> = {
  * the read carries no predicate at all — the policies in this package's own migrations are what
  * answers that question, so a query that forgot its session sees nothing rather than everything.
  */
-declare const pgFtsSearchIndex: <Kind extends string>({ executor, nowMs, projections, }: PgFtsOptions<Kind>) => SearchIndex<Kind>;
+declare const pgFtsSearchIndex: <Kind extends string>({ executor, nowMs, projections, table: named, }: PgFtsOptions<Kind>) => SearchIndex<Kind>;
 
-export { DEFAULT_LIMIT, DEFAULT_OPS_VALUE, type DocumentAddress, type DocumentFields, type IndexedDocument, MIGRATION_PLACEHOLDERS, type PgFtsOptions, type ReadFilter, type ReadQuery, SEARCH_INDEX_TABLE, type SearchConformanceCase, type SearchCursor, type SearchCursorKey, type SearchExample, type SearchHit, type SearchIndex, type SearchIndexSettings, type SearchMigration, type SearchOptions, type SearchPage, type SearchProjection, type SearchProjections, SearchRefusal, type SearchSubject, type SearchVocabulary, derivedProjectionConformance, encodeCursor, pgFtsSearchIndex, readCursor, readSearchQuery, searchConformance, searchIndexMigrations, tenantIsolationConformance, vocabularyConformance };
+export { DEFAULT_LIMIT, DEFAULT_OPS_VALUE, type DocumentAddress, type DocumentFields, type IndexedDocument, MIGRATION_PLACEHOLDERS, type PgFtsOptions, type ReadFilter, type ReadQuery, SEARCH_INDEX_TABLE, type SearchConformanceCase, type SearchCursor, type SearchCursorKey, type SearchExample, type SearchHit, type SearchIndex, type SearchIndexSettings, type SearchMigration, type SearchOptions, type SearchPage, type SearchProjection, type SearchProjections, SearchRefusal, type SearchSubject, type SearchVocabulary, carriesATerm, derivedProjectionConformance, encodeCursor, pgFtsSearchIndex, readCursor, readSearchQuery, searchConformance, searchIndexMigrations, tenantIsolationConformance, vocabularyConformance };

package/dist/index.js

@@ -1,7 +1,98 @@
 // src/conformance.ts
 import { assertRefuses, assertThat, ConformanceFailure } from "@geonosis/conformance";
+
+// src/contract.ts
+var SearchRefusal = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SearchRefusal";
+  }
+};
+var NOT_ZERO = "an empty answer to this is not a count of zero \u2014 it is a question nothing could match, and it is refused rather than answered";
+var DEFAULT_LIMIT = 50;
+var TERM = /[\p{L}\p{N}]/u;
+var carriesATerm = (terms) => TERM.test(terms);
+var readSearchQuery = (vocabulary, terms, options = {}) => {
+  if (!carriesATerm(terms)) {
+    throw new SearchRefusal(
+      `"${terms}" holds no letter or digit, so there is nothing in it to match: every row this index has matches it equally, and the page that comes back is a full scan wearing the shape of a search. A caller who wants the rows themselves is asking for a listing, which is a different question`
+    );
+  }
+  const orderings = vocabulary.orderings;
+  const first = orderings[0];
+  if (first === void 0) {
+    throw new SearchRefusal(
+      "this index declares no ordering, and a page of results is a sequence: declare at least one, because unordered rows cannot be paged by their key at all"
+    );
+  }
+  const order = options.order ?? first;
+  if (!orderings.includes(order)) {
+    throw new SearchRefusal(
+      `"${order}" is not an ordering this index declares \u2014 it orders by ${[...orderings].toSorted().join(", ")}. ${NOT_ZERO}`
+    );
+  }
+  const filters = Object.entries(options.filters ?? {}).map(([name, value]) => {
+    const values = vocabulary.filters[name];
+    if (values === void 0) {
+      throw new SearchRefusal(
+        `"${name}" is not a filter this index declares \u2014 it filters by ${Object.keys(vocabulary.filters).toSorted().join(", ")}. ${NOT_ZERO}`
+      );
+    }
+    if (!values.includes(value)) {
+      throw new SearchRefusal(
+        `"${name}" takes ${[...values].toSorted().join(", ")}, and was asked for "${value}". ${NOT_ZERO}`
+      );
+    }
+    return { name, value };
+  });
+  return {
+    ...options.after === void 0 ? {} : { after: readCursor(options.after, { order, terms }) },
+    filters,
+    limit: options.limit ?? DEFAULT_LIMIT,
+    order,
+    terms
+  };
+};
+var encodeCursor = (key) => encodeURIComponent(JSON.stringify(key));
+var KEYS = ["at", "id", "kind", "order", "rank", "terms"];
+var parsed = (cursor) => {
+  let value;
+  try {
+    value = JSON.parse(decodeURIComponent(cursor));
+  } catch {
+    throw new SearchRefusal(
+      "this cursor was not minted by this index: a page is reached by the key of the row before it, and that key is not readable here"
+    );
+  }
+  if (typeof value !== "object" || value === null) {
+    throw new SearchRefusal("this cursor holds no key at all");
+  }
+  const held = value;
+  const missing = KEYS.filter((key) => held[key] === void 0);
+  if (missing.length > 0) {
+    throw new SearchRefusal(`this cursor is missing ${missing.join(", ")}`);
+  }
+  return held;
+};
+var readCursor = (cursor, asked) => {
+  const key = parsed(cursor);
+  if (key.terms !== asked.terms) {
+    throw new SearchRefusal(
+      `this cursor was minted for "${key.terms}" and the query asks "${asked.terms}": ranks are comparable only within one question, so the page after it would be another query's`
+    );
+  }
+  if (key.order !== asked.order) {
+    throw new SearchRefusal(
+      `this cursor was minted under the "${key.order}" ordering and the query asks for "${asked.order}"`
+    );
+  }
+  return key;
+};
+
+// src/conformance.ts
 var A = "tenant_conformance_a";
 var B = "tenant_conformance_b";
+var TERMLESS = "?!?";
 var twoExamples = (subject) => {
   const [first, second] = subject.examples;
   if (first === void 0 || second === void 0) {
@@ -45,7 +136,8 @@ var vocabularyConformance = (subject) => {
           A,
           (index) => assertRefuses(
             () => index.query(first.findableBy, { filters: { conformance_unknown: "x" } }),
-            "a filter no vocabulary declares was answered rather than refused, and the empty answer it gives reads as a count of zero"
+            "a filter no vocabulary declares was answered rather than refused, and the empty answer it gives reads as a count of zero",
+            SearchRefusal
           )
         );
       }
@@ -59,7 +151,22 @@ var vocabularyConformance = (subject) => {
             () => index.query(first.findableBy, {
               filters: { [filter.name]: "conformance_undeclared_value" }
             }),
-            `"${filter.name}" takes ${[...filter.values].toSorted().join(", ")} and answered a value outside that list: publishing filter names without their values is how a caller filters for something nothing emits and reports the empty result as a count`
+            `"${filter.name}" takes ${[...filter.values].toSorted().join(", ")} and answered a value outside that list: publishing filter names without their values is how a caller filters for something nothing emits and reports the empty result as a count`,
+            SearchRefusal
+          );
+        });
+      }
+    },
+    {
+      name: "a query with no term in it is refused rather than answered with every row",
+      run: async () => {
+        await subject.reset();
+        await subject.inTenant(A, async (index) => {
+          await index.index(first.document);
+          await assertRefuses(
+            () => index.query(TERMLESS),
+            `"${TERMLESS}" carries nothing to match on, and the answer to it was a page rather than a refusal: a query whose terms hold no letter or digit selects every row this index has, which is a full scan wearing the shape of a search`,
+            SearchRefusal
           );
         });
       }
@@ -71,7 +178,8 @@ var vocabularyConformance = (subject) => {
           A,
           (index) => assertRefuses(
             () => index.query(first.findableBy, { order: "conformance_unknown" }),
-            "an ordering nobody declared was accepted, so the rows came back in whatever order the storage felt like and the page after them is unreachable"
+            "an ordering nobody declared was accepted, so the rows came back in whatever order the storage felt like and the page after them is unreachable",
+            SearchRefusal
           )
         );
       }
@@ -213,95 +321,25 @@ var searchConformance = (subject) => [
   ...tenantIsolationConformance(subject)
 ];
 
-// src/contract.ts
-var SearchRefusal = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "SearchRefusal";
-  }
-};
-var NOT_ZERO = "an empty answer to this is not a count of zero \u2014 it is a question nothing could match, and it is refused rather than answered";
-var DEFAULT_LIMIT = 50;
-var readSearchQuery = (vocabulary, terms, options = {}) => {
-  const orderings = vocabulary.orderings;
-  const first = orderings[0];
-  if (first === void 0) {
-    throw new SearchRefusal(
-      "this index declares no ordering, and a page of results is a sequence: declare at least one, because unordered rows cannot be paged by their key at all"
-    );
-  }
-  const order = options.order ?? first;
-  if (!orderings.includes(order)) {
-    throw new SearchRefusal(
-      `"${order}" is not an ordering this index declares \u2014 it orders by ${[...orderings].toSorted().join(", ")}. ${NOT_ZERO}`
-    );
-  }
-  const filters = Object.entries(options.filters ?? {}).map(([name, value]) => {
-    const values = vocabulary.filters[name];
-    if (values === void 0) {
-      throw new SearchRefusal(
-        `"${name}" is not a filter this index declares \u2014 it filters by ${Object.keys(vocabulary.filters).toSorted().join(", ")}. ${NOT_ZERO}`
-      );
-    }
-    if (!values.includes(value)) {
-      throw new SearchRefusal(
-        `"${name}" takes ${[...values].toSorted().join(", ")}, and was asked for "${value}". ${NOT_ZERO}`
-      );
-    }
-    return { name, value };
-  });
-  return {
-    ...options.after === void 0 ? {} : { after: readCursor(options.after, { order, terms }) },
-    filters,
-    limit: options.limit ?? DEFAULT_LIMIT,
-    order,
-    terms
-  };
-};
-var encodeCursor = (key) => encodeURIComponent(JSON.stringify(key));
-var KEYS = ["at", "id", "kind", "order", "rank", "terms"];
-var parsed = (cursor) => {
-  let value;
-  try {
-    value = JSON.parse(decodeURIComponent(cursor));
-  } catch {
-    throw new SearchRefusal(
-      "this cursor was not minted by this index: a page is reached by the key of the row before it, and that key is not readable here"
-    );
-  }
-  if (typeof value !== "object" || value === null) {
-    throw new SearchRefusal("this cursor holds no key at all");
-  }
-  const held = value;
-  const missing = KEYS.filter((key) => held[key] === void 0);
-  if (missing.length > 0) {
-    throw new SearchRefusal(`this cursor is missing ${missing.join(", ")}`);
-  }
-  return held;
-};
-var readCursor = (cursor, asked) => {
-  const key = parsed(cursor);
-  if (key.terms !== asked.terms) {
-    throw new SearchRefusal(
-      `this cursor was minted for "${key.terms}" and the query asks "${asked.terms}": ranks are comparable only within one question, so the page after it would be another query's`
-    );
-  }
-  if (key.order !== asked.order) {
-    throw new SearchRefusal(
-      `this cursor was minted under the "${key.order}" ordering and the query asks for "${asked.order}"`
-    );
-  }
-  return key;
-};
-
 // src/provider/ddl.ts
 var SEARCH_INDEX_TABLE = "search_index";
 var MIGRATION_PLACEHOLDERS = {
   opsSetting: "{{opsSetting}}",
+  table: "{{table}}",
   tenantSetting: "{{tenantSetting}}"
 };
 var DEFAULT_OPS_VALUE = "on";
 var CUSTOM_SETTING = /^[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$/;
+var TABLE_NAME = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+var readTableName = (name) => {
+  const table = name ?? SEARCH_INDEX_TABLE;
+  if (!TABLE_NAME.test(table)) {
+    throw new SearchRefusal(
+      `"${table}" is not a table name this DDL can write: it is inlined into every statement inside double quotes, and a name outside \`letter_or_underscore followed by letters, digits, underscores or $\` could close them. Name the schema in the search_path rather than here`
+    );
+  }
+  return table;
+};
 var readSettings = (settings) => {
   for (const named of ["opsSetting", "tenantSetting"]) {
     const name = settings[named];
@@ -316,14 +354,30 @@ var readSettings = (settings) => {
       );
     }
   }
-  return { ...settings, opsValue: settings.opsValue ?? DEFAULT_OPS_VALUE };
+  return {
+    ...settings,
+    opsValue: settings.opsValue ?? DEFAULT_OPS_VALUE,
+    table: readTableName(settings.table)
+  };
 };
 var quoted = (identifier) => `"${identifier}"`;
 var setting = (name) => `current_setting('${name}', true)`;
 var both = (predicate) => `using (${predicate}) with check (${predicate})`;
-var table = quoted(SEARCH_INDEX_TABLE);
-var searchIndexTable = (tenantSetting) => [
-  `create table if not exists ${table} (
+var accepted = (because, rules, statement) => `-- ${because}
+-- squawk-ignore ${rules.join(", ")}
+${statement}`;
+var TIMEOUTS_BELONG_TO_THE_DEPLOYMENT = "lock_timeout and statement_timeout are one deployment\u2019s numbers, and a value written into shipped DDL imposes that deployment\u2019s budget on every consumer: set them in the session that migrates.";
+var IN_ONE_TRANSACTION = "The migrator applies this file inside a transaction, which is also why CONCURRENTLY is not available here; the index is created in the same migration as its table, over no rows.";
+var RERUNNABLE = "This file is applied inside a transaction and every statement in it is idempotent, so a run that fails part way through leaves nothing behind and a rerun is a no-op.";
+var searchIndexTable = (tenantSetting, name) => {
+  const table = quoted(name);
+  const index = (suffix, over) => accepted(
+    `${IN_ONE_TRANSACTION} ${TIMEOUTS_BELONG_TO_THE_DEPLOYMENT}`,
+    ["require-concurrent-index-creation", "require-lock-timeout", "require-statement-timeout"],
+    `create index if not exists ${quoted(`${name}_${suffix}`)} on ${table} ${over}`
+  );
+  return [
+    `create table if not exists ${table} (
   "tenant_id" text not null default ${setting(tenantSetting)},
   "kind" text not null,
   "id" text not null,
@@ -331,53 +385,69 @@ var searchIndexTable = (tenantSetting) => [
   "body" text not null,
   "indexed_at" bigint not null,
   "search" tsvector generated always as (to_tsvector('simple', regexp_replace(coalesce("title", '') || ' ' || coalesce("body", ''), '[^[:alnum:]]+', ' ', 'g'))) stored,
-  constraint "search_index_pkey" primary key ("tenant_id", "kind", "id")
+  constraint ${quoted(`${name}_pkey`)} primary key ("tenant_id", "kind", "id")
 )`,
-  `create index if not exists "search_index_search_idx" on ${table} using gin ("search")`,
-  `create index if not exists "search_index_recent_idx" on ${table} ("tenant_id", "indexed_at" desc)`
-];
-var policy = (name, as, predicate) => [
+    index("search_idx", 'using gin ("search")'),
+    index("recent_idx", '("tenant_id", "indexed_at" desc)')
+  ];
+};
+var policy = (table, name, as, predicate) => [
   `drop policy if exists ${quoted(name)} on ${table}`,
   `create policy ${quoted(name)} on ${table} as ${as} for all ${both(predicate)}`
 ];
-var searchIndexPolicies = (settings) => [
-  `alter table ${table} enable row level security`,
-  `alter table ${table} force row level security`,
-  ...policy(
-    "tenant_isolation",
-    "permissive",
-    `"tenant_id" = (select ${setting(settings.tenantSetting)})`
-  ),
-  ...policy(
-    "ops_maintenance",
-    "permissive",
-    `(select ${setting(settings.opsSetting)}) = '${settings.opsValue}'`
-  )
-];
-var renderMigrations = (settings) => [
-  { name: "0001_search_index.sql", statements: searchIndexTable(settings.tenantSetting) },
-  {
-    name: "0002_search_index_policies.sql",
-    statements: searchIndexPolicies({
-      ...settings,
-      opsValue: settings.opsValue ?? DEFAULT_OPS_VALUE
-    })
-  }
-];
+var searchIndexPolicies = (settings) => {
+  const table = quoted(settings.table);
+  return [
+    accepted(
+      `${RERUNNABLE} ${TIMEOUTS_BELONG_TO_THE_DEPLOYMENT}`,
+      ["prefer-robust-stmts", "require-lock-timeout", "require-statement-timeout"],
+      `alter table ${table} enable row level security`
+    ),
+    accepted(RERUNNABLE, ["prefer-robust-stmts"], `alter table ${table} force row level security`),
+    ...policy(
+      table,
+      "tenant_isolation",
+      "permissive",
+      `"tenant_id" = (select ${setting(settings.tenantSetting)})`
+    ),
+    ...policy(
+      table,
+      "ops_maintenance",
+      "permissive",
+      `(select ${setting(settings.opsSetting)}) = '${settings.opsValue}'`
+    )
+  ];
+};
+var renderMigrations = (settings) => {
+  const table = settings.table ?? SEARCH_INDEX_TABLE;
+  return [
+    { name: "0001_search_index.sql", statements: searchIndexTable(settings.tenantSetting, table) },
+    {
+      name: "0002_search_index_policies.sql",
+      statements: searchIndexPolicies({
+        ...settings,
+        opsValue: settings.opsValue ?? DEFAULT_OPS_VALUE,
+        table
+      })
+    }
+  ];
+};
 var searchIndexMigrations = (settings) => renderMigrations(readSettings(settings));
 
 // src/provider/pg-fts.ts
 import { rowsOf } from "@geonosis/conformance";
 var TOKEN = /[\p{L}\p{N}]+/gu;
 var toTsQuery = (terms) => (terms.match(TOKEN) ?? []).map((token) => `${token.toLowerCase()}:*`).join(" & ");
-var table2 = `"${SEARCH_INDEX_TABLE}"`;
 var COLUMN_OF = { kind: '"kind"' };
 var ORDERINGS = ["relevance", "recent"];
 var pgFtsSearchIndex = ({
   executor,
   nowMs,
-  projections
+  projections,
+  table: named
 }) => {
+  const name = readTableName(named);
+  const table = `"${name}"`;
   const kinds = Object.keys(projections);
   const vocabulary = {
     filters: { kind: kinds },
@@ -404,7 +474,7 @@ var pgFtsSearchIndex = ({
           projection.body(document.fields),
           nowMs()
         ],
-        text: `insert into ${table2} ("kind", "id", "title", "body", "indexed_at") values ($1, $2, $3, $4, $5) on conflict on constraint "search_index_pkey" do update set "title" = excluded."title", "body" = excluded."body", "indexed_at" = excluded."indexed_at"`
+        text: `insert into ${table} ("kind", "id", "title", "body", "indexed_at") values ($1, $2, $3, $4, $5) on conflict on constraint "${name}_pkey" do update set "title" = excluded."title", "body" = excluded."body", "indexed_at" = excluded."indexed_at"`
       });
     },
     query: async (terms, options) => {
@@ -414,10 +484,9 @@ var pgFtsSearchIndex = ({
         params.push(value);
         return `$${params.length}`;
       };
-      const expression = toTsQuery(read.terms);
-      const matched = expression === "" ? void 0 : bind(expression);
-      const rank = matched === void 0 ? "0::real" : `ts_rank("search", to_tsquery('simple', ${matched}))`;
-      const where = matched === void 0 ? [] : [`"search" @@ to_tsquery('simple', ${matched})`];
+      const matched = bind(toTsQuery(read.terms));
+      const rank = `ts_rank("search", to_tsquery('simple', ${matched}))`;
+      const where = [`"search" @@ to_tsquery('simple', ${matched})`];
       for (const filter of read.filters) {
         const column = COLUMN_OF[filter.name];
         if (column === void 0) {
@@ -434,7 +503,7 @@ var pgFtsSearchIndex = ({
       }
       const answer = await executor.execute({
         params,
-        text: `select "kind", "id", "title", "indexed_at", ${rank} as "rank" from ${table2}${where.length === 0 ? "" : ` where ${where.join(" and ")}`} order by ${key} desc, "kind" desc, "id" desc limit ${bind(read.limit + 1)}`
+        text: `select "kind", "id", "title", "indexed_at", ${rank} as "rank" from ${table}${where.length === 0 ? "" : ` where ${where.join(" and ")}`} order by ${key} desc, "kind" desc, "id" desc limit ${bind(read.limit + 1)}`
       });
       const rows = rowsOf(answer);
       const hits = rows.slice(0, read.limit).map((row) => ({
@@ -461,7 +530,7 @@ var pgFtsSearchIndex = ({
     retire: async (document) => {
       await executor.execute({
         params: [document.kind, document.id],
-        text: `delete from ${table2} where "kind" = $1 and "id" = $2`
+        text: `delete from ${table} where "kind" = $1 and "id" = $2`
       });
     },
     vocabulary
@@ -473,6 +542,7 @@ export {
   MIGRATION_PLACEHOLDERS,
   SEARCH_INDEX_TABLE,
   SearchRefusal,
+  carriesATerm,
   derivedProjectionConformance,
   encodeCursor,
   pgFtsSearchIndex,

package/migrations/0001_search_index.sql

@@ -1,4 +1,4 @@
-create table if not exists "search_index" (
+create table if not exists "{{table}}" (
   "tenant_id" text not null default current_setting('{{tenantSetting}}', true),
   "kind" text not null,
   "id" text not null,
@@ -6,9 +6,13 @@ create table if not exists "search_index" (
   "body" text not null,
   "indexed_at" bigint not null,
   "search" tsvector generated always as (to_tsvector('simple', regexp_replace(coalesce("title", '') || ' ' || coalesce("body", ''), '[^[:alnum:]]+', ' ', 'g'))) stored,
-  constraint "search_index_pkey" primary key ("tenant_id", "kind", "id")
+  constraint "{{table}}_pkey" primary key ("tenant_id", "kind", "id")
 );
 
-create index if not exists "search_index_search_idx" on "search_index" using gin ("search");
+-- The migrator applies this file inside a transaction, which is also why CONCURRENTLY is not available here; the index is created in the same migration as its table, over no rows. lock_timeout and statement_timeout are one deployment’s numbers, and a value written into shipped DDL imposes that deployment’s budget on every consumer: set them in the session that migrates.
+-- squawk-ignore require-concurrent-index-creation, require-lock-timeout, require-statement-timeout
+create index if not exists "{{table}}_search_idx" on "{{table}}" using gin ("search");
 
-create index if not exists "search_index_recent_idx" on "search_index" ("tenant_id", "indexed_at" desc);
+-- The migrator applies this file inside a transaction, which is also why CONCURRENTLY is not available here; the index is created in the same migration as its table, over no rows. lock_timeout and statement_timeout are one deployment’s numbers, and a value written into shipped DDL imposes that deployment’s budget on every consumer: set them in the session that migrates.
+-- squawk-ignore require-concurrent-index-creation, require-lock-timeout, require-statement-timeout
+create index if not exists "{{table}}_recent_idx" on "{{table}}" ("tenant_id", "indexed_at" desc);

package/migrations/0002_search_index_policies.sql

@@ -1,11 +1,15 @@
-alter table "search_index" enable row level security;
+-- This file is applied inside a transaction and every statement in it is idempotent, so a run that fails part way through leaves nothing behind and a rerun is a no-op. lock_timeout and statement_timeout are one deployment’s numbers, and a value written into shipped DDL imposes that deployment’s budget on every consumer: set them in the session that migrates.
+-- squawk-ignore prefer-robust-stmts, require-lock-timeout, require-statement-timeout
+alter table "{{table}}" enable row level security;
 
-alter table "search_index" force row level security;
+-- This file is applied inside a transaction and every statement in it is idempotent, so a run that fails part way through leaves nothing behind and a rerun is a no-op.
+-- squawk-ignore prefer-robust-stmts
+alter table "{{table}}" force row level security;
 
-drop policy if exists "tenant_isolation" on "search_index";
+drop policy if exists "tenant_isolation" on "{{table}}";
 
-create policy "tenant_isolation" on "search_index" as permissive for all using ("tenant_id" = (select current_setting('{{tenantSetting}}', true))) with check ("tenant_id" = (select current_setting('{{tenantSetting}}', true)));
+create policy "tenant_isolation" on "{{table}}" as permissive for all using ("tenant_id" = (select current_setting('{{tenantSetting}}', true))) with check ("tenant_id" = (select current_setting('{{tenantSetting}}', true)));
 
-drop policy if exists "ops_maintenance" on "search_index";
+drop policy if exists "ops_maintenance" on "{{table}}";
 
-create policy "ops_maintenance" on "search_index" as permissive for all using ((select current_setting('{{opsSetting}}', true)) = 'on') with check ((select current_setting('{{opsSetting}}', true)) = 'on');
+create policy "ops_maintenance" on "{{table}}" as permissive for all using ((select current_setting('{{opsSetting}}', true)) = 'on') with check ((select current_setting('{{opsSetting}}', true)) = 'on');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geonosis/search",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "types": "./dist/index.d.ts",
   "description": "Full-text search as a domain: an index whose write path derives its own searchable projection, queries answered only inside a declared vocabulary with keyset cursors, and a Postgres provider that runs over an injected executor and ships its DDL as migrations.",
   "keywords": [
@@ -39,7 +39,7 @@
   ],
   "dependencies": {
     "@geonosis/conformance": "^0.2.0",
-    "@geonosis/db": "^0.2.0"
+    "@geonosis/db": "^0.3.0"
   },
   "devDependencies": {
     "@types/pg": "^8.15.5",