envio 3.0.0-rc.0 → 3.0.0

package/index.d.ts

@@ -1167,6 +1167,22 @@ type SvmEcosystem<Config extends IndexerConfigTypes = GlobalConfig> =
       : never
     : never;
 
+// Surfaced when the indexer has no configured ecosystem — typically because
+// `envio codegen` hasn't been run yet, so `Global` isn't augmented and
+// `GlobalConfig` resolves to `{}`. The handler methods are still present so
+// IDE autocomplete shows them; their rest parameter is typed as a
+// string-literal hint so any call site fails with an error message that
+// names codegen as the fix. A rest parameter (rather than a single one)
+// avoids "Expected N arguments" errors masking the hint.
+type CodegenRequiredHint =
+  "Run 'envio codegen' to generate handler types from config.yaml. Without codegen, the indexer has no contracts, chains, or events to register handlers for.";
+type CodegenRequiredFallback = {
+  readonly onEvent: (...hint: CodegenRequiredHint[]) => void;
+  readonly onBlock: (...hint: CodegenRequiredHint[]) => void;
+  readonly onSlot: (...hint: CodegenRequiredHint[]) => void;
+  readonly contractRegister: (...hint: CodegenRequiredHint[]) => void;
+};
+
 // Single-ecosystem chains live at the root of the indexer object alongside
 // the handler-registration methods. Multi-ecosystem indexers aren't
 // supported by the runtime, so there's no nested `evm` / `fuel` / `svm`
@@ -1178,7 +1194,7 @@ type SingleEcosystemChains<Config extends IndexerConfigTypes = GlobalConfig> =
     ? FuelEcosystem<Config>
     : HasSvm<Config> extends true
     ? SvmEcosystem<Config>
-    : {};
+    : CodegenRequiredFallback;
 
 /** Indexer type resolved from config. */
 export type IndexerFromConfig<Config extends IndexerConfigTypes = GlobalConfig> = Prettify<
@@ -1457,7 +1473,7 @@ type SingleEcosystemTestChains<Config extends IndexerConfigTypes = GlobalConfig>
     ? FuelTestEcosystem<Config>
     : HasSvm<Config> extends true
     ? SvmTestEcosystem<Config>
-    : {};
+    : CodegenRequiredFallback;
 
 /**
  * Test indexer type resolved from config.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envio",
-  "version": "3.0.0-rc.0",
+  "version": "3.0.0",
   "type": "module",
   "description": "A latency and sync speed optimized, developer friendly blockchain data indexer.",
   "bin": "./bin.mjs",
@@ -71,10 +71,10 @@
     "tsx": "4.21.0"
   },
   "optionalDependencies": {
-    "envio-linux-x64": "3.0.0-rc.0",
-    "envio-linux-x64-musl": "3.0.0-rc.0",
-    "envio-linux-arm64": "3.0.0-rc.0",
-    "envio-darwin-x64": "3.0.0-rc.0",
-    "envio-darwin-arm64": "3.0.0-rc.0"
+    "envio-linux-x64": "3.0.0",
+    "envio-linux-x64-musl": "3.0.0",
+    "envio-linux-arm64": "3.0.0",
+    "envio-darwin-x64": "3.0.0",
+    "envio-darwin-arm64": "3.0.0"
   }
 }

package/src/Config.res

@@ -145,11 +145,15 @@ module EnvioAddresses = {
   external castToInternal: t => Internal.entity = "%identity"
 
   let entityConfig = {
-    name,
+    Internal.name,
     index,
     schema,
     rowsSchema,
     table,
+    // Internal address tracking is Postgres-only; the global config is
+    // always required to have Postgres enabled (Storage::resolve forbids
+    // a Postgres-disabled global), so this is safe regardless of mode.
+    storage: {postgres: true, clickhouse: false},
   }->Internal.fromGenericEntityConfig
 }
 
@@ -269,9 +273,17 @@ let propertySchema = S.schema(s =>
   }
 )
 
+let entityStorageSchema = S.schema(s =>
+  {
+    "postgres": s.matches(S.option(S.bool)),
+    "clickhouse": s.matches(S.option(S.bool)),
+  }
+)
+
 let entityJsonSchema = S.schema(s =>
   {
     "name": s.matches(S.string),
+    "storage": s.matches(S.option(entityStorageSchema)),
     "properties": s.matches(S.array(propertySchema)),
     "derivedFields": s.matches(S.option(S.array(derivedFieldSchema))),
     "compositeIndices": s.matches(S.option(S.array(S.array(compositeIndexFieldSchema)))),
@@ -348,6 +360,7 @@ let parseEnumsFromJson = (enumsJson: dict<array<string>>): array<Table.enumConfi
 let parseEntitiesFromJson = (
   entitiesJson: array<'entityJson>,
   ~enumConfigsByName: dict<Table.enumConfig<Table.enum>>,
+  ~globalStorage: storage,
 ): array<Internal.entityConfig> => {
   entitiesJson->Array.mapWithIndex((entityJson, index) => {
     let entityName = entityJson["name"]
@@ -416,6 +429,21 @@ let parseEntitiesFromJson = (
       dict
     })
 
+    // Resolve per-entity storage against the global config. The CLI
+    // validates that an entity never opts into a backend the global
+    // config didn't enable, and that at least one backend stays true
+    // for an annotated entity — so `getOr(false)` is safe here.
+    let storage: Internal.entityStorage = switch entityJson["storage"] {
+    | Some(s) => {
+        postgres: s["postgres"]->Option.getOr(false),
+        clickhouse: s["clickhouse"]->Option.getOr(false),
+      }
+    | None => {
+        postgres: globalStorage.postgres,
+        clickhouse: globalStorage.clickhouse,
+      }
+    }
+
     {
       Internal.name: entityName,
       index,
@@ -424,6 +452,7 @@ let parseEntitiesFromJson = (
         Utils.magic: S.t<array<dict<unknown>>> => S.t<array<Internal.entity>>
       ),
       table,
+      storage,
     }->Internal.fromGenericEntityConfig
   })
 }
@@ -756,10 +785,15 @@ let fromPublic = (publicConfigJson: JSON.t) => {
   let enumConfigsByName =
     allEnums->Array.map(enumConfig => (enumConfig.name, enumConfig))->Dict.fromArray
 
+  let globalStorage: storage = {
+    postgres: publicConfig["storage"]["postgres"],
+    clickhouse: publicConfig["storage"]["clickhouse"]->Option.getOr(false),
+  }
+
   let userEntities =
     publicConfig["entities"]
     ->Option.getOr([])
-    ->parseEntitiesFromJson(~enumConfigsByName)
+    ->parseEntitiesFromJson(~enumConfigsByName, ~globalStorage)
 
   let allEntities = userEntities->Array.concat([EnvioAddresses.entityConfig])
 
@@ -791,10 +825,7 @@ let fromPublic = (publicConfigJson: JSON.t) => {
     contractHandlers,
     shouldRollbackOnReorg: publicConfig["rollbackOnReorg"]->Option.getOr(true),
     shouldSaveFullHistory: publicConfig["saveFullHistory"]->Option.getOr(false),
-    storage: {
-      postgres: publicConfig["storage"]["postgres"],
-      clickhouse: publicConfig["storage"]["clickhouse"]->Option.getOr(false),
-    },
+    storage: globalStorage,
     multichain: publicConfig["multichain"]->Option.getOr(Unordered),
     chainMap,
     defaultChain: chains->Array.get(0),
@@ -992,3 +1023,5 @@ let loadWithoutRegistrations = () =>
       c
     }
   }
+
+let getPgUserEntities = (config: t) => config.userEntities->Array.filter(e => e.storage.postgres)

package/src/Config.res.mjs

@@ -51,12 +51,18 @@ let table = Table.mkTable(name, undefined, [
   Table.mkField("contract_name", "String", S$RescriptSchema.string, undefined, undefined, undefined, undefined, undefined, undefined)
 ]);
 
+let entityConfig_storage = {
+  postgres: true,
+  clickhouse: false
+};
+
 let entityConfig = {
   name: name,
   index: -1,
   schema: schema,
   rowsSchema: rowsSchema,
-  table: table
+  table: table,
+  storage: entityConfig_storage
 };
 
 let EnvioAddresses = {
@@ -168,8 +174,14 @@ let propertySchema = S$RescriptSchema.schema(s => ({
   scale: s.m(S$RescriptSchema.option(S$RescriptSchema.int))
 }));
 
+let entityStorageSchema = S$RescriptSchema.schema(s => ({
+  postgres: s.m(S$RescriptSchema.option(S$RescriptSchema.bool)),
+  clickhouse: s.m(S$RescriptSchema.option(S$RescriptSchema.bool))
+}));
+
 let entityJsonSchema = S$RescriptSchema.schema(s => ({
   name: s.m(S$RescriptSchema.string),
+  storage: s.m(S$RescriptSchema.option(entityStorageSchema)),
   properties: s.m(S$RescriptSchema.array(propertySchema)),
   derivedFields: s.m(S$RescriptSchema.option(S$RescriptSchema.array(derivedFieldSchema))),
   compositeIndices: s.m(S$RescriptSchema.option(S$RescriptSchema.array(S$RescriptSchema.array(compositeIndexFieldSchema))))
@@ -285,7 +297,7 @@ function parseEnumsFromJson(enumsJson) {
   return Object.entries(enumsJson).map(param => Table.makeEnumConfig(param[0], param[1]));
 }
 
-function parseEntitiesFromJson(entitiesJson, enumConfigsByName) {
+function parseEntitiesFromJson(entitiesJson, enumConfigsByName, globalStorage) {
   return entitiesJson.map((entityJson, index) => {
     let entityName = entityJson.name;
     let fields = entityJson.properties.map(prop => {
@@ -308,12 +320,27 @@ function parseEntitiesFromJson(entitiesJson, enumConfigsByName) {
       });
       return dict;
     });
+    let s = entityJson.storage;
+    let storage;
+    if (s !== undefined) {
+      let s$1 = Primitive_option.valFromOption(s);
+      storage = {
+        postgres: Stdlib_Option.getOr(s$1.postgres, false),
+        clickhouse: Stdlib_Option.getOr(s$1.clickhouse, false)
+      };
+    } else {
+      storage = {
+        postgres: globalStorage.postgres,
+        clickhouse: globalStorage.clickhouse
+      };
+    }
     return {
       name: entityName,
       index: index,
       schema: schema,
       rowsSchema: S$RescriptSchema.array(schema),
-      table: table
+      table: table,
+      storage: storage
     };
   });
 }
@@ -583,7 +610,13 @@ function fromPublic(publicConfigJson) {
     enumConfig.name,
     enumConfig
   ]));
-  let userEntities = parseEntitiesFromJson(Stdlib_Option.getOr(publicConfig.entities, []), enumConfigsByName);
+  let globalStorage_postgres = publicConfig.storage.postgres;
+  let globalStorage_clickhouse = Stdlib_Option.getOr(publicConfig.storage.clickhouse, false);
+  let globalStorage = {
+    postgres: globalStorage_postgres,
+    clickhouse: globalStorage_clickhouse
+  };
+  let userEntities = parseEntitiesFromJson(Stdlib_Option.getOr(publicConfig.entities, []), enumConfigsByName, globalStorage);
   let allEntities = userEntities.concat([entityConfig]);
   let userEntitiesByName = Object.fromEntries(userEntities.map(entityConfig => [
     entityConfig.name,
@@ -600,10 +633,7 @@ function fromPublic(publicConfigJson) {
     contractHandlers: contractHandlers,
     shouldRollbackOnReorg: Stdlib_Option.getOr(publicConfig.rollbackOnReorg, true),
     shouldSaveFullHistory: Stdlib_Option.getOr(publicConfig.saveFullHistory, false),
-    storage: {
-      postgres: publicConfig.storage.postgres,
-      clickhouse: Stdlib_Option.getOr(publicConfig.storage.clickhouse, false)
-    },
+    storage: globalStorage,
     multichain: Stdlib_Option.getOr(publicConfig.multichain, "unordered"),
     chainMap: chainMap,
     defaultChain: chains[0],
@@ -822,6 +852,10 @@ function loadWithoutRegistrations() {
   return c$1;
 }
 
+function getPgUserEntities(config) {
+  return config.userEntities.filter(e => e.storage.postgres);
+}
+
 export {
   EnvioAddresses,
   rpcSourceForSchema,
@@ -836,6 +870,7 @@ export {
   compositeIndexFieldSchema,
   derivedFieldSchema,
   propertySchema,
+  entityStorageSchema,
   entityJsonSchema,
   getFieldTypeAndSchema,
   parseEnumsFromJson,
@@ -854,5 +889,6 @@ export {
   diffPaths,
   throwIfIncompatible,
   loadWithoutRegistrations,
+  getPgUserEntities,
 }
 /* schema Not a pure module */

package/src/Env.res

@@ -134,11 +134,24 @@ module ClickHouse = {
       const v = process.env[k];
       return v === undefined || v === "" ? undefined : v;
     }`)
+    // Empty password is a valid, passwordless ClickHouse user — distinguish
+    // "unset" (None) from "set but empty" (Some("")).
+    let readAllowEmpty: string => option<string> = %raw(`(k) => process.env[k]`)
   )
   let host = () => read("ENVIO_CLICKHOUSE_HOST")
   let database = () => read("ENVIO_CLICKHOUSE_DATABASE")
   let username = () => read("ENVIO_CLICKHOUSE_USERNAME")
-  let password = () => read("ENVIO_CLICKHOUSE_PASSWORD")
+  let password = () => readAllowEmpty("ENVIO_CLICKHOUSE_PASSWORD")
+  let replicated = () =>
+    switch read("ENVIO_CLICKHOUSE_REPLICATED") {
+    | None => false
+    | Some("true") => true
+    | Some(other) =>
+      JsError.throwWithMessage(
+        `Invalid ENVIO_CLICKHOUSE_REPLICATED value: "${other}". Only "true" is accepted.`,
+      )
+    }
+  let databaseEngine = () => read("ENVIO_CLICKHOUSE_DATABASE_ENGINE")
 }
 
 module Hasura = {

package/src/Env.res.mjs

@@ -4,6 +4,7 @@ import * as EnvSafe from "./EnvSafe.res.mjs";
 import * as Logging from "./Logging.res.mjs";
 import * as Postgres from "./bindings/Postgres.res.mjs";
 import * as Belt_Option from "@rescript/runtime/lib/es6/Belt_Option.js";
+import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 import * as HyperSyncClient from "./sources/HyperSyncClient.res.mjs";
 import * as S$RescriptSchema from "rescript-schema/src/S.res.mjs";
 import * as HypersyncClient from "@envio-dev/hypersync-client";
@@ -107,6 +108,8 @@ let read = ((k) => {
       return v === undefined || v === "" ? undefined : v;
     });
 
+let readAllowEmpty = ((k) => process.env[k]);
+
 function host$1() {
   return read("ENVIO_CLICKHOUSE_HOST");
 }
@@ -120,14 +123,33 @@ function username() {
 }
 
 function password$1() {
-  return read("ENVIO_CLICKHOUSE_PASSWORD");
+  return readAllowEmpty("ENVIO_CLICKHOUSE_PASSWORD");
+}
+
+function replicated() {
+  let other = read("ENVIO_CLICKHOUSE_REPLICATED");
+  if (other !== undefined) {
+    if (other === "true") {
+      return true;
+    } else {
+      return Stdlib_JsError.throwWithMessage(`Invalid ENVIO_CLICKHOUSE_REPLICATED value: "` + other + `". Only "true" is accepted.`);
+    }
+  } else {
+    return false;
+  }
+}
+
+function databaseEngine() {
+  return read("ENVIO_CLICKHOUSE_DATABASE_ENGINE");
 }
 
 let ClickHouse = {
   host: host$1,
   database: database$1,
   username: username,
-  password: password$1
+  password: password$1,
+  replicated: replicated,
+  databaseEngine: databaseEngine
 };
 
 let enabled = EnvSafe.get(envSafe, "ENVIO_HASURA", S$RescriptSchema.bool, undefined, true, undefined, undefined);

package/src/Internal.res

@@ -523,12 +523,21 @@ let fuelTransferParamsSchema = S.schema(s => {
 type multichain = | @as("ordered") Ordered | @as("unordered") Unordered
 
 type entity = private {id: string}
+
+// Per-entity storage resolved at parse time against the global storage
+// config. Downstream PG/CH consumers just check the matching boolean.
+type entityStorage = {
+  postgres: bool,
+  clickhouse: bool,
+}
+
 type genericEntityConfig<'entity> = {
   name: string,
   index: int,
   schema: S.t<'entity>,
   rowsSchema: S.t<array<'entity>>,
   table: Table.table,
+  storage: entityStorage,
 }
 type entityConfig = genericEntityConfig<entity>
 external fromGenericEntityConfig: genericEntityConfig<'entity> => entityConfig = "%identity"

package/src/PgStorage.res

@@ -1208,6 +1208,12 @@ let make = (
     ~enums=[],
     ~envioInfo,
   ): Persistence.initialState => {
+    // Per-entity storage routing: PG owns tables only for entities that
+    // opted into Postgres; the sink mirrors only those that opted into
+    // ClickHouse.
+    let pgEntities = entities->Array.filter((e: Internal.entityConfig) => e.storage.postgres)
+    let chEntities = entities->Array.filter((e: Internal.entityConfig) => e.storage.clickhouse)
+
     let schemaTableNames: array<schemaTableName> = await sql->Postgres.unsafe(
       makeSchemaTableNamesQuery(~pgSchema),
     )
@@ -1235,14 +1241,14 @@ let make = (
 
     // Call sink.initialize before executing PG queries
     switch sink {
-    | Some(sink) => await sink.initialize(~chainConfigs, ~entities, ~enums)
+    | Some(sink) => await sink.initialize(~chainConfigs, ~entities=chEntities, ~enums)
     | None => ()
     }
 
     let queries = makeInitializeTransaction(
       ~pgSchema,
       ~pgUser,
-      ~entities,
+      ~entities=pgEntities,
       ~enums,
       ~chainConfigs,
       ~isEmptyPgSchema=schemaTableNames->Utils.Array.isEmpty,
@@ -1620,12 +1626,25 @@ SELECT id, chain_id, -1, -1, contract_name FROM unnest($1::text[],$2::int[],$3::
     ~updatedEffectsCache,
     ~updatedEntities,
   ) => {
+    let pgUpdates = []
+    let chUpdates = []
+    for i in 0 to updatedEntities->Array.length - 1 {
+      let update = updatedEntities->Array.getUnsafe(i)
+      let {entityConfig}: Persistence.updatedEntity = update
+      if entityConfig.storage.postgres {
+        pgUpdates->Array.push(update)
+      }
+      if entityConfig.storage.clickhouse {
+        chUpdates->Array.push(update)
+      }
+    }
+
     // Initialize sink if configured
     let sinkPromise = switch sink {
     | Some(sink) => {
         let timerRef = Hrtime.makeTimer()
         Some(
-          sink.writeBatch(~batch, ~updatedEntities)
+          sink.writeBatch(~batch, ~updatedEntities=chUpdates)
           ->Promise.thenResolve(_ => {
             Prometheus.StorageWrite.increment(
               ~storage=sink.name,
@@ -1652,7 +1671,7 @@ SELECT id, chain_id, -1, -1, contract_name FROM unnest($1::text[],$2::int[],$3::
       ~allEntities,
       ~setEffectCacheOrThrow,
       ~updatedEffectsCache,
-      ~updatedEntities,
+      ~updatedEntities=pgUpdates,
       ~sinkPromise,
     )
     Prometheus.StorageWrite.increment(
@@ -1705,6 +1724,7 @@ let makeStorageFromEnv = (
         let host = Env.ClickHouse.host()
         let username = Env.ClickHouse.username()
         let password = Env.ClickHouse.password()
+        let database = Env.ClickHouse.database()
         let missing = []
         let checkEnv = (opt, name) =>
           switch opt {
@@ -1714,6 +1734,7 @@ let makeStorageFromEnv = (
         host->checkEnv("ENVIO_CLICKHOUSE_HOST")
         username->checkEnv("ENVIO_CLICKHOUSE_USERNAME")
         password->checkEnv("ENVIO_CLICKHOUSE_PASSWORD")
+        database->checkEnv("ENVIO_CLICKHOUSE_DATABASE")
         if missing->Array.length > 0 {
           JsError.throwWithMessage(
             `ClickHouse storage is enabled but required env vars are not set: ${missing->Array.joinUnsafe(
@@ -1724,7 +1745,7 @@ let makeStorageFromEnv = (
         Some(
           Sink.makeClickHouse(
             ~host=host->Option.getUnsafe,
-            ~database=Env.ClickHouse.database(),
+            ~database=database->Option.getUnsafe,
             ~username=username->Option.getUnsafe,
             ~password=password->Option.getUnsafe,
           ),
@@ -1744,7 +1765,7 @@ let makeStorageFromEnv = (
                 secret: Env.Hasura.secret,
               },
               ~pgSchema,
-              ~userEntities=config.userEntities,
+              ~userEntities=config->Config.getPgUserEntities,
               ~responseLimit=Env.Hasura.responseLimit,
               ~schema=Schema.make(config.allEntities->Belt.Array.map(e => e.table)),
               ~aggregateEntities=Env.Hasura.aggregateEntities,

package/src/PgStorage.res.mjs

@@ -794,14 +794,16 @@ function make(sql, pgHost, pgSchema, pgPort, pgUser, pgDatabase, pgPassword, isH
     let chainConfigs = chainConfigsOpt !== undefined ? chainConfigsOpt : [];
     let entities = entitiesOpt !== undefined ? entitiesOpt : [];
     let enums = enumsOpt !== undefined ? enumsOpt : [];
+    let pgEntities = entities.filter(e => e.storage.postgres);
+    let chEntities = entities.filter(e => e.storage.clickhouse);
     let schemaTableNames = await sql.unsafe(makeSchemaTableNamesQuery(pgSchema));
     if (Utils.$$Array.notEmpty(schemaTableNames) && !schemaTableNames.some(table => table.table_name === InternalTable.Chains.table.tableName ? true : table.table_name === "event_sync_state")) {
       Stdlib_JsError.throwWithMessage(`Cannot run Envio migrations on PostgreSQL schema "` + pgSchema + `" because it contains non-Envio tables. Running migrations would delete all data in this schema.\n\nTo resolve this:\n1. If you want to use this schema, first backup any important data, then drop it with: "pnpm envio local db-migrate down"\n2. Or specify a different schema name by setting the "ENVIO_PG_SCHEMA" environment variable\n3. Or manually drop the schema in your database if you're certain the data is not needed.`);
     }
     if (sink !== undefined) {
-      await sink.initialize(chainConfigs, entities, enums);
+      await sink.initialize(chainConfigs, chEntities, enums);
     }
-    let queries = makeInitializeTransaction(pgSchema, pgUser, isHasuraEnabled, chainConfigs, entities, enums, Utils.$$Array.isEmpty(schemaTableNames));
+    let queries = makeInitializeTransaction(pgSchema, pgUser, isHasuraEnabled, chainConfigs, pgEntities, enums, Utils.$$Array.isEmpty(schemaTableNames));
     await sql.begin(async sql => {
       await Promise.all(queries.map(query => sql.unsafe(query)));
       return await InternalTable.EnvioInfo.write(sql, pgSchema, envioInfo);
@@ -1019,17 +1021,29 @@ SELECT id, chain_id, -1, -1, contract_name FROM unnest($1::text[],$2::int[],$3::
     sql.unsafe(makeGetRollbackRestoredEntitiesQuery(entityConfig, pgSchema), [rollbackTargetCheckpointId.toString()], {prepare: true})
   ]);
   let writeBatchMethod = async (batch, rawEvents, rollbackTargetCheckpointId, isInReorgThreshold, config, allEntities, updatedEffectsCache, updatedEntities) => {
+    let pgUpdates = [];
+    let chUpdates = [];
+    for (let i = 0, i_finish = updatedEntities.length; i < i_finish; ++i) {
+      let update = updatedEntities[i];
+      let entityConfig = update.entityConfig;
+      if (entityConfig.storage.postgres) {
+        pgUpdates.push(update);
+      }
+      if (entityConfig.storage.clickhouse) {
+        chUpdates.push(update);
+      }
+    }
     let sinkPromise;
     if (sink !== undefined) {
       let timerRef = Hrtime.makeTimer();
-      sinkPromise = sink.writeBatch(batch, updatedEntities).then(() => {
+      sinkPromise = sink.writeBatch(batch, chUpdates).then(() => {
         Prometheus.StorageWrite.increment(sink.name, Hrtime.toSecondsFloat(Hrtime.timeSince(timerRef)));
       }).catch(exn => exn);
     } else {
       sinkPromise = undefined;
     }
     let primaryTimerRef = Hrtime.makeTimer();
-    await writeBatch(sql, batch, rawEvents, pgSchema, rollbackTargetCheckpointId, isInReorgThreshold, config, allEntities, setEffectCacheOrThrow, updatedEffectsCache, updatedEntities, sinkPromise, undefined);
+    await writeBatch(sql, batch, rawEvents, pgSchema, rollbackTargetCheckpointId, isInReorgThreshold, config, allEntities, setEffectCacheOrThrow, updatedEffectsCache, pgUpdates, sinkPromise, undefined);
     return Prometheus.StorageWrite.increment("postgres", Hrtime.toSecondsFloat(Hrtime.timeSince(primaryTimerRef)));
   };
   let close = () => sql.end();
@@ -1062,6 +1076,7 @@ function makeStorageFromEnv(config, sqlOpt, pgSchemaOpt, isHasuraEnabledOpt) {
     let host = Env.ClickHouse.host();
     let username = Env.ClickHouse.username();
     let password = Env.ClickHouse.password();
+    let database = Env.ClickHouse.database();
     let missing = [];
     let checkEnv = (opt, name) => {
       if (opt !== undefined) {
@@ -1074,17 +1089,18 @@ function makeStorageFromEnv(config, sqlOpt, pgSchemaOpt, isHasuraEnabledOpt) {
     checkEnv(host, "ENVIO_CLICKHOUSE_HOST");
     checkEnv(username, "ENVIO_CLICKHOUSE_USERNAME");
     checkEnv(password, "ENVIO_CLICKHOUSE_PASSWORD");
+    checkEnv(database, "ENVIO_CLICKHOUSE_DATABASE");
     if (missing.length !== 0) {
       Stdlib_JsError.throwWithMessage(`ClickHouse storage is enabled but required env vars are not set: ` + missing.join(", ") + `. Please set them, disable clickhouse in the \`storage\` config, or run \`envio dev\` for a pre-configured local ClickHouse.`);
     }
-    tmp = Sink.makeClickHouse(host, Env.ClickHouse.database(), username, password);
+    tmp = Sink.makeClickHouse(host, database, username, password);
   } else {
     tmp = undefined;
   }
   return make(sql, Env.Db.host, pgSchema, Env.Db.port, Env.Db.user, Env.Db.database, Env.Db.password, isHasuraEnabled, tmp, isHasuraEnabled ? () => Stdlib_Promise.$$catch(Hasura.trackDatabase(Env.Hasura.graphqlEndpoint, {
       role: Env.Hasura.role,
       secret: Env.Hasura.secret
-    }, pgSchema, config.userEntities, Env.Hasura.aggregateEntities, Env.Hasura.responseLimit, Schema.make(Belt_Array.map(config.allEntities, e => e.table))), err => Promise.resolve(Logging.errorWithExn(Utils.prettifyExn(err), `Error tracking tables`))) : undefined, isHasuraEnabled ? tableNames => Stdlib_Promise.$$catch(Hasura.trackTables(Env.Hasura.graphqlEndpoint, {
+    }, pgSchema, Config.getPgUserEntities(config), Env.Hasura.aggregateEntities, Env.Hasura.responseLimit, Schema.make(Belt_Array.map(config.allEntities, e => e.table))), err => Promise.resolve(Logging.errorWithExn(Utils.prettifyExn(err), `Error tracking tables`))) : undefined, isHasuraEnabled ? tableNames => Stdlib_Promise.$$catch(Hasura.trackTables(Env.Hasura.graphqlEndpoint, {
       role: Env.Hasura.role,
       secret: Env.Hasura.secret
     }, pgSchema, tableNames), err => Promise.resolve(Logging.errorWithExn(Utils.prettifyExn(err), `Error tracking new tables`))) : undefined);

package/src/Sink.res

@@ -19,13 +19,8 @@ let makeClickHouse = (~host, ~database, ~username, ~password): t => {
     password,
   })
 
-  // Don't assign it to client immediately,
-  // since it will fail if the database doesn't exist
-  // Call USE database instead
-  let database = switch database {
-  | Some(database) => database
-  | None => "envio_sink"
-  }
+  // Don't pass database to the client; it would fail if the database doesn't
+  // exist yet. Each query qualifies the name explicitly or runs USE first.
 
   let cache = Utils.WeakMap.make()
 

package/src/Sink.res.mjs

@@ -10,7 +10,6 @@ function makeClickHouse(host, database, username, password) {
     username: username,
     password: password
   });
-  let database$1 = database !== undefined ? database : "envio_sink";
   let cache = new WeakMap();
   return {
     name: "clickhouse",
@@ -18,12 +17,12 @@ function makeClickHouse(host, database, username, password) {
       $staropt$star !== undefined;
       let entities = $staropt$star$1 !== undefined ? $staropt$star$1 : [];
       let enums = $staropt$star$2 !== undefined ? $staropt$star$2 : [];
-      return ClickHouse.initialize(client, database$1, entities, enums);
+      return ClickHouse.initialize(client, database, entities, enums);
     },
-    resume: checkpointId => ClickHouse.resume(client, database$1, checkpointId),
+    resume: checkpointId => ClickHouse.resume(client, database, checkpointId),
     writeBatch: async (batch, updatedEntities) => {
-      await Promise.all(Belt_Array.map(updatedEntities, param => ClickHouse.setUpdatesOrThrow(client, cache, param.updates, param.entityConfig, database$1)));
-      return await ClickHouse.setCheckpointsOrThrow(client, batch, database$1);
+      await Promise.all(Belt_Array.map(updatedEntities, param => ClickHouse.setUpdatesOrThrow(client, cache, param.updates, param.entityConfig, database)));
+      return await ClickHouse.setCheckpointsOrThrow(client, batch, database);
     }
   };
 }

package/src/TestIndexer.res

@@ -75,7 +75,7 @@ let handleLoadByField = (
   let results = []
 
   // Get the field schema from the entity's table to properly parse the JSON field value
-  let fieldSchema = switch entityConfig.table->Table.getFieldByName(fieldName) {
+  let fieldSchema = switch entityConfig.table->Table.getFieldByDbName(fieldName) {
   | Some(Table.Field({fieldSchema})) => fieldSchema
   | _ => JsError.throwWithMessage(`Field ${fieldName} not found in entity ${tableName}`)
   }

package/src/TestIndexer.res.mjs

@@ -51,7 +51,7 @@ function handleLoadByField(state, tableName, fieldName, fieldValue, operator) {
   let entityDict = Stdlib_Option.getOr(state.entities[tableName], {});
   let entityConfig = state.entityConfigs[tableName];
   let results = [];
-  let match = Table.getFieldByName(entityConfig.table, fieldName);
+  let match = Table.getFieldByDbName(entityConfig.table, fieldName);
   let fieldSchema;
   let exit = 0;
   if (match !== undefined && match.TAG === "Field") {

package/src/UserContext.res

@@ -203,10 +203,20 @@ let getWhereHandler = (params: entityContextParams, filter: dict<dict<unknown>>)
 let noopSet = (_entity: Internal.entity) => ()
 let noopDeleteUnsafe = (_entityId: string) => ()
 
+// Reads against ClickHouse-only entities have no Postgres table to hit;
+// surface a friendly error instead of letting the SQL layer fail with
+// "relation does not exist".
+let throwClickHouseReadOnly = (entityConfig: Internal.entityConfig, op: string) =>
+  JsError.throwWithMessage(
+    `context.${entityConfig.name}.${op}() is unavailable: ClickHouse storage is currently write-only. Follow Envio releases to be notified when ClickHouse supports both reads and writes from handlers.`,
+  )
+
 let entityTraps: Utils.Proxy.traps<entityContextParams> = {
   get: (~target as params, ~prop: unknown) => {
     let prop = prop->(Utils.magic: unknown => string)
 
+    let isClickHouseOnly = !params.entityConfig.storage.postgres
+
     let set = params.isPreload
       ? noopSet
       : (entity: Internal.entity) => {
@@ -224,67 +234,92 @@ let entityTraps: Utils.Proxy.traps<entityContextParams> = {
 
     switch prop {
     | "get" =>
-      (
-        entityId =>
-          LoadLayer.loadById(
-            ~loadManager=params.loadManager,
-            ~persistence=params.persistence,
-            ~entityConfig=params.entityConfig,
-            ~inMemoryStore=params.inMemoryStore,
-            ~shouldGroup=params.isPreload,
-            ~item=params.item,
-            ~entityId,
-          )
-      )->(Utils.magic: (string => promise<option<Internal.entity>>) => unknown)
+      if isClickHouseOnly {
+        ((_entityId: string) => throwClickHouseReadOnly(params.entityConfig, "get"))->(
+          Utils.magic: (string => promise<option<Internal.entity>>) => unknown
+        )
+      } else {
+        (
+          entityId =>
+            LoadLayer.loadById(
+              ~loadManager=params.loadManager,
+              ~persistence=params.persistence,
+              ~entityConfig=params.entityConfig,
+              ~inMemoryStore=params.inMemoryStore,
+              ~shouldGroup=params.isPreload,
+              ~item=params.item,
+              ~entityId,
+            )
+        )->(Utils.magic: (string => promise<option<Internal.entity>>) => unknown)
+      }
     | "getWhere" =>
-      (filter => getWhereHandler(params, filter->(Utils.magic: unknown => dict<dict<unknown>>)))->(
-        Utils.magic: (unknown => promise<array<Internal.entity>>) => unknown
-      )
+      if isClickHouseOnly {
+        ((_filter: unknown) => throwClickHouseReadOnly(params.entityConfig, "getWhere"))->(
+          Utils.magic: (unknown => promise<array<Internal.entity>>) => unknown
+        )
+      } else {
+        (
+          filter => getWhereHandler(params, filter->(Utils.magic: unknown => dict<dict<unknown>>))
+        )->(Utils.magic: (unknown => promise<array<Internal.entity>>) => unknown)
+      }
 
     | "getOrThrow" =>
-      (
-        (entityId, ~message=?) =>
-          LoadLayer.loadById(
-            ~loadManager=params.loadManager,
-            ~persistence=params.persistence,
-            ~entityConfig=params.entityConfig,
-            ~inMemoryStore=params.inMemoryStore,
-            ~shouldGroup=params.isPreload,
-            ~item=params.item,
-            ~entityId,
-          )->Promise.thenResolve(entity => {
-            switch entity {
-            | Some(entity) => entity
-            | None =>
-              JsError.throwWithMessage(
-                message->Belt.Option.getWithDefault(
-                  `Entity '${params.entityConfig.name}' with ID '${entityId}' is expected to exist.`,
-                ),
-              )
-            }
-          })
-      )->(Utils.magic: ((string, ~message: string=?) => promise<Internal.entity>) => unknown)
+      if isClickHouseOnly {
+        (
+          (_entityId: string, ~message as _=?) =>
+            throwClickHouseReadOnly(params.entityConfig, "getOrThrow")
+        )->(Utils.magic: ((string, ~message: string=?) => promise<Internal.entity>) => unknown)
+      } else {
+        (
+          (entityId, ~message=?) =>
+            LoadLayer.loadById(
+              ~loadManager=params.loadManager,
+              ~persistence=params.persistence,
+              ~entityConfig=params.entityConfig,
+              ~inMemoryStore=params.inMemoryStore,
+              ~shouldGroup=params.isPreload,
+              ~item=params.item,
+              ~entityId,
+            )->Promise.thenResolve(entity => {
+              switch entity {
+              | Some(entity) => entity
+              | None =>
+                JsError.throwWithMessage(
+                  message->Belt.Option.getWithDefault(
+                    `Entity '${params.entityConfig.name}' with ID '${entityId}' is expected to exist.`,
+                  ),
+                )
+              }
+            })
+        )->(Utils.magic: ((string, ~message: string=?) => promise<Internal.entity>) => unknown)
+      }
     | "getOrCreate" =>
-      (
-        (entity: Internal.entity) =>
-          LoadLayer.loadById(
-            ~loadManager=params.loadManager,
-            ~persistence=params.persistence,
-            ~entityConfig=params.entityConfig,
-            ~inMemoryStore=params.inMemoryStore,
-            ~shouldGroup=params.isPreload,
-            ~item=params.item,
-            ~entityId=entity.id,
-          )->Promise.thenResolve(storageEntity => {
-            switch storageEntity {
-            | Some(entity) => entity
-            | None => {
-                set(entity)
-                entity
+      if isClickHouseOnly {
+        (
+          (_entity: Internal.entity) => throwClickHouseReadOnly(params.entityConfig, "getOrCreate")
+        )->(Utils.magic: (Internal.entity => promise<Internal.entity>) => unknown)
+      } else {
+        (
+          (entity: Internal.entity) =>
+            LoadLayer.loadById(
+              ~loadManager=params.loadManager,
+              ~persistence=params.persistence,
+              ~entityConfig=params.entityConfig,
+              ~inMemoryStore=params.inMemoryStore,
+              ~shouldGroup=params.isPreload,
+              ~item=params.item,
+              ~entityId=entity.id,
+            )->Promise.thenResolve(storageEntity => {
+              switch storageEntity {
+              | Some(entity) => entity
+              | None => {
+                  set(entity)
+                  entity
+                }
               }
-            }
-          })
-      )->(Utils.magic: (Internal.entity => promise<Internal.entity>) => unknown)
+            })
+        )->(Utils.magic: (Internal.entity => promise<Internal.entity>) => unknown)
+      }
     | "set" => set->(Utils.magic: (Internal.entity => unit) => unknown)
     | "deleteUnsafe" =>
       if params.isPreload {

package/src/UserContext.res.mjs

@@ -119,7 +119,12 @@ function noopDeleteUnsafe(_entityId) {
   
 }
 
+function throwClickHouseReadOnly(entityConfig, op) {
+  return Stdlib_JsError.throwWithMessage(`context.` + entityConfig.name + `.` + op + `() is unavailable: ClickHouse storage is currently write-only. Follow Envio releases to be notified when ClickHouse supports both reads and writes from handlers.`);
+}
+
 let entityTraps_get = (params, prop) => {
+  let isClickHouseOnly = !params.entityConfig.storage.postgres;
   let set = params.isPreload ? noopSet : entity => InMemoryTable.Entity.set(InMemoryStore.getInMemTable(params.inMemoryStore, params.entityConfig), {
       type: "SET",
       entityId: entity.id,
@@ -138,26 +143,42 @@ let entityTraps_get = (params, prop) => {
         }, params.shouldSaveHistory, undefined);
       }
     case "get" :
-      return entityId => LoadLayer.loadById(params.loadManager, params.persistence, params.entityConfig, params.inMemoryStore, params.isPreload, params.item, entityId);
+      if (isClickHouseOnly) {
+        return _entityId => throwClickHouseReadOnly(params.entityConfig, "get");
+      } else {
+        return entityId => LoadLayer.loadById(params.loadManager, params.persistence, params.entityConfig, params.inMemoryStore, params.isPreload, params.item, entityId);
+      }
     case "getOrCreate" :
-      return entity => LoadLayer.loadById(params.loadManager, params.persistence, params.entityConfig, params.inMemoryStore, params.isPreload, params.item, entity.id).then(storageEntity => {
-        if (storageEntity !== undefined) {
-          return storageEntity;
-        } else {
-          set(entity);
-          return entity;
-        }
-      });
+      if (isClickHouseOnly) {
+        return _entity => throwClickHouseReadOnly(params.entityConfig, "getOrCreate");
+      } else {
+        return entity => LoadLayer.loadById(params.loadManager, params.persistence, params.entityConfig, params.inMemoryStore, params.isPreload, params.item, entity.id).then(storageEntity => {
+          if (storageEntity !== undefined) {
+            return storageEntity;
+          } else {
+            set(entity);
+            return entity;
+          }
+        });
+      }
     case "getOrThrow" :
-      return (entityId, message) => LoadLayer.loadById(params.loadManager, params.persistence, params.entityConfig, params.inMemoryStore, params.isPreload, params.item, entityId).then(entity => {
-        if (entity !== undefined) {
-          return entity;
-        } else {
-          return Stdlib_JsError.throwWithMessage(Belt_Option.getWithDefault(message, `Entity '` + params.entityConfig.name + `' with ID '` + entityId + `' is expected to exist.`));
-        }
-      });
+      if (isClickHouseOnly) {
+        return (_entityId, param) => throwClickHouseReadOnly(params.entityConfig, "getOrThrow");
+      } else {
+        return (entityId, message) => LoadLayer.loadById(params.loadManager, params.persistence, params.entityConfig, params.inMemoryStore, params.isPreload, params.item, entityId).then(entity => {
+          if (entity !== undefined) {
+            return entity;
+          } else {
+            return Stdlib_JsError.throwWithMessage(Belt_Option.getWithDefault(message, `Entity '` + params.entityConfig.name + `' with ID '` + entityId + `' is expected to exist.`));
+          }
+        });
+      }
     case "getWhere" :
-      return filter => getWhereHandler(params, filter);
+      if (isClickHouseOnly) {
+        return _filter => throwClickHouseReadOnly(params.entityConfig, "getWhere");
+      } else {
+        return filter => getWhereHandler(params, filter);
+      }
     case "set" :
       return set;
     default:
@@ -284,6 +305,7 @@ export {
   getWhereHandler,
   noopSet,
   noopDeleteUnsafe,
+  throwClickHouseReadOnly,
   entityTraps,
   handlerTraps,
   getHandlerContext,

package/src/bindings/ClickHouse.res

@@ -299,7 +299,12 @@ let setUpdatesOrThrow = async (
 }
 
 // Generate CREATE TABLE query for entity history table
-let makeCreateHistoryTableQuery = (~entityConfig: Internal.entityConfig, ~database: string) => {
+let makeCreateHistoryTableQuery = (
+  ~entityConfig: Internal.entityConfig,
+  ~database: string,
+  ~replicated: bool=false,
+) => {
+  let tableEngine = replicated ? "ReplicatedMergeTree" : "MergeTree()"
   let fieldDefinitions = entityConfig.table.fields->Belt.Array.keepMap(field => {
     switch field {
     | Field(field) =>
@@ -332,12 +337,13 @@ let makeCreateHistoryTableQuery = (~entityConfig: Internal.entityConfig, ~databa
       ~isArray=false,
     )}
 )
-ENGINE = MergeTree()
+ENGINE = ${tableEngine}
 ORDER BY (${Table.idFieldName}, ${EntityHistory.checkpointIdFieldName})`
 }
 
 // Generate CREATE TABLE query for checkpoints
-let makeCreateCheckpointsTableQuery = (~database: string) => {
+let makeCreateCheckpointsTableQuery = (~database: string, ~replicated: bool=false) => {
+  let tableEngine = replicated ? "ReplicatedMergeTree" : "MergeTree()"
   let idField = (#id: InternalTable.Checkpoints.field :> string)
   let chainIdField = (#chain_id: InternalTable.Checkpoints.field :> string)
   let blockNumberField = (#block_number: InternalTable.Checkpoints.field :> string)
@@ -367,7 +373,7 @@ let makeCreateCheckpointsTableQuery = (~database: string) => {
       ~isArray=false,
     )}
 )
-ENGINE = MergeTree()
+ENGINE = ${tableEngine}
 ORDER BY (${idField})`
 }
 
@@ -414,16 +420,43 @@ let initialize = async (
   ~enums as _: array<Table.enumConfig<Table.enum>>,
 ) => {
   try {
+    let replicated = Env.ClickHouse.replicated()
+    let databaseEngine = Env.ClickHouse.databaseEngine()
+    let databaseEngineClause = switch databaseEngine {
+    | Some(engine) => ` ENGINE = ${engine}`
+    | None => ""
+    }
+
+    switch databaseEngine {
+    | Some(engineSpec) => {
+        let expectedEngineName = engineSpec->String.split("(")->Belt.Array.getUnsafe(0)->String.trim
+        let existingResult = await client->query({
+          query: `SELECT engine FROM system.databases WHERE name = '${database}'`,
+        })
+        let rows: array<{"engine": string}> = await existingResult->json
+        switch rows->Belt.Array.get(0) {
+        | Some(row) if row["engine"] !== expectedEngineName =>
+          JsError.throwWithMessage(
+            `ClickHouse database "${database}" exists with engine "${row["engine"]}" but ENVIO_CLICKHOUSE_DATABASE_ENGINE specifies "${expectedEngineName}". Drop the database manually to change its engine.`,
+          )
+        | _ => ()
+        }
+      }
+    | None => ()
+    }
+
     await client->exec({query: `TRUNCATE DATABASE IF EXISTS ${database}`})
-    await client->exec({query: `CREATE DATABASE IF NOT EXISTS ${database}`})
+    await client->exec({
+      query: `CREATE DATABASE IF NOT EXISTS ${database}${databaseEngineClause}`,
+    })
     await client->exec({query: `USE ${database}`})
 
     await Promise.all(
       entities->Belt.Array.map(entityConfig =>
-        client->exec({query: makeCreateHistoryTableQuery(~entityConfig, ~database)})
+        client->exec({query: makeCreateHistoryTableQuery(~entityConfig, ~database, ~replicated)})
       ),
     )->Utils.Promise.ignoreValue
-    await client->exec({query: makeCreateCheckpointsTableQuery(~database)})
+    await client->exec({query: makeCreateCheckpointsTableQuery(~database, ~replicated)})
 
     await Promise.all(
       entities->Belt.Array.map(entityConfig =>
@@ -431,10 +464,10 @@ let initialize = async (
       ),
     )->Utils.Promise.ignoreValue
 
-    Logging.trace("ClickHouse sink initialization completed successfully")
+    Logging.trace("ClickHouse storage initialization completed successfully")
   } catch {
   | exn => {
-      Logging.errorWithExn(exn, "Failed to initialize ClickHouse sink")
+      Logging.errorWithExn(exn, "Failed to initialize ClickHouse storage")
       JsError.throwWithMessage("ClickHouse initialization failed")
     }
   }
@@ -450,7 +483,7 @@ let resume = async (client, ~database: string, ~checkpointId: Internal.checkpoin
     | exn =>
       Logging.errorWithExn(
         exn,
-        `ClickHouse sink database "${database}" not found. Please run 'envio start -r' to reinitialize the indexer (it'll also drop Postgres database).`,
+        `ClickHouse storage database "${database}" not found. Please run 'envio start -r' to reinitialize the indexer (it'll also drop Postgres database).`,
       )
       JsError.throwWithMessage("ClickHouse resume failed")
     }
@@ -478,7 +511,7 @@ let resume = async (client, ~database: string, ~checkpointId: Internal.checkpoin
   } catch {
   | Persistence.StorageError(_) as exn => throw(exn)
   | exn => {
-      Logging.errorWithExn(exn, "Failed to resume ClickHouse sink")
+      Logging.errorWithExn(exn, "Failed to resume ClickHouse storage")
       JsError.throwWithMessage("ClickHouse resume failed")
     }
   }

package/src/bindings/ClickHouse.res.mjs

@@ -1,5 +1,6 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as Env from "../Env.res.mjs";
 import * as Table from "../db/Table.res.mjs";
 import * as Utils from "../Utils.res.mjs";
 import * as Logging from "../Logging.res.mjs";
@@ -8,6 +9,7 @@ import * as Persistence from "../Persistence.res.mjs";
 import * as EntityHistory from "../db/EntityHistory.res.mjs";
 import * as InternalTable from "../db/InternalTable.res.mjs";
 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";
 import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
 
@@ -234,7 +236,9 @@ async function setUpdatesOrThrow(client, cache, updates, entityConfig, database)
   }
 }
 
-function makeCreateHistoryTableQuery(entityConfig, database) {
+function makeCreateHistoryTableQuery(entityConfig, database, replicatedOpt) {
+  let replicated = replicatedOpt !== undefined ? replicatedOpt : false;
+  let tableEngine = replicated ? "ReplicatedMergeTree" : "MergeTree()";
   let fieldDefinitions = Belt_Array.keepMap(entityConfig.table.fields, field => {
     if (field.TAG !== "Field") {
       return;
@@ -252,11 +256,13 @@ function makeCreateHistoryTableQuery(entityConfig, database) {
     config: EntityHistory.RowAction.config
   }, false, false) + `
 )
-ENGINE = MergeTree()
+ENGINE = ` + tableEngine + `
 ORDER BY (` + Table.idFieldName + `, ` + EntityHistory.checkpointIdFieldName + `)`;
 }
 
-function makeCreateCheckpointsTableQuery(database) {
+function makeCreateCheckpointsTableQuery(database, replicatedOpt) {
+  let replicated = replicatedOpt !== undefined ? replicatedOpt : false;
+  let tableEngine = replicated ? "ReplicatedMergeTree" : "MergeTree()";
   return `CREATE TABLE IF NOT EXISTS ` + database + `.\`` + InternalTable.Checkpoints.table.tableName + `\` (
   \`` + "id" + `\` ` + getClickHouseFieldType("UInt64", false, false) + `,
   \`` + "chain_id" + `\` ` + getClickHouseFieldType("Int32", false, false) + `,
@@ -264,7 +270,7 @@ function makeCreateCheckpointsTableQuery(database) {
   \`` + "block_hash" + `\` ` + getClickHouseFieldType("String", true, false) + `,
   \`` + "events_processed" + `\` ` + getClickHouseFieldType("UInt64", false, false) + `
 )
-ENGINE = MergeTree()
+ENGINE = ` + tableEngine + `
 ORDER BY (` + "id" + `)`;
 }
 
@@ -292,28 +298,45 @@ WHERE \`` + EntityHistory.changeFieldName + `\` = '` + "SET" + `'`;
 
 async function initialize(client, database, entities, param) {
   try {
+    let replicated = Env.ClickHouse.replicated();
+    let databaseEngine = Env.ClickHouse.databaseEngine();
+    let databaseEngineClause = databaseEngine !== undefined ? ` ENGINE = ` + databaseEngine : "";
+    if (databaseEngine !== undefined) {
+      let expectedEngineName = databaseEngine.split("(")[0].trim();
+      let existingResult = await client.query({
+        query: `SELECT engine FROM system.databases WHERE name = '` + database + `'`
+      });
+      let rows = await existingResult.json();
+      let row = Belt_Array.get(rows, 0);
+      if (row !== undefined) {
+        let row$1 = Primitive_option.valFromOption(row);
+        if (row$1.engine !== expectedEngineName) {
+          Stdlib_JsError.throwWithMessage(`ClickHouse database "` + database + `" exists with engine "` + row$1.engine + `" but ENVIO_CLICKHOUSE_DATABASE_ENGINE specifies "` + expectedEngineName + `". Drop the database manually to change its engine.`);
+        }
+      }
+    }
     await client.exec({
       query: `TRUNCATE DATABASE IF EXISTS ` + database
     });
     await client.exec({
-      query: `CREATE DATABASE IF NOT EXISTS ` + database
+      query: `CREATE DATABASE IF NOT EXISTS ` + database + databaseEngineClause
     });
     await client.exec({
       query: `USE ` + database
     });
     await Promise.all(Belt_Array.map(entities, entityConfig => client.exec({
-      query: makeCreateHistoryTableQuery(entityConfig, database)
+      query: makeCreateHistoryTableQuery(entityConfig, database, replicated)
     })));
     await client.exec({
-      query: makeCreateCheckpointsTableQuery(database)
+      query: makeCreateCheckpointsTableQuery(database, replicated)
     });
     await Promise.all(Belt_Array.map(entities, entityConfig => client.exec({
       query: makeCreateViewQuery(entityConfig, database)
     })));
-    return Logging.trace("ClickHouse sink initialization completed successfully");
+    return Logging.trace("ClickHouse storage initialization completed successfully");
   } catch (raw_exn) {
     let exn = Primitive_exceptions.internalToException(raw_exn);
-    Logging.errorWithExn(exn, "Failed to initialize ClickHouse sink");
+    Logging.errorWithExn(exn, "Failed to initialize ClickHouse storage");
     return Stdlib_JsError.throwWithMessage("ClickHouse initialization failed");
   }
 }
@@ -326,7 +349,7 @@ async function resume(client, database, checkpointId) {
       });
     } catch (raw_exn) {
       let exn = Primitive_exceptions.internalToException(raw_exn);
-      Logging.errorWithExn(exn, `ClickHouse sink database "` + database + `" not found. Please run 'envio start -r' to reinitialize the indexer (it'll also drop Postgres database).`);
+      Logging.errorWithExn(exn, `ClickHouse storage database "` + database + `" not found. Please run 'envio start -r' to reinitialize the indexer (it'll also drop Postgres database).`);
       Stdlib_JsError.throwWithMessage("ClickHouse resume failed");
     }
     let tablesResult = await client.query({
@@ -347,7 +370,7 @@ async function resume(client, database, checkpointId) {
     if (exn$1.RE_EXN_ID === Persistence.StorageError) {
       throw exn$1;
     }
-    Logging.errorWithExn(exn$1, "Failed to resume ClickHouse sink");
+    Logging.errorWithExn(exn$1, "Failed to resume ClickHouse storage");
     return Stdlib_JsError.throwWithMessage("ClickHouse resume failed");
   }
 }

package/src/tui/Tui.res

@@ -78,15 +78,52 @@ module ChainLine = {
   }
 }
 
+module EventsPerSecond = {
+  type sample = {time: float, events: float}
+
+  let windowMs = 60_000.
+
+  let computeEps = (samples: array<sample>) => {
+    let len = samples->Array.length
+    switch (samples->Array.get(0), samples->Array.get(len - 1)) {
+    | (Some(first), Some(last)) if last.time > first.time =>
+      Some((last.events -. first.events) /. ((last.time -. first.time) /. 1000.))
+    | _ => None
+    }
+  }
+
+  let use = (~totalEventsProcessed: float) => {
+    let (samples, setSamples) = React.useState((): array<sample> => [])
+
+    React.useEffect1(() => {
+      let now = Date.now()
+      let cutoff = now -. windowMs
+      setSamples(prev => {
+        let kept = prev->Array.filter(s => s.time >= cutoff)
+        kept->Array.concat([{time: now, events: totalEventsProcessed}])
+      })
+      None
+    }, [totalEventsProcessed])
+
+    computeEps(samples)
+  }
+}
+
 module TotalEventsProcessed = {
   @react.component
-  let make = (~totalEventsProcessed) => {
-    let label = "Total Events: "
+  let make = (~totalEventsProcessed, ~eventsPerSecond: option<float>) => {
     <Text>
-      <Text bold=true> {label->React.string} </Text>
+      <Text bold=true> {"Total Events: "->React.string} </Text>
       <Text color={Secondary}>
         {`${totalEventsProcessed->TuiData.formatFloatLocaleString}`->React.string}
       </Text>
+      {switch eventsPerSecond {
+      | Some(eps) =>
+        <Text color={Gray}>
+          {` (${Math.round(eps)->TuiData.formatFloatLocaleString} events/sec)`->React.string}
+        </Text>
+      | None => React.null
+      }}
     </Text>
   }
 }
@@ -188,6 +225,7 @@ module App = {
         acc
       }
     })
+    let eventsPerSecond = EventsPerSecond.use(~totalEventsProcessed)
 
     <Box flexDirection={Column}>
       <BigText
@@ -214,7 +252,10 @@ module App = {
         />
       })
       ->React.array}
-      <TotalEventsProcessed totalEventsProcessed />
+      <TotalEventsProcessed
+        totalEventsProcessed
+        eventsPerSecond={SyncETA.isIndexerFullySynced(chains) ? None : eventsPerSecond}
+      />
       <SyncETA chains indexerStartTime=state.indexerStartTime />
       <Newline />
       <Box flexDirection={Row}>

package/src/tui/Tui.res.mjs

@@ -136,7 +136,40 @@ let ChainLine = {
   make: Tui$ChainLine
 };
 
+function computeEps(samples) {
+  let len = samples.length;
+  let match = samples[0];
+  let match$1 = samples[len - 1 | 0];
+  if (match !== undefined && match$1 !== undefined && match$1.time > match.time) {
+    return (match$1.events - match.events) / ((match$1.time - match.time) / 1000);
+  }
+}
+
+function use(totalEventsProcessed) {
+  let match = React.useState(() => []);
+  let setSamples = match[1];
+  React.useEffect(() => {
+    let now = Date.now();
+    let cutoff = now - 60000;
+    setSamples(prev => {
+      let kept = prev.filter(s => s.time >= cutoff);
+      return kept.concat([{
+          time: now,
+          events: totalEventsProcessed
+        }]);
+    });
+  }, [totalEventsProcessed]);
+  return computeEps(match[0]);
+}
+
+let EventsPerSecond = {
+  windowMs: 60000,
+  computeEps: computeEps,
+  use: use
+};
+
 function Tui$TotalEventsProcessed(props) {
+  let eventsPerSecond = props.eventsPerSecond;
   return JsxRuntime.jsxs(Ink$1.Text, {
     children: [
       JsxRuntime.jsx(Ink$1.Text, {
@@ -146,7 +179,11 @@ function Tui$TotalEventsProcessed(props) {
       JsxRuntime.jsx(Ink$1.Text, {
         children: TuiData.formatFloatLocaleString(props.totalEventsProcessed),
         color: "#FFBB2F"
-      })
+      }),
+      eventsPerSecond !== undefined ? JsxRuntime.jsx(Ink$1.Text, {
+          children: ` (` + TuiData.formatFloatLocaleString(Math.round(eventsPerSecond)) + ` events/sec)`,
+          color: "gray"
+        }) : null
     ]
   });
 }
@@ -229,6 +266,7 @@ function Tui$App(props) {
       return acc;
     }
   });
+  let eventsPerSecond = use(totalEventsProcessed);
   let defaultPassword = "testing";
   let match$1 = state.ctx.config.storage.clickhouse;
   let match$2 = Env.ClickHouse.host();
@@ -257,7 +295,8 @@ function Tui$App(props) {
         eventsProcessed: chainData.eventsProcessed
       }, i.toString())),
       JsxRuntime.jsx(Tui$TotalEventsProcessed, {
-        totalEventsProcessed: totalEventsProcessed
+        totalEventsProcessed: totalEventsProcessed,
+        eventsPerSecond: SyncETA.isIndexerFullySynced(chains) ? undefined : eventsPerSecond
       }),
       JsxRuntime.jsx(SyncETA.make, {
         chains: chains,
@@ -331,6 +370,7 @@ function start(getState) {
 
 export {
   ChainLine,
+  EventsPerSecond,
   TotalEventsProcessed,
   App,
   start,