2026-02-01 09:31:38 +01:00

19 KiB

Raw Permalink Blame History

Story 1.2: Configurer la base de données SQLite avec Drizzle ORM

Status: review

Story

As a développeur, I want configurer SQLite avec Drizzle ORM dans Next.js, So que je peux stocker et récupérer des données pour l'application.

Acceptance Criteria

Given le projet Next.js est initialisé When j'installe drizzle-orm, better-sqlite3 et drizzle-kit Then les packages sont installés avec les versions spécifiées (Drizzle v0.44.7) And la configuration Drizzle est créée dans src/lib/db.ts And la connexion SQLite fonctionne And le fichier de base de données .db est créé (ou spécifié dans config)

Given Drizzle est configuré When j'exécute la commande de génération de schéma Then Drizzle Kit est configuré avec le chemin vers la base de données And les migrations peuvent être générées avec drizzle-kit generate

Tasks / Subtasks

Installer les dépendances Drizzle ORM et better-sqlite3 (AC: #1)
- Installer drizzle-orm version 0.44.7
- Installer better-sqlite3 comme driver SQLite
- Installer drizzle-kit pour les migrations
- Vérifier les versions dans package.json
- Confirmer que les packages sont installés sans erreurs
Créer la configuration Drizzle ORM (AC: #1, #2)
- Créer le fichier src/lib/db.ts avec la connexion SQLite
- Configurer better-sqlite3 avec le driver Drizzle
- Définir le chemin vers le fichier de base de données SQLite
- Exporter l'instance de base de données pour utilisation dans l'application
- Vérifier que la connexion fonctionne correctement
Configurer Drizzle Kit pour les migrations (AC: #2)
- Créer le fichier drizzle.config.ts à la racine du projet
- Configurer le schéma et le driver SQLite
- Définir le dossier pour les migrations (ex: drizzle/migrations)
- Configurer le préfixe de timestamp pour les migrations
- Vérifier que drizzle-kit generate fonctionne
Créer un exemple de schéma de table de test
- Créer src/db/schema.ts avec au moins un schéma de table
- Définir une table de test (ex: users ou test_table)
- Utiliser les conventions de nommage: snake_case pour tables/colonnes
- Ajouter des colonnes de base (id, created_at, etc.)
- Confirmer que le schéma suit les patterns de l'architecture
Générer et appliquer la migration initiale
- Exécuter drizzle-kit generate pour créer la migration
- Vérifier que le fichier de migration est créé dans drizzle/migrations
- Examiner le contenu de la migration pour confirmer la structure
- Créer un script d'application de migration si nécessaire
- Appliquer la migration pour créer la table dans SQLite
Valider l'installation complète de Drizzle
- Vérifier que le fichier de base de données SQLite existe
- Tester une requête simple (SELECT, INSERT)
- Confirmer que les types TypeScript sont générés correctement
- Vérifier que la configuration Drizzle Kit est fonctionnelle
- Documenter l'emplacement et la structure des migrations

Dev Notes

Architecture Patterns et Contraintes

Stack Technique Imposé:

ORM Next.js: Drizzle ORM v0.44.7 avec driver better-sqlite3
Migrations: Drizzle Kit pour génération et application des migrations
Base de données: SQLite Phase 1 (fichier local partagé avec FastAPI)
Conventions de nommage: snake_case pour tables et colonnes (cohérence avec SQLAlchemy)

Configuration Requise:

Fichier de configuration: src/lib/db.ts (connexion SQLite)
Fichier de migrations: drizzle/migrations/ (migrations versionnées)
Configuration Drizzle Kit: drizzle.config.ts (génération migrations)
Schémas de tables: src/db/schema.ts (définitions de schémas Drizzle)

Intégration avec Architecture Globale:

SQLite partagé entre FastAPI (SQLAlchemy) et Next.js (Drizzle)
Même convention de nommage: snake_case pour cohérence entre ORMs
Migrations versionnées pour traçabilité et rollback
Types TypeScript générés automatiquement depuis schémas

Conventions de Nommage (Database - Drizzle):

Tables: snake_case pluriel (ex: users, predictions, matches)
Colonnes: snake_case (ex: user_id, created_at, is_premium)
Foreign Keys: {table}_id (ex: user_id, match_id, prediction_id)
Indexes: idx_{table}_{column} (ex: idx_users_email, idx_predictions_match_id)
Constraints: {table}_{column}_{constraint} (ex: users_email_unique)

Source Tree Components à Toucher

Fichiers à créer/modifier:

chartbastan/src/lib/db.ts - Configuration connexion SQLite avec Drizzle (CRÉER)
chartbastan/src/db/schema.ts - Schémas de tables Drizzle (CRÉER)
chartbastan/drizzle.config.ts - Configuration Drizzle Kit (CRÉER)
chartbastan/drizzle/migrations/ - Dossier pour migrations (CRÉER)
chartbastan/package.json - Ajouter dépendances drizzle-orm, better-sqlite3, drizzle-kit (MODIFIER)

Fichiers générés automatiquement:

chartbastan/drizzle/migrations/XXXXX_init.sql - Migration initiale générée par Drizzle Kit
Types TypeScript générés depuis schémas Drizzle (via Drizzle Kit)

Project Structure Notes

Alignment with unified project structure:

✅ Drizzle ORM v0.44.7 comme spécifié dans architecture.md
✅ better-sqlite3 comme driver SQLite (cohérent avec architecture)
✅ Conventions snake_case pour tables/colonnes (cohérence SQLAlchemy)
✅ Migrations versionnées via Drizzle Kit
✅ Structure src/lib/db.ts et src/db/schema.ts (conventions Next.js)

Conventions de code à respecter:

Schémas Drizzle définis avec types TypeScript stricts
Utilisation de better-sqlite3 comme driver synchrone
Configuraton Drizzle Kit avec schema path et driver
Migrations dans dossier séparé drizzle/migrations/
Génération automatique de types TypeScript depuis schémas

Intégration avec architecture existante:

SQLite fichier partagé entre FastAPI et Next.js (Phase 1)
Même convention de nommage snake_case que SQLAlchemy
Migrations Drizzle synchronisées avec Alembic (FastAPI) si possible
Types TypeScript générés pour type safety côté frontend

Conflits ou variances détectés: Aucun conflit majeur. Cependant, il est important de:

S'assurer que le chemin vers le fichier SQLite est cohérent entre FastAPI et Next.js
Synchroniser les conventions de schéma entre SQLAlchemy et Drizzle pour éviter les incompatibilités futures lors de la migration vers PostgreSQL

Previous Story Intelligence

Story 1.1 - Initialiser le projet Next.js avec starter template:

Fichiers créés/modifiés:

chartbastan/ (répertoire racine Next.js)
chartbastan/src/app/ (structure App Router)
chartbastan/components.json (configuration shadcn/ui)
chartbastan/tailwind.config.ts (configuration Tailwind v4)
chartbastan/tsconfig.json (configuration TypeScript strict)
chartbastan/next.config.mjs (configuration Next.js avec Turbopack)
chartbastan/package.json (dépendances Next.js 16)

Learnings et bonnes pratiques:

✅ Structure src/ directory établie correctement
✅ TypeScript strict mode activé dans tsconfig.json
✅ Turbopack activé pour bundling rapide
✅ shadcn/ui avec composants copiés localement dans components/ui/
✅ Convention de nommage: PascalCase pour composants, camelCase pour fonctions

Patterns établis à réutiliser:

Utiliser Server Components par défaut (Next.js 16 standard)
Pas de mutations directes d'état (utiliser setters immutables)
Co-location des tests avec composants OU dans dossier tests/
TypeScript strict mode activé (déjà configuré)

Warnings ou points d'attention:

Aucun warning majeur. Le projet est propre et suit les conventions.

Impact sur Story 1.2:

Le projet Next.js est déjà configuré et fonctionnel
La structure src/ directory est prête pour accueillir src/lib/db.ts et src/db/schema.ts
TypeScript strict mode sera bénéfique pour les types Drizzle générés
La base technique est solide pour l'ajout de Drizzle ORM

Latest Technical Information

Drizzle ORM v0.44.7 - Latest Stable Version:

Installation:

npm install drizzle-orm better-sqlite3
npm install -D drizzle-kit

Configuration Connexion SQLite (src/lib/db.ts):

import { drizzle } from 'drizzle-orm/better-sqlite3';
import Database from 'better-sqlite3';

// Créer la connexion SQLite
const sqlite = new Database('chartbastan.db');

// Exporter l'instance Drizzle
export const db = drizzle(sqlite);

Configuration Drizzle Kit (drizzle.config.ts):

import type { Config } from 'drizzle-kit';

export default {
  schema: './src/db/schema.ts',
  out: './drizzle/migrations',
  driver: 'better-sqlite3',
  dbCredentials: {
    url: './chartbastan.db',
  },
} satisfies Config;

Schéma de Table Exemple (src/db/schema.ts):

import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';

export const users = sqliteTable('users', {
  id: integer('id').primaryKey({ autoIncrement: true }),
  email: text('email').notNull().unique(),
  name: text('name'),
  is_premium: integer('is_premium', { mode: 'boolean' }).default(false),
  created_at: integer('created_at', { mode: 'timestamp' }).notNull(),
});

Génération de Migration:

npx drizzle-kit generate

Application de Migration:

npx drizzle-kit migrate

Notes de Version v0.44.7:

Stable et bien maintenu
Support complet de TypeScript
Migration facile depuis d'autres ORMs
Documentation complète sur drizzle.team
Compatible avec Next.js 16 et Server Components

Meilleures Pratiques:

Utiliser better-sqlite3 comme driver synchrone (recommandé pour Next.js)
Définir les schémas dans un fichier séparé src/db/schema.ts
Utiliser les types génériques Drizzle pour type safety
Générer les types TypeScript avec drizzle-kit si nécessaire
Versionner toutes les migrations dans le dossier drizzle/migrations/

Technical Requirements

Configuration Drizzle ORM - Détails:

Fichier de Connexion (src/lib/db.ts):
- Importer drizzle depuis drizzle-orm/better-sqlite3
- Importer better-sqlite3 comme Database
- Créer instance de base de données SQLite
- Exporter l'instance db pour utilisation dans l'application
- Gérer les erreurs de connexion si nécessaire
Configuration Drizzle Kit (drizzle.config.ts):
- Spécifier le chemin vers src/db/schema.ts
- Définir le dossier de sortie des migrations (./drizzle/migrations)
- Configurer le driver better-sqlite3
- Spécifier le chemin vers le fichier SQLite (./chartbastan.db)
- Utiliser le type Config de drizzle-kit pour type safety
Schémas de Tables (src/db/schema.ts):
- Importer les helpers Drizzle depuis drizzle-orm/sqlite-core
- Définir au moins une table de test (ex: users ou test_table)
- Utiliser les conventions de nommage: snake_case pour tables/colonnes
- Inclure les colonnes de base: id (primary key), created_at
- Utiliser les types appropriés: text, integer, boolean, timestamp
- Exporter tous les schémas pour utilisation dans l'application
Migrations:
- Exécuter npx drizzle-kit generate pour créer la migration initiale
- Vérifier que le fichier de migration est créé dans drizzle/migrations/
- Examiner le SQL généré pour confirmer la structure correcte
- Créer un script d'application de migration si nécessaire pour les futures migrations
- Documenter le processus de génération et d'application des migrations
Validation:
- Vérifier que le fichier de base de données SQLite existe
- Tester une requête simple (SELECT, INSERT) avec Drizzle
- Confirmer que les types TypeScript sont générés correctement
- Vérifier que la configuration Drizzle Kit est fonctionnelle
- Documenter l'emplacement et la structure des migrations

Architecture Compliance

Conformité avec Architecture Decision Document:

✅ Data Architecture:

SQLite Phase 1 comme spécifié
Conventions snake_case pour tables/colonnes (cohérence SQLAlchemy)
Foreign keys format {table}_id (ex: user_id)
Indexes format idx_{table}_{column} (ex: idx_users_email)

✅ ORM Selection:

Drizzle ORM v0.44.7 avec better-sqlite3 driver
Migrations via Drizzle Kit
Compatible avec Server Components Next.js
TypeScript-first pour type safety

✅ Naming Conventions:

Tables: snake_case pluriel
Colonnes: snake_case
Foreign Keys: {table}_id
Cohérence avec conventions SQLAlchemy

✅ Code Organization:

src/lib/db.ts pour configuration
src/db/schema.ts pour schémas
drizzle/migrations/ pour migrations versionnées
Co-location avec tests (future)

✅ Integration Points:

SQLite partagé avec FastAPI (fichier local)
Même conventions de nommage que SQLAlchemy
Migration vers PostgreSQL facilitée (Phase 2+)

Library/Framework Requirements

Packages Requis (versions exactes):

drizzle-orm: v0.44.7 (ou latest stable)
better-sqlite3: latest stable
drizzle-kit: latest stable (dev dependency)

Installation Commands:

npm install drizzle-orm better-sqlite3
npm install -D drizzle-kit

Configuration Files:

src/lib/db.ts - Connexion SQLite
src/db/schema.ts - Schémas Drizzle
drizzle.config.ts - Configuration Drizzle Kit

Migration Commands:

npx drizzle-kit generate - Générer migration
npx drizzle-kit migrate - Appliquer migration (si nécessaire)

Script NPM Suggestion (optionnel pour package.json):

{
  "scripts": {
    "db:generate": "drizzle-kit generate",
    "db:migrate": "drizzle-kit migrate",
    "db:push": "drizzle-kit push"
  }
}

File Structure Requirements

Structure Attendue après Story:

chartbastan/
├── src/
│   ├── lib/
│   │   └── db.ts                    # Configuration SQLite + Drizzle (CRÉER)
│   └── db/
│       └── schema.ts                # Schémas de tables Drizzle (CRÉER)
├── drizzle/
│   └── migrations/
│       └── XXXXX_init.sql          # Migration initiale générée (CRÉÉ)
├── drizzle.config.ts                # Configuration Drizzle Kit (CRÉER)
├── package.json                     # Dépendances ajoutées (MODIFIER)
└── chartbastan.db                   # Fichier de base de données (CRÉÉ)

Fichiers à créer:

src/lib/db.ts - Configuration connexion SQLite
src/db/schema.ts - Schémas de tables
drizzle.config.ts - Configuration Drizzle Kit
drizzle/migrations/ - Dossier pour migrations

Fichiers à modifier:

package.json - Ajouter dépendances drizzle-orm, better-sqlite3, drizzle-kit

Fichiers générés automatiquement:

drizzle/migrations/XXXXX_init.sql - Migration initiale
chartbastan.db - Fichier de base de données SQLite

Testing Requirements

Tests Recommandés (Phase 2+):

Tests de Connexion:
- Vérifier que la connexion SQLite s'établit correctement
- Tester la création du fichier de base de données
- Valider que l'instance db est exportée correctement
Tests de Schéma:
- Vérifier que les schémas Drizzle sont définis correctement
- Tester la création de tables avec les schémas
- Valider les types TypeScript générés
Tests de Migration:
- Vérifier que drizzle-kit generate crée la migration
- Tester l'application de la migration
- Valider que les tables sont créées dans SQLite
Tests d'Intégration:
- Tester les requêtes SELECT/INSERT avec Drizzle
- Vérifier la cohérence avec les conventions SQLAlchemy
- Tester la cohérence du fichier SQLite partagé

Frameworks de Test Suggérés:

Vitest pour tests unitaires TypeScript
Testing Library pour tests d'intégration
Playwright pour tests E2E (Phase 2+)

References

Sources des informations:

[Source: _bmad-output/planning-artifacts/epics.md#Story-1.2] - Story originale et critères d'acceptation
[Source: _bmad-output/planning-artifacts/architecture.md#Data-Architecture] - Décisions ORM et base de données
[Source: _bmad-output/planning-artifacts/architecture.md#ORM-Selection] - Sélection Drizzle ORM v0.44.7
[Source: _bmad-output/planning-artifacts/architecture.md#Naming-Conventions] - Conventions de nommage database
[Source: _bmad-output/project-context.md#Stack-Technologique] - Stack technique imposé
[Source: _bmad-output/project-context.md#Conventions-de-Code-Nommage] - Conventions de nommage TypeScript/Database
[Source: _bmad-output/implementation-artifacts/1-1-initialiser-le-projet-nextjs-avec-starter-template.md] - Story précédente et learnings

Documentation Externe:

Drizzle ORM Documentation: https://orm.drizzle.team/docs/overview
Drizzle Kit Documentation: https://orm.drizzle.team/docs/kit-overview
Better SQLite3 Documentation: https://github.com/WiseLibs/better-sqlite3

Dev Agent Record

Agent Model Used

GLM-4.7

Debug Log References

Aucune référence de debug pour le moment.

Completion Notes List

Installation des dépendances : drizzle-orm v0.44.7, better-sqlite3 v12.6.2, drizzle-kit v0.31.8
Configuration Drizzle ORM dans src/lib/db.ts avec connexion SQLite et clés étrangères activées
Configuration Drizzle Kit dans drizzle.config.ts avec dialect 'sqlite' et chemin migrations
Schéma de table de test users créé dans src/db/schema.ts avec conventions snake_case
Migration initiale générée (0000_lively_rage.sql) et appliquée avec succès
Script de migration (src/scripts/migrate.ts) créé pour appliquer les migrations
Tests de base de données validés : INSERT, SELECT, SELECT avec WHERE tous réussis
Fichier de base de données chartbastan.db créé et fonctionnel
Tous les critères d'acceptation satisfaits

File List

Fichiers créés/modifiés lors de cette story:

chartbastan/package.json (MODIFIER - Ajouté drizzle-orm, better-sqlite3, drizzle-kit)
chartbastan/src/lib/db.ts (CRÉER - Configuration SQLite + Drizzle)
chartbastan/src/db/schema.ts (CRÉER - Schémas Drizzle avec table users)
chartbastan/drizzle.config.ts (CRÉER - Configuration Drizzle Kit)
chartbastan/src/scripts/migrate.ts (CRÉER - Script application migrations)
chartbastan/src/scripts/test-db.ts (CRÉER - Script test DB)
chartbastan/drizzle/migrations/0000_lively_rage.sql (CRÉER - Migration initiale générée)
chartbastan/drizzle/migrations/meta/ (CRÉER - Métadonnées migrations)
chartbastan/chartbastan.db (CRÉER - Fichier de base de données SQLite)

19 KiB Raw Permalink Blame History