@coffre/db 0.1.16 → 0.1.17

package/README.md

@@ -5,8 +5,9 @@ coffre uses in tests and local development, their migrations and the
 migrator, the helpers for what the two engines do differently, and the
 connections, Hyperdrive's included.
 
-A deployment does not import it. `@coffre/server` runs its migrations with
-`coffre-server migrate`. The server and vault open the same database with
+A deployment does not import it. Its own CLI applies the migrations,
+`pnpm exec coffre migrate`, before the deploy; `coffre-server migrate` does
+the same for local SQLite and tests. The server and vault open the same database with
 separate logins, `coffre_runtime` and `coffre_vault_runtime`. The migrations
 grant each its own rights; only the owner runs migrations. The owner needs
 `CREATEROLE` and `CREATEDB`, and `ADMIN OPTION` on existing group roles.

package/dist/migrate.d.ts

@@ -8,6 +8,22 @@ export declare function restrictDatabase(client: Pick<PoolClient, 'query'>): Pro
  * in the built package, where the build copies them.
  */
 export declare function migrationsFolder(engine: Engine): string;
+/**
+ * A database a newer coffre migrated: it has applied every migration this
+ * version knows, and more. The ledger keeps no names, so each one it does not
+ * know is named by when it was made and its hash.
+ */
+export declare class DatabaseAhead extends Error {
+  readonly known: string[];
+  readonly unknown: {
+    createdAt: string;
+    hash: string;
+  }[];
+  constructor(known: string[], unknown: {
+    createdAt: string;
+    hash: string;
+  }[]);
+}
 /**
  * A migration run's plan: `applied` of the `total` migrations there before
  * it, and the tags of the rest, which it applies.

package/dist/migrate.js

@@ -47,14 +47,33 @@ async function expectedMigrations(engine) {
 	for (let index = 1; index < expected.length; index += 1) if (BigInt(expected[index - 1].createdAt) >= BigInt(expected[index].createdAt)) throw new Error("Drizzle migration journal timestamps must be strictly increasing");
 	return expected;
 }
+/**
+* A database a newer coffre migrated: it has applied every migration this
+* version knows, and more. The ledger keeps no names, so each one it does not
+* know is named by when it was made and its hash.
+*/
+var DatabaseAhead = class extends Error {
+	known;
+	unknown;
+	constructor(known, unknown) {
+		const made = unknown.map(({ createdAt, hash }) => `one made ${new Date(Number(createdAt)).toISOString().slice(0, 16).replace("T", " ")} UTC (${hash.slice(0, 12)})`);
+		super(`the database has applied ${unknown.length === 1 ? "a migration" : `${unknown.length} migrations`} this version does not know, after ${known.at(-1) ?? "none"}: ${made.join(", ")}. A newer coffre migrated it`);
+		this.name = "DatabaseAhead";
+		this.known = known;
+		this.unknown = unknown;
+	}
+};
 function verifyHistory(expected, applied, requireComplete) {
 	const rows = applied ?? [];
-	if (rows.length > expected.length) throw new Error("database contains migrations that are absent from this image");
-	if (requireComplete && rows.length !== expected.length) throw new Error(`migration history is incomplete: expected ${expected.length}, found ${rows.length}`);
-	rows.forEach((row, index) => {
+	rows.slice(0, expected.length).forEach((row, index) => {
 		const local = expected[index];
 		if (row.created_at !== local.createdAt || row.hash !== local.hash) throw new Error(`migration history diverged at ${local.tag}; applied migrations must never be edited`);
 	});
+	if (rows.length > expected.length) throw new DatabaseAhead(expected.map((entry) => entry.tag), rows.slice(expected.length).map((row) => ({
+		createdAt: row.created_at,
+		hash: row.hash
+	})));
+	if (requireComplete && rows.length !== expected.length) throw new Error(`migration history is incomplete: expected ${expected.length}, found ${rows.length}`);
 }
 async function postgresMigrator(url) {
 	const [{ default: pg }, { drizzle }, { migrate }] = await Promise.all([
@@ -166,4 +185,4 @@ async function migrateDatabase(url, onPlan) {
 	}
 }
 //#endregion
-export { migrateDatabase, migrationStatus, migrationsFolder, restrictDatabase };
+export { DatabaseAhead, migrateDatabase, migrationStatus, migrationsFolder, restrictDatabase };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffre/db",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "description": "coffre's database: the schema, its migrations and the connections, on Postgres or SQLite.",
   "license": "MIT",
   "repository": {
@@ -74,7 +74,7 @@
     "drizzle-orm": "0.45.2",
     "pg": "8.16.3",
     "pg-connection-string": "2.14.0",
-    "@coffre/core": "0.1.16"
+    "@coffre/core": "0.1.17"
   },
   "devDependencies": {
     "@types/node": "26.1.1",

package/src/migrate.ts

@@ -101,27 +101,47 @@ async function expectedMigrations(engine: Engine): Promise<ExpectedMigration[]>
   return expected;
 }
 
+/**
+ * A database a newer coffre migrated: it has applied every migration this
+ * version knows, and more. The ledger keeps no names, so each one it does not
+ * know is named by when it was made and its hash.
+ */
+export class DatabaseAhead extends Error {
+  readonly known: string[];
+  readonly unknown: { createdAt: string; hash: string }[];
+
+  constructor(known: string[], unknown: { createdAt: string; hash: string }[]) {
+    const made = unknown.map(({ createdAt, hash }) => `one made ${new Date(Number(createdAt)).toISOString().slice(0, 16).replace('T', ' ')} UTC (${hash.slice(0, 12)})`);
+    super(
+      `the database has applied ${unknown.length === 1 ? 'a migration' : `${unknown.length} migrations`} this version does not know, ` +
+        `after ${known.at(-1) ?? 'none'}: ${made.join(', ')}. A newer coffre migrated it`,
+    );
+    this.name = 'DatabaseAhead';
+    this.known = known;
+    this.unknown = unknown;
+  }
+}
+
 function verifyHistory(
   expected: ExpectedMigration[],
   applied: AppliedMigration[] | null,
   requireComplete: boolean,
 ): void {
   const rows = applied ?? [];
-  if (rows.length > expected.length) {
-    throw new Error('database contains migrations that are absent from this image');
-  }
-  if (requireComplete && rows.length !== expected.length) {
-    throw new Error(`migration history is incomplete: expected ${expected.length}, found ${rows.length}`);
-  }
-
-  rows.forEach((row, index) => {
-    const local = expected[index];
+  rows.slice(0, expected.length).forEach((row, index) => {
+    const local = expected[index]!;
     if (row.created_at !== local.createdAt || row.hash !== local.hash) {
       throw new Error(
         `migration history diverged at ${local.tag}; applied migrations must never be edited`,
       );
     }
   });
+  if (rows.length > expected.length) {
+    throw new DatabaseAhead(expected.map((entry) => entry.tag), rows.slice(expected.length).map((row) => ({ createdAt: row.created_at, hash: row.hash })));
+  }
+  if (requireComplete && rows.length !== expected.length) {
+    throw new Error(`migration history is incomplete: expected ${expected.length}, found ${rows.length}`);
+  }
 }
 
 async function postgresMigrator(url: string): Promise<Migrator> {