Update ENSDb schema definitions

apps/ensapi/src/lib/db.ts

@@ -2,9 +2,12 @@ import config from "@/config";
 
 import * as schema from "@ensnode/ensnode-schema";
 
-import { makeDrizzle } from "@/lib/handlers/drizzle";
+import { makeReadOnlyDrizzle } from "@/lib/handlers/drizzle";
 
-export const db = makeDrizzle({
+/**
+ * Read-only Drizzle instance for ENSDb queries to ENSIndexer Schema
+ */
+export const db = makeReadOnlyDrizzle({
   databaseUrl: config.databaseUrl,
   databaseSchema: config.databaseSchemaName,
   schema,

apps/ensapi/src/lib/handlers/drizzle.ts

@@ -1,5 +1,6 @@
 import { setDatabaseSchema } from "@ponder/client";
 import { drizzle } from "drizzle-orm/node-postgres";
+import { parseIntoClientConfig } from "pg-connection-string";
 
 import { makeLogger } from "@/lib/logger";
 
@@ -8,9 +9,9 @@ type Schema = { [name: string]: unknown };
 const logger = makeLogger("drizzle");
 
 /**
- * Makes a Drizzle DB object.
+ * Makes a read-only Drizzle DB object.
  */
-export const makeDrizzle = <SCHEMA extends Schema>({
+export const makeReadOnlyDrizzle = <SCHEMA extends Schema>({
   schema,
   databaseUrl,
   databaseSchema,
@@ -22,7 +23,11 @@ export const makeDrizzle = <SCHEMA extends Schema>({
   // monkeypatch schema onto tables
   setDatabaseSchema(schema, databaseSchema);
 
-  return drizzle(databaseUrl, {
+  return drizzle({
+    connection: {
+      ...parseIntoClientConfig(databaseUrl),
+      options: "-c default_transaction_read_only=on",
+    },
     schema,
     casing: "snake_case",
     logger: {

apps/ensindexer/src/lib/ensdb-client/ensdb-client.test.ts

@@ -1,6 +1,6 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
-import { ensNodeMetadata } from "@ensnode/ensnode-schema";
+import * as ensNodeSchema from "@ensnode/ensnode-schema/ensnode";
 import {
   deserializeCrossChainIndexingStatusSnapshot,
   EnsNodeMetadataKeys,
@@ -59,7 +59,7 @@ describe("EnsDbClient", () => {
       await expect(client.getEnsDbVersion()).resolves.toBeUndefined();
 
       expect(selectMock).toHaveBeenCalledTimes(1);
-      expect(fromMock).toHaveBeenCalledWith(ensNodeMetadata);
+      expect(fromMock).toHaveBeenCalledWith(ensNodeSchema.ensNodeMetadata);
     });
 
     it("returns value when one record exists", async () => {
@@ -150,13 +150,14 @@ describe("EnsDbClient", () => {
       await client.upsertEnsDbVersion("0.2.0");
 
       // assert
-      expect(insertMock).toHaveBeenCalledWith(ensNodeMetadata);
+      expect(insertMock).toHaveBeenCalledWith(ensNodeSchema.ensNodeMetadata);
       expect(valuesMock).toHaveBeenCalledWith({
+        ensIndexerRef: ensDbClientMock.databaseSchemaName,
         key: EnsNodeMetadataKeys.EnsDbVersion,
         value: "0.2.0",
       });
       expect(onConflictDoUpdateMock).toHaveBeenCalledWith({
-        target: ensNodeMetadata.key,
+        target: [ensNodeSchema.ensNodeMetadata.ensIndexerRef, ensNodeSchema.ensNodeMetadata.key],
         set: { value: "0.2.0" },
       });
     });
@@ -176,6 +177,7 @@ describe("EnsDbClient", () => {
 
       // assert
       expect(valuesMock).toHaveBeenCalledWith({
+        ensIndexerRef: ensDbClientMock.databaseSchemaName,
         key: EnsNodeMetadataKeys.EnsIndexerPublicConfig,
         value: expectedValue,
       });
@@ -199,6 +201,7 @@ describe("EnsDbClient", () => {
 
       // assert
       expect(valuesMock).toHaveBeenCalledWith({
+        ensIndexerRef: ensDbClientMock.databaseSchemaName,
         key: EnsNodeMetadataKeys.EnsIndexerIndexingStatus,
         value: expectedValue,
       });

apps/ensindexer/src/lib/ensdb-client/ensdb-client.ts

@@ -1,7 +1,7 @@
 import type { NodePgDatabase } from "drizzle-orm/node-postgres";
-import { eq, sql } from "drizzle-orm/sql";
+import { and, eq, sql } from "drizzle-orm/sql";
 
-import { ensNodeMetadata } from "@ensnode/ensnode-schema";
+import * as ensNodeSchema from "@ensnode/ensnode-schema/ensnode";
 import {
   type CrossChainIndexingStatusSnapshot,
   deserializeCrossChainIndexingStatusSnapshot,
@@ -20,21 +20,12 @@ import {
 
 import { makeDrizzle } from "./drizzle";
 
-/**
- * ENSDb Client Schema
- *
- * Includes schema definitions for {@link EnsDbClient} queries and mutations.
- */
-const schema = {
-  ensNodeMetadata,
-};
-
 /**
  * Drizzle database
  *
  * Allows interacting with Postgres database for ENSDb, using Drizzle ORM.
  */
-interface DrizzleDb extends NodePgDatabase<typeof schema> {}
+interface DrizzleDb extends NodePgDatabase<typeof ensNodeSchema> {}
 
 /**
  * ENSDb Client
@@ -53,16 +44,23 @@ export class EnsDbClient implements EnsDbClientQuery, EnsDbClientMutation {
    */
   private db: DrizzleDb;
 
+  /**
+   * ENSIndexer reference string for multi-tenancy in ENSDb.
+   */
+  private ensIndexerRef: string;
+
   /**
    * @param databaseUrl connection string for ENSDb Postgres database
-   * @param databaseSchemaName Postgres schema name for ENSDb tables
+   * @param ensIndexerRef reference string for ENSIndexer instance (used for multi-tenancy in ENSDb)
    */
-  constructor(databaseUrl: string, databaseSchemaName: string) {
+  constructor(databaseUrl: string, ensIndexerRef: string) {
     this.db = makeDrizzle({
-      databaseSchema: databaseSchemaName,
+      databaseSchema: ensNodeSchema.ENSNODE_SCHEMA_NAME,
       databaseUrl,
-      schema,
+      schema: ensNodeSchema,
     });
+
+    this.ensIndexerRef = ensIndexerRef;
   }
 
   /**
@@ -154,8 +152,13 @@ export class EnsDbClient implements EnsDbClientQuery, EnsDbClientMutation {
   ): Promise<EnsNodeMetadataType["value"] | undefined> {
     const result = await this.db
       .select()
-      .from(ensNodeMetadata)
-      .where(eq(ensNodeMetadata.key, metadata.key));
+      .from(ensNodeSchema.ensNodeMetadata)
+      .where(
+        and(
+          eq(ensNodeSchema.ensNodeMetadata.ensIndexerRef, this.ensIndexerRef),
+          eq(ensNodeSchema.ensNodeMetadata.key, metadata.key),
+        ),
+      );
 
     if (result.length === 0) {
       return undefined;
@@ -186,13 +189,14 @@ export class EnsDbClient implements EnsDbClientQuery, EnsDbClientMutation {
       );
 
       await tx
-        .insert(ensNodeMetadata)
+        .insert(ensNodeSchema.ensNodeMetadata)
         .values({
+          ensIndexerRef: this.ensIndexerRef,
           key: metadata.key,
           value: metadata.value,
         })
         .onConflictDoUpdate({
-          target: ensNodeMetadata.key,
+          target: [ensNodeSchema.ensNodeMetadata.ensIndexerRef, ensNodeSchema.ensNodeMetadata.key],
           set: { value: metadata.value },
         });
     });

packages/ensnode-schema/package.json

@@ -16,34 +16,60 @@
     "Ponder"
   ],
   "exports": {
-    ".": "./src/ponder.schema.ts"
+    ".": "./src/index.ts",
+    "./ponder": "./src/ponder-schema/index.ts",
+    "./ensindexer": "./src/ensindexer-schema/index.ts",
+    "./ensnode": "./src/ensnode-schema/index.ts"
   },
   "files": [
     "dist"
   ],
   "publishConfig": {
     "access": "public",
     "exports": {
-      "types": "./dist/ponder.schema.d.ts",
-      "default": "./dist/ponder.schema.js"
-    },
-    "main": "./dist/ponder.schema.js",
-    "module": "./dist/ponder.schema.mjs",
-    "types": "./dist/ponder.schema.d.ts"
+      ".": {
+        "import": {
+          "types": "./dist/index.d.ts",
+          "default": "./dist/index.js"
+        }
+      },
+      "./ponder": {
+        "import": {
+          "types": "./dist/ponder-schema.d.ts",
+          "default": "./dist/ponder-schema.js"
+        }
+      },
+      "./ensindexer": {
+        "import": {
+          "types": "./dist/ensindexer-schema.d.ts",
+          "default": "./dist/ensindexer-schema.js"
+        }
+      },
+      "./ensnode": {
+        "import": {
+          "types": "./dist/ensnode-schema.d.ts",
+          "default": "./dist/ensnode-schema.js"
+        }
+      }
+    }
   },
   "scripts": {
     "prepublish": "tsup",
     "lint": "biome check --write .",
     "lint:ci": "biome ci"
   },
-  "dependencies": {
+  "peerDependencies": {
+    "drizzle-orm": "catalog:",
     "ponder": "catalog:",
     "viem": "catalog:"
   },
   "devDependencies": {
     "@ensnode/ensnode-sdk": "workspace:",
     "@ensnode/shared-configs": "workspace:*",
+    "drizzle-orm": "catalog:",
+    "ponder": "catalog:",
     "tsup": "catalog:",
-    "typescript": "catalog:"
+    "typescript": "catalog:",
+    "viem": "catalog:"
   }
 }

packages/ensnode-schema/src/README.md

@@ -0,0 +1,28 @@
+# ENSDb Schemas
+
+Package defining database schemas used in ENSDb.
+
+## Ponder Schema
+
+- Owned by Ponder app.
+- Shared across ENSIndexer instances.
+- Includes responses to RPC requests made by cached public clients.
+- Usually large in size, depending on selected ENS Namespace.
+- Takes a long time to build.
+- Backups highly recommended for sharing RPC cache across different ENSNode environments.
+  - For example, pulling production backup into local environment in order to test production workflows in isolation.
+
+## ENSIndexer Schema
+
+- Owned by an ENSIndexer instance and also influenced by Ponder implementation details, as ENSIndexer is a Ponder app.
+- Isolated for specific ENSIndexer instance.
+- Includes indexed data based on event handlers logic from active ENSIndexer plugins.
+- May be large in size, depending on selected ENS Namespace and active plugins.
+- May take a long time to build. Must be re-built from scratch in case of indexing logic changes (i.e. event handler code change, active plugins change).
+
+## ENSNode Schema
+
+- Owned by ENSNode services.
+- Includes metadata describing configuration and state of various ENSNode services.
+- Tiny in size.
+- Takes virtually no time to be built.

packages/ensnode-schema/src/ensindexer-schema/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Merge the various sub-schemas into ENSIndexer Schema.
+ */
+
+export * from "./ensv2.subschema";
+export * from "./protocol-acceleration.subschema";
+export * from "./registrars.subschema";
+export * from "./subgraph.subschema";
+export * from "./tokenscope.subschema";

packages/ensnode-schema/src/ensnode-schema/index.ts

@@ -0,0 +1,66 @@
+/**
+ * ENSNode Schema
+ *
+ * Defines the database objects describing the ENSNode services state.
+ */
+
+import { primaryKey } from "drizzle-orm/pg-core";
+
+import { ENSNODE_SCHEMA } from "./schema";
+
+export { ENSNODE_SCHEMA_NAME } from "./schema";
+
+/**
+ * ENSNode Metadata
+ *
+ * Possible key value pairs are defined by 'EnsNodeMetadata' type:
+ * - `EnsNodeMetadataEnsDbVersion`
+ * - `EnsNodeMetadataEnsIndexerPublicConfig`
+ * - `EnsNodeMetadataEnsIndexerIndexingStatus`
+ */
+export const ensNodeMetadata = ENSNODE_SCHEMA.table(
+  "ensnode_metadata",
+  (t) => ({
+    /**
+     * ENSIndexer Reference
+     *
+     * References the ENSIndexer instance by a unique ENSIndexer schema name
+     * that a metadata record is associated with. This allows us to support
+     * multiple ENSIndexer instances using the same database, while ensuring
+     * that their metadata records do not conflict with each other.
+     */
+    ensIndexerRef: t.text().notNull(),
+
+    /**
+     * Key
+     *
+     * Allowed keys:
+     * - `EnsNodeMetadataEnsDbVersion['key']`
+     * - `EnsNodeMetadataEnsIndexerPublicConfig['key']`
+     * - `EnsNodeMetadataEnsIndexerIndexingStatus['key']`
+     */
+    key: t.text().notNull(),
+
+    /**
+     * Value
+     *
+     * Allowed values:
+     * - `EnsNodeMetadataEnsDbVersion['value']`
+     * - `EnsNodeMetadataEnsIndexerPublicConfig['value']`
+     * - `EnsNodeMetadataEnsIndexerIndexingStatus['value']`
+     *
+     * Guaranteed to be a serialized representation of JSON object.
+     */
+    value: t.jsonb().notNull(),
+  }),
+  (table) => [
+    /**
+     * Primary key constraint on 'ensIndexerRef' and 'key' columns,
+     * to ensure that there is only one record for each key per ENSIndexer instance.
+     */
+    primaryKey({
+      name: "ensnode_metadata_pkey",
+      columns: [table.ensIndexerRef, table.key],
+    }),
+  ],
+);

packages/ensnode-schema/src/ensnode-schema/schema.ts

@@ -0,0 +1,5 @@
+import { pgSchema } from "drizzle-orm/pg-core";
+
+export const ENSNODE_SCHEMA_NAME = "ensnode";
+
+export const ENSNODE_SCHEMA = pgSchema(ENSNODE_SCHEMA_NAME);

packages/ensnode-schema/src/index.ts

@@ -0,0 +1,2 @@
+// Re-export relevant schema definitions for backward compatibility.
+export * from "./ensindexer-schema";

packages/ensnode-schema/src/ponder-schema/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Ponder Schema
+ *
+ * Definition of the Ponder Schema can be found in the Ponder repository.
+ * @see https://github.com/ponder-sh/ponder/blob/ponder%400.16.3/packages/core/src/sync-store/schema.ts
+ */
+
+export const PONDER_SCHEMA_NAME = "ponder_sync";