Tutoriel Knex.js avec TypeScript et PostgreSQL

Dans le tutoriel d’aujourd’hui, je vais vous montrer comment utiliser le constructeur de requêtes Knex.js dans des applications Node.js afin d’interagir avec la base de données PostgreSQL. Vous vous demandez ce qu’est un constructeur de requêtes ? Pas d’inquiétude, je vais vous l’expliquer ; gardez simplement à l’esprit que ceci est un tutoriel destiné à ceux qui maîtrisent déjà Node.js, TypeScript et qui connaissent aussi la base Postgres.

Si vous avez besoin de connaissances de base ou d’un renforcement en TS, utilisez ce tutoriel.

#1 – Pilote natif x Query Builder x ORM

Lorsque nous allons créer une application qui se connecte à une base de données pour interroger et enregistrer des données, nous avons trois approches possibles:

en utilisant le pilote natif de la base pour notre langage;
en utilisant un constructeur de requêtes (query builder);
en utilisant un ORM (Object-Relational Mapping);

Chacune de ces trois approches présente ses avantages et ses inconvénients, ainsi que ses partisans et ses détracteurs. En résumé, voici le comparatif:

Pilote: la forme “officielle”, avec la meilleure performance et qui demande le plus de travail (moins productive) car elle implique l’utilisation directe de SQL et aucune abstraction de données. Dans le cas de PostgreSQL par exemple, cela reviendrait à développer en utilisant le package pg, comme nous l’avons fait dans ce tutoriel.
ORM: la forme la plus “courante” et la plus productive pour développer. Dans ce mode, vous manipulez uniquement des objets, le niveau le plus élevé d’abstraction en programmation, sans toucher au SQL. Cependant, la conversion constante entre objets et données rend cette approche plus lente en termes de performance. Un exemple célèbre est Sequelize, que nous avons déjà utilisé dans ce tutoriel.
Query Builder: dans cette approche, nous utilisons des objets pour construire les requêtes, ce qui représente un degré d’abstraction moyen, mais plus léger que celui des ORM, et plus productif que de tout gérer manuellement comme avec le pilote natif. On peut dire que les query builders comme Knex.js constituent le compromis entre performance et productivité dans le monde du développement.

Ayant compris ce point initial sur les approches, avançons.

#2 – Environnement et Projet

Si vous n’avez jamais programmé avec Node et Postgre avant, je vous laisse ci-dessous une vidéo montrant l’installation de l’environnement.

Lorsque l’environnement est prêt, vous pouvez créer la base et la table pour notre application.

Maintenant, créez un dossier sur votre machine pour le projet, j’utiliserai le nom “crud-knex-postgresql”. Ouvrez le terminal et dans ce dossier lancez un “npm init -y” pour initialiser le projet et créer le fichier package.json.

Toujours dans le terminal, installez les dépendances dont nous aurons besoin dans ce tutoriel

npm i pg knex dotenv

À savoir :

pg: paquet contenant le driver natif pour PostgreSQL;
Knex: paquet du constructeur de requêtes Knex.js;
DotEnv: paquet pour la gestion des variables d’environnement;

D’autres options de bases de données possibles seraient CockroachDB, MS SQL Server, MySQL, MariaDB, SQLite3, Better-SQLite3, Oracle et Amazon Redshift, il suffirait de changer le connecteur (pg).

Et maintenant les dépendances de développement :

npm i -D typescript tsx @types/node

À savoir :

TypeScript: paquet pour utiliser TypeScript dans le projet;
TSX: paquet qui permet d’exécuter TS directement, sans le transpiler en JS;
@types/node: paquet pour les types de Node.js natif;

Et ensuite, initialisez TypeScript dans le projet.

npx tsc --init

Et ajustez votre package.json pour que le type du projet soit module, au lieu de commonjs et le script de démarrage.

"type": "module",
"scripts": {
  "start": "tsx src/index.ts"
},

Faites cela, créez maintenant un fichier .env à la racine de votre projet et placez-y les variables d’environnement suivantes, dûment configurées avec les données du serveur PostgreSQL que vous allez utiliser.

NODE_ENV=development
DB_HOST=localhost
DB_PORT=5432
DB_USER=luiztools
DB_PASSWORD=
DB_DATABASE=luiztools
DEBUG=knex:query

La variable debug sert à ce que Knex affiche dans le terminal le SQL qu’il exécute sur la base de données, utile pendant le développement.

Et avec cela, nous terminons la configuration initiale du projet.

#3 – Configuration de Knex

La première étape consiste à créer un dossier src à la racine du projet et, à l’intérieur, un dossier config, où nous allons stocker les fichiers de configuration. Le premier fichier de configuration dont nous allons avoir besoin est knex.ts, qui comme son nom l’indique, configure le query builder.

 import "dotenv/config";
import Knex from "knex";

const knex = Knex({
  client: "pg",
  connection: {
    host: `${process.env.DB_HOST}`,
    port: Number(process.env.DB_PORT),
    user: `${process.env.DB_USER}`,
    password: `${process.env.DB_PASSWORD}`,
    database: `${process.env.DB_DATABASE}`,
  },
  pool: {
    min: 2,
    max: 10,
  },
});

export const onDatabaseConnect = () => knex.raw("SELECT 1");

export default knex;

Nous commençons par importer les variables d’environnement, puis le paquet Knex. Comme c’est courant avec les abstractions de base de données, nous devons d’abord diriger notre query builder vers notre base (connection), préciser quel client de base de données nous utilisons (pg) et les configurations du pool de connexions, optionnelles mais recommandées pour de meilleures performances.

Après les configurations de connexion de Knex, je crée et exporte une fonction qui teste la connexion. Si tout est correct, cette fonction retournera une ligne contenant le chiffre 1, sinon une erreur.

Enfin, j’exporte par défaut l’objet Knex, correctement connecté.

Maintenant, passons à index.ts qui doit exister dans src pour écrire un code initial qui teste la connexion en utilisant Knex.

 
import {onDatabaseConnect} from "./config/knex.js";

console.log(await onDatabaseConnect());

Si vous exécutez le projet maintenant avec npm start, vous verrez dans la console le SQL que Knex a tenté d’exécuter et l’objet de retour de la requête. Si vous obtenez une erreur, il faudra alors revoir vos variables du fichier .env, selon l’erreur.

#4 – Migrations avec Knex

Une fois la connexion correctement testée, il est temps de créer la table dans notre base de données. Vous pourriez le faire manuellement, mais il est plus professionnel d’utiliser les migrations, qui permettent de versionner la base de données par le biais de modifications incrémentielles.

Pour créer et utiliser les migrations, nous devons utiliser Knex CLI, un outil en ligne de commande de Knex. La première étape pour l’utiliser est d’initialiser les paramètres dans notre projet, en utilisant la commande ci-dessous. Le flag -x indique que nous allons utiliser TypeScript (ts) dans ce fichier.

npx knex init -x ts

Le fichier de configuration du Knex CLI s’appelle knexfile.ts et se situe à la racine du projet. Ouvrez-le et chargez les variables d’environnement et remplissez les configurations avec elles, de manière analogue à ce que nous avons fait dans knex.ts. Vous remarquerez que les configurations se répètent parfois, car vous pouvez avoir des configurations différentes pour des environnements différents, Knex lisant la variable NODE_ENV pour décider quelle configuration utiliser.

Ci-dessous, un extrait de code qui montre uniquement la configuration du bloc que nous allons utiliser :

import "dotenv/config";
import type { Knex } from "knex";

const config: { [key: string]: Knex.Config } = {
  development: {
    client: "pg",
    connection: {
      host: `${process.env.DB_HOST}`,
      port: Number(process.env.DB_PORT),
      user: `${process.env.DB_USER}`,
      password: `${process.env.DB_PASSWORD}`,
      database: `${process.env.DB_DATABASE}`,
    },
    pool: {
      min: 2,
      max: 10,
    },
    migrations: {
      tableName: "knex_migrations",
    },
  },

Notez qu’à la fin j’ai ajouté une configuration nommée migrations. Dans celle-ci, je précise quelle table va stocker les métadonnées des migrations, c’est-à-dire les enregistrements de versionnage de la base par Knex. J’ai aussi constaté que l’export par défaut à la fin était incorrect et je l’ai ajusté pour :

export default config;

Maintenant, pour créer notre migration avec ces configurations, exécutons la commande suivante dans le terminal.

npx knex migrate:make add_books_table -x ts

Cette instruction exécute Knex CLI avec la commande migrate:make, qui sert à créer une nouvelle migration, suivie du nom et du langage que nous voulons y utiliser.

Si tout est correctement saisi, cette commande va créer un dossier migrations dans votre projet et, à l’intérieur, un fichier pour notre migration de création de table, avec les fonctions up et down, qui servent respectivement à faire progresser une version dans notre base ou à revenir en arrière en annulant les modifications. Il peut y avoir quelques erreurs dans le terminal, mais si le dossier et le fichier ont été créés, il n’y a pas lieu de s’inquiéter.

Voici le code de notre migration :

import type { Knex } from "knex";

export async function up(knex: Knex): Promise<void> {
    await knex.schema.createTable("books", (table) => {
        table.increments("id").primary();
        table.string("title").notNullable();
        table.string("author").notNullable();
        table.integer("year").notNullable();
        table.timestamps(true, true);
    });
}

export async function down(knex: Knex): Promise<void> {
    await knex.schema.dropTableIfExists("books");
}

Dans la fonction up, qui reçoit un objet knex en paramètre, nous utilisons cet objet pour accéder à knex.schema où se trouvent les fonctions DDL (Data Definition Language), comme createTable. Là, nous passons le nom de la table (books) et une fonction qui reçoit la table et dans laquelle nous devons ajouter les colonnes à cet objet en utilisant des fonctions, une pour chaque colonne.

id : nous utilisons la fonction increments qui sert à créer des identifiants auto-incrémentés, ainsi que primary pour en faire notre clé primaire ;
title et author : nous utilisons la fonction string qui sert pour des champs de texte court et notNullable pour exiger que ce champ soit renseigné ;
year : nous utilisons la fonction integer car nous ne stockerons que l’année de publication du livre, en plus de notNullable ;
timestamps : cette fonction sert à créer des champs de timestamp standards de Knex, tandis que le second true indique qu’ils recevront automatiquement l’heure actuelle du système lors de l’enregistrement d’un enregistrement ;

Maintenant, dans le down, nous devons effectuer l’opération inverse de up, à savoir dropTableIfExists, qui va supprimer la table books de notre base.

Pour exécuter cette migration, lancez la commande ci-dessous.

npx knex migrate:latest

Cela va exécuter toutes les migrations en attente, c’est‑à‑dire celles qui ont été créées mais pas encore exécutées. Ce contrôle se fait via la table knex_migrations. Pour vérifier, vous pouvez utiliser un outil de gestion de base Postgre, comme pgAdmin.

Dans la deuxième partie, nous allons apprendre à utiliser cette table pour effectuer des opérations de CRUD.

À bientôt !

Auteur

Fabien Delpont

Fabien Delpont, développeur et créateur du site Python Doctor.

Python débutant

Python avancé

Django

Raspberry Pi

Actualités

Toutes les actualités