Kisley Kanel: ein perfektes Duo

Ich bin jemand, der sich seit Beginn der Entwicklung meiner ersten Projekte (meiner OT-Pokémon und meiner ersten Websites für Habbo) immer für Raw SQL entschieden hat. Ehrlich gesagt genieße ich es immer noch sehr, meine eigenen Abfragen zu schreiben und eine präzisere Kontrolle über diese „untergeordnete“ Ebene zu haben. Mit einem ORM fühle ich mich nicht ganz wohl, da ich bereits Tage damit verbracht habe, Protokolle zu analysieren, um ineffiziente Abfragen zu identifizieren und zu optimieren.

Allerdings gab es in vielen Codebasen, in denen ich mit Raw SQL arbeitete, in der überwiegenden Mehrheit keine Migrationskontrolle und die Datenbank wurde auch nicht überwacht. Alles funktionierte improvisatorisch: „Benötigen Sie ein neues Feld? Führen Sie ALTER TABLE aus und fügen Sie eine neue Spalte hinzu.“ Dieser Ansatz war in allen Szenarien äußerst schädlich, es stellten sich mehrere Fragen wie: „Welche Spalten sollten wir in der Produktionsumgebung nach oben verschieben?“, „Welche neuen Entitäten wurden erstellt?“, „Sind die Umgebungen synchronisiert?“ – und viele andere ähnliche Probleme.

Die Lösung meiner Probleme

Angesichts all dieser Probleme beschloss ich, neue Tools einzuführen, um meine Routine und die der Teams, mit denen ich zusammengearbeitet habe, gesünder zu gestalten. Ich wollte nicht auf die Flexibilität verzichten, die ich hatte, aber ich wollte auch die Freiheitsgrade der Anwendung besser kontrollieren. Nach vielen Recherchen habe ich ein Tool gefunden, das meiner Meinung nach das vollständigste zur Lösung dieser Probleme ist: Kysely, es ist ein Abfrage-Builder für TypeScript, der nicht nur praktisch, sondern auch absolut typsicher ist – ein super wichtiger Punkt für mich. Diese Bibliothek erregte meine Aufmerksamkeit so sehr, dass ich begann, direkt und indirekt aktiv zur Community beizutragen und Plugins für andere Open-Source-Bibliotheken zu erstellen, die in Kysely integriert sind.

Eine der größten Schwierigkeiten bei der Arbeit mit Kysely besteht jedoch darin, dass es im Gegensatz zu ORMs keine Entität oder automatische Generierung von Typen/Schnittstellen hat. All diese Arbeiten müssen manuell erledigt werden, was etwas anstrengend sein kann. Während meiner Suche nach Lösungen habe ich ein Tool gefunden, das ich letztendlich in allen meinen Projekten mit PostgreSQL übernommen habe: Kanel. Kanel generiert automatisch Datenbanktypisierungen und ergänzt Kysely perfekt.

Darüber hinaus verfügt Kanel über eine zusätzliche Funktion zur direkten Verwendung mit Kysely: Kanel-Kysely. Ich habe aktiv zu diesem Repository beigetragen und dabei geholfen, neue Funktionen zu entwickeln, wie z. B. Typfilter für Migrationstabellen und die Konvertierung von Zod-Objekten in camelCase.

Kysely konfigurieren

Ich werde NestJS verwenden, um die folgenden Beispiele zu veranschaulichen. Wenn Sie also die Syntax oder etwas im Code nicht verstehen, empfehle ich Ihnen, die NestJS-Dokumentation zu lesen. Meiner Meinung nach ist es das beste JavaScript-Framework – insbesondere, wenn Sie JavaScript „entkommen“ möchten. Aber das ist ein Thema für einen anderen Beitrag von mir.

Zuvor müssen Sie ein Repository mit NestJS initialisiert haben, wenn Sie den Beispielen genau folgen möchten. Sie können jedoch auch Ihren eigenen Code entwickeln.

Zuerst müssen wir Kysely selbst, seine CLI und das PostgreSQL-Modul für Node.js installieren.

npm i kysely pg && npm i kysely-ctl --save-dev

Als nächstes müssen wir im Stammverzeichnis des Projekts eine Konfigurationsdatei für Kysely erstellen. Ich werde auch das Knex-Präfix für unsere Migrations- und Seed-Dateien verwenden.

// kysely.config.ts

import "dotenv/config";

import { defineConfig, getKnexTimestampPrefix } from "kysely-ctl";
import { Pool } from "pg";

export default defineConfig({
  dialect: "pg",
  dialectConfig: {
    pool: new Pool({ connectionString: process.env.DATABASE_URL }),
  },
  migrations: {
    migrationFolder: "src/database/migrations",
    getMigrationPrefix: getKnexTimestampPrefix,
  },
  seeds: {
    seedFolder: "src/database/seeds",
    getSeedPrefix: getKnexTimestampPrefix,
  },
});

Als nächstes führen wir den Befehl npx kysely migrate make create_user_table in unserem Terminal aus. Es wird für die Erstellung unserer ersten Migration verantwortlich sein. Als Nächstes erstellen wir eine neue Benutzertabelle und führen diese Migration anschließend in unserer Datenbank mit dem Befehl npx kysely migrate Latest aus.

// 20241225222128_create_user_table.ts

import { sql, type Kysely } from 'kysely'


export async function up(db: Kysely<any>): Promise<void> {
  await db.schema
  .createTable("user")
  .addColumn("id", "serial", (col) => col.primaryKey())
  .addColumn("name", "text", (col) => col.notNull())
  .addColumn("email", "text", (col) => col.unique().notNull())
  .addColumn("password", "text", (col) => col.notNull())
  .addColumn("created_at", "timestamp", (col) =>
    col.defaultTo(sql`now()`).notNull(),
  )
  .execute();
}

export async function down(db: Kysely<any>): Promise<void> {
  await db.schema.dropTable("user").execute();
}

Nachdem wir alle diese Schritte abgeschlossen haben, erstellen wir ein Modul für unsere Datenbank. Beachten Sie auch, dass ich ein Kysely-Plugin verwende, um unsere Spalten in camelCase zu konvertieren.

// src/database/database.module.ts

import { EnvService } from "@/env/env.service";
import { Global, Logger, Module } from "@nestjs/common";
import { CamelCasePlugin, Kysely, PostgresDialect } from "kysely";
import { Pool } from "pg";

export const DATABASE_CONNECTION = "DATABASE_CONNECTION";

@Global()
@Module({
  providers: [
    {
      provide: DATABASE_CONNECTION,
      useFactory: async (envService: EnvService) => {
        const dialect = new PostgresDialect({
          pool: new Pool({
            connectionString: envService.get("DATABASE_URL"),
          }),
        });

        const nodeEnv = envService.get("NODE_ENV");

        const db = new Kysely({
          dialect,
          plugins: [new CamelCasePlugin()],
          log: nodeEnv === "dev" ? ["query", "error"] : ["error"],
        });

        const logger = new Logger("DatabaseModule");

        logger.log("Successfully connected to database");

        return db;
      },
      inject: [EnvService],
    },
  ],
  exports: [DATABASE_CONNECTION],
})
export class DatabaseModule {}

Kanel konfigurieren

Beginnen wir mit der Installation unserer Abhängigkeiten.

npm i kanel kanel-kysely --save-dev

Als nächstes erstellen wir unsere Konfigurationsdatei, damit Kanel mit seiner Arbeit beginnen kann. Beachten Sie, dass ich einige Plugins verwenden werde, wie etwa camelCaseHook (um unsere Schnittstellen in camelCase umzuwandeln) und kyselyTypeFilter (um Kyselys Migrationstabellen auszuschließen), eine dieser Funktionen, zu denen ich das Vergnügen beisteuern und die Arbeit, die wir hatten, gleichmäßig machen konnte einfacher .

// .kanelrc.js

require("dotenv/config");

const { kyselyCamelCaseHook, makeKyselyHook, kyselyTypeFilter } = require("kanel-kysely");

/** @type {import('kanel').Config} */
module.exports = {
  connection: {
    connectionString: process.env.DATABASE_URL,
  },
  typeFilter: kyselyTypeFilter,
  preDeleteOutputFolder: true,
  outputPath: "./src/database/schema",
  preRenderHooks: [makeKyselyHook(), kyselyCamelCaseHook],
};

Sobald die Datei erstellt ist, führen wir den Befehl npx kanel in unserem Terminal aus. Beachten Sie, dass in dem in der Konfigurationsdatei angegebenen Pfad ein Verzeichnis erstellt wurde. Dieses Verzeichnis entspricht dem Namen Ihres Schemas, in unserem Fall Public, und darin befinden sich zwei neue Dateien: PublicSchema.ts und User.ts . Ihre User.ts wird wahrscheinlich genau so aussehen:

// @generated
// This file is automatically generated by Kanel. Do not modify manually.

import type { ColumnType, Selectable, Insertable, Updateable } from 'kysely';

/** Identifier type for public.user */
export type UserId = number & { __brand: 'UserId' };

/** Represents the table public.user */
export default interface UserTable {
  id: ColumnType<UserId, UserId | undefined, UserId>;

  name: ColumnType<string, string, string>;

  email: ColumnType<string, string, string>;

  password: ColumnType<string, string, string>;

  createdAt: ColumnType<Date, Date | string | undefined, Date | string>;
}

export type User = Selectable<UserTable>;

export type NewUser = Insertable<UserTable>;

export type UserUpdate = Updateable<UserTable>;

Das Wichtigste ist jedoch die Datei außerhalb dieses Verzeichnisses Public, die Datei Database.ts, denn diese werden wir weitergeben, damit Kysely das verstehen kann gesamte Struktur unserer Datenbank. In unsere Datei app.service.ts fügen wir unseren DatabaseModule-Anbieter ein und übergeben unseren Typ Database.
an Kysely

npm i kysely pg && npm i kysely-ctl --save-dev

Beachten Sie, dass die von Kanel generierte Eingabe korrekt funktioniert, da unser Code-Editor genau die Spalten vorschlägt, die wir bei unserer ersten Migration erstellt haben.

Abschließende Überlegungen

Dies ist ein Duo, das ich sehr gerne in meinen persönlichen Projekten und sogar bei der Arbeit verwende (wenn ich die Freiheit dazu habe). Ein Query Builder ist das unverzichtbare Werkzeug für alle, die die Flexibilität von Raw SQL schätzen, sich aber auch für einen „sichereren“ Weg entscheiden. Kanel hat mir auch viele Stunden beim Debuggen und Erstellen neuer Typisierungen erspart. Ich empfehle Ihnen dringend, ein Projekt mit diesen beiden zu erstellen, Sie werden es definitiv nicht bereuen.

Repository-Link: frankenstein-nodejs

Das obige ist der detaillierte Inhalt vonKisley Kanel: ein perfektes Duo. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!