evilspins/server/MIGRATION_GUIDE.md

Migration vers SQLite - Guide d'utilisation

📦 Installation

pnpm add better-sqlite3
pnpm add -D @types/better-sqlite3

🚀 Migration des données

1. Exécuter la migration

pnpm tsx server/database/migrate.ts

Cette commande va :

• Créer la base de données SQLite dans server/database/evilspins.db
• Créer les tables (boxes, sides, artists, tracks)
• Importer toutes vos données existantes

2. Vérifier la migration

Lancez votre serveur Nuxt :

pnpm dev

Testez les nouveaux endpoints :

# Récupérer toutes les boxes
curl http://localhost:3000/api/boxes

# Récupérer tous les artistes
curl http://localhost:3000/api/artists

# Récupérer les tracks de compilation (première page)
curl http://localhost:3000/api/tracks/compilation

# Filtrer par boxId
curl http://localhost:3000/api/tracks/compilation?boxId=ES00

# Pagination
curl http://localhost:3000/api/tracks/compilation?page=2&limit=10

📁 Structure créée

server/
├── database/
│   ├── evilspins.db          # Base SQLite (créée automatiquement)
│   ├── schema.sql             # Schéma de la base
│   └── migrate.ts             # Script de migration
├── utils/
│   └── database.ts            # Utilitaire de connexion
└── api/
    ├── boxes.ts               # ✅ Nouveau (SQLite)
    ├── artists.ts             # ✅ Nouveau (SQLite)
    └── tracks/
        ├── compilation.ts     # ✅ Nouveau (SQLite avec pagination)
        └── playlist.ts        # ⚠️ À adapter

🔄 Côté client : utiliser la pagination

Exemple pour charger les tracks progressivement :

// Au lieu de charger tout d'un coup
const { data } = await useFetch('/api/tracks/compilation')

// Maintenant avec pagination
const { data } = await useFetch('/api/tracks/compilation', {
  query: {
    page: 1,
    limit: 50,
    boxId: 'ES00',
    side: 'A'
  }
})

// data.tracks -> tableau de tracks
// data.pagination -> { page, limit, total, totalPages }

📊 Avantages obtenus

✅ Performances : Plus de chargement massif, pagination efficace ✅ Scalabilité : Peut gérer des milliers de tracks sans ralentir ✅ Filtrage : Recherche et filtres côté serveur (ultra rapide) ✅ Déploiement : Un seul fichier .db à déployer

🔧 À faire ensuite

1. Adapter l'endpoint playlist

L'endpoint tracks/playlist.ts lit des fichiers sur disque. Options :

Option A : Scanner le dossier au démarrage et insérer dans SQLite Option B : Garder la lecture filesystem mais optimiser avec un cache

2. Modifier le frontend

Mettre à jour vos composants Vue pour utiliser la pagination :

<script setup>
const page = ref(1)
const { data, refresh } = await useFetch('/api/tracks/compilation', {
  query: { page, limit: 20 }
})

function loadMore() {
  page.value++
  refresh()
}
</script>

3. Ajouter des fonctionnalités

Exemples de requêtes possibles maintenant :

// Recherche par titre
GET /api/tracks/compilation?search=love

// Tracks d'un artiste
GET /api/tracks/compilation?artistId=5

// Tri personnalisé
GET /api/tracks/compilation?sortBy=title&order=asc

🐛 Dépannage

Erreur "Cannot find module 'better-sqlite3'"

pnpm add better-sqlite3

La base ne se crée pas

Vérifiez les permissions :

chmod -R 755 server/database

Données manquantes après migration

Re-exécutez la migration :

pnpm tsx scripts/migrate.ts

📝 Notes

• La base SQLite est créée automatiquement au premier lancement
• Elle est incluse dans .gitignore par défaut (à ajuster selon vos besoins)
• Pour un déploiement, commitez le fichier .db OU re-exécutez la migration en production