@enbox/dwn-sql-store 0.0.10 → 0.0.11

package/dist/types/src/resumable-task-store-sql.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resumable-task-store-sql.d.ts","sourceRoot":"","sources":["../../../src/resumable-task-store-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,KAAK,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAMlF,qBAAa,qBAAsB,YAAW,kBAAkB;;IAC9D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,CAAM;gBAKtC,OAAO,EAAE,OAAO;IAItB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkCrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,QAAQ,CAAC,IAAI,EAAE,GAAG,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAoB5E,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;IA0CpD,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC;IAsB/D,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAc/D,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAS7B"}
+{"version":3,"file":"resumable-task-store-sql.d.ts","sourceRoot":"","sources":["../../../src/resumable-task-store-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,KAAK,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAMlF,qBAAa,qBAAsB,YAAW,kBAAkB;;IAC9D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,CAAM;gBAKtC,OAAO,EAAE,OAAO;IAItB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAyBrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,QAAQ,CAAC,IAAI,EAAE,GAAG,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAoB5E,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;IA0CpD,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC;IAsB/D,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAc/D,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAS7B"}

package/dist/types/src/state-index-sql.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state-index-sql.d.ts","sourceRoot":"","sources":["../../../src/state-index-sql.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAOpD,qBAAa,aAAc,YAAW,UAAU;;gBAiBlC,OAAO,EAAE,OAAO;IAItB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA2ErB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAOtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAatB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IA4B7E,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAsC5D,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKtC,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKhE,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAKhE,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAK1F,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAK/D,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAO/F;;;OAGG;IACH,OAAO,CAAC,aAAa;IAWrB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAYvB;;OAEG;YACW,UAAU;CAWzB"}
+{"version":3,"file":"state-index-sql.d.ts","sourceRoot":"","sources":["../../../src/state-index-sql.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAOpD,qBAAa,aAAc,YAAW,UAAU;;gBAiBlC,OAAO,EAAE,OAAO;IAItB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA+BrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAOtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAatB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IA4B7E,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAsC5D,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKtC,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKhE,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAKhE,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAK1F,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAK/D,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAO/F;;;OAGG;IACH,OAAO,CAAC,aAAa;IAWrB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAYvB;;OAEG;YACW,UAAU;CAWzB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enbox/dwn-sql-store",
-  "version": "0.0.10",
+  "version": "0.0.11",
   "description": "SQL backed implementations of DWN MessageStore, DataStore, and StateIndex",
   "type": "module",
   "license": "Apache-2.0",
@@ -25,7 +25,7 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.700.0",
     "@aws-sdk/lib-storage": "^3.700.0",
-    "@enbox/dwn-sdk-js": "0.1.1",
+    "@enbox/dwn-sdk-js": "0.1.2",
     "@ipld/dag-cbor": "9.0.5",
     "interface-blockstore": "5.2.3",
     "interface-store": "5.1.2",

package/src/data-store-s3.ts

@@ -3,7 +3,6 @@ import type { DwnDatabaseType } from './types.js';
 import type { DataStore, DataStoreGetResult, DataStorePutResult } from '@enbox/dwn-sdk-js';
 
 import { DataStream } from '@enbox/dwn-sdk-js';
-import { Kysely } from 'kysely';
 import { Readable } from 'stream';
 import { Upload } from '@aws-sdk/lib-storage';
 import {
@@ -14,6 +13,7 @@ import {
   PutObjectCommand,
   S3Client,
 } from '@aws-sdk/client-s3';
+import { Kysely, sql } from 'kysely';
 
 /**
  * S3-backed implementation of {@link DataStore} with SQL-based reference
@@ -56,7 +56,9 @@ export class DataStoreS3 implements DataStore {
     }
 
     this.#db = new Kysely<DwnDatabaseType>({ dialect: this.#dialect });
-    await this.#ensureRefsTable();
+
+    // Fail fast if migrations have not been run — the dataRefs table must already exist.
+    await this.#assertTablesExist();
   }
 
   public async close(): Promise<void> {
@@ -277,30 +279,17 @@ export class DataStoreS3 implements DataStore {
   }
 
   /**
-   * Creates the `dataRefs` table if it doesn't already exist.
-   * Shares the same schema as DataStoreSql's `dataRefs` table.
+   * Verifies that the required `dataRefs` table exists by executing a
+   * zero-row SELECT. Throws a clear error directing the caller to run
+   * migrations first.
    */
-  async #ensureRefsTable(): Promise<void> {
-    const db = this.#db!;
-
-    if (!(await this.#dialect.hasTable(db, 'dataRefs'))) {
-      await db.schema
-        .createTable('dataRefs')
-        .ifNotExists()
-        .addColumn('tenant', 'varchar(255)', (col) => col.notNull())
-        .addColumn('recordId', 'varchar(60)', (col) => col.notNull())
-        .addColumn('dataCid', 'varchar(60)', (col) => col.notNull())
-        .addColumn('dataSize', 'bigint', (col) => col.notNull())
-        .execute();
-
-      await db.schema.createIndex('index_dataRefs_tenant_recordId_dataCid')
-        .on('dataRefs').columns(['tenant', 'recordId', 'dataCid']).unique().execute();
-
-      await db.schema.createIndex('index_dataRefs_dataCid')
-        .on('dataRefs').column('dataCid').execute();
-
-      await db.schema.createIndex('index_dataRefs_tenant')
-        .on('dataRefs').column('tenant').execute();
+  async #assertTablesExist(): Promise<void> {
+    try {
+      await sql`SELECT 1 FROM ${sql.table('dataRefs')} LIMIT 0`.execute(this.#db!);
+    } catch {
+      throw new Error(
+        'DataStoreS3: table \'dataRefs\' does not exist. Run DWN store migrations before opening stores.'
+      );
     }
   }
 }

package/src/data-store-sql.ts

@@ -8,7 +8,7 @@ import { CID } from 'multiformats';
 import { DataStream } from '@enbox/dwn-sdk-js';
 import { exporter } from 'ipfs-unixfs-exporter';
 import { importer } from 'ipfs-unixfs-importer';
-import { Kysely } from 'kysely';
+import { Kysely, sql } from 'kysely';
 
 /**
  * SQL-backed implementation of {@link DataStore} with content-addressed
@@ -37,10 +37,8 @@ export class DataStoreSql implements DataStore {
 
     this.#db = new Kysely<DwnDatabaseType>({ dialect: this.#dialect });
 
-    // Create tables if they don't exist. In production the MigrationRunner
-    // creates these before open() is called; this fallback handles standalone
-    // usage (tests, plugins) that bypass the migration runner.
-    await this.#ensureTables();
+    // Fail fast if migrations have not been run — tables must already exist.
+    await this.#assertTablesExist();
   }
 
   public async close(): Promise<void> {
@@ -218,46 +216,19 @@ export class DataStoreSql implements DataStore {
   }
 
   /**
-   * Creates the `dataRefs` and `dataBlocks` tables if they don't already exist.
-   * This is a fallback for standalone usage without the MigrationRunner.
+   * Verifies that the required tables exist by executing a zero-row SELECT.
+   * Throws a clear error directing the caller to run migrations first.
    */
-  async #ensureTables(): Promise<void> {
-    const db = this.#db!;
-
-    // ─── dataRefs ─────────────────────────────────────────────────────
-    if (!(await this.#dialect.hasTable(db, 'dataRefs'))) {
-      await db.schema
-        .createTable('dataRefs')
-        .ifNotExists()
-        .addColumn('tenant', 'varchar(255)', (col) => col.notNull())
-        .addColumn('recordId', 'varchar(60)', (col) => col.notNull())
-        .addColumn('dataCid', 'varchar(60)', (col) => col.notNull())
-        .addColumn('dataSize', 'bigint', (col) => col.notNull())
-        .execute();
-
-      await db.schema.createIndex('index_dataRefs_tenant_recordId_dataCid')
-        .on('dataRefs').columns(['tenant', 'recordId', 'dataCid']).unique().execute();
-
-      await db.schema.createIndex('index_dataRefs_dataCid')
-        .on('dataRefs').column('dataCid').execute();
-
-      await db.schema.createIndex('index_dataRefs_tenant')
-        .on('dataRefs').column('tenant').execute();
-    }
-
-    // ─── dataBlocks ───────────────────────────────────────────────────
-    if (!(await this.#dialect.hasTable(db, 'dataBlocks'))) {
-      let table = db.schema
-        .createTable('dataBlocks')
-        .ifNotExists()
-        .addColumn('rootDataCid', 'varchar(60)', (col) => col.notNull())
-        .addColumn('blockCid', 'varchar(60)', (col) => col.notNull());
-
-      table = this.#dialect.addBlobColumn(table, 'data', (col) => col.notNull());
-      await table.execute();
-
-      await db.schema.createIndex('index_dataBlocks_rootDataCid_blockCid')
-        .on('dataBlocks').columns(['rootDataCid', 'blockCid']).unique().execute();
+  async #assertTablesExist(): Promise<void> {
+    const tables = ['dataRefs', 'dataBlocks'] as const;
+    for (const table of tables) {
+      try {
+        await sql`SELECT 1 FROM ${sql.table(table)} LIMIT 0`.execute(this.#db!);
+      } catch {
+        throw new Error(
+          `DataStoreSql: table '${table}' does not exist. Run DWN store migrations before opening stores.`
+        );
+      }
     }
   }
 

package/src/main.ts

@@ -8,6 +8,7 @@ export * from './data-store-s3.js';
 export * from './data-store-sql.js';
 export * from './state-index-sql.js';
 export * from './message-store-sql.js';
+export * from './migration-provider.js';
 export * from './migration-runner.js';
 export * from './migrations/index.js';
 export * from './resumable-task-store-sql.js';

package/src/message-store-sql.ts

@@ -43,123 +43,24 @@ export class MessageStoreSql implements MessageStore {
 
     this.#db = new Kysely<DwnDatabaseType>({ dialect: this.#dialect });
 
-    // create messages table if it does not exist
-    const messagesTableName = 'messageStoreMessages';
-    const messagesTableExists = await this.#dialect.hasTable(this.#db, messagesTableName);
-    if (!messagesTableExists) {
-      let createMessagesTable = this.#db.schema
-        .createTable(messagesTableName)
-        .ifNotExists()
-        .addColumn('tenant', 'varchar(255)', (col) => col.notNull())
-        .addColumn('messageCid', 'varchar(60)', (col) => col.notNull())
-        .addColumn('interface', 'varchar(20)')
-        .addColumn('method', 'varchar(20)')
-        .addColumn('recordId', 'varchar(60)')
-        .addColumn('entryId','varchar(60)')
-        .addColumn('parentId', 'varchar(60)')
-        .addColumn('protocol', 'varchar(200)')
-        .addColumn('protocolPath', 'varchar(200)')
-        .addColumn('contextId', 'varchar(600)')
-        .addColumn('schema', 'varchar(200)')
-        .addColumn('author', 'varchar(255)')
-        .addColumn('recipient', 'varchar(255)')
-        .addColumn('messageTimestamp', 'varchar(30)')
-        .addColumn('dateCreated', 'varchar(30)')
-        .addColumn('datePublished', 'varchar(30)')
-        .addColumn('isLatestBaseState', 'boolean')
-        .addColumn('published', 'boolean')
-        .addColumn('prune', 'boolean')
-        .addColumn('squash', 'boolean')
-        .addColumn('dataFormat', 'varchar(30)')
-        .addColumn('dataCid', 'varchar(60)')
-        .addColumn('dataSize', 'integer')
-        .addColumn('encodedData', 'text') // we optionally store encoded data if it is below a threshold
-        .addColumn('attester', 'text')
-        .addColumn('permissionGrantId', 'varchar(60)');
-
-      // Add columns that have dialect-specific constraints
-      createMessagesTable = this.#dialect.addAutoIncrementingColumn(createMessagesTable, 'id', (col) => col.primaryKey());
-      createMessagesTable = this.#dialect.addBlobColumn(createMessagesTable, 'encodedMessageBytes', (col) => col.notNull());
-      await createMessagesTable.execute();
-
-      // add unique index for get() and delete() by messageCid — the most fundamental lookup path
-      await this.#db.schema
-        .createIndex('index_tenant_messageCid')
-        .on(messagesTableName)
-        .columns(['tenant', 'messageCid'])
-        .unique()
-        .execute();
-
-      // add indexes to the table
-      await this.createIndexes(this.#db, messagesTableName, [
-        ['tenant', 'recordId'], // multiple uses, notably heavily depended by record chain construction for protocol authorization
-        ['tenant', 'entryId'], // used by fetchInitialRecordsWriteMessage in RecordsRead, RecordsQuery, and RecordsDelete
-        ['tenant', 'parentId'], // used to walk down hierarchy of records, use cases include purging of records
-        ['tenant', 'protocol', 'published', 'messageTimestamp'], // index used for basically every external query
-        ['tenant', 'interface'], // mainly for fast fetch of ProtocolsConfigure for authorization, not needed if protocol was a DWN Record
-        ['tenant', 'permissionGrantId'], // for deleting grant-authorized messages though pending https://github.com/enboxorg/enbox/issues/716
-        ['tenant', 'dateCreated'], // sort optimization for RecordsQuery with DateSort.CreatedAscending/Descending
-        ['tenant', 'datePublished'], // sort optimization for RecordsQuery with DateSort.PublishedAscending/Descending
-      ]);
-
-      // contextId index created separately because MySQL requires a prefix length to fit within
-      // the 3072-byte InnoDB index key limit. contextId is varchar(600) × 4 bytes (utf8mb4) = 2400 bytes,
-      // which combined with tenant (255 × 4 = 1020) and messageTimestamp (30 × 4 = 120) = 3540 bytes,
-      // exceeding the limit. A prefix of 480 chars (1920 bytes) brings the total to 3060 bytes.
-      // contextId values only contain ASCII chars [a-zA-Z0-9/], so a 480-char prefix is sufficient
-      // to distinguish most records (covers ~8 nesting levels of 59-char CID segments).
-      if (this.#dialect.name === 'MySQL') {
-        await sql`CREATE INDEX index_tenant_contextId_messageTimestamp
-          ON ${sql.table(messagesTableName)} (tenant, contextId(480), messageTimestamp)`
-          .execute(this.#db);
-      } else {
-        await this.createIndexes(this.#db, messagesTableName, [
-          ['tenant', 'contextId', 'messageTimestamp'], // expected to be used for common query pattern
-        ]);
-      }
-    }
-
-    // create tags table
-    const tagsTableName = 'messageStoreRecordsTags';
-    const tagsTableExists = await this.#dialect.hasTable(this.#db, tagsTableName);
-    if (!tagsTableExists) {
-      let createRecordsTagsTable = this.#db.schema
-        .createTable(tagsTableName)
-        .ifNotExists()
-        .addColumn('tag', 'varchar(30)', (col) => col.notNull())
-        .addColumn('valueString', 'varchar(200)')
-        .addColumn('valueNumber', 'decimal');
-
-      // Add columns that have dialect-specific constraints
-      const foreignMessageInsertId = 'messageInsertId';
-      createRecordsTagsTable = this.#dialect.addAutoIncrementingColumn(createRecordsTagsTable, 'id', (col) => col.primaryKey());
-      createRecordsTagsTable = this.#dialect.addReferencedColumn(createRecordsTagsTable, tagsTableName, foreignMessageInsertId, 'integer', 'messageStoreMessages', 'id', 'cascade');
-      await createRecordsTagsTable.execute();
-
-      // add indexes to the table
-      await this.createIndexes(this.#db, tagsTableName, [
-        [foreignMessageInsertId],
-        ['tag', 'valueString'],
-        ['tag', 'valueNumber']
-      ]);
-    }
+    // Fail fast if migrations have not been run — tables must already exist.
+    await this.#assertTablesExist();
   }
 
   /**
-   *  Creates indexes on the given table.
-   * @param tableName The name of the table to create the indexes on.
-   * @param indexes Each inner array represents a single index and contains the column names to be indexed as a composite index.
-   *                If the inner array contains only one element, it will be treated as a single column index.
+   * Verifies that the required tables exist by executing a zero-row SELECT.
+   * Throws a clear error directing the caller to run migrations first.
    */
-  async createIndexes<T>(database: Kysely<T>, tableName: string, indexes: string[][]): Promise<void> {
-    for (const columnNames of indexes) {
-      const indexName = 'index_' + columnNames.join('_'); // e.g. index_tenant_protocol
-      await database.schema
-        .createIndex(indexName)
-        // .ifNotExists() // intentionally kept commented out code to show that it is not supported by all dialects (ie. MySQL)
-        .on(tableName)
-        .columns(columnNames)
-        .execute();
+  async #assertTablesExist(): Promise<void> {
+    const tables = ['messageStoreMessages', 'messageStoreRecordsTags'] as const;
+    for (const table of tables) {
+      try {
+        await sql`SELECT 1 FROM ${sql.table(table)} LIMIT 0`.execute(this.#db!);
+      } catch {
+        throw new Error(
+          `MessageStoreSql: table '${table}' does not exist. Run DWN store migrations before opening stores.`
+        );
+      }
     }
   }
 

package/src/migration-provider.ts

@@ -0,0 +1,52 @@
+import type { Dialect } from './dialect/dialect.js';
+import type { Migration, MigrationProvider } from 'kysely';
+
+/**
+ * Factory function type for DWN migrations. Each migration module exports a
+ * factory that receives the {@link Dialect} and returns a standard Kysely
+ * {@link Migration}. This closure pattern lets migrations use dialect-specific
+ * DDL helpers (blob columns, auto-increment, `hasTable()`) without requiring
+ * Kysely's `Migration.up()` signature to accept extra parameters.
+ */
+export type DwnMigrationFactory = (dialect: Dialect) => Migration;
+
+/**
+ * Kysely {@link MigrationProvider} for DWN store migrations.
+ *
+ * Wraps an ordered list of `(name, factory)` pairs. At resolution time each
+ * factory is called with the dialect, producing the concrete Kysely
+ * {@link Migration} objects that the `Migrator` consumes.
+ *
+ * @example
+ * ```ts
+ * const provider = new DwnMigrationProvider(dialect, allDwnMigrations);
+ * const migrator  = new Migrator({ db, provider });
+ * await migrator.migrateToLatest();
+ * ```
+ */
+export class DwnMigrationProvider implements MigrationProvider {
+  #dialect: Dialect;
+  #factories: ReadonlyArray<readonly [name: string, factory: DwnMigrationFactory]>;
+
+  constructor(
+    dialect: Dialect,
+    factories: ReadonlyArray<readonly [name: string, factory: DwnMigrationFactory]>,
+  ) {
+    this.#dialect = dialect;
+    this.#factories = factories;
+  }
+
+  /**
+   * Called by the Kysely `Migrator` to retrieve all available migrations.
+   * Keys are migration names (e.g. `'001-initial-schema'`); values are the
+   * concrete `Migration` objects produced by invoking each factory with the
+   * captured dialect.
+   */
+  public async getMigrations(): Promise<Record<string, Migration>> {
+    const migrations: Record<string, Migration> = {};
+    for (const [name, factory] of this.#factories) {
+      migrations[name] = factory(this.#dialect);
+    }
+    return migrations;
+  }
+}

package/src/migration-runner.ts

@@ -1,137 +1,47 @@
 import type { Dialect } from './dialect/dialect.js';
-import type { Kysely } from 'kysely';
+import type { DwnMigrationFactory } from './migration-provider.js';
+import type { Kysely, MigrationResultSet } from 'kysely';
 
-import { allMigrations } from './migrations/index.js';
+import { allDwnMigrations } from './migrations/index.js';
+import { DwnMigrationProvider } from './migration-provider.js';
+import { Migrator } from 'kysely';
 
-/**
- * A single migration step. Migrations are TypeScript functions (not raw SQL)
- * so they can use the Dialect abstraction for cross-dialect column types.
- */
-export type Migration = {
-  /** Unique sequential name, e.g. '001-initial-schema'. */
-  name: string;
-  /**
-   * Apply this migration. Receives the Kysely instance and dialect for
-   * dialect-aware DDL (blob types, auto-increment, etc.).
-   */
-  up(db: Kysely<any>, dialect: Dialect): Promise<void>;
-};
-
-type MigrationRecord = {
-  name: string;
-  appliedAt: string;
-};
-
-type MigrationDatabaseType = {
-  dwn_migrations: MigrationRecord;
-};
-
-/**
- * Minimal forward-only migration runner for dwn-sql-store.
- *
- * Tracks applied migrations in a `dwn_migrations` table and applies
- * pending migrations in sequential order on each call to `run()`.
- *
- * Design decisions:
- * - Forward-only: no rollback support. Keep migrations simple and additive.
- * - TypeScript migrations: use the Dialect interface for cross-dialect DDL.
- * - Idempotent: calling `run()` on an up-to-date database is a no-op.
- * - Transaction per migration: each migration runs in its own transaction
- *   so a failure leaves the database in the last known-good state.
- */
 /**
  * Convenience function to run all DWN store migrations against a database.
  *
- * Creates a `MigrationRunner` with the full set of built-in migrations and
- * runs them. Call this once during application startup, before opening any
- * stores — e.g. in `getDwnConfig()` or equivalent initialization code.
+ * Uses Kysely's native {@link Migrator} with the {@link DwnMigrationProvider}
+ * to apply pending migrations. The Migrator handles locking (Postgres uses
+ * `pg_advisory_xact_lock`, MySQL uses `GET_LOCK`/`RELEASE_LOCK`, SQLite is
+ * single-writer) and migration tracking via its own `kysely_migration` /
+ * `kysely_migration_lock` tables.
+ *
+ * Call this once during application startup, before opening any stores —
+ * e.g. in `getDwnConfig()` or equivalent initialization code.
  *
  * @param db - An open Kysely instance connected to the target database.
  * @param dialect - The dialect for the target database.
+ * @param migrations - Optional custom migration list; defaults to the
+ *   built-in {@link allDwnMigrations}.
  * @returns The names of newly applied migrations (empty if already up-to-date).
+ * @throws If any migration fails (the Migrator rolls back only the failed migration).
  */
-export async function runDwnStoreMigrations(db: Kysely<any>, dialect: Dialect): Promise<string[]> {
-  const runner = new MigrationRunner(db, dialect, allMigrations);
-  return runner.run();
-}
-
-export class MigrationRunner {
-  #db: Kysely<MigrationDatabaseType>;
-  #dialect: Dialect;
-  #migrations: Migration[];
-
-  constructor(db: Kysely<any>, dialect: Dialect, migrations: Migration[]) {
-    this.#db = db as Kysely<MigrationDatabaseType>;
-    this.#dialect = dialect;
-    this.#migrations = migrations;
+export async function runDwnStoreMigrations(
+  db: Kysely<any>,
+  dialect: Dialect,
+  migrations?: ReadonlyArray<readonly [name: string, factory: DwnMigrationFactory]>,
+): Promise<string[]> {
+  const provider = new DwnMigrationProvider(dialect, migrations ?? allDwnMigrations);
+  const migrator = new Migrator({ db, provider });
+  const resultSet: MigrationResultSet = await migrator.migrateToLatest();
+
+  if (resultSet.error) {
+    // Re-throw the underlying error so callers get a useful stack trace.
+    // The resultSet.results still contains info about which migrations
+    // succeeded before the failure.
+    throw resultSet.error;
   }
 
-  /**
-   * Ensure the `dwn_migrations` tracking table exists, then apply any
-   * pending migrations in order. Returns the names of newly applied migrations.
-   */
-  public async run(): Promise<string[]> {
-    await this.#ensureMigrationTable();
-
-    const applied = await this.#getAppliedMigrations();
-    const appliedSet = new Set(applied);
-    const pending = this.#migrations.filter((m) => !appliedSet.has(m.name));
-
-    const newlyApplied: string[] = [];
-    for (const migration of pending) {
-      await this.#applyMigration(migration);
-      newlyApplied.push(migration.name);
-    }
-
-    return newlyApplied;
-  }
-
-  /**
-   * Create the `dwn_migrations` table if it does not already exist.
-   */
-  async #ensureMigrationTable(): Promise<void> {
-    const exists = await this.#dialect.hasTable(this.#db, 'dwn_migrations');
-    if (exists) {
-      return;
-    }
-
-    await this.#db.schema
-      .createTable('dwn_migrations')
-      .ifNotExists()
-      .addColumn('name', 'varchar(255)', (col) => col.primaryKey().notNull())
-      .addColumn('appliedAt', 'varchar(30)', (col) => col.notNull())
-      .execute();
-  }
-
-  /**
-   * Get the list of migration names that have already been applied.
-   */
-  async #getAppliedMigrations(): Promise<string[]> {
-    const rows = await this.#db
-      .selectFrom('dwn_migrations')
-      .select('name')
-      .orderBy('name', 'asc')
-      .execute();
-
-    return rows.map((r) => r.name);
-  }
-
-  /**
-   * Apply a single migration within a transaction and record it.
-   */
-  async #applyMigration(migration: Migration): Promise<void> {
-    await this.#db.transaction().execute(async (trx) => {
-      // Run the migration
-      await migration.up(trx as unknown as Kysely<any>, this.#dialect);
-
-      // Record it as applied
-      await (trx as unknown as Kysely<MigrationDatabaseType>)
-        .insertInto('dwn_migrations')
-        .values({
-          name      : migration.name,
-          appliedAt : new Date().toISOString(),
-        })
-        .execute();
-    });
-  }
+  return (resultSet.results ?? [])
+    .filter((r) => r.status === 'Success')
+    .map((r) => r.migrationName);
 }

package/src/migrations/001-initial-schema.ts

@@ -1,6 +1,6 @@
 import type { Dialect } from '../dialect/dialect.js';
-import type { Kysely } from 'kysely';
-import type { Migration } from '../migration-runner.js';
+import type { DwnMigrationFactory } from '../migration-provider.js';
+import type { Kysely, Migration } from 'kysely';
 
 import { sql } from 'kysely';
 
@@ -8,13 +8,12 @@ import { sql } from 'kysely';
  * Baseline migration: captures the schema as of the pre-migration era.
  *
  * For existing databases that already have these tables, this migration is
- * detected as "already applied" during the adoption bootstrap (see MigrationRunner).
+ * detected as "already applied" during the adoption bootstrap (see runDwnStoreMigrations).
  * For new databases, this creates the full initial schema.
  */
-export const migration001InitialSchema: Migration = {
-  name: '001-initial-schema',
+export const migration001InitialSchema: DwnMigrationFactory = (dialect: Dialect): Migration => ({
 
-  async up(db: Kysely<any>, dialect: Dialect): Promise<void> {
+  async up(db: Kysely<any>): Promise<void> {
 
     // ─── messageStoreMessages ───────────────────────────────────────────
     if (!(await dialect.hasTable(db, 'messageStoreMessages'))) {
@@ -187,4 +186,4 @@ export const migration001InitialSchema: Migration = {
         .on('stateIndexMeta').columns(['tenant', 'messageCid']).execute();
     }
   },
-};
+});

package/src/migrations/002-content-addressed-datastore.ts

@@ -1,6 +1,6 @@
 import type { Dialect } from '../dialect/dialect.js';
-import type { Kysely } from 'kysely';
-import type { Migration } from '../migration-runner.js';
+import type { DwnMigrationFactory } from '../migration-provider.js';
+import type { Kysely, Migration } from 'kysely';
 
 import { sql } from 'kysely';
 
@@ -29,10 +29,9 @@ import { sql } from 'kysely';
  * NOTE: For large databases, the data migration may take significant time.
  * The migration runs in a single transaction for atomicity.
  */
-export const migration002ContentAddressedDatastore: Migration = {
-  name: '002-content-addressed-datastore',
+export const migration002ContentAddressedDatastore: DwnMigrationFactory = (dialect: Dialect): Migration => ({
 
-  async up(db: Kysely<any>, dialect: Dialect): Promise<void> {
+  async up(db: Kysely<any>): Promise<void> {
 
     // ─── Create dataRefs table ──────────────────────────────────────────
     if (!(await dialect.hasTable(db, 'dataRefs'))) {
@@ -137,4 +136,4 @@ export const migration002ContentAddressedDatastore: Migration = {
       await db.schema.dropTable('dataStore').execute();
     }
   },
-};
+});

package/src/migrations/003-add-squash-column.ts

@@ -1,6 +1,5 @@
-import type { Dialect } from '../dialect/dialect.js';
-import type { Kysely } from 'kysely';
-import type { Migration } from '../migration-runner.js';
+import type { DwnMigrationFactory } from '../migration-provider.js';
+import type { Kysely, Migration } from 'kysely';
 
 /**
  * Migration 003: Add `squash` boolean column to `messageStoreMessages`.
@@ -9,13 +8,12 @@ import type { Migration } from '../migration-runner.js';
  * introduced in the DWN spec. It follows the same pattern as `published`
  * and `prune` — a nullable boolean column used for query filtering.
  */
-export const migration003AddSquashColumn: Migration = {
-  name: '003-add-squash-column',
+export const migration003AddSquashColumn: DwnMigrationFactory = (): Migration => ({
 
-  async up(db: Kysely<any>, _dialect: Dialect): Promise<void> {
+  async up(db: Kysely<any>): Promise<void> {
     await db.schema
       .alterTable('messageStoreMessages')
       .addColumn('squash', 'boolean')
       .execute();
   },
-};
+});