編碼練習：nodejs 中的資料庫遷移工具

Anforderungen

Ich möchte ein Datenbankmigrationstool haben, das die folgenden Eigenschaften hat:

1. Jede Migration wird in einer einzigen SQL-Datei geschrieben, d. h. sowohl im „Up“- als auch im „Down“-Teil. Dadurch kann Copilot die Rollback-Migration durchführen. Und die Tatsache, dass es sich um reines SQL handelt, macht es auch zur flexibelsten und unterstütztesten Lösung.
2. Die aktuell angewendete Version sollte vom Tool verwaltet werden. Ich möchte, dass das Tool autark ist.
3. Ich möchte, dass das Tool verschiedene Datenbanken wie Postgres, MySQL, SQL Server usw. unterstützt, daher sollte es in diesem Sinne erweiterbar sein.
4. Ich möchte nicht, dass es überdimensioniert wird, daher sollten nur Treiber für die erforderliche Datenbank installiert werden, idealerweise bei Bedarf.
5. Ich möchte, dass es Teil des Javascript-Ökosystems ist, da die meisten Projekte, an denen ich arbeite, ein Teil davon sind.
6. Jede Migration sollte innerhalb einer Transaktion durchgeführt werden.

Einführung

Viele dieser Punkte sind aus meiner Erfahrung mit diesem tollen Tool namens Tern entstanden. Ich war traurig, dass Javascript nicht das Gleiche hat! (Oder vielleicht ist mir das Googeln scheiße...). Deshalb habe ich beschlossen, dass dies eine schöne Programmierübung für mich selbst und eine Geschichte sein könnte, die für jemand anderen interessant sein könnte :)

Entwicklung

Teil 1. Entwerfen des Werkzeugs

Lassen Sie uns stehlen das CLI-Tool entwerfen!

1. Alle Migrationen hätten das folgende Benennungsschema: _.sql, wobei die Nummer die Versionsnummer der Migration darstellen würde, zum Beispiel 001_initial_setup.sql.
2. Alle Migrationen würden sich in einem einzigen Verzeichnis befinden.
3. Der Datenbanktreiber wird bei Bedarf heruntergeladen, entweder als vorgefertigtes Paket oder einfach durch Ausgabe einer Art NPM-Installation .

Die Syntax für das Tool wäre also die folgende: martlet up --database-url --driver --dir

oder martlet down .

Wobei „oben“ alle Migrationen anwenden sollte, die noch nicht angewendet wurden, und „unten“ auf die angegebene Version zurücksetzen sollte.
Optionen haben die folgende Bedeutung und Standardeinstellungen:

• Datenbank-URL – Verbindungszeichenfolge für die Datenbank. Standardmäßig wird nach der Umgebungsvariablen DATABASE_URL gesucht
• Treiber – zu verwendender Datenbanktreiber. Für die erste Version werde ich Postgres nur mit einer Option namens „pg“ unterstützen.
• dir – Verzeichnis, in dem sich Migrationen befinden, Standard ist Migrationen

Wie Sie sehen, habe ich zunächst herausgefunden, wie ich das Tool aufrufen würde, bevor ich tatsächlichen Code schreibe. Dies ist eine gute Vorgehensweise, sie hilft, Anforderungen zu realisieren und Entwicklungszyklen zu verkürzen.

Teil 2. Implementierung

2.1 Parsing-Optionen

Ok, das Wichtigste zuerst! Lassen Sie uns eine index.js-Datei erstellen und die Hilfemeldung ausgeben. Es würde ungefähr so ​​aussehen:

function printHelp() {
  console.log(
    "Usage: martlet up --driver <driver> --dir <dir> --database-url <url>",
  );
  console.log(
    "       martlet down <version> --driver <driver> --dir <dir> --database-url <url>",
  );
  console.log(
    "       <version> is a number that specifies the version to migrate down to",
  );
  console.log("Options:");
  console.log('  --driver <driver>  Driver to use, default is "pg"');
  console.log('  --dir <dir>        Directory to use, default is "migrations"');
  console.log(
    "  --database-url <url> Database URL to use, default is DATABASE_URL environment variable",
  );
}

printHelp();

Jetzt analysieren wir die Optionen:

export function parseOptions(args) {
  const options = {
    dir: "migrations",
    driver: "pg",
    databaseUrl: process.env.DATABASE_URL,
  };
  for (let idx = 0; idx < args.length; ) {
    switch (args[idx]) {
      case "--help":
      case "-h": {
        printHelp();
        process.exit(0);
      }
      case "--dir": {
        options.dir = args[idx + 1];
        idx += 2;
        break;
      }
      case "--driver": {
        options.driver = args[idx + 1];
        idx += 2;
        break;
      }
      case "--database-url": {
        options.databaseUrl = args[idx + 1];
        idx += 2;
        break;
      }

      default: {
        console.error(`Unknown option: ${args[idx]}`);
        printHelp();
        process.exit(1);
      }
    }
  }
  return options;
}

Wie Sie sehen, verwende ich keine Bibliothek zum Parsen; Ich gehe einfach die Argumentliste durch und verarbeite jede Option. Wenn ich also eine boolesche Option habe, würde ich den Iterationsindex um 1 verschieben, und wenn ich eine Option mit einem Wert habe, würde ich ihn um 2 verschieben.

2.2 Implementierung des Treiberadapters

Um mehrere Treiber zu unterstützen, benötigen wir eine universelle Schnittstelle für den Zugriff auf eine Datenbank. So könnte es aussehen:

interface Adapter {
    connect(url: string): Promise<void>;
    transact(query: (fn: (text) => Promise<ResultSet>)): Promise<ResultSet>;
    close(): Promise<void>;
}

Ich denke, Verbinden und Schließen sind ziemlich offensichtliche Funktionen. Lassen Sie mich die Transaktionsmethode erklären. Es sollte eine Funktion akzeptieren, die mit einer Funktion aufgerufen würde, die einen Abfragetext akzeptiert und ein Versprechen mit einem Zwischenergebnis zurückgibt. Diese Komplexität ist erforderlich, um über eine allgemeine Schnittstelle zu verfügen, die die Möglichkeit bietet, mehrere Abfragen innerhalb einer Transaktion auszuführen. Es ist leichter zu verstehen, wenn man sich das Anwendungsbeispiel ansieht.

So sucht der Adapter also nach dem Postgres-Treiber:

class PGAdapter {
  constructor(driver) {
    this.driver = driver;
  }

  async connect(url) {
    this.sql = this.driver(url);
  }

  async transact(query) {
    return this.sql.begin((sql) => (
      query((text) => sql.unsafe(text))
    ));
  }

  async close() {
    await this.sql.end();
  }
}

Und das Anwendungsbeispiel könnte sein:

import postgres from "postgres";

const adapter = new PGAdapter(postgres);
await adapter.connect(url);
await adapter.transact(async (sql) => {
    const rows = await sql("SELECT * FROM table1");
    await sql(`INSERT INTO table2 (id) VALUES (${rows[0].id})`);
});

2.3 On-Demand-Treiberinstallation

const PACKAGES = {
  pg: "postgres@3.4.4",
};

const downloadDriver = async (driver) => {
  const pkg = PACKAGES[driver];
  if (!pkg) {
    throw new Error(`Unknown driver: ${driver}`);
  }
  try {
    await stat(join(process.cwd(), "yarn.lock"));
    const lockfile = await readFile(join(process.cwd(), "yarn.lock"));
    const packagejson = await readFile(join(process.cwd(), "package.json"));
    spawnSync("yarn", ["add", pkg], {
      stdio: "inherit",
    });
    await writeFile(join(process.cwd(), "yarn.lock"), lockfile);
    await writeFile(join(process.cwd(), "package.json"), packagejson);
    return;
  } catch {}
  spawnSync("npm", ["install", "--no-save", "--legacy-peer-deps", pkg], {
    stdio: "inherit",
  });
};

Wir versuchen zunächst, den Treiber mit Garn zu installieren, möchten aber keine Diffs im Verzeichnis generieren, deshalb behalten wir die Dateien Yarn.lock und Package.json bei. Sollte Garn nicht verfügbar sein, greifen wir auf npm zurück.

Wenn wir sichergestellt haben, dass der Treiber installiert ist, können wir einen Adapter erstellen und verwenden:

export async function loadAdapter(driver) {
  await downloadDriver(driver);
  return import(PACKAGES[driver].split("@")[0]).then(
    (m) => new PGAdapter(m.default),
  );

2.4 Implementierung der Migrationslogik

Wir beginnen damit, eine Verbindung zur Datenbank herzustellen und die aktuelle Version abzurufen:

await adapter.connect(options.databaseUrl);
console.log("Connected to database");

const currentVersion = await adapter.transact(async (sql) => {
    await sql(`create table if not exists schema_migrations (
      version integer primary key
    )`);
    const result = await sql(`select version from schema_migrations limit 1`);
    return result[0]?.version || 0;
});

console.log(`Current version: ${currentVersion}`);

Then, we read the migrations directory and sort them by version. After that, we apply every migration that has a version greater than the current one. I will just present the actual migration in the following snippet:

await adapter.transact(async (sql) => {
    await sql(upMigration);
    await sql(
      `insert into schema_migrations (version) values (${version})`
    );
    await sql(`delete from schema_migrations where version != ${version}`);
});

The rollback migration is similar, but we sort the migrations in reverse order and apply them until we reach the desired version.

3. Testing

I decided not to use any specific testing framework but use the built-in nodejs testing capabilities. They include the test runner and the assertion package.

import { it, before, after, describe } from "node:test";
import assert from "node:assert";

And to execute tests I would run node --test --test-concurrency=1.

Actually, I was writing the code in a sort of TDD manner. I didn't validate that my migrations code worked by hand, but I was writing it along with tests. That's why I decided that end-to-end tests would be the best fit for this tool.
For such an approach, tests would need to bootstrap an empty database, apply some migrations, check that database contents are correct, and then roll back to the initial state and validate that the database is empty.
To run a database, I used the "testcontainers" library, which provides a nice wrapper around docker.

before(async () => {
    console.log("Starting container");
    container = await new GenericContainer("postgres:16-alpine")
    .withExposedPorts(5432)
    .withEnvironment({ POSTGRES_PASSWORD: "password" })
    .start();
});

after(async () => {
    await container.stop();
});

I wrote some simple migrations and tested that they worked as expected. Here is an example of a database state validation:

const sql = pg(`postgres://postgres:password@localhost:${port}/postgres`);
const result = await sql`select * from schema_migrations`;
assert.deepEqual(result, [{ version: 2 }]);
const tables =
    await sql`select table_name from information_schema.tables where table_schema = 'public'`;
assert.deepEqual(tables, [
    { table_name: "schema_migrations" },
    { table_name: "test" },
]);

4. Conclusion

This was an example of how I would approach the development of a simple CLI tool in the javascript ecosystem. I want to note that the modern javascript ecosystem is pretty charged and powerful, and I managed to implement the tool with a minimum of external dependencies. I used a postgres driver that would be downloaded on demand and testcontainers for tests. I think that approach gives developers the most flexibility and control over the application.

5. References

• martlet repo
• tern
• postgres driver

以上是編碼練習：nodejs 中的資料庫遷移工具的詳細內容。更多資訊請關注PHP中文網其他相關文章！