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

package/src/PgStorage.res

@@ -20,105 +20,6 @@ let makeClient = () => {
   )
 }
 
-let makeCreateIndexQuery = (~tableName, ~indexFields, ~pgSchema) => {
-  let indexName = tableName ++ "_" ++ indexFields->Array.joinUnsafe("_")
-
-  // Case for indexer before envio@2.28
-  let index = indexFields->Array.map(idx => `"${idx}"`)->Array.joinUnsafe(", ")
-  `CREATE INDEX IF NOT EXISTS "${indexName}" ON "${pgSchema}"."${tableName}"(${index});`
-}
-
-let directionToSql = (direction: Table.indexFieldDirection) =>
-  switch direction {
-  | Asc => ""
-  | Desc => " DESC"
-  }
-
-let directionToIndexName = (direction: Table.indexFieldDirection) =>
-  switch direction {
-  | Asc => ""
-  | Desc => "_desc"
-  }
-
-let makeCreateCompositeIndexQuery = (
-  ~tableName,
-  ~indexFields: array<Table.compositeIndexField>,
-  ~pgSchema,
-) => {
-  let indexName =
-    tableName ++
-    "_" ++
-    indexFields
-    ->Array.map(f => f.fieldName ++ directionToIndexName(f.direction))
-    ->Array.joinUnsafe("_")
-  let index =
-    indexFields
-    ->Array.map(f => `"${f.fieldName}"${directionToSql(f.direction)}`)
-    ->Array.joinUnsafe(", ")
-  `CREATE INDEX IF NOT EXISTS "${indexName}" ON "${pgSchema}"."${tableName}"(${index});`
-}
-
-let makeCreateTableIndexesQuery = (table: Table.table, ~pgSchema) => {
-  let tableName = table.tableName
-  let createIndex = indexField =>
-    makeCreateIndexQuery(~tableName, ~indexFields=[indexField], ~pgSchema)
-  let createCompositeIndex = indexFields => {
-    makeCreateCompositeIndexQuery(~tableName, ~indexFields, ~pgSchema)
-  }
-
-  let singleIndexes = table->Table.getSingleIndexes
-  let compositeIndexes = table->Table.getCompositeIndexes
-
-  singleIndexes->Array.map(createIndex)->Array.joinUnsafe("\n") ++
-    compositeIndexes->Array.map(createCompositeIndex)->Array.joinUnsafe("\n")
-}
-
-// One index the schema promises: an `@index` field, a composite index, or the
-// index backing a derived relationship. Carries enough to derive its name, its
-// DDL and its registry key, so the deferred creation at the end of backfill and
-// the registry stay described by the same value.
-type schemaIndex = {
-  tableName: string,
-  indexFields: array<Table.compositeIndexField>,
-}
-
-// `<Entity>_<column>` for a single column, with each further column appended in
-// order (and `_desc` where it applies). The full description, before Postgres'
-// identifier limit is applied — `validateIndexNamesOrThrow` compares these, so
-// it can tell two descriptions apart after they truncate to the same name.
-let schemaIndexDescription = ({tableName, indexFields}: schemaIndex) =>
-  tableName ++
-  "_" ++
-  indexFields
-  ->Array.map(f => f.fieldName ++ directionToIndexName(f.direction))
-  ->Array.joinUnsafe("_")
-
-// The identifier Postgres actually stores. Automatic and schema-defined indexes
-// share it, so both are named the same way and both stay reachable through
-// `CREATE INDEX IF NOT EXISTS`.
-let schemaIndexName = schemaIndex =>
-  schemaIndex->schemaIndexDescription->IndexRegistry.truncateIndexName
-
-let schemaIndexKey = ({tableName, indexFields}: schemaIndex) =>
-  IndexRegistry.makeKey(
-    ~tableName,
-    ~columns=indexFields->IndexRegistry.fromIndexFields,
-    ~method=IndexRegistry.btree,
-  )
-
-// Plain DDL, not CONCURRENTLY: it builds from a single table scan instead of
-// two, and the SHARE lock it takes blocks writes but not reads, so queries keep
-// being served while it runs. The indexer is the only writer, and both callers
-// are happy to wait on it.
-let makeCreateSchemaIndexQuery = (schemaIndex, ~pgSchema) => {
-  let {tableName, indexFields} = schemaIndex
-  let columns =
-    indexFields
-    ->Array.map(f => `"${f.fieldName}"${directionToSql(f.direction)}`)
-    ->Array.joinUnsafe(", ")
-  `CREATE INDEX IF NOT EXISTS "${schemaIndex->schemaIndexName}" ON "${pgSchema}"."${tableName}"(${columns});`
-}
-
 let formatSeconds = (timeRef: Performance.timeRef) =>
   (Math.round(timeRef->Performance.secondsSince *. 100.) /. 100.)->Float.toString
 
@@ -127,35 +28,15 @@ let formatSeconds = (timeRef: Performance.timeRef) =>
 // stalled-looking indexer is explainable from the logs alone.
 let slowOnLargeDatabaseNotice = "This can take a long time on a large database."
 
-// An index Postgres reports as INVALID still owns its name, so
-// `CREATE INDEX IF NOT EXISTS` would quietly skip it and leave the query
-// unserved. REINDEX rebuilds it from its own stored definition — a repair, not
-// a replacement — which is right only when that definition is the one we
-// wanted. Runs inside a transaction, unlike REINDEX CONCURRENTLY.
-let makeReindexQuery = (~pgSchema, ~indexName) => `REINDEX INDEX "${pgSchema}"."${indexName}";`
-
-// A name taken by an invalid index the indexer didn't create isn't ours to
-// touch: rebuilding it reuses its own definition, so it would come back valid
-// but still not serve the query, and dropping it could take out a unique
-// constraint someone else relies on.
-let nameCollisionError = (~indexName, ~pgSchema) =>
-  Utils.Error.make(
-    `Cannot create the index "${indexName}" in schema "${pgSchema}". An index of that name already exists and PostgreSQL reports it as invalid, but it isn't one the indexer created — it covers different columns, or it is a unique or partial index — so it is left untouched. Drop or repair it by hand, then restart the indexer.`,
-  )
-
-let makeSingleColumnSchemaIndex = (~tableName, ~column): schemaIndex => {
-  tableName,
-  indexFields: [{fieldName: column, direction: Table.Asc}],
-}
-
-// Every index the entity schema promises. Deferred past the initial DDL and
+// Every index the entity schema promises: an `@index` field, a composite index,
+// or the index backing a derived relationship. Deferred past the initial DDL and
 // created in one transaction once backfill completes, so a resumed indexer that
 // reports itself ready always has all of them.
 //
 // `entities` is the Postgres-backed set, and every `@derivedFrom` target within
 // it resolves: config parsing rejects a Postgres entity deriving from one that
 // isn't in Postgres (`validate_relationship_storage`).
-let getSchemaIndexes = (~entities: array<Internal.entityConfig>): array<schemaIndex> => {
+let getSchemaIndexes = (~entities: array<Internal.entityConfig>): array<IndexDefinition.t> => {
   let derivedSchema = Schema.make(entities->Array.map(e => e.table))
   let all = []
 
@@ -163,12 +44,14 @@ let getSchemaIndexes = (~entities: array<Internal.entityConfig>): array<schemaIn
     table
     ->Table.getSingleIndexes
     ->Array.forEach(column =>
-      all->Array.push(makeSingleColumnSchemaIndex(~tableName=table.tableName, ~column))->ignore
+      all->Array.push(IndexDefinition.single(~tableName=table.tableName, ~column))->ignore
     )
     table
     ->Table.getCompositeIndexes
     ->Array.forEach(indexFields =>
-      all->Array.push({tableName: table.tableName, indexFields})->ignore
+      all
+      ->Array.push(IndexDefinition.fromIndexFields(~tableName=table.tableName, ~indexFields))
+      ->ignore
     )
   })
 
@@ -179,9 +62,7 @@ let getSchemaIndexes = (~entities: array<Internal.entityConfig>): array<schemaIn
       let column =
         derivedSchema->Schema.getDerivedFromPgFieldName(derivedFromField)->Utils.unwrapResultExn
       all
-      ->Array.push(
-        makeSingleColumnSchemaIndex(~tableName=derivedFromField.derivedFromEntity, ~column),
-      )
+      ->Array.push(IndexDefinition.single(~tableName=derivedFromField.derivedFromEntity, ~column))
       ->ignore
     })
   )
@@ -189,8 +70,8 @@ let getSchemaIndexes = (~entities: array<Internal.entityConfig>): array<schemaIn
   // An `@index` field and a derived relationship pointing at it describe the
   // same index, so the list is deduped on identity rather than on name.
   let seen = Utils.Set.make()
-  all->Array.filter(schemaIndex => {
-    let key = schemaIndex->schemaIndexKey
+  all->Array.filter(definition => {
+    let key = definition->IndexDefinition.key
     if seen->Utils.Set.has(key) {
       false
     } else {
@@ -200,7 +81,12 @@ let getSchemaIndexes = (~entities: array<Internal.entityConfig>): array<schemaIn
   })
 }
 
-let makeCreateTableQuery = (table: Table.table, ~pgSchema, ~isNumericArrayAsText) => {
+let makeCreateTableQuery = (
+  table: Table.table,
+  ~pgSchema,
+  ~isNumericArrayAsText,
+  ~chainIdMode: ChainId.mode=Int32,
+) => {
   let fieldsMapped =
     table
     ->Table.getFields
@@ -210,6 +96,7 @@ let makeCreateTableQuery = (table: Table.table, ~pgSchema, ~isNumericArrayAsText
 
       {
         `"${fieldName}" ${Table.getPgFieldType(
+            ~chainIdMode,
             ~fieldType,
             ~pgSchema,
             ~isArray,
@@ -314,6 +201,7 @@ let makeInitializeTransaction = (
   // initial DDL creates only tables, primary keys, views and chain rows; the
   // rest is created by `finalizeBackfill` before the indexer reports ready.
   ~deferSchemaIndexes=false,
+  ~chainIdMode: ChainId.mode=Int32,
 ) => {
   let generalTables = [
     InternalTable.Chains.table,
@@ -329,7 +217,6 @@ let makeInitializeTransaction = (
   })
 
   let schemaIndexes = getSchemaIndexes(~entities)
-  IndexRegistry.validateIndexNamesOrThrow(schemaIndexes->Array.map(schemaIndexDescription))
 
   let query = ref(
     (
@@ -360,13 +247,13 @@ GRANT ALL ON SCHEMA "${pgSchema}" TO public;`,
     query :=
       query.contents ++
       "\n" ++
-      makeCreateTableQuery(table, ~pgSchema, ~isNumericArrayAsText=isHasuraEnabled)
+      makeCreateTableQuery(table, ~pgSchema, ~isNumericArrayAsText=isHasuraEnabled, ~chainIdMode)
   })
 
   // Then batch all indexes (better performance when tables exist)
   if !deferSchemaIndexes {
-    schemaIndexes->Array.forEach(schemaIndex => {
-      query := query.contents ++ "\n" ++ makeCreateSchemaIndexQuery(schemaIndex, ~pgSchema)
+    schemaIndexes->Array.forEach(definition => {
+      query := query.contents ++ "\n" ++ definition->IndexDefinition.makeCreateQuery(~pgSchema)
     })
   }
 
@@ -478,9 +365,15 @@ let makeLoadAllQuery = (~pgSchema, ~tableName) => {
   `SELECT * FROM "${pgSchema}"."${tableName}";`
 }
 
-let makeInsertUnnestSetQuery = (~pgSchema, ~table: Table.table, ~itemSchema, ~isRawEvents) => {
+let makeInsertUnnestSetQuery = (
+  ~pgSchema,
+  ~table: Table.table,
+  ~itemSchema,
+  ~isRawEvents,
+  ~chainIdMode: ChainId.mode=Int32,
+) => {
   let {quotedFieldNames, quotedNonPrimaryFieldNames, arrayFieldTypes} =
-    table->Table.toSqlParams(~schema=itemSchema, ~pgSchema)
+    table->Table.toSqlParams(~schema=itemSchema, ~pgSchema, ~chainIdMode)
 
   let primaryKeyFieldNames = Table.getPgPrimaryKeyFieldNames(table)
 
@@ -508,9 +401,15 @@ SELECT * FROM unnest(${arrayFieldTypes
   } ++ ";"
 }
 
-let makeInsertValuesSetQuery = (~pgSchema, ~table: Table.table, ~itemSchema, ~itemsCount) => {
+let makeInsertValuesSetQuery = (
+  ~pgSchema,
+  ~table: Table.table,
+  ~itemSchema,
+  ~itemsCount,
+  ~chainIdMode: ChainId.mode=Int32,
+) => {
   let {quotedFieldNames, quotedNonPrimaryFieldNames} =
-    table->Table.toSqlParams(~schema=itemSchema, ~pgSchema)
+    table->Table.toSqlParams(~schema=itemSchema, ~pgSchema, ~chainIdMode)
 
   let primaryKeyFieldNames = Table.getPgPrimaryKeyFieldNames(table)
   let fieldsCount = quotedFieldNames->Array.length
@@ -553,8 +452,14 @@ VALUES${placeholders.contents}` ++
 // Constants for chunking
 let maxItemsPerQuery = 500
 
-let makeTableBatchSetQuery = (~pgSchema, ~table: Table.table, ~itemSchema: S.t<'item>) => {
-  let {dbSchema, hasArrayField} = table->Table.toSqlParams(~schema=itemSchema, ~pgSchema)
+let makeTableBatchSetQuery = (
+  ~pgSchema,
+  ~table: Table.table,
+  ~itemSchema: S.t<'item>,
+  ~chainIdMode: ChainId.mode=Int32,
+) => {
+  let {dbSchema, hasArrayField} =
+    table->Table.toSqlParams(~schema=itemSchema, ~pgSchema, ~chainIdMode)
 
   // Should move this to a better place
   // We need it for the isRawEvents check in makeTableBatchSet
@@ -578,7 +483,7 @@ let makeTableBatchSetQuery = (~pgSchema, ~table: Table.table, ~itemSchema: S.t<'
 
   if (isRawEvents || !hasArrayField) && !isHistoryUpdate {
     {
-      "query": makeInsertUnnestSetQuery(~pgSchema, ~table, ~itemSchema, ~isRawEvents),
+      "query": makeInsertUnnestSetQuery(~pgSchema, ~table, ~itemSchema, ~isRawEvents, ~chainIdMode),
       "convertOrThrow": S.compile(
         S.unnest(dbSchema),
         ~input=Value,
@@ -595,6 +500,7 @@ let makeTableBatchSetQuery = (~pgSchema, ~table: Table.table, ~itemSchema: S.t<'
         ~table,
         ~itemSchema,
         ~itemsCount=maxItemsPerQuery,
+        ~chainIdMode,
       ),
       "convertOrThrow": S.compile(
         S.unnest(itemSchema)->S.preprocess(_ => {
@@ -683,7 +589,14 @@ let classifyWriteError = (~specificError: ref<option<exn>>, ~table: Table.table,
 
 // WeakMap for caching table batch set queries
 let setQueryCache = Utils.WeakMap.make()
-let setOrThrow = async (sql, ~items, ~table: Table.table, ~itemSchema, ~pgSchema) => {
+let setOrThrow = async (
+  sql,
+  ~items,
+  ~table: Table.table,
+  ~itemSchema,
+  ~pgSchema,
+  ~chainIdMode: ChainId.mode=Int32,
+) => {
   if items->Array.length === 0 {
     ()
   } else {
@@ -695,6 +608,7 @@ let setOrThrow = async (sql, ~items, ~table: Table.table, ~itemSchema, ~pgSchema
           ~pgSchema,
           ~table,
           ~itemSchema=itemSchema->S.toUnknown,
+          ~chainIdMode,
         )
         setQueryCache->Utils.WeakMap.set(table, newQuery)->ignore
         newQuery
@@ -715,7 +629,13 @@ let setOrThrow = async (sql, ~items, ~table: Table.table, ~itemSchema, ~pgSchema
           let response = isFullChunk
             ? sql->Postgres.preparedUnsafe(data["query"], params)
             : sql->Postgres.unpreparedUnsafe(
-                makeInsertValuesSetQuery(~pgSchema, ~table, ~itemSchema, ~itemsCount=chunkSize),
+                makeInsertValuesSetQuery(
+                  ~pgSchema,
+                  ~table,
+                  ~itemSchema,
+                  ~itemsCount=chunkSize,
+                  ~chainIdMode,
+                ),
                 params,
               )
           responses->Array.push(response)->ignore
@@ -969,6 +889,7 @@ let rec writeBatch = async (
   ~escapeTables=?,
 ) => {
   try {
+    let chainIdMode = config.chainIdMode
     let shouldSaveHistory = config->Config.shouldSaveHistory(~isInReorgThreshold)
 
     let specificError = ref(None)
@@ -983,7 +904,7 @@ let rec writeBatch = async (
         | Internal.Event(_) =>
           let coordinate = `${item
             ->Internal.getItemChainId
-            ->Int.toString}-${item
+            ->ChainId.toString}-${item
             ->Internal.getItemBlockNumber
             ->Int.toString}-${item->Internal.getItemLogIndex->Int.toString}`
           if seenLogCoordinates->Utils.Set.has(coordinate) {
@@ -1013,6 +934,7 @@ let rec writeBatch = async (
             ~table=InternalTable.RawEvents.table,
             ~itemSchema=InternalTable.RawEvents.schema,
             ~pgSchema,
+            ~chainIdMode,
           )
         }, ~items=rawEvents)
       } catch {
@@ -1132,6 +1054,7 @@ let rec writeBatch = async (
                   ~itemSchema=entityHistory.setChangeSchema,
                   ~table=entityHistory.table,
                   ~pgSchema,
+                  ~chainIdMode,
                 ),
               )
               ->ignore
@@ -1148,6 +1071,7 @@ let rec writeBatch = async (
                 ~table=entityConfig.table,
                 ~itemSchema=entityConfig.schema,
                 ~pgSchema,
+                ~chainIdMode,
               ),
             )
           }
@@ -1179,14 +1103,19 @@ let rec writeBatch = async (
     | Some({targetCheckpointId: rollbackTargetCheckpointId}) =>
       Some(
         sql => {
-          let promises = allEntities->Array.map(entityConfig => {
-            sql->EntityHistory.rollback(
-              ~pgSchema,
-              ~entityName=entityConfig.name,
-              ~entityIndex=entityConfig.index,
-              ~rollbackTargetCheckpointId,
-            )
-          })
+          // Postgres owns history tables only for Postgres-backed entities;
+          // ClickHouse-only entities have none to roll back.
+          let promises =
+            allEntities
+            ->Array.filter(entityConfig => entityConfig.storage.postgres)
+            ->Array.map(entityConfig => {
+              sql->EntityHistory.rollback(
+                ~pgSchema,
+                ~entityName=entityConfig.name,
+                ~entityIndex=entityConfig.index,
+                ~rollbackTargetCheckpointId,
+              )
+            })
           promises
           ->Array.push(
             sql->InternalTable.Checkpoints.rollback(~pgSchema, ~rollbackTargetCheckpointId),
@@ -1243,6 +1172,7 @@ let rec writeBatch = async (
                 ~checkpointBlockNumbers=batch.checkpointBlockNumbers,
                 ~checkpointBlockHashes=batch.checkpointBlockHashes,
                 ~checkpointEventsProcessed=batch.checkpointEventsProcessed,
+                ~chainIdMode,
               )
             )
           }
@@ -1389,6 +1319,7 @@ let make = (
   ~pgDatabase,
   ~pgPassword,
   ~isHasuraEnabled,
+  ~chainIdMode: ChainId.mode=Int32,
   ~sink: option<Sink.t>=?,
   ~onInitialize=?,
   ~onNewTables=?,
@@ -1409,29 +1340,36 @@ let make = (
   // storage record's own name are all the same string.
   let storageName = "postgres"
 
-  let indexRegistry = IndexRegistry.make()
+  let indexManager = IndexManager.make()
 
-  // The only point where the catalog is consulted. Afterwards this process is
-  // the sole writer of the schema, so the registry is kept in sync by adding
-  // each index right after its DDL succeeds.
-  let reloadIndexRegistry = async () => {
-    let rows =
-      (await sql->Postgres.unsafe(IndexRegistry.makeCatalogQuery(~pgSchema)))->S.parseOrThrow(
-        IndexRegistry.catalogRowsSchema,
-      )
-    switch indexRegistry->IndexRegistry.reload(~rows) {
+  let loadCatalogRows = (sql, ~indexName=?) =>
+    sql
+    ->Postgres.unsafe(IndexCatalog.makeQuery(~pgSchema, ~indexName?))
+    ->Promise.thenResolve(rows => rows->S.parseOrThrow(IndexCatalog.rowsSchema))
+
+  // The whole-schema snapshot, taken on a clean initialize and on every resume.
+  // Individual indexes are re-read from the catalog as they are built, so this
+  // is the only point where the full listing is needed.
+  let refreshIndexCatalog = async () => {
+    let rows = await sql->loadCatalogRows
+    indexManager->IndexManager.reload(~rows)
+  }
+
+  let reloadIndexCatalog = async () => {
+    let catalog = await refreshIndexCatalog()
+    switch catalog->IndexCatalog.invalidNames {
     | [] => ()
     | invalidIndexNames =>
       Logging.warn({
         "storage": storageName,
-        "msg": `Ignoring invalid PostgreSQL indexes in schema "${pgSchema}". They are left untouched — drop and recreate them manually if you need them.`,
+        "msg": `Ignoring invalid PostgreSQL indexes in schema "${pgSchema}". They can't serve queries, so the indexer builds its own alongside them.`,
         "indexes": invalidIndexNames,
       })
     }
     Logging.info({
       "storage": storageName,
-      "msg": `Found ${indexRegistry
-        ->IndexRegistry.size
+      "msg": `Found ${catalog
+        ->IndexCatalog.size
         ->Int.toString} existing indexes in the indexer schema.`,
     })
   }
@@ -1628,6 +1566,7 @@ let make = (
       ~isEmptyPgSchema=schemaTableNames->Utils.Array.isEmpty,
       ~isHasuraEnabled,
       ~deferSchemaIndexes=true,
+      ~chainIdMode,
     )
     // Execute all queries within a single transaction for integrity.
     // The envio_info row is written in the same transaction so a successful
@@ -1655,16 +1594,24 @@ let make = (
       })
     })
     if ids->Array.length > 0 {
+      let addrChainIdArrayType = Table.getPgFieldType(
+        ~fieldType=ChainId,
+        ~pgSchema,
+        ~isArray=true,
+        ~isNumericArrayAsText=false,
+        ~isNullable=false,
+        ~chainIdMode,
+      )
       await sql->Postgres.unpreparedUnsafe(
         `INSERT INTO "${pgSchema}"."${Config.EnvioAddresses.table.tableName}" ("id", "chain_id", "registration_block", "registration_log_index", "contract_name")
-SELECT id, chain_id, -1, -1, contract_name FROM unnest($1::text[],$2::int[],$3::text[]) AS t(id, chain_id, contract_name);`,
+SELECT id, chain_id, -1, -1, contract_name FROM unnest($1::text[],$2::${addrChainIdArrayType},$3::text[]) AS t(id, chain_id, contract_name);`,
         (ids, addrChainIds, addrContractNames)->(Utils.magic: _ => unknown),
       )
     }
 
     let cache = await restoreEffectCache(~withUpload=true)
 
-    await reloadIndexRegistry()
+    await reloadIndexCatalog()
 
     // Integration with other tools like Hasura
     switch onInitialize {
@@ -1745,95 +1692,164 @@ SELECT id, chain_id, -1, -1, contract_name FROM unnest($1::text[],$2::int[],$3::
     columns
   }
 
-  // The DDL that leaves `schemaIndex` in place. Normally a create; a repair
-  // when an invalid index already holds the name with the definition we want.
-  let makeEnsureIndexQuery = schemaIndex => {
-    let indexName = schemaIndex->schemaIndexName
-    switch indexRegistry->IndexRegistry.getInvalid(indexName) {
-    | None => makeCreateSchemaIndexQuery(schemaIndex, ~pgSchema)
-    | Some({key, isRepairable: true}) if key === schemaIndex->schemaIndexKey =>
-      makeReindexQuery(~pgSchema, ~indexName)
-    | Some(_) => throw(nameCollisionError(~indexName, ~pgSchema))
+  // Runs a prepared build's DDL and reads the index back from pg_catalog before
+  // it counts as existing. `sql` is the transaction's handle when there is one,
+  // so a failed verification rolls the DDL back with it.
+  let runAndVerify = async (sql, prepared: IndexManager.prepared) => {
+    // Sequential rather than Promise.all: inside a transaction they share one
+    // connection, and a rebuild's DROP has to land before its CREATE.
+    for idx in 0 to prepared.queries->Array.length - 1 {
+      let _ = await sql->Postgres.unsafe(prepared.queries->Array.getUnsafe(idx))
     }
+    let rows = await sql->loadCatalogRows(~indexName=prepared.name)
+    prepared->IndexManager.verifyOrThrow(~rows, ~pgSchema)
   }
 
-  let isRepair = schemaIndex =>
-    indexRegistry->IndexRegistry.getInvalid(schemaIndex->schemaIndexName)->Option.isSome
+  // A build outside a transaction can commit its DDL and still fail — the
+  // read-back is a second round trip. Re-reading the index puts the catalog
+  // back in step, so the next attempt plans against what the database holds
+  // instead of retrying a create that can only raise "already exists".
+  //
+  // If this read fails too, the next attempt does waste a create before landing
+  // here again — bounded, and it recovers as soon as the database answers.
+  let resyncIndex = async name =>
+    switch await sql->loadCatalogRows(~indexName=name) {
+    | rows => indexManager->IndexManager.resync(~name, ~rows)
+    | exception exn =>
+      Logging.debug({
+        "storage": storageName,
+        "msg": `Could not re-read the index "${name}" after a failed build. The next attempt reads it again.`,
+        "err": exn->Utils.prettifyExn,
+      })
+    }
 
   let ensureQueryIndexes = async (~table: Table.table, ~filters: array<EntityFilter.t>) => {
-    let missing = filterColumns(~table, ~filters)->Array.filterMap(column => {
-      let schemaIndex = makeSingleColumnSchemaIndex(~tableName=table.tableName, ~column)
-      indexRegistry->IndexRegistry.has(schemaIndex->schemaIndexKey) ? None : Some(schemaIndex)
+    let columns = filterColumns(~table, ~filters)
+    let _ = await columns
+    ->Array.map(column => {
+      let definition = IndexDefinition.single(~tableName=table.tableName, ~column)
+      indexManager
+      ->IndexManager.ensure(~definition, ~coverage=LeadingColumns, ~build=async () => {
+        // Resolved before logging so a rebuild is reported as one, and an
+        // unrelated index holding the name fails before any DDL runs.
+        switch indexManager->IndexManager.prepare(
+          ~definition,
+          ~coverage=LeadingColumns,
+          ~pgSchema,
+        ) {
+        | None => ()
+        | Some(prepared) =>
+          let verb = prepared.isRebuild ? "Rebuilding unusable index" : "Creating index"
+          // Logged from inside the build so it reports the one request that
+          // actually creates the index, not the ones waiting on it.
+          Logging.info({
+            "storage": storageName,
+            "msg": `${verb} "${prepared.name}" to serve a getWhere query on "${table.tableName}". Writes to the table are paused until it completes. ${slowOnLargeDatabaseNotice}`,
+          })
+          let timeRef = Performance.now()
+          let entry = await sql->runAndVerify(prepared)
+          indexManager->IndexManager.record(entry)
+          Logging.info({
+            "storage": storageName,
+            "msg": `Index "${prepared.name}" is ready after ${timeRef->formatSeconds}s. Resuming indexing.`,
+          })
+        }
+      })
+      // A failed build records nothing, so the next getWhere retries. Meanwhile
+      // the query still runs — just without the index.
+      ->Promise.catch(async exn => {
+        Logging.warn({
+          "storage": storageName,
+          "msg": `Failed to create an index on "${table.tableName}"("${column}") for a getWhere query. The query runs without it.`,
+          "err": exn->Utils.prettifyExn,
+        })
+        await resyncIndex(definition->IndexDefinition.name)
+      })
     })
+    ->Promise.all
+  }
 
-    if missing->Utils.Array.notEmpty {
-      let _ = await missing
-      ->Array.map(schemaIndex => {
-        let indexName = schemaIndex->schemaIndexName
-        indexRegistry
-        ->IndexRegistry.ensure(
-          ~key=schemaIndex->schemaIndexKey,
-          ~tableName=table.tableName,
-          ~build=async () => {
-            // Resolved before logging so a repair is reported as one, and an
-            // unrelated index holding the name fails before any DDL runs.
-            let query = makeEnsureIndexQuery(schemaIndex)
-            let verb = schemaIndex->isRepair ? "Repairing invalid index" : "Creating index"
-            // Logged from inside the build so it reports the one request that
-            // actually creates the index, not the ones waiting on it.
-            Logging.info({
-              "storage": storageName,
-              "msg": `${verb} "${indexName}" to serve a getWhere query on "${table.tableName}". Writes to the table are paused until it completes. ${slowOnLargeDatabaseNotice}`,
-            })
-            let timeRef = Performance.now()
-            let _ = await sql->Postgres.unsafe(query)
-            indexRegistry->IndexRegistry.clearInvalidName(indexName)
-            Logging.info({
-              "storage": storageName,
-              "msg": `Index "${indexName}" is ready after ${timeRef->formatSeconds}s. Resuming indexing.`,
-            })
-          },
-        )
-        // A failed build leaves the registry untouched, so the next getWhere
-        // retries. Meanwhile the query still runs — just without the index.
-        ->Utils.Promise.catchResolve(exn => {
-          Logging.warn({
+  // Goes through `IndexManager.ensure`, unlike `finalizeBackfill` below: that
+  // one runs with processing paused, while this runs on a resumed indexer that
+  // is already ready, so handlers may be issuing getWhere queries alongside it
+  // and the per-table queues are what keep the two from colliding. Nothing here
+  // writes `ready_at` — the chains already carry theirs.
+  let ensureSchemaIndexes = async (~entities: array<Internal.entityConfig>) => {
+    let schemaIndexes = getSchemaIndexes(
+      ~entities=entities->Array.filter((e: Internal.entityConfig) => e.storage.postgres),
+    )
+
+    let _ = await schemaIndexes
+    ->Array.map(definition =>
+      indexManager
+      ->IndexManager.ensure(~definition, ~coverage=Exact, ~build=async () => {
+        switch indexManager->IndexManager.prepare(~definition, ~coverage=Exact, ~pgSchema) {
+        | None => ()
+        | Some(prepared) =>
+          let verb = prepared.isRebuild ? "Rebuilding unusable index" : "Creating missing index"
+          Logging.info({
+            "storage": storageName,
+            "msg": `${verb} "${prepared.name}" the schema promises but the database no longer has. Writes to the table are paused until it completes. ${slowOnLargeDatabaseNotice}`,
+          })
+          let timeRef = Performance.now()
+          let entry = await sql->runAndVerify(prepared)
+          indexManager->IndexManager.record(entry)
+          Logging.info({
             "storage": storageName,
-            "msg": `Failed to create the index "${indexName}" for a getWhere query. The query runs without it.`,
-            "err": exn->Utils.prettifyExn,
+            "msg": `Index "${prepared.name}" is ready after ${timeRef->formatSeconds}s.`,
           })
+        }
+      })
+      ->Promise.catch(async exn => {
+        Logging.warn({
+          "storage": storageName,
+          "msg": `Failed to restore the schema index "${definition->IndexDefinition.name}". Queries relying on it run unindexed until the next restart.`,
+          "err": exn->Utils.prettifyExn,
         })
+        await resyncIndex(definition->IndexDefinition.name)
       })
-      ->Promise.all
-    }
+    )
+    ->Promise.all
   }
 
+  // Unlike `ensureQueryIndexes`, this doesn't go through `IndexManager.ensure`.
+  // It's safe because the caller guarantees exclusivity — `FinalizeBackfill.run`
+  // is reached from the processing loop with processing already paused, so no
+  // handler can be running a getWhere.
+  //
+  // Each index is built on its own rather than in one transaction with
+  // `ready_at`: a build that dies half way through a large schema would
+  // otherwise roll back every index before it and make the retry start over.
   let finalizeBackfill = async (
     ~entities: array<Internal.entityConfig>,
-    ~chainIds: array<int>,
+    ~chainIds: array<ChainId.t>,
     ~readyAt: Date.t,
   ) => {
     let schemaIndexes = getSchemaIndexes(
       ~entities=entities->Array.filter((e: Internal.entityConfig) => e.storage.postgres),
     )
-    IndexRegistry.validateIndexNamesOrThrow(schemaIndexes->Array.map(schemaIndexDescription))
 
+    // Resolved up front so a name held by an unrelated index fails before any
+    // DDL runs, rather than part way through the set.
+    //
+    // `Exact`, so the set built here is decided by the schema alone: matching a
+    // declared index against a composite that happens to lead with the same
+    // column would make a fresh database and an upgraded one end up holding
+    // different tables.
     let missing =
-      schemaIndexes->Array.filter(schemaIndex =>
-        !(indexRegistry->IndexRegistry.has(schemaIndex->schemaIndexKey))
+      schemaIndexes->Array.filterMap(definition =>
+        indexManager->IndexManager.prepare(~definition, ~coverage=Exact, ~pgSchema)
       )
 
-    // `IF NOT EXISTS` would quietly skip an index whose name is taken by an
-    // invalid one, and the indexer would then report ready with an index the
-    // planner can't use. Those are repaired in the same transaction instead.
-    let repaired = missing->Array.filter(isRepair)
-    if repaired->Utils.Array.notEmpty {
+    switch missing->Array.filter((prepared: IndexManager.prepared) => prepared.isRebuild) {
+    | [] => ()
+    | rebuilt =>
       Logging.warn({
         "storage": storageName,
-        "msg": `PostgreSQL reports ${repaired
+        "msg": `PostgreSQL reports ${rebuilt
           ->Array.length
-          ->Int.toString} existing indexes as invalid, so they can't serve queries. Rebuilding them.`,
-        "indexes": repaired->Array.map(schemaIndexName),
+          ->Int.toString} of the indexer's own indexes as invalid, so they can't serve queries. Rebuilding them.`,
+        "indexes": rebuilt->Array.map((prepared: IndexManager.prepared) => prepared.name),
       })
     }
 
@@ -1851,39 +1867,46 @@ SELECT id, chain_id, -1, -1, contract_name FROM unnest($1::text[],$2::int[],$3::
         "msg": `Creating the ${missing
           ->Array.length
           ->Int.toString} remaining schema indexes before the indexer reports ready. Writes are paused until they are committed. ${slowOnLargeDatabaseNotice}`,
-        "indexes": missing->Array.map(schemaIndexName),
+        "indexes": missing->Array.map((prepared: IndexManager.prepared) => prepared.name),
       })
     }
-    // Resolved up front so a name held by an unrelated invalid index fails
-    // before the transaction opens, rather than rolling one back.
-    let indexQueries = missing->Array.map(makeEnsureIndexQuery)
     let timeRef = Performance.now()
 
-    await sql->Postgres.beginSql(async sql => {
-      // Sequential rather than Promise.all: they share one connection inside
-      // the transaction, and several of them target the same table.
-      for idx in 0 to indexQueries->Array.length - 1 {
-        let _ = await sql->Postgres.unsafe(indexQueries->Array.getUnsafe(idx))
+    // Sequential, one committed index at a time: whatever is built before a
+    // failure stays built and recorded, so the retry owes only the rest.
+    for idx in 0 to missing->Array.length - 1 {
+      let prepared = missing->Array.getUnsafe(idx)
+      switch await sql->runAndVerify(prepared) {
+      | entry => indexManager->IndexManager.record(entry)
+      | exception exn =>
+        // The DDL is outside a transaction, so a create that commits and then
+        // fails its read-back leaves the index in place and unrecorded.
+        // Re-reading it means the retry plans against the database rather than
+        // replaying a create that can only raise "already exists".
+        await resyncIndex(prepared.name)
+        throw(exn)
       }
-      await sql
-      ->Postgres.preparedUnsafe(
-        InternalTable.Chains.makeSetReadyAtQuery(~pgSchema),
-        [
-          readyAt->(Utils.magic: Date.t => unknown),
-          chainIds->(Utils.magic: array<int> => unknown),
-        ]->(Utils.magic: array<unknown> => unknown),
-      )
-      ->Utils.Promise.ignoreValue
-    })
+    }
 
-    // Only after the commit: a rollback takes both the indexes and ready_at
-    // with it, and the registry must not claim what the schema doesn't have.
-    missing->Array.forEach(schemaIndex =>
-      indexRegistry->IndexRegistry.add(schemaIndex->schemaIndexKey)
-    )
-    repaired->Array.forEach(schemaIndex =>
-      indexRegistry->IndexRegistry.clearInvalidName(schemaIndex->schemaIndexName)
-    )
+    // Reached only once every definition is verified against pg_catalog, so a
+    // crash either leaves `ready_at` null and the retry finds the indexes
+    // already built, or commits readiness the schema backs.
+    //
+    // One transaction for the whole set: readiness is an indexer-wide fact, and
+    // a crash part way through would otherwise leave some chains stamped and
+    // some not, reporting the indexer as half ready.
+    let setReadyAtQuery = InternalTable.Chains.makeSetReadyAtQuery(~pgSchema)
+    let _ = await sql->Postgres.beginSql(async sql => {
+      for idx in 0 to chainIds->Array.length - 1 {
+        let _ = await sql->Postgres.preparedUnsafe(
+          setReadyAtQuery,
+          [
+            readyAt->(Utils.magic: Date.t => unknown),
+            chainIds->Array.getUnsafe(idx)->(Utils.magic: ChainId.t => unknown),
+          ]->(Utils.magic: array<unknown> => unknown),
+        )
+      }
+    })
 
     Logging.info({
       "storage": storageName,
@@ -2037,14 +2060,14 @@ SELECT id, chain_id, -1, -1, contract_name FROM unnest($1::text[],$2::int[],$3::
       InternalTable.EnvioInfo.read(sql, ~pgSchema),
     ))
 
-    await reloadIndexRegistry()
+    await reloadIndexCatalog()
 
     let checkpointId = (checkpointIdResult->Array.getUnsafe(0))["id"]->BigInt.fromStringOrThrow
 
     // Convert string checkpoint IDs from DB to bigint
     let reorgCheckpoints = Array.map(reorgCheckpoints, (raw): Internal.reorgCheckpoint => {
       checkpointId: raw["id"]->BigInt.fromStringOrThrow,
-      chainId: raw["chain_id"],
+      chainId: raw["chain_id"]->ChainId.normalizeOrThrow,
       blockNumber: raw["block_number"],
       blockHash: raw["block_hash"],
     })
@@ -2200,6 +2223,7 @@ SELECT id, chain_id, -1, -1, contract_name FROM unnest($1::text[],$2::int[],$3::
     resumeInitialState,
     loadOrThrow,
     ensureQueryIndexes,
+    ensureSchemaIndexes,
     finalizeBackfill,
     dumpEffectCache,
     reset,
@@ -2228,6 +2252,7 @@ let makeStorageFromEnv = (
     ~pgPort=Env.Db.port,
     ~pgDatabase=Env.Db.database,
     ~pgPassword=Env.Db.password,
+    ~chainIdMode=config.chainIdMode,
     ~sink=?{
       // Internally ClickHouse storage is implemented as a sync of the
       // Postgres storage. Required env vars are validated here only when
@@ -2260,6 +2285,7 @@ let makeStorageFromEnv = (
             ~database=database->Option.getUnsafe,
             ~username=username->Option.getUnsafe,
             ~password=password->Option.getUnsafe,
+            ~chainIdMode=config.chainIdMode,
           ),
         )
       } else {