chartbastan/_bmad-output/implementation-artifacts/1-2-configurer-la-base-de-donnees-sqlite-avec-drizzle-orm.md

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

Status: review

<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->

## 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

- [x] Installer les dépendances Drizzle ORM et better-sqlite3 (AC: #1)
  - [x] Installer `drizzle-orm` version 0.44.7
  - [x] Installer `better-sqlite3` comme driver SQLite
  - [x] Installer `drizzle-kit` pour les migrations
  - [x] Vérifier les versions dans `package.json`
  - [x] Confirmer que les packages sont installés sans erreurs

- [x] Créer la configuration Drizzle ORM (AC: #1, #2)
  - [x] Créer le fichier `src/lib/db.ts` avec la connexion SQLite
  - [x] Configurer `better-sqlite3` avec le driver Drizzle
  - [x] Définir le chemin vers le fichier de base de données SQLite
  - [x] Exporter l'instance de base de données pour utilisation dans l'application
  - [x] Vérifier que la connexion fonctionne correctement

- [x] Configurer Drizzle Kit pour les migrations (AC: #2)
  - [x] Créer le fichier `drizzle.config.ts` à la racine du projet
  - [x] Configurer le schéma et le driver SQLite
  - [x] Définir le dossier pour les migrations (ex: `drizzle/migrations`)
  - [x] Configurer le préfixe de timestamp pour les migrations
  - [x] Vérifier que `drizzle-kit generate` fonctionne

- [x] Créer un exemple de schéma de table de test
  - [x] Créer `src/db/schema.ts` avec au moins un schéma de table
  - [x] Définir une table de test (ex: `users` ou `test_table`)
  - [x] Utiliser les conventions de nommage: `snake_case` pour tables/colonnes
  - [x] Ajouter des colonnes de base (id, created_at, etc.)
  - [x] Confirmer que le schéma suit les patterns de l'architecture

- [x] Générer et appliquer la migration initiale
  - [x] Exécuter `drizzle-kit generate` pour créer la migration
  - [x] Vérifier que le fichier de migration est créé dans `drizzle/migrations`
  - [x] Examiner le contenu de la migration pour confirmer la structure
  - [x] Créer un script d'application de migration si nécessaire
  - [x] Appliquer la migration pour créer la table dans SQLite

- [x] Valider l'installation complète de Drizzle
  - [x] Vérifier que le fichier de base de données SQLite existe
  - [x] Tester une requête simple (SELECT, INSERT)
  - [x] Confirmer que les types TypeScript sont générés correctement
  - [x] Vérifier que la configuration Drizzle Kit est fonctionnelle
  - [x] 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:**
1. `chartbastan/src/lib/db.ts` - Configuration connexion SQLite avec Drizzle (CRÉER)
2. `chartbastan/src/db/schema.ts` - Schémas de tables Drizzle (CRÉER)
3. `chartbastan/drizzle.config.ts` - Configuration Drizzle Kit (CRÉER)
4. `chartbastan/drizzle/migrations/` - Dossier pour migrations (CRÉER)
5. `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:**
```bash
npm install drizzle-orm better-sqlite3
npm install -D drizzle-kit
```

**Configuration Connexion SQLite (`src/lib/db.ts`):**
```typescript
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`):**
```typescript
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`):**
```typescript
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:**
```bash
npx drizzle-kit generate
```

**Application de Migration:**
```bash
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:**

1. **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

2. **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

3. **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

4. **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

5. **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:**
```bash
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`):**
```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:**
1. `src/lib/db.ts` - Configuration connexion SQLite
2. `src/db/schema.ts` - Schémas de tables
3. `drizzle.config.ts` - Configuration Drizzle Kit
4. `drizzle/migrations/` - Dossier pour migrations

**Fichiers à modifier:**
1. `package.json` - Ajouter dépendances drizzle-orm, better-sqlite3, drizzle-kit

**Fichiers générés automatiquement:**
1. `drizzle/migrations/XXXXX_init.sql` - Migration initiale
2. `chartbastan.db` - Fichier de base de données SQLite

### Testing Requirements

**Tests Recommandés (Phase 2+):**

1. **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

2. **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

3. **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

4. **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)