Drizzle ORM

PetraDB fournit un pilote Drizzle ORM via le package @petradb/drizzle. Il implémente un pilote de dialecte PostgreSQL personnalisé — Drizzle génère du SQL en dialecte PostgreSQL, et PetraDB l’exécute en processus sans protocole filaire. Le pilote offre une parité complète des fonctionnalités avec drizzle-orm/node-postgres, y compris db.transaction(), returning() sur toutes les mutations et les requêtes relationnelles.

Installation

npm install @petradb/drizzle drizzle-orm @petradb/engine

Configuration

import { Session } from "@petradb/engine";
import { drizzle } from "@petradb/drizzle";

const session = new Session({ storage: "memory" });
const db = drizzle(session);

Modes de stockage

// En mémoire (par défaut)
new Session({ storage: "memory" })

// Stockage persistant sur fichier
new Session({ storage: "persistent", path: "./mydb.petra" })

Définition du schéma

Définissez les tables en utilisant le pgTable de Drizzle :

import { pgTable, serial, text, integer, boolean } from "drizzle-orm/pg-core";

const users = pgTable("users", {
  id: serial("id").primaryKey(),
  name: text("name").notNull(),
  email: text("email").notNull(),
  age: integer("age"),
  active: boolean("active").default(true),
});

Créez la table via la session, ou utilisez les migrations avec drizzle-kit generate + migrate() :

await session.execute(`
  CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name TEXT NOT NULL,
    email TEXT NOT NULL,
    age INTEGER,
    active BOOLEAN DEFAULT true
  )
`);

Insertion

// Ligne unique
await db.insert(users).values({
  name: "Alice",
  email: "alice@example.com",
  age: 30,
});

// Lignes multiples
await db.insert(users).values([
  { name: "Bob", email: "bob@example.com", age: 25 },
  { name: "Charlie", email: "charlie@example.com", age: 35 },
]);

// Avec returning
const [inserted] = await db
  .insert(users)
  .values({ name: "Diana", email: "diana@example.com", age: 28 })
  .returning();
console.log(inserted.id); // serial auto-généré

Sélection

import { eq, gt } from "drizzle-orm";

// Toutes les lignes
const allUsers = await db.select().from(users);

// Clause where
const alice = await db.select().from(users).where(eq(users.name, "Alice"));

// Conditions
const older = await db.select().from(users).where(gt(users.age, 28));

// Colonnes spécifiques
const names = await db
  .select({ name: users.name, email: users.email })
  .from(users);

// Limite
const first = await db.select().from(users).limit(1);

Mise à jour

// Mettre à jour des lignes
await db.update(users).set({ age: 31 }).where(eq(users.name, "Alice"));

// Avec returning
const [updated] = await db
  .update(users)
  .set({ active: false })
  .where(eq(users.name, "Bob"))
  .returning();

Suppression

// Supprimer des lignes
await db.delete(users).where(eq(users.name, "Charlie"));

// Avec returning
const [deleted] = await db
  .delete(users)
  .where(eq(users.name, "Diana"))
  .returning();

Transactions

Utilisez l’API db.transaction() de Drizzle pour un commit/rollback automatique :

// Commit automatique
const result = await db.transaction(async (tx) => {
  const [inserted] = await tx
    .insert(users)
    .values({ name: "Eve", email: "eve@example.com", age: 22 })
    .returning();
  return inserted;
});

// Rollback automatique en cas d'erreur
await db.transaction(async (tx) => {
  await tx.insert(users).values({ name: "Frank", email: "frank@example.com" });
  throw new Error("something went wrong");
  // Frank n'est pas inséré — la transaction est annulée
});

// Rollback explicite
await db.transaction(async (tx) => {
  await tx.insert(users).values({ name: "Grace", email: "grace@example.com" });
  tx.rollback(); // lance TransactionRollbackError
});

Vous pouvez également utiliser db.$session pour un contrôle manuel des transactions :

await db.$session.execute("BEGIN");
await db.insert(users).values({ name: "Hank", email: "hank@example.com" });
await db.$session.execute("COMMIT");

Mapping de types

PetraDB retourne des types JS natifs — pas de coercition de chaînes nécessaire :

Type Drizzle	Colonne PetraDB	Type JS
serial()	SERIAL	number
integer()	INTEGER	number
text()	TEXT	string
boolean()	BOOLEAN	boolean
numeric()	NUMERIC	string

Les colonnes nullables retournent null lorsqu’aucune valeur n’est présente.

Migrations

Appliquez les migrations Drizzle Kit avec la fonction migrate() :

import { migrate } from "@petradb/drizzle";

await migrate(db, { migrationsFolder: "./drizzle" });

Cela lit le journal de migration et les fichiers SQL générés par drizzle-kit generate, les exécute dans l’ordre et suit les migrations appliquées dans une table drizzle.__drizzle_migrations (créée automatiquement).

Flux de travail typique :

# Générer les migrations à partir des changements de schéma
npx drizzle-kit generate

# Appliquer les migrations au démarrage

import { Session } from "@petradb/engine";
import { drizzle, migrate } from "@petradb/drizzle";

const session = new Session({ storage: "memory" });
const db = drizzle(session);

await migrate(db, { migrationsFolder: "./drizzle" });
// Les tables sont maintenant créées — utilisez db normalement

Nettoyage

await session.close();