Extend ensdb-sdk with EnsDbConfig data model

.changeset/fluffy-forks-film.md

@@ -0,0 +1,5 @@
+---
+"@ensnode/ensdb-sdk": minor
+---
+
+Added `validateEnsDbConfig` function to support validation for the `EnsDbConfig` data model.

apps/ensapi/package.json

@@ -58,7 +58,6 @@
     "hono": "catalog:",
     "p-memoize": "^8.0.0",
     "p-retry": "catalog:",
-    "pg-connection-string": "catalog:",
     "pino": "catalog:",
     "ponder-enrich-gql-docs-middleware": "^0.1.3",
     "superjson": "^2.2.6",

apps/ensapi/src/config/config.schema.test.ts

@@ -11,6 +11,13 @@ vi.mock("@/lib/ensdb/singleton", () => ({
   },
 }));
 
+vi.mock("@/config/ensdb-config", () => ({
+  default: {
+    ensDbUrl: "postgresql://user:password@localhost:5432/mydb",
+    ensIndexerSchemaName: "ensindexer_0",
+  },
+}));
+
 import { buildConfigFromEnvironment, buildEnsApiPublicConfig } from "@/config/config.schema";
 import { ENSApi_DEFAULT_PORT } from "@/config/defaults";
 import type { EnsApiEnvironment } from "@/config/environment";
@@ -97,9 +104,7 @@ describe("buildConfigFromEnvironment", () => {
       mockExit.mockClear();
     });
 
-    const TEST_ENV: EnsApiEnvironment = {
-      ENSDB_URL: BASE_ENV.ENSDB_URL,
-    };
+    const TEST_ENV: EnsApiEnvironment = structuredClone(BASE_ENV);
 
     it("logs error and exits when CUSTOM_REFERRAL_PROGRAM_EDITIONS is not a valid URL", async () => {
       await buildConfigFromEnvironment({

apps/ensapi/src/config/config.schema.ts

@@ -14,7 +14,7 @@ import {
 } from "@ensnode/ensnode-sdk/internal";
 
 import { ENSApi_DEFAULT_PORT } from "@/config/defaults";
-import { EnsDbConfigSchema } from "@/config/ensdb-config.schema";
+import ensDbConfig from "@/config/ensdb-config";
 import type { EnsApiEnvironment } from "@/config/environment";
 import { invariant_ensIndexerPublicConfigVersionInfo } from "@/config/validations";
 import { ensDbClient } from "@/lib/ensdb/singleton";
@@ -47,8 +47,11 @@ const EnsApiConfigSchema = z
     rpcConfigs: RpcConfigsSchema,
     ensIndexerPublicConfig: makeENSIndexerPublicConfigSchema("ensIndexerPublicConfig"),
     customReferralProgramEditionConfigSetUrl: CustomReferralProgramEditionConfigSetUrlSchema,
+
+    // include the ENSDbConfig params in the EnsApiConfigSchema
+    ensDbUrl: z.string(),
+    ensIndexerSchemaName: z.string(),
   })
-  .extend(EnsDbConfigSchema.shape)
   .check(invariant_rpcConfigsSpecifiedForRootChain)
   .check(invariant_ensIndexerPublicConfigVersionInfo);
 
@@ -89,13 +92,15 @@ export async function buildConfigFromEnvironment(env: EnsApiEnvironment): Promis
 
     return EnsApiConfigSchema.parse({
       port: env.PORT,
-      ensDbUrl: env.ENSDB_URL,
       theGraphApiKey: env.THEGRAPH_API_KEY,
       ensIndexerPublicConfig,
       namespace: ensIndexerPublicConfig.namespace,
-      ensIndexerSchemaName: ensIndexerPublicConfig.ensIndexerSchemaName,
       rpcConfigs,
       customReferralProgramEditionConfigSetUrl: env.CUSTOM_REFERRAL_PROGRAM_EDITIONS,
+
+      // include the validated ENSDb config values in the parsed EnsApiConfig
+      ensDbUrl: ensDbConfig.ensDbUrl,
+      ensIndexerSchemaName: ensDbConfig.ensIndexerSchemaName,
     });
   } catch (error) {
     if (error instanceof ZodError) {

apps/ensapi/src/config/ensdb-config.ts

@@ -1,3 +1,31 @@
-import { buildEnsDbConfigFromEnvironment } from "./ensdb-config.schema";
+import { type EnsDbConfig, validateEnsDbConfig } from "@ensnode/ensdb-sdk";
+import type { Unvalidated } from "@ensnode/ensnode-sdk";
 
-export default buildEnsDbConfigFromEnvironment(process.env);
+import { lazyProxy } from "@/lib/lazy";
+import logger from "@/lib/logger";
+
+/**
+ * Build ENSDb config from environment variables for ENSApi app.
+ *
+ * Exits the process if the configuration is invalid, logging the error details.
+ */
+export function buildEnsDbConfigFromEnvironment(env: NodeJS.ProcessEnv): EnsDbConfig {
+  const unvalidatedConfig = {
+    ensDbUrl: env.ENSDB_URL,
+    ensIndexerSchemaName: env.ENSINDEXER_SCHEMA_NAME,
+  } satisfies Unvalidated<EnsDbConfig>;
+
+  try {
+    return validateEnsDbConfig(unvalidatedConfig);
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    logger.error(`Failed to validate ENSDb config from environment: ${errorMessage}`);
+    process.exit(1);
+  }
+}
+
+// lazyProxy defers construction until first use so that this module can be
+// imported without env vars being present (e.g. during OpenAPI generation).
+const ensDbConfig = lazyProxy<EnsDbConfig>(() => buildEnsDbConfigFromEnvironment(process.env));
+
+export default ensDbConfig;

apps/ensapi/src/lib/ensdb/singleton.ts

@@ -1,6 +1,6 @@
 import { EnsDbReader } from "@ensnode/ensdb-sdk";
 
-import { buildEnsDbConfigFromEnvironment } from "@/config/ensdb-config.schema";
+import { buildEnsDbConfigFromEnvironment } from "@/config/ensdb-config";
 import { lazyProxy } from "@/lib/lazy";
 
 // lazyProxy defers construction until first use so that this module can be

apps/ensindexer/package.json

@@ -34,7 +34,6 @@
     "deepmerge-ts": "^7.1.5",
     "dns-packet": "^5.6.1",
     "drizzle-orm": "catalog:",
-    "pg-connection-string": "catalog:",
     "p-retry": "catalog:",
     "hono": "catalog:",
     "ponder": "catalog:",

apps/ensindexer/src/config/config.schema.ts

@@ -1,11 +1,9 @@
-import { parse as parseConnectionString } from "pg-connection-string";
 import { prettifyError, ZodError, z } from "zod/v4";
 
 import { buildBlockNumberRange, PluginName, uniq } from "@ensnode/ensnode-sdk";
 import {
   buildRpcConfigsFromEnv,
   ENSNamespaceSchema,
-  EnsIndexerSchemaNameSchema,
   invariant_isSubgraphCompatibleRequirements,
   invariant_rpcConfigsSpecifiedForRootChain,
   makeFullyPinnedLabelSetSchema,
@@ -14,6 +12,7 @@ import {
 } from "@ensnode/ensnode-sdk/internal";
 
 import { DEFAULT_SUBGRAPH_COMPAT } from "@/config/defaults";
+import ensDbConfig from "@/config/ensdb-config";
 import type { ENSIndexerEnvironment } from "@/config/environment";
 import { applyDefaults, EnvironmentDefaults } from "@/config/environment-defaults";
 
@@ -27,24 +26,6 @@ import {
   invariant_validContractConfigs,
 } from "./validations";
 
-export const EnsDbUrlSchema = z.string().refine(
-  (url) => {
-    try {
-      if (!url.startsWith("postgresql://") && !url.startsWith("postgres://")) {
-        return false;
-      }
-      const config = parseConnectionString(url);
-      return !!(config.host && config.port && config.database);
-    } catch {
-      return false;
-    }
-  },
-  {
-    error:
-      "Invalid PostgreSQL connection string for ENSDb. Expected format: postgresql://username:password@host:port/database",
-  },
-);
-
 // parses an env string bool with strict requirement of 'true' or 'false'
 const makeEnvStringBoolSchema = (envVarKey: string) =>
   z
@@ -106,8 +87,6 @@ const IsSubgraphCompatibleSchema =
 
 const ENSIndexerConfigSchema = z
   .object({
-    ensDbUrl: EnsDbUrlSchema,
-    ensIndexerSchemaName: EnsIndexerSchemaNameSchema,
     rpcConfigs: RpcConfigsSchema,
 
     namespace: ENSNamespaceSchema,
@@ -116,6 +95,10 @@ const ENSIndexerConfigSchema = z
     globalBlockrange: BlockrangeSchema,
     ensRainbowUrl: EnsRainbowUrlSchema,
     labelSet: LabelSetSchema,
+
+    // include the ENSDbConfig params in the ENSIndexerConfigSchema
+    ensDbUrl: z.string(),
+    ensIndexerSchemaName: z.string(),
   })
   /**
    * Derived configuration
@@ -184,8 +167,6 @@ export function buildConfigFromEnvironment(_env: ENSIndexerEnvironment): EnsInde
 
     // parse/validate with ENSIndexerConfigSchema
     return ENSIndexerConfigSchema.parse({
-      ensDbUrl: env.ENSDB_URL,
-      ensIndexerSchemaName: env.ENSINDEXER_SCHEMA_NAME,
       namespace: env.NAMESPACE,
       rpcConfigs,
 
@@ -200,6 +181,10 @@ export function buildConfigFromEnvironment(_env: ENSIndexerEnvironment): EnsInde
         labelSetId: env.LABEL_SET_ID,
         labelSetVersion: env.LABEL_SET_VERSION,
       },
+
+      // include the validated ENSDb config values in the parsed EnsIndexerConfig
+      ensDbUrl: ensDbConfig.ensDbUrl,
+      ensIndexerSchemaName: ensDbConfig.ensIndexerSchemaName,
     });
   } catch (error) {
     if (error instanceof ZodError) {

apps/ensindexer/src/config/config.test.ts

@@ -1,5 +1,28 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
+// For config.test.ts, we need a mock that validates env vars without providing defaults,
+// because this test file specifically tests validation failures.
+vi.mock("@/config/ensdb-config", async () => {
+  const { validateEnsDbConfig } =
+    await vi.importActual<typeof import("@ensnode/ensdb-sdk")>("@ensnode/ensdb-sdk");
+  return {
+    default: {
+      get ensDbUrl() {
+        const url = process.env.ENSDB_URL;
+        const schema = process.env.ENSINDEXER_SCHEMA_NAME;
+        validateEnsDbConfig({ ensDbUrl: url, ensIndexerSchemaName: schema });
+        return url;
+      },
+      get ensIndexerSchemaName() {
+        const url = process.env.ENSDB_URL;
+        const schema = process.env.ENSINDEXER_SCHEMA_NAME;
+        validateEnsDbConfig({ ensDbUrl: url, ensIndexerSchemaName: schema });
+        return schema;
+      },
+    },
+  };
+});
+
 import {
   type ENSNamespaceId,
   ensTestEnvChain,
@@ -170,21 +193,17 @@ describe("config (with base env)", () => {
 
     it("throws an error when ENSINDEXER_SCHEMA_NAME is not set", async () => {
       vi.stubEnv("ENSINDEXER_SCHEMA_NAME", undefined);
-      await expect(getConfig()).rejects.toThrow(/ENSINDEXER_SCHEMA_NAME is required/);
+      await expect(getConfig()).rejects.toThrow(/ENSIndexer Schema Name is required/);
     });
 
     it("throws an error when ENSINDEXER_SCHEMA_NAME is empty", async () => {
       vi.stubEnv("ENSINDEXER_SCHEMA_NAME", "");
-      await expect(getConfig()).rejects.toThrow(
-        /ENSINDEXER_SCHEMA_NAME is required and cannot be an empty string/,
-      );
+      await expect(getConfig()).rejects.toThrow(/ENSIndexer Schema Name cannot be an empty string/);
     });
 
     it("throws an error when ENSINDEXER_SCHEMA_NAME is only whitespace", async () => {
       vi.stubEnv("ENSINDEXER_SCHEMA_NAME", "   ");
-      await expect(getConfig()).rejects.toThrow(
-        /ENSINDEXER_SCHEMA_NAME is required and cannot be an empty string/,
-      );
+      await expect(getConfig()).rejects.toThrow(/ENSIndexer Schema Name cannot be an empty string/);
     });
   });
 

apps/ensindexer/src/config/ensdb-config.ts

@@ -0,0 +1,24 @@
+import { type EnsDbConfig, validateEnsDbConfig } from "@ensnode/ensdb-sdk";
+import type { Unvalidated } from "@ensnode/ensnode-sdk";
+
+/**
+ * Build ENSDb config from environment variables for ENSIndexer app.
+ *
+ * Exits the process if the configuration is invalid, logging the error details.
+ */
+function buildEnsDbConfigFromEnvironment(env: NodeJS.ProcessEnv): EnsDbConfig {
+  const unvalidatedConfig = {
+    ensDbUrl: env.ENSDB_URL,
+    ensIndexerSchemaName: env.ENSINDEXER_SCHEMA_NAME,
+  } satisfies Unvalidated<EnsDbConfig>;
+
+  try {
+    return validateEnsDbConfig(unvalidatedConfig);
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    console.error(`Failed to validate ENSDb config from environment: ${errorMessage}`);
+    process.exit(1);
+  }
+}
+
+export default buildEnsDbConfigFromEnvironment(process.env);

apps/ensindexer/src/config/types.ts

@@ -1,11 +1,7 @@
 import type { ENSNamespaceId } from "@ensnode/datasources";
+import type { EnsDbConfig } from "@ensnode/ensdb-sdk";
 import type { BlockNumberRange, ChainId, PluginName } from "@ensnode/ensnode-sdk";
-import {
-  type DatabaseUrl,
-  type EnsIndexerSchemaName,
-  RpcConfig,
-  type RpcConfigs,
-} from "@ensnode/ensnode-sdk/internal";
+import { RpcConfig, type RpcConfigs } from "@ensnode/ensnode-sdk/internal";
 import type { EnsRainbowClientLabelSet } from "@ensnode/ensrainbow-sdk";
 
 /**
@@ -81,7 +77,7 @@ export interface EnsIndexerConfig {
    * Invariants:
    * - Must be a non-empty string that is a valid Postgres database schema identifier.
    */
-  ensIndexerSchemaName: EnsIndexerSchemaName;
+  ensIndexerSchemaName: EnsDbConfig["ensIndexerSchemaName"];
 
   /**
    * A set of {@link PluginName}s indicating which plugins to activate.
@@ -119,7 +115,7 @@ export interface EnsIndexerConfig {
    * Invariants:
    * - The URL must be a valid PostgreSQL connection string
    */
-  ensDbUrl: DatabaseUrl;
+  ensDbUrl: EnsDbConfig["ensDbUrl"];
 
   /**
    * Constrains the global blockrange for indexing, useful for testing purposes.