Database migrations toolkit for ENSNode Schema in ENSDb

.changeset/tasty-pigs-shine.md

@@ -0,0 +1,5 @@
+---
+"@ensnode/ensdb-sdk": minor
+---
+
+Introduced toolkit for managing ENSDb migrations for ENSNode Schema.

packages/ensdb-sdk/README.md

@@ -1,3 +1,53 @@
 # ENSDb SDK
 
-This package is a utility library for interacting with ENSDb.
+This package defines the database schema used by ENSDb.
+
+It exposes two schema modules because `ENSIndexer` needs two different kinds of tables:
+
+- ENSIndexer Schema for indexing onchain data
+- ENSNode Schema for indexing offchain data
+
+## ENSIndexer Schema
+
+Source: `packages/ensdb-sdk/src/ensindexer`
+
+This database schema is required by the Ponder app that powers `ENSIndexer`.
+
+Ponder requires `ponder.schema.ts` to follow specific rules: `https://ponder.sh/docs/api-reference/ponder/schema#file-requirements`.
+
+The most important rule here is that tables must be defined with `onchainTable()`, not with Drizzle's `pgSchema(schemaName).table()`.
+
+Both APIs produce Drizzle table objects, but there is one important difference: `onchainTable()` does not hardcode the Postgres schema name up front. Ponder chooses the schema name dynamically from its configuration.
+
+Ponder is also responsible for initializing and migrating the ENSIndexer Schema. It reads this schema through `apps/ensindexer/ponder/ponder.schema.ts`, which re-exports `packages/ensdb-sdk/src/ensindexer`.
+
+### When it changes
+
+Update files in `src/ensindexer`, then start `ENSIndexer`. Ponder handles the rest.
+
+## ENSNode Schema
+
+Source: `packages/ensdb-sdk/src/ensnode`
+
+This schema is also required by `ENSIndexer`, but for offchain data rather than onchain data.
+
+It uses Drizzle's Postgres schema APIs such as `pgSchema("ensnode").table()`. Unlike the ENSIndexer Schema, the database schema name is fixed up front as `ensnode`.
+
+### When it changes
+
+You must generate migration files:
+
+```bash
+pnpm -F @ensnode/ensdb-sdk drizzle-kit:generate
+```
+
+This updates `packages/ensdb-sdk/migrations`. `ENSIndexer` currently takes responsibility for applying those migrations and initializing the ENSNode Schema.
+
+## Rule of thumb
+
+- `onchainTable()` + schema name chosen by Ponder = ENSIndexer Schema
+- `pgSchema().table()` + fixed schema name + generated migrations = ENSNode Schema
+
+## Current transition
+
+`packages/ensdb-sdk/src/ensindexer/index.ts` still re-exports `ensnode-metadata.schema.ts` as a temporary bridge until ENSNode Schema migrations are fully in place.

packages/ensdb-sdk/drizzle.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from "drizzle-kit";
+
+const ensNodeSchemaPath = "./src/ensnode/index.ts";
+
+export default defineConfig({
+  casing: "snake_case",
+  dialect: "postgresql",
+  out: "migrations",
+  schema: ensNodeSchemaPath,
+});

packages/ensdb-sdk/migrations/0000_cultured_captain_cross.sql

@@ -0,0 +1,8 @@
+CREATE SCHEMA IF NOT EXISTS ensnode;
+
+CREATE TABLE "ensnode"."metadata" (
+	"ens_indexer_schema_name" text NOT NULL,
+	"key" text NOT NULL,
+	"value" jsonb NOT NULL,
+	CONSTRAINT "metadata_pkey" PRIMARY KEY("ens_indexer_schema_name","key")
+);

packages/ensdb-sdk/migrations/meta/0000_snapshot.json

@@ -0,0 +1,55 @@
+{
+  "id": "d661dcae-f64d-4ecd-a4da-3d5783e17e2c",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "ensnode.metadata": {
+      "name": "metadata",
+      "schema": "ensnode",
+      "columns": {
+        "ens_indexer_schema_name": {
+          "name": "ens_indexer_schema_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "key": {
+          "name": "key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "value": {
+          "name": "value",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {
+        "metadata_pkey": {
+          "name": "metadata_pkey",
+          "columns": ["ens_indexer_schema_name", "key"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}

packages/ensdb-sdk/migrations/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1773743108514,
+      "tag": "0000_cultured_captain_cross",
+      "breakpoints": true
+    }
+  ]
+}

packages/ensdb-sdk/package.json

@@ -21,7 +21,9 @@
     "./ensnode": "./src/ensnode/index.ts"
   },
   "files": [
-    "dist"
+    "dist",
+    "migrations",
+    "migrations/meta"
   ],
   "publishConfig": {
     "access": "public",
@@ -52,7 +54,8 @@
   "scripts": {
     "prepublish": "tsup",
     "lint": "biome check --write .",
-    "lint:ci": "biome ci"
+    "lint:ci": "biome ci",
+    "drizzle-kit:generate": "drizzle-kit generate"
   },
   "peerDependencies": {
     "drizzle-orm": "catalog:",
@@ -62,6 +65,7 @@
   "devDependencies": {
     "@ensnode/ensnode-sdk": "workspace:",
     "@ensnode/shared-configs": "workspace:*",
+    "drizzle-kit": "0.31.10",
     "drizzle-orm": "catalog:",
     "ponder": "catalog:",
     "tsup": "catalog:",