Make ENSDb Writer Worker to execute database migrations

Author: tk-o

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

@@ -1,5 +1,6 @@
 import type { NodePgDatabase } from "drizzle-orm/node-postgres";
-import { and, eq, sql } from "drizzle-orm/sql";
+import { migrate } from "drizzle-orm/node-postgres/migrator";
+import { and, eq } from "drizzle-orm/sql";
 
 import * as ensNodeSchema from "@ensnode/ensnode-schema/ensnode";
 import {
@@ -8,6 +9,7 @@ import {
   deserializeEnsIndexerPublicConfig,
   type EnsDbClientMutation,
   type EnsDbClientQuery,
+  type EnsDbMigration,
   type EnsIndexerPublicConfig,
   EnsNodeMetadataKeys,
   type SerializedEnsNodeMetadata,
@@ -38,7 +40,7 @@ interface DrizzleDb extends NodePgDatabase<typeof ensNodeSchema> {}
  * - ENSDb version
  * - ENSIndexer Public Config, and Indexing Status Snapshot and CrossChainIndexingStatusSnapshot.
  */
-export class EnsDbClient implements EnsDbClientQuery, EnsDbClientMutation {
+export class EnsDbClient implements EnsDbClientQuery, EnsDbClientMutation, EnsDbMigration {
   /**
    * Drizzle database instance for ENSDb.
    */
@@ -191,4 +193,13 @@ export class EnsDbClient implements EnsDbClientQuery, EnsDbClientMutation {
         set: { value: metadata.value },
       });
   }
+
+  /**
+   * @inheritdoc
+   */
+  async migrate(migrationsDirPath: string): Promise<void> {
+    return migrate(this.db, {
+      migrationsFolder: migrationsDirPath,
+    });
+  }
 }

apps/ensindexer/src/lib/ensdb-writer-worker/ensdb-writer-worker.ts

@@ -24,10 +24,12 @@ const INDEXING_STATUS_RECORD_UPDATE_INTERVAL: Duration = 1;
 /**
  * ENSDb Writer Worker
  *
- * A worker responsible for writing ENSIndexer-related metadata into ENSDb, including:
- * - ENSDb version
- * - ENSIndexer Public Config
- * - ENSIndexer Indexing Status Snapshots
+ * A worker responsible for:
+ * - executing ENSDb database migrations on startup, and
+ * - writing ENSNode-related metadata into ENSDb, including:
+ *   - ENSDb version
+ *   - ENSIndexer Public Config
+ *   - Indexing Status Snapshots
  */
 export class EnsDbWriterWorker {
   /**
@@ -50,32 +52,42 @@ export class EnsDbWriterWorker {
    */
   private publicConfigBuilder: PublicConfigBuilder;
 
+  /**
+   * Path to the directory containing ENSDb migrations to be executed by the worker on startup.
+   */
+  private migrationsDirPath: string;
+
   /**
    * @param ensDbClient ENSDb Client instance used by the worker to interact with ENSDb.
    * @param publicConfigBuilder ENSIndexer Public Config Builder instance used by the worker to read ENSIndexer Public Config.
    * @param indexingStatusBuilder Indexing Status Builder instance used by the worker to read ENSIndexer Indexing Status.
+   * @param migrationsDirPath Path to the directory containing ENSDb migrations to be executed by the worker on startup.
    */
   constructor(
     ensDbClient: EnsDbClient,
     publicConfigBuilder: PublicConfigBuilder,
     indexingStatusBuilder: IndexingStatusBuilder,
+    migrationsDirPath: string,
   ) {
     this.ensDbClient = ensDbClient;
     this.publicConfigBuilder = publicConfigBuilder;
     this.indexingStatusBuilder = indexingStatusBuilder;
+    this.migrationsDirPath = migrationsDirPath;
   }
 
   /**
    * Run the ENSDb Writer Worker
    *
    * The worker performs the following tasks:
+   * 0) Execute pending ENSDb migrations.
    * 1) A single attempt to upsert ENSDb version into ENSDb.
    * 2) A single attempt to upsert serialized representation of
    *   {@link EnsIndexerPublicConfig} into ENSDb.
    * 3) A recurring attempt to upsert serialized representation of
    *    {@link CrossChainIndexingStatusSnapshot} into ENSDb.
    *
    * @throws Error if the worker is already running, or
+   *         if database migrations execution fails, or
    *         if the in-memory ENSIndexer Public Config could not be fetched, or
    *         if the in-memory ENSIndexer Public Config is incompatible with the stored config in ENSDb.
    */
@@ -85,6 +97,11 @@ export class EnsDbWriterWorker {
       throw new Error("EnsDbWriterWorker is already running");
     }
 
+    // Task 0: execute database migrations
+    console.log(`[EnsDbWriterWorker]: Executing database migrations...`);
+    await this.executeMigrations();
+    console.log(`[EnsDbWriterWorker]: Database migrations executed successfully`);
+
     // Fetch data required for task 1 and task 2.
     const inMemoryConfig = await this.getValidatedEnsIndexerPublicConfig();
 
@@ -126,6 +143,17 @@ export class EnsDbWriterWorker {
     }
   }
 
+  /**
+   * Execute database migrations for the ENSDb Writer Worker.
+   *
+   * Runs all pending migrations in the defined migrations directory.
+   *
+   * @throws Error if any migration fails to execute.
+   */
+  private async executeMigrations(): Promise<void> {
+    await this.ensDbClient.migrate(this.migrationsDirPath);
+  }
+
   /**
    * Get validated ENSIndexer Public Config object for the ENSDb Writer Worker.
    *

apps/ensindexer/src/lib/ensdb-writer-worker/singleton.ts

@@ -1,3 +1,5 @@
+import { fileURLToPath } from "node:url";
+
 import { ensDbClient } from "@/lib/ensdb-client/singleton";
 import { indexingStatusBuilder } from "@/lib/indexing-status-builder/singleton";
 import { publicConfigBuilder } from "@/lib/public-config-builder/singleton";
@@ -20,10 +22,15 @@ export function startEnsDbWriterWorker() {
     throw new Error("EnsDbWriterWorker has already been initialized");
   }
 
+  const migrationsDirPath = fileURLToPath(
+    new URL("../../../drizzle-kit/migrations/", import.meta.url),
+  );
+
   ensDbWriterWorker = new EnsDbWriterWorker(
     ensDbClient,
     publicConfigBuilder,
     indexingStatusBuilder,
+    migrationsDirPath,
   );
 
   ensDbWriterWorker

packages/ensnode-sdk/src/ensdb/client.ts

@@ -56,3 +56,13 @@ export interface EnsDbClientMutation {
    */
   upsertIndexingStatusSnapshot(indexingStatus: CrossChainIndexingStatusSnapshot): Promise<void>;
 }
+
+export interface EnsDbMigration {
+  /**
+   * Execute pending migrations for ENSDb.
+   *
+   * @param migrationsDirPath - The file path to the directory containing migration files.
+   * @throws error when migration execution fails.
+   */
+  migrate(migrationsDirPath: string): Promise<void>;
+}