envio 3.5.0-alpha.2 → 3.5.0-rc.0

package/src/TestIndexer.res.mjs

@@ -3,6 +3,7 @@
 import * as Env from "./Env.res.mjs";
 import * as Utils from "./Utils.res.mjs";
 import * as Config from "./Config.res.mjs";
+import * as ChainId from "./ChainId.res.mjs";
 import * as Logging from "./Logging.res.mjs";
 import * as ChainMap from "./ChainMap.res.mjs";
 import * as EntityId from "./EntityId.res.mjs";
@@ -38,7 +39,7 @@ function getIndexingAddressesByChain(state) {
   let dcDict = state.entities[Config.EnvioAddresses.name];
   if (dcDict !== undefined) {
     Object.values(dcDict).forEach(entity => {
-      let chainIdStr = entity.chain_id.toString();
+      let chainIdStr = ChainId.toString(entity.chain_id);
       let arr = byChain[chainIdStr];
       let contracts;
       if (arr !== undefined) {
@@ -116,7 +117,7 @@ function handleWriteBatch(state, updatedEntities, checkpointIds, checkpointChain
   for (let i = 0, i_finish = checkpointIds.length; i < i_finish; ++i) {
     let checkpointId = checkpointIds[i];
     let change = {};
-    state.progressBlockByChain[checkpointChainIds[i].toString()] = checkpointBlockNumbers[i];
+    state.progressBlockByChain[ChainId.toString(checkpointChainIds[i])] = checkpointBlockNumbers[i];
     change["block"] = checkpointBlockNumbers[i];
     change["chainId"] = checkpointChainIds[i];
     change["eventsProcessed"] = checkpointEventsProcessed[i];
@@ -157,15 +158,14 @@ function handleWriteBatch(state, updatedEntities, checkpointIds, checkpointChain
 function makeInitialState(config, processConfigChains, indexingAddressesByChain) {
   let chainKeys = Object.keys(processConfigChains);
   let chains = chainKeys.map(chainIdStr => {
-    let chainId = Stdlib_Option.getOr(Stdlib_Int.fromString(chainIdStr, undefined), 0);
-    let chain = ChainMap.Chain.makeUnsafe(chainId);
+    let chain = ChainId.normalizeOrThrow(chainIdStr);
     if (!ChainMap.has(config.chainMap, chain)) {
       Stdlib_JsError.throwWithMessage(`Chain ` + chainIdStr + ` is not configured in config.yaml`);
     }
     let processChainConfig = processConfigChains[chainIdStr];
     let indexingAddresses = Stdlib_Option.getOr(indexingAddressesByChain[chainIdStr], []);
     return {
-      id: chainId,
+      id: chain,
       startBlock: processChainConfig.startBlock,
       endBlock: processChainConfig.endBlock,
       maxReorgDepth: 0,
@@ -222,9 +222,12 @@ function getSimulateEndBlock(simulateItems, config, startBlock) {
 }
 
 function parseBlockRange(chainIdStr, config, rawChainConfig, progressBlock) {
-  let id = Stdlib_Int.fromString(chainIdStr, undefined);
-  let chainId = id !== undefined ? id : Stdlib_JsError.throwWithMessage(`Invalid chain ID "` + chainIdStr + `": expected a numeric chain ID`);
-  let chain = ChainMap.Chain.makeUnsafe(chainId);
+  let chain;
+  try {
+    chain = ChainId.normalizeOrThrow(chainIdStr);
+  } catch (exn) {
+    chain = Stdlib_JsError.throwWithMessage(`Invalid chain ID "` + chainIdStr + `": expected a numeric chain ID`);
+  }
   if (!ChainMap.has(config.chainMap, chain)) {
     Stdlib_JsError.throwWithMessage(`Chain ` + chainIdStr + ` is not configured in config.yaml`);
   }
@@ -315,6 +318,9 @@ function makeInMemoryStorage(state) {
     initialize: async (param, param$1, param$2, param$3) => Stdlib_JsError.throwWithMessage("TestIndexer: initialize should not be called; the initial state is derived from config."),
     resumeInitialState: async () => Stdlib_JsError.throwWithMessage("TestIndexer: resumeInitialState should not be called; the initial state is derived from config."),
     loadOrThrow: async (filter, table) => handleLoad(state, table.tableName, filter),
+    ensureQueryIndexes: async (param, param$1) => {},
+    ensureSchemaIndexes: async param => {},
+    finalizeBackfill: async (param, param$1, param$2) => {},
     dumpEffectCache: async () => {},
     reset: async () => {},
     setChainMeta: async param => {},
@@ -410,7 +416,7 @@ function createTestIndexer() {
   let chainIds = [];
   let chains = Object.create(null);
   ChainMap.values(config.chainMap).forEach(chainConfig => {
-    let chainIdStr = chainConfig.id.toString();
+    let chainIdStr = ChainId.toString(chainConfig.id);
     chainIds.push(chainConfig.id);
     let chainObj = Object.create(null);
     Object.defineProperty(Object.defineProperty(Object.defineProperty(Object.defineProperty(Object.defineProperty(chainObj, "id", {
@@ -443,7 +449,7 @@ function createTestIndexer() {
           if (state.processInProgress) {
             Stdlib_JsError.throwWithMessage(`Cannot access ` + contract.name + `.addresses while indexer.process() is running. ` + "Wait for process() to complete before reading contract addresses.");
           }
-          return Stdlib_Array.filterMap(Stdlib_Option.getOr(getIndexingAddressesByChain(state)[chainConfig.id.toString()], []), ia => {
+          return Stdlib_Array.filterMap(Stdlib_Option.getOr(getIndexingAddressesByChain(state)[ChainId.toString(chainConfig.id)], []), ia => {
             if (ia.contractName === contract.name) {
               return Primitive_option.some(ia.address);
             }

package/src/UserContext.res

@@ -52,7 +52,7 @@ EffectContext.prototype = effectContextPrototype;
 @new
 external makeEffectContext: (
   contextParams,
-  ~chainId: option<int>,
+  ~chainId: option<ChainId.t>,
   ~effectName: string,
   ~defaultShouldCache: bool,
   ~callEffect: (Internal.effect, Internal.effectInput) => promise<Internal.effectOutput>,
@@ -318,7 +318,7 @@ let handlerTraps: Utils.Proxy.traps<contextParams> = {
     | "chain" =>
       let chainId = params.item->Internal.getItemChainId
       params.chains
-      ->Utils.Dict.dangerouslyGetByIntNonOption(chainId)
+      ->ChainId.Dict.dangerouslyGetNonOption(chainId)
       ->(Utils.magic: option<Internal.chainInfo> => unknown)
     | _ =>
       switch params.config.userEntitiesByName->Utils.Dict.dangerouslyGetNonOption(prop) {

package/src/UserContext.res.mjs

@@ -12,6 +12,7 @@ import * as InMemoryStore from "./InMemoryStore.res.mjs";
 import * as InMemoryTable from "./InMemoryTable.res.mjs";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
+import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
 import * as S$RescriptSchema from "rescript-schema/src/S.res.mjs";
 
 let paramsByThis = new WeakMap();
@@ -54,7 +55,7 @@ function initEffect(params) {
       Stdlib_JsError.throwWithMessage(`The cross-chain effect "` + caller.name + `" cannot call the chain-scoped effect "` + effect.name + `", because a cross-chain effect isn't tied to a single chain. Make "` + effect.name + `" cross-chain (\`crossChain: true\`), or make "` + caller.name + `" chain-scoped (\`crossChain: false\`).`);
     }
     let tmp;
-    tmp = scope === "crossChain" ? undefined : scope;
+    tmp = scope === "crossChain" ? undefined : Primitive_option.some(scope);
     let effectContext = new EffectContext(params, tmp, effect.name, effect.defaultShouldCache, makeCaller(effect));
     let effectArgs_cacheKey = Utils.Hash.makeOrThrow(S$RescriptSchema.reverseConvertOrThrow(input, effect.input));
     let effectArgs_checkpointId = params.checkpointId;

package/src/Utils.res

@@ -218,10 +218,6 @@ module Dict = {
 
   @set_index
   external setByInt: (dict<'a>, int, 'a) => unit = ""
-
-  let incrementByInt: (dict<int>, int) => unit = %raw(`(dict, key) => {
-    dict[key]++
-  }`)
 }
 
 module Math = {

package/src/Utils.res.mjs

@@ -161,10 +161,6 @@ let updateImmutable = ((dict, key, value) => ({...dict, [key]: value}));
 
 let shallowCopy = ((dict) => ({...dict}));
 
-let incrementByInt = ((dict, key) => {
-    dict[key]++
-  });
-
 let Dict = {
   $$delete: Stdlib_Dict.$$delete,
   getOrInsertEmptyDict: getOrInsertEmptyDict,
@@ -181,8 +177,7 @@ let Dict = {
   deleteInPlace: deleteInPlace,
   unsafeDeleteUndefinedFieldsInPlace: unsafeDeleteUndefinedFieldsInPlace,
   updateImmutable: updateImmutable,
-  shallowCopy: shallowCopy,
-  incrementByInt: incrementByInt
+  shallowCopy: shallowCopy
 };
 
 function minOptInt(a, b) {

package/src/bindings/ClickHouse.res

@@ -44,9 +44,15 @@ let getClickHouseFieldType = (
   ~fieldType: Table.fieldType,
   ~isNullable: bool,
   ~isArray: bool,
+  ~chainIdMode: ChainId.mode=Int32,
 ): string => {
   let baseType = switch fieldType {
   | Int32 => "Int32"
+  | ChainId =>
+    switch chainIdMode {
+    | Int32 => "Int32"
+    | Int64 => "UInt64"
+    }
   | Uint32 => "UInt32"
   | UInt52 => "UInt64"
   | UInt64 => "UInt64"
@@ -123,6 +129,7 @@ let makeClickHouseEntitySchema = (table: Table.table): S.t<Internal.entity> => {
                 dateSchema
               }
             }
+          | ChainId => ChainId.schema->S.toUnknown
           // ClickHouse returns UInt64 values as strings, need to parse to float
           | UInt52 => {
               let uint52Schema =
@@ -337,6 +344,7 @@ let makeCreateHistoryTableQuery = (
   ~database: string,
   ~replicated: bool=false,
   ~onCluster: bool=false,
+  ~chainIdMode: ChainId.mode=Int32,
 ) => {
   let tableEngine = replicated ? "ReplicatedMergeTree" : "MergeTree()"
   let fieldDefinitions = entityConfig.table.fields->Array.filterMap(field => {
@@ -348,6 +356,7 @@ let makeCreateHistoryTableQuery = (
           ~fieldType=field.fieldType,
           ~isNullable=field.isNullable,
           ~isArray=field.isArray,
+          ~chainIdMode,
         )
         `\`${fieldName}\` ${clickHouseType}`
       })
@@ -446,6 +455,7 @@ let makeCreateCheckpointsTableQuery = (
   ~database: string,
   ~replicated: bool=false,
   ~onCluster: bool=false,
+  ~chainIdMode: ChainId.mode=Int32,
 ) => {
   let tableEngine = replicated ? "ReplicatedMergeTree" : "MergeTree()"
   let idField = (#id: InternalTable.Checkpoints.field :> string)
@@ -459,9 +469,10 @@ let makeCreateCheckpointsTableQuery = (
     )} (
   \`${idField}\` ${getClickHouseFieldType(~fieldType=UInt64, ~isNullable=false, ~isArray=false)},
   \`${chainIdField}\` ${getClickHouseFieldType(
-      ~fieldType=Int32,
+      ~fieldType=ChainId,
       ~isNullable=false,
       ~isArray=false,
+      ~chainIdMode,
     )},
   \`${blockNumberField}\` ${getClickHouseFieldType(
       ~fieldType=Int32,
@@ -528,6 +539,7 @@ let initialize = async (
   ~database: string,
   ~entities: array<Internal.entityConfig>,
   ~enums as _: array<Table.enumConfig<Table.enum>>,
+  ~chainIdMode: ChainId.mode=Int32,
 ) => {
   try {
     let databaseEngine = Env.ClickHouse.databaseEngine()
@@ -600,12 +612,18 @@ let initialize = async (
             ~database,
             ~replicated,
             ~onCluster=ddlOnCluster,
+            ~chainIdMode,
           ),
         })
       ),
     )->Utils.Promise.ignoreValue
     await client->exec({
-      query: makeCreateCheckpointsTableQuery(~database, ~replicated, ~onCluster=ddlOnCluster),
+      query: makeCreateCheckpointsTableQuery(
+        ~database,
+        ~replicated,
+        ~onCluster=ddlOnCluster,
+        ~chainIdMode,
+      ),
     })
 
     // The client pools HTTP connections, so consecutive statements may reach

package/src/bindings/ClickHouse.res.mjs

@@ -3,6 +3,7 @@
 import * as Env from "../Env.res.mjs";
 import * as Table from "../db/Table.res.mjs";
 import * as Utils from "../Utils.res.mjs";
+import * as ChainId from "../ChainId.res.mjs";
 import * as Logging from "../Logging.res.mjs";
 import * as Persistence from "../Persistence.res.mjs";
 import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
@@ -13,7 +14,8 @@ import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js
 import * as S$RescriptSchema from "rescript-schema/src/S.res.mjs";
 import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
 
-function getClickHouseFieldType(fieldType, isNullable, isArray) {
+function getClickHouseFieldType(fieldType, isNullable, isArray, chainIdModeOpt) {
+  let chainIdMode = chainIdModeOpt !== undefined ? chainIdModeOpt : "int32";
   let baseType;
   if (typeof fieldType !== "object") {
     switch (fieldType) {
@@ -27,6 +29,9 @@ function getClickHouseFieldType(fieldType, isNullable, isArray) {
       case "UInt64" :
         baseType = "UInt64";
         break;
+      case "ChainId" :
+        baseType = chainIdMode === "int32" ? "Int32" : "UInt64";
+        break;
       case "Number" :
         baseType = "Float64";
         break;
@@ -99,6 +104,9 @@ function makeClickHouseEntitySchema(table) {
                 f.isArray ? S$RescriptSchema.array(uint52Schema) : uint52Schema
               );
             break;
+          case "ChainId" :
+            fieldSchema = ChainId.schema;
+            break;
           case "Date" :
             let dateSchema = Utils.Schema.clickHouseDate;
             fieldSchema = f.isNullable ? S$RescriptSchema.$$null(dateSchema) : (
@@ -244,9 +252,10 @@ function databaseEngineName(engineSpec) {
   return engineSpec.trim().split("(")[0].split(" ")[0].trim();
 }
 
-function makeCreateHistoryTableQuery(entityConfig, database, replicatedOpt, onClusterOpt) {
+function makeCreateHistoryTableQuery(entityConfig, database, replicatedOpt, onClusterOpt, chainIdModeOpt) {
   let replicated = replicatedOpt !== undefined ? replicatedOpt : false;
   let onCluster = onClusterOpt !== undefined ? onClusterOpt : false;
+  let chainIdMode = chainIdModeOpt !== undefined ? chainIdModeOpt : "int32";
   let tableEngine = replicated ? "ReplicatedMergeTree" : "MergeTree()";
   let fieldDefinitions = Stdlib_Array.filterMap(entityConfig.table.fields, field => {
     if (field.TAG !== "Field") {
@@ -254,7 +263,7 @@ function makeCreateHistoryTableQuery(entityConfig, database, replicatedOpt, onCl
     }
     let field$1 = field._0;
     let fieldName = Table.getClickHouseDbFieldName(field$1);
-    let clickHouseType = getClickHouseFieldType(field$1.fieldType, field$1.isNullable, field$1.isArray);
+    let clickHouseType = getClickHouseFieldType(field$1.fieldType, field$1.isNullable, field$1.isArray, chainIdMode);
     return `\`` + fieldName + `\` ` + clickHouseType;
   });
   let options = entityConfig.storage.clickhouseOptions;
@@ -306,28 +315,29 @@ function makeCreateHistoryTableQuery(entityConfig, database, replicatedOpt, onCl
     onCluster ? ` ON CLUSTER '{cluster}'` : ""
   ) + ` (
   ` + fieldDefinitions.join(",\n  ") + `,
-  \`` + EntityHistory.checkpointIdFieldName + `\` ` + getClickHouseFieldType("UInt64", false, false) + `,
+  \`` + EntityHistory.checkpointIdFieldName + `\` ` + getClickHouseFieldType("UInt64", false, false, undefined) + `,
   \`` + EntityHistory.changeFieldName + `\` ` + getClickHouseFieldType({
     type: "Enum",
     config: EntityHistory.RowAction.config
-  }, false, false) + `
+  }, false, false, undefined) + `
 )
 ENGINE = ` + tableEngine + partitionByClause + `
 ORDER BY (` + orderByColumns + `)` + ttlClause;
 }
 
-function makeCreateCheckpointsTableQuery(database, replicatedOpt, onClusterOpt) {
+function makeCreateCheckpointsTableQuery(database, replicatedOpt, onClusterOpt, chainIdModeOpt) {
   let replicated = replicatedOpt !== undefined ? replicatedOpt : false;
   let onCluster = onClusterOpt !== undefined ? onClusterOpt : false;
+  let chainIdMode = chainIdModeOpt !== undefined ? chainIdModeOpt : "int32";
   let tableEngine = replicated ? "ReplicatedMergeTree" : "MergeTree()";
   return `CREATE TABLE IF NOT EXISTS ` + database + `.\`` + InternalTable.Checkpoints.table.tableName + `\`` + (
     onCluster ? ` ON CLUSTER '{cluster}'` : ""
   ) + ` (
-  \`` + "id" + `\` ` + getClickHouseFieldType("UInt64", false, false) + `,
-  \`` + "chain_id" + `\` ` + getClickHouseFieldType("Int32", false, false) + `,
-  \`` + "block_number" + `\` ` + getClickHouseFieldType("Int32", false, false) + `,
-  \`` + "block_hash" + `\` ` + getClickHouseFieldType("String", true, false) + `,
-  \`` + "events_processed" + `\` ` + getClickHouseFieldType("UInt64", false, false) + `
+  \`` + "id" + `\` ` + getClickHouseFieldType("UInt64", false, false, undefined) + `,
+  \`` + "chain_id" + `\` ` + getClickHouseFieldType("ChainId", false, false, chainIdMode) + `,
+  \`` + "block_number" + `\` ` + getClickHouseFieldType("Int32", false, false, undefined) + `,
+  \`` + "block_hash" + `\` ` + getClickHouseFieldType("String", true, false, undefined) + `,
+  \`` + "events_processed" + `\` ` + getClickHouseFieldType("UInt64", false, false, undefined) + `
 )
 ENGINE = ` + tableEngine + `
 ORDER BY (` + "id" + `)`;
@@ -358,7 +368,8 @@ FROM (
 WHERE \`` + EntityHistory.changeFieldName + `\` = '` + "SET" + `'`;
 }
 
-async function initialize(client, database, entities, param) {
+async function initialize(client, database, entities, param, chainIdModeOpt) {
+  let chainIdMode = chainIdModeOpt !== undefined ? chainIdModeOpt : "int32";
   try {
     let databaseEngine = Env.ClickHouse.databaseEngine();
     let databaseEngineClause = databaseEngine !== undefined ? ` ENGINE = ` + databaseEngine : "";
@@ -399,10 +410,10 @@ async function initialize(client, database, entities, param) {
       query: `CREATE DATABASE IF NOT EXISTS ` + database + databaseOnClusterClause + databaseEngineClause
     });
     await Promise.all(entities.map(entityConfig => client.exec({
-      query: makeCreateHistoryTableQuery(entityConfig, database, replicated, ddlOnCluster)
+      query: makeCreateHistoryTableQuery(entityConfig, database, replicated, ddlOnCluster, chainIdMode)
     })));
     await client.exec({
-      query: makeCreateCheckpointsTableQuery(database, replicated, ddlOnCluster)
+      query: makeCreateCheckpointsTableQuery(database, replicated, ddlOnCluster, chainIdMode)
     });
     if (hasReplicatedDatabaseEngine) {
       await client.exec({

package/src/db/EntityFilter.res

@@ -176,10 +176,6 @@ let parseGetWhereOrThrow = (filter: dict<dict<unknown>>, ~entityName, ~table: Ta
       JsError.throwWithMessage(
         `The field "${apiFieldName}" on entity "${entityName}" is a derived field and cannot be used in getWhere(). Use the source entity's indexed field instead.`,
       )
-    | Some(Field({isPrimaryKey: false, isIndex: false, linkedEntity: None})) =>
-      JsError.throwWithMessage(
-        `The field "${apiFieldName}" on entity "${entityName}" does not have an index. To use it in getWhere(), add the @index directive in your schema.graphql:\n\n  ${apiFieldName}: ... @index\n\nThen run 'pnpm envio codegen' to regenerate.`,
-      )
     | Some(Field(_)) => ()
     }
 

package/src/db/EntityFilter.res.mjs

@@ -142,14 +142,7 @@ function parseGetWhereOrThrow(filter, entityName, table) {
     });
     let match = Table.getFieldByApiName(table, apiFieldName);
     if (match !== undefined) {
-      if (match.TAG === "Field") {
-        let match$1 = match._0;
-        if (match$1.isPrimaryKey || match$1.isIndex || match$1.linkedEntity !== undefined) {
-          
-        } else {
-          Stdlib_JsError.throwWithMessage(`The field "` + apiFieldName + `" on entity "` + entityName + `" does not have an index. To use it in getWhere(), add the @index directive in your schema.graphql:\n\n  ` + apiFieldName + `: ... @index\n\nThen run 'pnpm envio codegen' to regenerate.`);
-        }
-      } else {
+      if (match.TAG !== "Field") {
         Stdlib_JsError.throwWithMessage(`The field "` + apiFieldName + `" on entity "` + entityName + `" is a derived field and cannot be used in getWhere(). Use the source entity's indexed field instead.`);
       }
     } else {

package/src/db/EntityHistory.res

@@ -64,7 +64,7 @@ let historyTableName = (~entityName, ~entityIndex) => {
 }
 
 type safeReorgBlocks = {
-  chainIds: array<int>,
+  chainIds: array<ChainId.t>,
   blockNumbers: array<int>,
 }
 

package/src/db/IndexCatalog.res

@@ -0,0 +1,248 @@
+// What PostgreSQL actually holds, read straight from pg_catalog and classified
+// against what the indexer wanted. Postgres stays authoritative: nothing is
+// counted as present until it has been read back from here.
+
+type row = {
+  tableName: string,
+  indexName: string,
+  method: string,
+  // 1/0 rather than bools: postgres.js hands booleans back inconsistently
+  // depending on the driver's type resolution, so the query casts them.
+  isValid: int,
+  isUnique: int,
+  // An index with a WHERE clause only covers rows inside its predicate, so it
+  // can't stand in for the unrestricted index a filter needs.
+  isPartial: int,
+  isExpression: int,
+  // The predicate itself, for the error a partial index under our name earns.
+  predicate: option<string>,
+  columns: array<string>,
+  // "ASC"/"DESC" per column, in the same order as `columns`.
+  directions: array<string>,
+}
+
+let rowsSchema = S.array(
+  S.object((s): row => {
+    tableName: s.field("tableName", S.string),
+    indexName: s.field("indexName", S.string),
+    method: s.field("method", S.string),
+    isValid: s.field("isValid", S.int),
+    isUnique: s.field("isUnique", S.int),
+    isPartial: s.field("isPartial", S.int),
+    isExpression: s.field("isExpression", S.int),
+    predicate: s.field("predicate", S.null(S.string)),
+    columns: s.field("columns", S.array(S.string)),
+    directions: s.field("directions", S.array(S.string)),
+  }),
+)
+
+// One row per index, with its key columns aggregated in ordinal order.
+// INCLUDE columns are excluded (they don't affect what the index can serve),
+// and expression columns come back as their printed definition so an
+// expression index can never be mistaken for a plain-column one.
+//
+// Both interpolated values are identifiers, not user input: `pgSchema` comes
+// from the operator's own environment, and `indexName` is always a generated
+// name — a codegen-validated `[A-Za-z_][A-Za-z0-9_]*` prefix plus a base36
+// hash, so neither can carry a quote.
+let makeQuery = (~pgSchema, ~indexName=?) =>
+  `SELECT
+  t.relname AS "tableName",
+  i.relname AS "indexName",
+  am.amname AS "method",
+  CASE WHEN ix.indisvalid AND ix.indisready THEN 1 ELSE 0 END AS "isValid",
+  CASE WHEN ix.indisunique THEN 1 ELSE 0 END AS "isUnique",
+  CASE WHEN ix.indpred IS NOT NULL THEN 1 ELSE 0 END AS "isPartial",
+  CASE WHEN ix.indexprs IS NOT NULL THEN 1 ELSE 0 END AS "isExpression",
+  pg_get_expr(ix.indpred, ix.indrelid, true) AS "predicate",
+  array_agg(
+    CASE WHEN k.attnum = 0
+      THEN pg_get_indexdef(ix.indexrelid, k.ord::int, true)
+      ELSE a.attname
+    END ORDER BY k.ord
+  ) AS "columns",
+  array_agg(
+    CASE WHEN (ix.indoption[k.ord - 1] & 1) = 1 THEN 'DESC' ELSE 'ASC' END ORDER BY k.ord
+  ) AS "directions"
+FROM pg_index ix
+JOIN pg_class i ON i.oid = ix.indexrelid
+JOIN pg_class t ON t.oid = ix.indrelid
+JOIN pg_namespace n ON n.oid = t.relnamespace
+JOIN pg_am am ON am.oid = i.relam
+JOIN LATERAL unnest(ix.indkey) WITH ORDINALITY AS k(attnum, ord) ON k.ord <= ix.indnkeyatts
+LEFT JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = k.attnum
+WHERE n.nspname = '${pgSchema}'${switch indexName {
+    | Some(indexName) => ` AND i.relname = '${indexName}'`
+    | None => ""
+    }}
+GROUP BY t.relname, i.relname, am.amname, ix.indisvalid, ix.indisready,
+         ix.indisunique, ix.indpred, ix.indrelid, (ix.indexprs IS NOT NULL);`
+
+type entry = {
+  name: string,
+  tableName: string,
+  method: string,
+  columns: array<IndexDefinition.column>,
+  isValid: bool,
+  isUnique: bool,
+  isPartial: bool,
+  isExpression: bool,
+  predicate: option<string>,
+}
+
+let fromRow = (row: row): entry => {
+  name: row.indexName,
+  tableName: row.tableName,
+  method: row.method,
+  columns: row.columns->Array.mapWithIndex((name, idx) => {
+    IndexDefinition.name,
+    direction: switch row.directions->Array.get(idx) {
+    | Some("DESC") => Table.Desc
+    | _ => Asc
+    },
+  }),
+  isValid: row.isValid === 1,
+  isUnique: row.isUnique === 1,
+  isPartial: row.isPartial === 1,
+  isExpression: row.isExpression === 1,
+  predicate: row.predicate,
+}
+
+// A btree's key columns are ordered, so an index leading with the requested
+// columns can serve them. The reverse isn't true, which is why order matters.
+let leadsWith = (entry, definition: IndexDefinition.t) =>
+  definition.columns->Array.length <= entry.columns->Array.length &&
+    definition.columns->Array.everyWithIndex((column, idx) =>
+      switch entry.columns->Array.get(idx) {
+      | Some(actual) => actual.name === column.name && actual.direction === column.direction
+      | None => false
+      }
+    )
+
+// How much of an existing index has to line up before it counts as coverage.
+//
+// A schema-declared `@index` is a promise about the physical schema, so it is
+// matched `Exact`: whether some composite index happens to exist must not
+// change what a fresh database ends up with, or two indexers on the same
+// schema would hold different tables.
+//
+// An automatic getWhere index is an optimization nobody declared, so
+// `LeadingColumns` is enough — an existing composite that already starts with
+// the column serves the query, and building a second one would only cost write
+// amplification.
+type coverage = Exact | LeadingColumns
+
+let coverageKey = coverage =>
+  switch coverage {
+  | Exact => "="
+  | LeadingColumns => "^"
+  }
+
+// Why an index can't serve a request, in the order the checks are worth
+// reporting. `None` means it can.
+let rejectReason = (entry, definition: IndexDefinition.t, ~coverage) =>
+  if entry.tableName !== definition.tableName {
+    Some(`it is on table "${entry.tableName}"`)
+  } else if !entry.isValid {
+    Some("PostgreSQL reports it as invalid or not ready")
+  } else if entry.isPartial {
+    Some(
+      `it is partial (WHERE ${entry.predicate->Option.getOr(
+          "...",
+        )}), so it only covers part of the table`,
+    )
+  } else if entry.isExpression {
+    Some("it indexes an expression rather than plain columns")
+  } else if entry.method !== definition.method {
+    Some(`it uses the ${entry.method} access method, not ${definition.method}`)
+  } else if !(entry->leadsWith(definition)) {
+    Some(
+      `it covers (${entry.columns
+        ->Array.map(IndexDefinition.columnKey)
+        ->Array.joinUnsafe(", ")}) instead of leading with the requested columns`,
+    )
+  } else if coverage === Exact && entry.columns->Array.length !== definition.columns->Array.length {
+    Some(
+      `it covers (${entry.columns
+        ->Array.map(IndexDefinition.columnKey)
+        ->Array.joinUnsafe(", ")}) rather than exactly the declared columns`,
+    )
+  } else {
+    None
+  }
+
+let satisfies = (entry, definition, ~coverage) =>
+  entry->rejectReason(definition, ~coverage)->Option.isNone
+
+// The index is byte-for-byte what `definition` asks for, valid or not. Used to
+// decide ownership, where even an exact-coverage match would be too loose: a
+// unique index covering the same columns still isn't one the indexer created.
+let isExactly = (entry, definition: IndexDefinition.t) =>
+  entry.tableName === definition.tableName &&
+  entry.method === definition.method &&
+  !entry.isUnique &&
+  !entry.isPartial &&
+  !entry.isExpression &&
+  entry.columns->Array.length === definition.columns->Array.length &&
+  entry->leadsWith(definition)
+
+type t = {
+  byName: dict<entry>,
+  // `find` answers "is this index already covered?", which runs per filtered
+  // column on every batched getWhere load. Scanning every index in the schema
+  // there would make a hot path grow with the size of the schema, so the
+  // answer is memoized by identity and thrown away whenever the catalog moves
+  // — which only happens when an index is built, resynced or reloaded.
+  mutable covering: dict<string>,
+}
+
+let make = () => {byName: Dict.make(), covering: Dict.make()}
+
+let set = (catalog, entry) => {
+  catalog.byName->Dict.set(entry.name, entry)
+  catalog.covering = Dict.make()
+}
+
+let remove = (catalog, name) => {
+  catalog.byName->Utils.Dict.deleteInPlace(name)
+  catalog.covering = Dict.make()
+}
+
+let fromRows = (~rows) => {
+  let catalog = make()
+  rows->Array.forEach(row => catalog->set(row->fromRow))
+  catalog
+}
+
+let getByName = (catalog, name) => catalog.byName->Utils.Dict.dangerouslyGetNonOption(name)
+
+let entries = catalog => catalog.byName->Dict.valuesToArray
+
+let size = catalog => catalog.byName->Dict.keysToArray->Array.length
+
+// Postgres has no zero-length identifier, so this can't collide with a name.
+let nothingCovers = ""
+
+let find = (catalog, definition, ~coverage) => {
+  let cacheKey = `${coverage->coverageKey}${definition->IndexDefinition.key}`
+  switch catalog.covering->Utils.Dict.dangerouslyGetNonOption(cacheKey) {
+  | Some(name) if name === nothingCovers => None
+  | Some(name) => catalog.byName->Utils.Dict.dangerouslyGetNonOption(name)
+  | None =>
+    let found = catalog->entries->Array.find(entry => entry->satisfies(definition, ~coverage))
+    catalog.covering->Dict.set(
+      cacheKey,
+      switch found {
+      | Some(entry) => entry.name
+      | None => nothingCovers
+      },
+    )
+    found
+  }
+}
+
+let invalidNames = catalog =>
+  catalog
+  ->entries
+  ->Array.filterMap(entry => entry.isValid ? None : Some(entry.name))
+  ->Array.toSorted(String.compare)