Kisley Kanel : un duo parfait

Je suis une personne qui, depuis que j'ai commencé à développer mes premiers projets (mon OT Pokémon et mes premiers sites web pour Habbo), j'ai toujours opté pour le Raw SQL. Honnêtement, j'aime toujours beaucoup écrire mes propres requêtes et avoir un contrôle plus précis sur cette couche "de bas niveau". Un ORM ne me met pas complètement à l'aise, car j'ai déjà passé des journées à analyser des logs pour identifier et optimiser les requêtes inefficaces.

Cependant, dans de nombreuses bases de code où j'ai travaillé avec Raw SQL, la grande majorité n'avait pas de contrôle de migration, et la base de données n'était pas non plus surveillée. Tout a fonctionné sur une base improvisée : "Avez-vous besoin d'un nouveau champ ? Exécutez ALTER TABLE et ajoutez une nouvelle colonne." Cette approche s'est avérée extrêmement néfaste dans tous les scénarios, plusieurs questions se sont posées, telles que : "Quelles colonnes doit-on monter dans l'environnement de production ?", "Quelles nouvelles entités ont été créées ?", "Les environnements sont-ils synchronisés ?" — et bien d'autres problèmes similaires.

La solution à mes problèmes

Face à tous ces problèmes, j'ai décidé d'adopter de nouveaux outils pour rendre ma routine et celle des équipes avec qui je travaillais plus saines. Je ne voulais pas renoncer à la flexibilité dont je disposais, mais je voulais aussi mieux contrôler les degrés de liberté de l'application. Après de nombreuses recherches, j'ai trouvé un outil que je considère comme le plus complet pour résoudre ces problèmes : Kysely, c'est un générateur de requêtes pour TypeScript qui, en plus d'être pratique, est totalement sécurisé — un point super important pour moi. Cette bibliothèque a tellement attiré mon attention que j'ai commencé à contribuer activement à la communauté, directement et indirectement, en créant des plugins pour d'autres bibliothèques open source intégrées à Kysely.

Cependant, l'une des plus grandes difficultés lorsque l'on travaille avec Kysely est que, contrairement aux ORM, il n'a pas d'entité ni de génération automatique de types/interfaces. Tout ce travail doit être effectué manuellement, ce qui peut être un peu épuisant. Lors de ma recherche de solutions, j'ai trouvé un outil que j'ai fini par adopter dans tous mes projets impliquant PostgreSQL : Kanel. Kanel génère automatiquement des typages de base de données, complétant parfaitement Kysely.

De plus, Kanel dispose d'une fonctionnalité supplémentaire pour une utilisation directe avec Kysely : Kanel-Kysely. J'ai contribué activement à ce référentiel, en aidant au développement de nouvelles fonctionnalités, telles que les filtres de type pour les tables de migration et la conversion des objets Zod en camelCase.

Configuration de Kysely

J'utiliserai NestJS pour illustrer les exemples suivants. Donc, si vous ne comprenez pas une syntaxe ou quelque chose dans le code, je vous suggère de lire la documentation NestJS. À mon avis, c'est le meilleur framework JavaScript, surtout si vous souhaitez « échapper » à JavaScript. Mais c'est un sujet pour un autre de mes articles.

Au préalable, vous devrez avoir un dépôt avec NestJS initialisé, si vous souhaitez suivre les exemples à la lettre. Cependant, vous pouvez également développer votre propre code.

Dans un premier temps, nous devrons installer Kysely lui-même, sa CLI et le module PostgreSQL pour Node.js.

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

Ensuite, nous devrons créer un fichier de configuration à la racine du projet pour Kysely. J'utiliserai également le préfixe Knex pour nos migrations et fichiers de départ.

// 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,
  },
});

Ensuite, nous exécuterons la commande npx kysely migrate make create_user_table dans notre terminal. Il sera responsable de la création de notre première migration. Ensuite, nous créerons une nouvelle table utilisateur et, une fois cela fait, nous exécuterons cette migration dans notre base de données avec la commande npx kysely migrate Latest.

// 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();
}
</void></any></void></any>

Une fois toutes ces étapes terminées, créons un module pour notre base de données. Notez également que j'utilise un plugin Kysely pour convertir nos colonnes en camelCase.

// 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 {}

Configuration de Kanel

Commençons par installer nos dépendances.

npm i kanel kanel-kysely --save-dev

Ensuite, créons notre fichier de configuration pour que Kanel commence à faire son travail. A noter que j'utiliserai certains plugins, comme camelCaseHook (pour transformer nos interfaces en camelCase) et kyselyTypeFilter (pour exclure les tables de migration de Kysely), une de ces fonctionnalités à laquelle j'ai eu le plaisir de pouvoir contribuer et rendre le travail que nous avions encore plus facile.

// .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],
};

Une fois le fichier créé, nous exécuterons la commande npx kanel dans notre terminal. Notez qu'un répertoire a été créé dans le chemin spécifié dans le fichier de configuration. Ce répertoire correspond au nom de votre schéma, dans notre cas, Public, et à l'intérieur nous avons deux nouveaux fichiers : PublicSchema.ts et User.ts . Votre User.ts ressemblera probablement exactement à ceci :

// @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>;

  name: ColumnType<string string>;

  email: ColumnType<string string>;

  password: ColumnType<string string>;

  createdAt: ColumnType<date date string undefined>;
}

export type User = Selectable<usertable>;

export type NewUser = Insertable<usertable>;

export type UserUpdate = Updateable<usertable>;

</usertable></usertable></usertable></date></string></string></string></userid>

Cependant, le plus important est le fichier en dehors de ce répertoire Public, le fichier Database.ts, car c'est lui que nous allons transmettre pour que Kysely puisse comprendre le structure entière de notre base de données. Dans notre fichier app.service.ts, nous allons injecter notre fournisseur DatabaseModule et transmettre notre type Database.
à Kysely

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

Remarquez que la saisie générée par Kanel fonctionne correctement, car notre éditeur de code proposera précisément les colonnes que nous avons créées lors de notre première migration.

Considérations finales

C'est un duo que j'aime beaucoup utiliser dans mes projets personnels et même au travail (quand j'en ai la liberté). Un générateur de requêtes est l'outil essentiel pour tous ceux qui aiment la flexibilité qu'offre Raw SQL, mais optent également pour une voie « plus sûre ». Kanel m'a également permis d'économiser de nombreuses heures de débogage et de création de nouveaux typages. Je vous recommande fortement de créer un projet avec ces deux-là, vous ne le regretterez certainement pas.

Lien du référentiel : frankenstein-nodejs

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!