@sebspark/spanner-migrate 0.1.1 → 1.0.0

package/README.md

@@ -14,90 +14,196 @@ yarn add -D @sebspark/spanner-migrate
 
 ---
 
-## CLI Usage
+## CLI Commands
 
-Run `spanner-migrate` from your project root. If no command is provided, the help message is displayed.
+`spanner-migrate` provides several commands for managing database migrations in Google Spanner.
 
-```zsh
-spanner-migrate [command] [options]
+### Initialize Configuration
+
+```sh
+spanner-migrate init
 ```
 
-### Commands
+Initializes a `.spanner-migrate.config.json` file by prompting for:
+- Spanner instance name
+- One or more database configurations
+- Optional Google Cloud project name
 
-#### `init`
-Initialize a Spanner migration configuration file (`.spanner-migrate.config.json`).
+### Create a Migration
 
-**Usage:**
+```sh
+spanner-migrate create <description ...> [--database <name>]
+spanner-migrate create add users table
+spanner-migrate create --database=mydb add users table
+```
 
-```zsh
-spanner-migrate init
+Creates a new migration file with the specified description.
+
+- If `--database` (`-d`) is provided, it uses the specified database.
+- If multiple databases exist and none is specified, the user is prompted to select one.
+- The filename is generated from the description (`<timestamp>_add_users_table.sql`).
+
+### Apply Migrations
+
+```sh
+spanner-migrate up
+spanner-migrate up --database <name>
+spanner-migrate up --database <name> --max <n>
+```
+
+Applies pending migrations.
+
+- If **no** `--database` and `--max` are provided, applies all migrations to all databases.
+- If `--database` (`-d`) is provided, applies migrations only to that database.
+- If `--max` (`-m`) is provided, limits the number of migrations applied (requires `--database`).
+- `--max` must be an integer greater than 0.
+
+### Roll Back Last Migration
+
+```sh
+spanner-migrate down
+spanner-migrate down --database <name>
+```
+
+Rolls back the last applied migration.
+
+- If a **single** database exists, it is automatically selected.
+- If multiple databases exist, `--database` is **required**.
+- The specified `--database` must exist.
+
+### Show Migration Status
+
+```sh
+spanner-migrate status
+spanner-migrate status --database <name>
+```
+
+Displays migration status.
+
+- If `--database` is specified, shows status for that database.
+- If no `--database` is provided, shows status for all configured databases.
+
+### Help
+
+```sh
+spanner-migrate --help
+spanner-migrate <command> --help
 ```
 
-**Prompts:**
-- `Enter the path for your migrations`: Directory for migration files (default: `./migrations`).
-- `Enter Spanner instance name`: The name of the Spanner instance.
-- `Enter Spanner database name`: The name of the Spanner database.
-- `Enter Google Cloud project name`: (Optional) The Google Cloud project name.
+Displays help for the CLI or a specific command.
 
 ---
 
-#### `create <description>`
-Create a new migration file.
+## Programmatic Usage
 
-**Usage:**
+In addition to the CLI, `spanner-migrate` can be used as a Node.js module to manage migrations programmatically.
 
-```zsh
-spanner-migrate create add users table
+### Importing
+
+```typescript
+import { init, create, up, down, status } from '@sebspark/spanner-migrate'
 ```
 
-#### `up`
-Apply pending migrations
+### Initializing Configuration
 
-**Usage:**
+```typescript
+import { init, type Config } from '@sebspark/spanner-migrate'
 
-```zsh
-spanner-migrate up
+const config: Config = {
+  instance: {
+    name: 'my-instance',
+    databases: [
+      { name: 'mydb', migrationsPath: './migrations' },
+    ],
+  },
+  projectId: 'my-gcp-project',
+}
+
+await init(config, '.spanner-migrate.config.json')
 ```
 
-If you don't want to apply all pending migrations, use the `--max` or `-m` flag
+Writes the given configuration to a `.spanner-migrate.config.json` file.
 
-```zsh
-spanner migrate up --max 1
+### Creating a Migration
+
+```typescript
+import { create, type DatabaseConfig } from '@sebspark/spanner-migrate'
+
+const databaseConfig: DatabaseConfig = {
+  name: 'mydb',
+  migrationsPath: './migrations',
+}
+
+await create(databaseConfig, 'add users table')
 ```
 
-#### `down`
-Rollback one migration
+Creates a new migration file for the specified database.
 
-**Usage:**
+### Applying Migrations
 
-```zsh
-spanner-migrate down
+```typescript
+import { up, type Config, type DatabaseConfig } from '@sebspark/spanner-migrate'
+
+// Load configuration
+const config: Config = /* Load from file or define inline */
+
+// Apply all migrations to all databases
+await up(config)
+
+// Apply all migrations to a specific database
+const databaseConfig: DatabaseConfig = config.instance.databases[0]
+await up(config, databaseConfig)
+
+// Apply up to 5 migrations to a specific database
+await up(config, databaseConfig, 5)
 ```
 
-#### `status`
-Check migration status
+- Applies pending migrations.
+- If a database is specified, only applies migrations to that database.
+- If `max` is specified, applies at most `max` migrations.
 
-**Usage:**
+### Rolling Back Migrations
 
-```zsh
-spanner-migrate status
+```typescript
+import { up, type Config, type DatabaseConfig } from '@sebspark/spanner-migrate'
+
+const config: Config = /* Load from file */
+const databaseConfig: DatabaseConfig = config.instance.databases[0]
+
+// Roll back the last applied migration
+await down(config, databaseConfig)
 ```
-Displays an overview of applied and peding migrations
 
-```text
-Migrations
+- Rolls back the last applied migration for the specified database.
+- Requires a database to be specified.
+
+### Checking Migration Status
 
-Applied
---------------------------------------------------------------------------------
-20250122080434866_add_users_table
-20250122080444982_add_index_on_users
+```typescript
+import { up, type Config, type DatabaseConfig } from '@sebspark/spanner-migrate'
 
-New
---------------------------------------------------------------------------------
-20250122080444982_add_index_on_users
+const config: Config = /* Load from file */
+
+// Check status for all databases
+const migrationStatus = await status(config)
+console.log(migrationStatus)
+
+// Check status for a specific database
+const databaseConfig = config.instance.databases[0]
+const migrationStatusSingle = await status(config, [databaseConfig])
+console.log(migrationStatusSingle)
 ```
 
----
+- Displays applied and pending migrations for one or more databases.
+- If a specific database is provided, only its status is shown.
+
+## Running on Spanner Emulator
+
+If you want to test your migrations against a Spanner Emulator, you will need to set:
+
+```typescript
+process.env.SPANNER_EMULATOR_HOST = 'localhost:<port>'
+```
 
 ## License
 

package/dist/{chunk-K5WX6ESL.mjs → chunk-SZDH364K.mjs}

@@ -38,7 +38,7 @@ var applyDown = async (db) => {
     json: true
   };
   const [rows] = await db.run(req);
-  const lastMigration = rows == null ? void 0 : rows[0];
+  const lastMigration = rows?.[0];
   if (!lastMigration) {
     throw new Error("No migrations found to roll back.");
   }
@@ -70,12 +70,11 @@ var runScript = async (db, script) => {
   }
   for (const statement of statements) {
     console.log(`Executing statement: ${statement}`);
-    const sql = statement.replace(/--.*$/gm, "");
-    if (isSchemaChange(sql)) {
-      await db.updateSchema(sql);
+    if (isSchemaChange(statement)) {
+      await db.updateSchema(statement);
     } else {
       await db.runTransactionAsync(async (transaction) => {
-        await transaction.runUpdate(sql);
+        await transaction.runUpdate(statement);
         await transaction.commit();
       });
     }
@@ -101,12 +100,12 @@ var SQL_CREATE_TABLE_MIGRATIONS = `
     down STRING(1024)
   ) PRIMARY KEY (id)
 `;
-var ensureMigrationTable = async (database) => {
-  const [rows] = await database.run(SQL_SELECT_TABLE_MIGRATIONS);
+var ensureMigrationTable = async (db) => {
+  const [rows] = await db.run(SQL_SELECT_TABLE_MIGRATIONS);
   if (rows.length) return;
   console.log("Creating migration table");
   try {
-    await database.updateSchema(SQL_CREATE_TABLE_MIGRATIONS);
+    await db.updateSchema(SQL_CREATE_TABLE_MIGRATIONS);
   } catch (err) {
     console.error("Failed to create migrations table");
     throw err;
@@ -132,12 +131,12 @@ var getAppliedMigrations = async (db) => {
 };
 
 // src/files.ts
-import { access, mkdir, readdir, writeFile } from "node:fs/promises";
+import { access, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 var getMigrationFiles = async (path) => {
   try {
     const files = await readdir(path);
-    const migrationFileIds = files.filter((file) => file.endsWith(".ts")).map((file) => file.replace(/\.ts$/, ""));
+    const migrationFileIds = files.filter((file) => file.endsWith(".sql")).map((file) => file.replace(/\.sql$/, ""));
     return migrationFileIds;
   } catch (error) {
     throw new Error(
@@ -147,35 +146,39 @@ var getMigrationFiles = async (path) => {
 };
 var getMigration = async (path, id) => {
   try {
-    const filePath = resolve(process.cwd(), join(path, `${id}.ts`));
+    const filePath = resolve(process.cwd(), join(path, `${id}.sql`));
     try {
       await access(filePath);
     } catch (err) {
       throw new Error(`Migration file not found: ${filePath}`);
     }
-    const migrationModule = await import(filePath);
-    if (!migrationModule.up || !migrationModule.down) {
+    const migrationText = await readFile(filePath, "utf8");
+    const up2 = getSql(migrationText, "up");
+    const down2 = getSql(migrationText, "down");
+    const description = getDescription(migrationText);
+    if (!up2 || !down2) {
       throw new Error(
         `Migration file ${filePath} does not export required scripts (up, down).`
       );
     }
-    return {
-      id,
-      description: id.split("_").slice(1).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" "),
-      // Generate a human-readable description
-      up: migrationModule.up,
-      down: migrationModule.down
-    };
+    return { id, description, up: up2, down: down2 };
   } catch (error) {
     throw new Error(
       `Failed to get migration ${id}: ${error.message}`
     );
   }
 };
+var getDescription = (text) => text?.match(/^--\s*Description:\s*(.+)$/m)?.[1]?.trim() || "";
+var getSql = (text, direction) => {
+  const rx = {
+    up: /---- UP ----\n([\s\S]*?)\n---- DOWN ----/,
+    down: /---- DOWN ----\n([\s\S]*)$/
+  };
+  return text?.match(rx[direction])?.[1]?.replace(/--.*$/gm, "").trim();
+};
 var getNewMigrations = (applied, files) => {
   const sortedFiles = files.sort();
   for (let ix = 0; ix < applied.length; ix++) {
-    console.log(sortedFiles[ix], applied[ix].id);
     if (sortedFiles[ix] !== applied[ix].id) {
       throw new Error(
         `Mismatch between applied migrations and files. Found '${sortedFiles[ix]}' but expected '${applied[ix].id}' at position ${ix}.`
@@ -183,25 +186,24 @@ var getNewMigrations = (applied, files) => {
     }
   }
   const newMigrations = sortedFiles.slice(applied.length);
-  console.log(`Found ${newMigrations.length} new migrations.`);
   return newMigrations;
 };
 var createMigration = async (path, description) => {
   const timestamp = (/* @__PURE__ */ new Date()).toISOString();
   const compactTimestamp = timestamp.replace(/[-:.TZ]/g, "");
   const parsedDescription = description.replace(/\s+/g, "_").toLowerCase();
-  const filename = `${compactTimestamp}_${parsedDescription}.ts`;
+  const filename = `${compactTimestamp}_${parsedDescription}.sql`;
   const filePath = join(path, filename);
-  const template = `// ${timestamp}
-// ${description}
+  const template = `-- Created: ${timestamp}
+-- Description: ${description}
+
+---- UP ----
+
+
+
+---- DOWN ----
 
-export const up = \`
-  -- SQL for migrate up
-\`
 
-export const down = \`
-  -- SQL for migrate down
-\`
 `;
   try {
     await mkdir(path, { recursive: true });
@@ -234,42 +236,74 @@ var init = async (config, configPath) => {
 var create = async (config, description) => {
   await createMigration(config.migrationsPath, description);
 };
-var up = async (config, max = 1e3) => {
-  const db = getDb(config);
-  await ensureMigrationTable(db);
-  const appliedMigrations = await getAppliedMigrations(db);
-  const migrationFiles = await getMigrationFiles(config.migrationsPath);
-  const newMigrations = getNewMigrations(appliedMigrations, migrationFiles);
-  console.log(`Found ${newMigrations.length} new migrations.`);
-  console.log(newMigrations.map((mig) => `	${mig}`).join("\n"));
-  for (const id of newMigrations.slice(0, max)) {
-    const migration = await getMigration(config.migrationsPath, id);
-    await applyUp(db, migration);
+var up = async (config, database, max) => {
+  if (max && !database) {
+    throw new Error("Max number of migrations requires specifying a database");
+  }
+  const databases = database ? [database] : config.instance.databases;
+  for (const databaseConfig of databases) {
+    const path = {
+      projectId: config.projectId,
+      instanceName: config.instance.name,
+      databaseName: databaseConfig.name
+    };
+    const db = getDb(path);
+    await ensureMigrationTable(db);
+    const appliedMigrations = await getAppliedMigrations(db);
+    const migrationFiles = await getMigrationFiles(
+      databaseConfig.migrationsPath
+    );
+    const newMigrations = getNewMigrations(appliedMigrations, migrationFiles);
+    console.log(`Found ${newMigrations.length} new migrations.`);
+    console.log(newMigrations.map((mig) => `	${mig}`).join("\n"));
+    const newMigrationsToApply = max ? newMigrations.slice(0, max) : newMigrations;
+    for (const id of newMigrationsToApply) {
+      const migration = await getMigration(databaseConfig.migrationsPath, id);
+      await applyUp(db, migration);
+    }
   }
 };
-var down = async (config) => {
-  const db = getDb(config);
+var down = async (config, database) => {
+  const path = {
+    projectId: config.projectId,
+    instanceName: config.instance.name,
+    databaseName: database.name
+  };
+  const db = getDb(path);
   await ensureMigrationTable(db);
   await applyDown(db);
 };
-var status = async (config) => {
-  const db = getDb(config);
-  await ensureMigrationTable(db);
-  const appliedMigrations = await getAppliedMigrations(db);
-  const migrationFiles = await getMigrationFiles(config.migrationsPath);
-  const newMigrations = getNewMigrations(appliedMigrations, migrationFiles);
-  return [
-    "Migrations",
-    "",
-    "Applied",
-    "--------------------------------------------------------------------------------",
-    `${appliedMigrations.map((m) => m.id).join("\n")}
+var status = async (config, databases) => {
+  const statuses = [];
+  for (const databaseConfig of databases || config.instance.databases) {
+    const path = {
+      projectId: config.projectId,
+      instanceName: config.instance.name,
+      databaseName: databaseConfig.name
+    };
+    const db = getDb(path);
+    await ensureMigrationTable(db);
+    const appliedMigrations = await getAppliedMigrations(db);
+    const migrationFiles = await getMigrationFiles(
+      databaseConfig.migrationsPath
+    );
+    const newMigrations = getNewMigrations(appliedMigrations, migrationFiles);
+    statuses.push(
+      [
+        `Migrations [${databaseConfig.name}]`,
+        "",
+        "Applied",
+        "--------------------------------------------------------------------------------",
+        `${appliedMigrations.map((m) => m.id).join("\n")}
 `,
-    "New",
-    "--------------------------------------------------------------------------------",
-    `${newMigrations.join("\n")}
+        "New",
+        "--------------------------------------------------------------------------------",
+        `${newMigrations.join("\n")}
 `
-  ].join("\n");
+      ].join("\n")
+    );
+  }
+  return statuses.join("\n\n");
 };
 
 export {