Datenbankmigrationen sind Änderungen, die an einer Datenbank vorgenommen werden. Diese Änderungen können das Ändern des Schemas einer Tabelle, das Aktualisieren der Daten in einer Reihe von Datensätzen, das Befüllen von Daten oder das Löschen eines Bereichs von Datensätzen umfassen.

Datenbankmigrationen werden in der Regel ausgeführt, bevor eine Anwendung gestartet wird, und sie werden nicht mehr als einmal erfolgreich für dieselbe Datenbank ausgeführt. Datenbankmigrationstools speichern eine Historie von Migrationen, die in einer Datenbank ausgeführt wurden, damit sie für zukünftige Zwecke nachverfolgt werden können.

In diesem Artikel erfahren Sie, wie Sie Datenbankmigrationen in einer minimalen Node.js-API-Anwendung einrichten und ausführen. Wir werden ts-migrate-mongoose und ein npm-Skript verwenden, um eine Migration zu erstellen und Daten in eine MongoDB-Datenbank einzufügen. ts-migrate-mongoose unterstützt das Ausführen von Migrationsskripten aus TypeScript-Code sowie aus CommonJS-Code.

ts-migrate-mongoose ist ein Migrationsframework für Node.js-Projekte, die mongoose als Objekt-Daten-Mapping verwenden. Es bietet eine Vorlage zum Schreiben von Migrationsskripten. Es bietet auch eine Konfiguration, um die Skripte programmgesteuert und von der CLI aus auszuführen.

Inhaltsverzeichnis

So richten Sie das Projekt ein

Um ts-migrate-mongoose für Datenbankmigrationen zu verwenden, benötigen Sie Folgendes:

  1. Ein Node.js-Projekt mit mongoose als Abhängigkeit installiert.

  2. Eine mit dem Projekt verbundene MongoDB-Datenbank.

  3. MongoDB Compass (Optional – um uns die Änderungen in der Datenbank anzeigen zu lassen).

Ein Starter-Repository, das von ts-migrate-mongoose-starter-repo geklont werden kann, wurde für die einfache Verwendung erstellt. Klone das Repository, fülle die Umgebungsvariablen aus und starte die Anwendung, indem du den Befehl npm start ausführst.

Gehe mit einem Browser oder einem API-Client wie Postman zu http://localhost:8000 und der Server gibt den Text „Hallo!“ zurück, um zu zeigen, dass die Starter-Anwendung wie erwartet läuft.

Wie man ts-migrate-mongoose für das Projekt konfiguriert

Um ts-migrate-mongoose für das Projekt zu konfigurieren, installiere ts-migrate-mongoose mit diesem Befehl:

npm install ts-migrate-mongoose

ts-migrate-mongoose ermöglicht die Konfiguration mit einer JSON-Datei, einer TypeScript-Datei, einer .env-Datei oder über die Befehlszeile. Es wird empfohlen, eine .env-Datei zu verwenden, da der Inhalt der Konfiguration ein Datenbankpasswort enthalten kann und es nicht ratsam ist, dies öffentlich zugänglich zu machen. .env-Dateien sind normalerweise über .gitignore-Dateien verborgen, damit sie sicherer zu verwenden sind. In diesem Projekt wird eine .env-Datei für die ts-migrate-mongoose-Konfiguration verwendet.

Die Datei sollte die folgenden Schlüssel und ihre Werte enthalten:

  • MIGRATE_MONGO_URI – die URI der Mongo-Datenbank. Sie ist identisch mit der Datenbank-URL.

  • MIGRATE_MONGO_COLLECTION – der Name der Sammlung (oder Tabelle), in der Migrationen gespeichert werden sollen. Der Standardwert ist Migrationen, der in diesem Projekt verwendet wird. ts-migrate-mongoose speichert Migrationen in MongoDB.

  • MIGRATE_MIGRATIONS_PATH – der Pfad zum Ordner zur Speicherung und zum Lesen von Migrationskripten. Der Standardwert ist ./migrations, der in diesem Projekt verwendet wird.

Wie man Benutzerdaten mit ts-migrate-mongoose seedet

Wir konnten ein Projekt erstellen und erfolgreich mit einer Mongo-Datenbank verbinden. Zu diesem Zeitpunkt möchten wir Benutzerdaten in die Datenbank einpflegen. Wir müssen:

  1. Eine Benutzersammlung (oder Tabelle) erstellen

  2. Verwenden Sie ts-migrate-mongoose, um ein Migrationskript zum Einpflegen von Daten zu erstellen

  3. Verwenden Sie ts-migrate-mongoose, um die Migration auszuführen, um die Benutzerdaten vor dem Start der Anwendung in die Datenbank einzupflegen

1. Erstellen Sie eine Benutzerkollektion mit Mongoose

Mongoose-Schema kann verwendet werden, um eine Benutzerkollektion (oder Tabelle) zu erstellen. Benutzerdokumente (oder Datensätze) haben die folgenden Felder (oder Spalten): E-Mail, liebstesEmoji und Geburtsjahr.

Um ein Mongoose-Schema für die Benutzerkollektion zu erstellen, erstellen Sie eine Datei user.model.js im Stammverzeichnis des Projekts mit dem folgenden Codeschnipsel:

const mongoose = require("mongoose");

const userSchema = new mongoose.Schema(
  {
    email: {
      type: String,
      lowercase: true,
      required: true,
    },
    favouriteEmoji: {
      type: String,
      required: true,
    },
    yearOfBirth: {
      type: Number,
      required: true,
    },
  },
  {
    timestamps: true,
  }
);

module.exports.UserModel = mongoose.model("User", userSchema);

2. Erstellen Sie ein Migrationskript mit ts-migrate-mongoose

ts-migrate-mongoose bietet CLI-Befehle, die verwendet werden können, um Migrationskripte zu erstellen.

Das Ausführen von npx migrate create <name-of-script> im Stammordner des Projekts erstellt ein Skript im MIGRATE_MIGRATIONS_PATH Ordner (./migrations in unserem Fall). <name-of-script> ist der Name, den wir dem Migrationskript geben möchten, wenn es erstellt wird.

Um ein Migrationskript zum Einpflegen von Benutzerdaten zu erstellen, führen Sie folgendes aus:

npx migrate create seed-users

Der Befehl wird eine Datei im ./migrations Ordner mit einem Namen im Format –<timestamp>-seed-users.ts erstellen. Die Datei wird den folgenden Codeschnipselinhalt haben:

// Importiere hier deine Modelle

export async function up (): Promise<void> {
  // Schreibe hier die Migration
}

export async function down (): Promise<void> {
  // Schreibe hier die Migration
}

Die Funktion up wird verwendet, um die Migration auszuführen. Die Funktion down wird verwendet, um das, was die Funktion up ausführt, bei Bedarf rückgängig zu machen. In unserem Fall versuchen wir, Benutzer in die Datenbank einzufügen. Die Funktion up wird den Code enthalten, um Benutzer in die Datenbank einzufügen, und die Funktion down wird den Code enthalten, um die Benutzer zu löschen, die in der Funktion up erstellt wurden.

Wenn die Datenbank mit MongoDB Compass überprüft wird, wird die Migrationskollektion ein Dokument haben, das so aussieht:

{
  "_id": ObjectId("6744740465519c3bd9c1a7d1"),
  "name": "seed-users",
  "state": "down",
  "createdAt": 2024-11-25T12:56:36.316+00:00,
  "updatedAt": 2024-11-25T12:56:36.316+00:00,
  "__v": 0
}

Das Feld state des Migrationsdokuments ist auf down gesetzt. Nach erfolgreicher Ausführung ändert es sich in up.

Sie können den Code in ./migrations/<timestamp>-seed-users.ts auf den untenstehenden Ausschnitt aktualisieren:

require("dotenv").config() // Umgebungsvariablen laden
const db = require("../db.js")
const { UserModel } = require("../user.model.js");

const seedUsers = [
  { email: "[email protected]", favouriteEmoji: "🏃", yearOfBirth: 1997 },
  { email: "[email protected]", favouriteEmoji: "🍏", yearOfBirth: 1998 },
];

export async function up (): Promise<void> {
  await db.connect(process.env.MONGO_URI)
  await UserModel.create(seedUsers);}

export async function down (): Promise<void> {
  await db.connect(process.env.MONGO_URI)
  await UserModel.delete({
    email: {
      $in: seedUsers.map((u) => u.email),
    },
  });
}

3. Führen Sie die Migration vor dem Start der Anwendung aus

ts-migrate-mongoose bietet uns CLI-Befehle zum Ausführen der Funktionen up und down von Migrationskripts.

Mit npx migrate up <name-of-script> können wir die Funktion up eines bestimmten Skripts ausführen. Mit npx migrate up können wir die Funktion up aller Skripts im Ordner ./migrations ausführen, deren state in der Datenbank auf down steht.

Um die Migration vor dem Start der Anwendung auszuführen, nutzen wir npm-Skripte. npm-Skripte mit einem Präfix von pre werden vor einem Skript ohne den pre-Präfix ausgeführt. Zum Beispiel, wenn es ein dev-Skript und ein predev-Skript gibt, wird jedes Mal, wenn das dev-Skript mit npm run dev ausgeführt wird, das predev-Skript automatisch vor dem dev-Skript ausgeführt.

Wir werden dieses Feature von npm-Skripten nutzen, um den Befehl ts-migrate-mongoose in ein prestart-Skript zu platzieren, damit die Migration vor dem Ausführen des start-Skripts ausgeführt wird.

Aktualisieren Sie die package.json-Datei, um ein prestart-Skript zu haben, das den ts-migrate-mongoose-Befehl für das Ausführen der up-Funktion von Migrations-Skripten im Projekt ausführt.

  "scripts": {
    "prestart": "npx migrate up",
    "start": "node index.js"
  },

Mit diesem Setup, wenn npm run start ausgeführt wird, um die Anwendung zu starten, wird das prestart-Skript ausgeführt, um die Migration mithilfe von ts-migrate-mongoose auszuführen und die Datenbank vor dem Start der Anwendung zu befüllen.

Sie sollten nach dem Ausführen von npm run start etwas Ähnliches wie den untenstehenden Schnipsel haben:

Synchronizing database with file system migrations...
MongoDB connection successful
up: 1732543529744-seed-users.ts 
All migrations finished successfully

> [email protected] start
> node index.js

MongoDB connection successful                      
Server listening on port 8000

Überprüfen Sie den seed-users-Branch des Repositories, um den aktuellen Stand des Quellcodes zu diesem Zeitpunkt im Artikel zu sehen.

Wie man einen API-Endpunkt erstellt, um vorgefertigte Daten abzurufen

Wir können einen API-Endpunkt erstellen, um die vorgefertigten Benutzerdaten in unserer Datenbank abzurufen. Aktualisieren Sie in der Datei server.js den Code wie im untenstehenden Schnipsel:

const { UserModel } = require("./user.model.js")

module.exports = async function (req, res) {
  const users = await UserModel.find({}) // Holen Sie alle Benutzer aus der Datenbank

  res.writeHead(200, { "Content-Type": "application/json" });
  return res.end(JSON.stringify({ // Geben Sie eine JSON-Repräsentation der abgerufenen Benutzerdaten zurück
    users: users.map((u) => ({
      email: u.email,
      favouriteEmoji: u.favouriteEmoji,
      yearOfBirth: u.yearOfBirth,
      createdAt: u.createdAt
    }))
  }, null, 2));
};

Wenn wir die Anwendung starten und http://localhost:8000 mit Postman oder einem Browser besuchen, erhalten wir eine JSON-Antwort ähnlich der unten stehenden:

{
  "users": [
    {
      "email": "[email protected]",
      "favouriteEmoji": "🏃",
      "yearOfBirth": 1997,
      "createdAt": "2024-11-25T14:18:55.416Z"
    },
    {
      "email": "[email protected]",
      "favouriteEmoji": "🍏",
      "yearOfBirth": 1998,
      "createdAt": "2024-11-25T14:18:55.416Z"
    }
  ]
}

Beachten Sie, dass wenn die Anwendung erneut gestartet wird, das Migrations-Skript nicht mehr ausgeführt wird, da der Zustand der Migration nach erfolgreicher Ausführung nun up sein wird.

Überprüfen Sie den fetch-users Zweig des Repositorys, um den aktuellen Stand des Codebases zu diesem Zeitpunkt im Artikel zu sehen.

Abschluss

Migrationen sind nützlich beim Aufbau von Anwendungen, wenn Initialdaten zum Testen gesät werden müssen, administrative Benutzer gesät werden müssen, Datenbankschema durch Hinzufügen oder Entfernen von Spalten aktualisiert werden müssen und die Werte von Spalten in vielen Datensätzen auf einmal aktualisiert werden müssen.

ts-migrate-mongoose kann ein Framework für die Ausführung von Migrationen für Ihre Node.js-Anwendungen bereitstellen, wenn Sie Mongoose mit MongoDB verwenden.