---
title: "Référence d'API — @nodefony/drizzle — orm-core"
source: docs/api/drizzle/orm-core.md
url: https://nodefony.github.io/nodefony-core/docs/api/drizzle/orm-core/
---


[Documentation](../../../) › [Référence d'API](../../) › [`@nodefony/drizzle`](../) › orm-core

> Générée depuis les déclarations de types publiées de `@nodefony/drizzle` **10.0.0-beta.5** : exactement ce que reçoit une application qui l'installe. Cette page n'existe dans aucun dépôt — pour la corriger, on corrige le TSDoc du code.

## `@nodefony/drizzle`

`import { … } from "@nodefony/drizzle"` — 7 symboles.

### Classes (3)

#### `DrizzleOrm`

```ts
class DrizzleOrm extends Orm
```

- `get liveness(): "events" | "assumed"` — Ce que cet adapter sait de l'état de sa connexion, **par dialecte**.
- `constructor(name: string, options?: DrizzleOrmOptions)`
- `get derivesSchema(): boolean` — Le schéma est-il dérivé du code à la connexion, ou appartient-il aux migrations ?
- `get dialect(): SqlDialect` — Dialecte SQL de ce connecteur.
- `get schemaDrift(): ISchemaComparison | null` — Écart constaté entre le schéma déclaré par le code et la base — `null` quand la base est conforme.
- `compareToDeclared(): Promise<ISchemaComparison>` — Compare la base à ce que le code déclare — sans jamais rien modifier.
- `get location(): string` — Emplacement PHYSIQUE lisible de la base, pour l'écran Studio « Stores » (« où sont écrites mes données ?
- `protected onConnect(): Promise<void>` — Établit la connexion native du driver (compilation des entités, pool...).
- `disconnect(): Promise<void>` — Ferme la connexion et libère le pool.
- `getRepository<T = unknown>(name: string): IRepository<T>` — Repository typé d'une entité enregistrée.
- `transaction<R>(work: (tx: ITransaction) => Promise<R>): Promise<R>` — Exécute `work` dans une transaction, sur les TROIS dialectes : commit si la closure résout, rollback si elle rejette (cf `DrizzleTransaction`).
- `getNativeConnection<C = unknown>(): C` — Expose la connexion native du driver (trappe SQL/commandes brutes).
- `migrationStatus(): Promise<IOrmMigrationReply>` — État des migrations de ce connecteur — la MÊME charge utile que `orm:migrate:status --json`, jamais un second calcul.
- `migrationPlan(): Promise<IOrmMigrationPlanReply>` — Ce qui S'APPLIQUERAIT, avec son SQL — lecture seule.
- `applyMigrations(): Promise<IOrmMigrationApplyReply>` — Applique les migrations en attente — **développement seulement**, le lecteur injecté refuse ailleurs en le disant.
- `ping(): Promise<void>` — Ping bas-coût : `SELECT 1` — round-trip RÉEL vers la base, routé par dialecte (pool pg/mysql, client better-sqlite3 synchrone).
- `probe(): Promise<IOrmProbe>` — Sonde driver-spécifique, **routée par dialecte** — alimente le data plane admin (panneau Studio ORM) : - **sqlite** : stockage via PRAGMA (synchrone, bon marché) — taille (`page_count × page_size`), m …
- `describeEntity(name: string): IColumnInfo[]` — Colonnes normalisées d'une entité, dérivées du DDL Drizzle (`getTableConfig`) — alimente le graphe canonique / ERD / contexte IA.
- `describeTables(): { entity: string; table: string; columns: IColumnInfo[]; }[]` — Décrit le schéma ENTIER attendu par le code : une entrée par table.
- `describeConnection(): IConnectionInfo` — Décrit la connexion : driver `sqlite` (better-sqlite3) + cible (chemin du fichier, `:memory:` pour les tests).

#### `DrizzleRepository`

```ts
class DrizzleRepository<T = unknown> implements IRepository<T>
```

Repository portable (contrat `IRepository`) au-dessus d'une table Drizzle + driver `better-sqlite3`.

- `constructor(db: DrizzleDb, table: DrizzleTable, relations: Record<string, DrizzleResolvedRelation>, connector?: string, dialect?: SqlDialect, transactional?: boolean)`
- `find(criteria?: Criteria<T>, options?: RepositoryReadOptions): Promise<T[]>` — Retourne toutes les entités correspondant au critère (toutes si omis).
- `findOne(criteria: Criteria<T>, options?: RepositoryReadOptions): Promise<T | null>` — Retourne la première entité correspondant au critère, ou `null`.
- `create(data: Partial<T>): Promise<T>` — Persiste une nouvelle entité et retourne sa version persistée (id généré, valeurs par défaut).
- `createMany(data: Partial<T>[]): Promise<T[]>` — Insère **plusieurs** entités en **une seule** requête (`INSERT … VALUES (…),(…)` SQL / `insertMany` Mongo) et retourne leurs versions persistées (ids générés, défauts appliqués), dans l'ordre.
- `updateOne(criteria: Criteria<T>, data: Partial<T>): Promise<T | null>` — Met à jour **au plus une** entité correspondant au critère, de façon **atomique**, et retourne sa version persistée (ou `null` si aucune ne correspond).
- `upsert(criteria: Criteria<T>, update: UpdateData<T>, insertOnly?: Partial<T>): Promise<T>` — Insère **ou** met à jour atomiquement l'entité identifiée par `criteria` (clé unique), en **une seule** requête (`INSERT … ON CONFLICT DO UPDATE … RETURNING` SQL / `findOneAndUpdate({ upsert })` Mongo …
- `updateMany(criteria: Criteria<T>, data: Partial<T>): Promise<number>` — Met à jour **toutes** les entités correspondant au critère et retourne le **nombre** de lignes modifiées (parité de signature avec `IRepository.delete`).
- `increment(criteria: Criteria<T>, changes: Partial<Record<keyof T, number>>): Promise<T | null>` — Incrémente **atomiquement** des champs numériques d'**au plus une** entité (`SET f = f + ?` SQL / `$inc` Mongo), sans read-modify-write (donc sans race) — pour les compteurs (stats, usage/tokens, rate …
- `delete(criteria: Criteria<T>): Promise<number>` — Supprime les entités correspondant au critère.
- `deleteOne(criteria: Criteria<T>): Promise<boolean>` — Supprime **au plus une** entité de façon **atomique** (symétrique d'`IRepository.updateOne` ; `DELETE … LIMIT 1` SQL / `deleteOne` Mongo).
- `findOneAndDelete(criteria: Criteria<T>): Promise<T | null>` — Supprime **au plus une** entité et **retourne** sa valeur supprimée (ou `null`), de façon atomique (`DELETE … RETURNING` SQL / `findOneAndDelete` Mongo) — claim-and-remove (file de jobs, outbox, pop a …
- `count(criteria?: Criteria<T>): Promise<number>` — Compte les entités correspondant au critère (toutes si omis).
- `countDistinct(field: keyof T & string, criteria?: Criteria<T>): Promise<number>` — `COUNT(DISTINCT col)` natif — la déduplication reste dans le moteur, aucune ligne n'est rapatriée.
- `exists(criteria: Criteria<T>): Promise<boolean>` — Indique si **au moins une** entité correspond au critère, sans rapatrier la ligne (`SELECT 1 … LIMIT 1` SQL / `exists` Mongo).
- `withTransaction(tx: ITransaction): IRepository<T>` — Retourne une **vue de ce repository liée à une transaction** : toutes ses opérations s'exécutent dans `tx` (commit/rollback gérés par `IOrm.transaction()`).

#### `DrizzleTransaction`

```ts
class DrizzleTransaction implements ITransaction
```

Adapte une transaction SQL au contrat portable `ITransaction`, sur les trois dialectes (sqlite, postgres, mysql).

- `constructor(db: DrizzleDb, driver: ITxDriver)`
- `isDone(): boolean` — Indique si la transaction est déjà terminée (commit ou rollback).
- `commit(): Promise<void>` — Valide la transaction (no-op si déjà terminée).
- `rollback(): Promise<void>` — Annule la transaction (no-op si déjà terminée).
- `savepoint(name: string): Promise<void>` — Crée un savepoint nommé (nom validé — anti-injection, cf `assertSavepointName`).
- `rollbackTo(name: string): Promise<void>` — Annule jusqu'au savepoint sans terminer la transaction (nom validé).
- `getNative<C = unknown>(): C` — Expose le handle Drizzle lié à la connexion encadrée par la transaction.

### Fonctions (1)

#### `seedEntityRow`

```ts
function seedEntityRow(orm: DrizzleOrm, entity: IEntity): Promise<string | number>
```

Insère une ligne minimale dans la table d'une entité, et rend son identifiant.

### Interfaces (2)

#### `DrizzleOrmOptions`

```ts
interface DrizzleOrmOptions
```

Options de connexion de l'adapter Drizzle (driver selon `dialect`).

- `dialect?: SqlDialect` — Dialecte SQL : `sqlite` (défaut, driver better-sqlite3) · `postgres` (driver `pg`, lazy) · `mysql` (driver `mysql2`, lazy).
- `filename?: string` — Fichier SQLite (`":memory:"` par défaut) — dialecte `sqlite` uniquement.
- `url?: string` — Chaîne de connexion (`postgres://…`, `mysql://…`) — dialectes `postgres`/ `mysql`.
- `container?: Container` — Container du service qui construit l'ORM — il porte le `syslog` du kernel.
- `deriveSchema?: boolean` — Le schéma doit-il être DÉRIVÉ du code à la connexion ?
- `migrationStatus?: () => Promise<IOrmMigrationReply>` — Qui sait lire l'état des migrations de CE connecteur.
- `migrationPlan?: () => Promise<IOrmMigrationPlanReply>` — Qui sait dire ce qui S'APPLIQUERAIT — même origine que `migrationStatus`.
- `applyMigrations?: () => Promise<IOrmMigrationApplyReply>` — Qui sait APPLIQUER — refuse hors développement, en le disant.

#### `DrizzleResolvedRelation`

```ts
interface DrizzleResolvedRelation
```

Relation résolue au boot de l'ORM, prête pour l'eager-load manuel (sans la couche `relations()` de Drizzle, pour rester générique cross-entités).

- `type: "one-to-many" | "many-to-one" | "one-to-one"` — Cardinalité.
- `targetTable: DrizzleTable` — Table cible Drizzle (variante du dialecte du connecteur).
- `foreignKey: string` — Colonne clé étrangère (sur la cible pour 1-N, sur la source pour N-1).
- `localKey: string` — Clé primaire de l'entité courante (côté parent du 1-N).
- `targetKey: string` — Clé primaire de la cible (côté lookup du N-1).

### Types (1)

#### `DrizzleDb`

```ts
type DrizzleDb = BetterSQLite3Database
```

Handle Drizzle (instance racine ou transaction) — schéma résolu côté adapter.

---

[← Toutes les références d'API](../../)