Migrations de base de données
Le binaire porte son propre schéma. Chaque fichier de migration est lu à la
compilation et embarqué dans le binaireà ; un binaire déployé n’a donc
pas besoin de l’arborescence db/ sur le disque. Le moteur applique les
migrations en attente dans l’ordre des noms de fichiers et consigne les
fichiers appliqués dans une table _migrations. Un fichier de migration
modifié ou ajouté exige une recompilation.
Quand l’utiliser
Section intitulée « Quand l’utiliser »Vous aurez affaire aux migrations dans trois casà :
- vous mettez une installation à niveau vers une nouvelle version,
- vous devez annuler une migration,
- vous connectez un client qui ne doit pas fausser les timestamps.
Avant de commencer
Section intitulée « Avant de commencer »DATABASE_URLpointe vers la base cible.- Prenez un instantané de la base avant d’annuler une migration. Une annulation exécute du DDLà; seul un instantané permet ensuite de le défaire.
- Sachez distinguer les deux chaînes d’amorçageà :
migrateplusseed:coreest sûr partoutà ;db_resetdétruit la base de données.
1. Appliquer les migrations en attente
Section intitulée « 1. Appliquer les migrations en attente »facet migrateLe moteur trie les fichiers en attente par nom, applique la section
-- UP de chacun, puis consigne le fichier dans _migrations. Les
fichiers déj à appliqués sont ignorésà : la commande est idempotente. Au
démarrage, le point d’entrée du conteneur lance
facet migrate && facet seed:core : trois tentatives de migration,
puis l’initialisation, puis le serveur démarre.
Après un simple facet migrate sur une base neuve, lancez
l’initialisation :
facet seed:coreCette commande initialise les doctypes du noyau et le registre des devises. Elle est idempotente et sans risque à chaque démarrage.
2. Annuler une migration au besoin
Section intitulée « 2. Annuler une migration au besoin »facet migrate:down # annule la dernière migration appliquéefacet migrate:down 0008 # annule tout ce qui a été appliqué après 0008 ; 0008 reste appliquéfacet migrate:down --yes # passe la demande de confirmationRèglesà :
- La cible accepte le nom de fichier complet ou son préfixe numérique
NNNN. - Les migrations s’annulent dans l’ordre inverse des noms de fichiers.
Chaque annulation exécute la section
-- DOWNdu fichier et supprime sa ligne de_migrationsdans une seule transaction. - La commande affiche le plan et demande confirmation. Elle refuse de poser
la question quand stdin n’est pas un terminalà : les appels scriptés
passent
--yes. - Le plan est validé avant toute exécution. Une cible inconnue, une cible
non appliquée ou une migration sans section
-- DOWNexploitable interrompt la commande sans aucun changement. - Une migration annulée se réapplique normalement au prochain
facet migrate.
3. Respecter la règle de l’ajout seul
Section intitulée « 3. Respecter la règle de l’ajout seul »Après la première mise en production, le dossier db/migrations/ n’accepte
que les ajouts. Ne modifiez, ne renumérotez et ne fusionnez jamais une
migration qu’une base installée a déj à appliquée. La table _migrations
conserve les noms des fichiers appliqués. Un fichier modifié désynchronise
chaque base déployée de l’historique du dépôt, et un binaire recompilé
embarque alors un SQL en désaccord avec son propre historique.
4. Garder chaque session en UTC
Section intitulée « 4. Garder chaque session en UTC »Chaque colonne de timestamp stocke l’heure en UTC, sans fuseau horaire attaché. Deux couches fixent le fuseau de la session :
- L’application ajoute
TimeZone=UTCaux options de chaque connexion du pool. - La migration
0001_document_store.sqla défini la valeur par défaut du rôle applicatif avecALTER ROLE CURRENT_USER SET timezone TO 'UTC'.
Un client qui se connecte avec un autre rôle reçoit la valeur par défaut
du serveur. Il doit alors fixer TimeZone=UTC lui-même, dans les options
de connexion ou avec ALTER ROLE ... SET.
Une mise à niveau d’une version à la suivante sur une installation en conteneursà :
docker compose -f docker/compose.prod.yml pulldocker compose -f docker/compose.prod.yml up -dLa nouvelle image du backend s’amorce, applique ses migrations embarquées, réexécute l’initialisation des doctypes du noyau, puis le serveur démarre. Aucune étape de schéma manuelle n’existe. Si le démarrage signale un échec de migration après trois tentatives, lisez les logs du backend et corrigez la cause avant de réessayer.
L’équivalent en passant par les sourcesà :
make build_releasefacet migrate && facet seed:core# puis redémarrez le processus du serveurDépannage
Section intitulée « Dépannage »migrate:down s’interrompt sans rien changer.
La validation du plan a refusé la cibleà : nom de fichier inconnu,
cible non appliquée, ou section -- DOWN inexploitable. Rien n’a été
modifié.
Une migration ne peut pas être annulée.
Sa section -- DOWN est absente ou vide. Passez par un instantané pour
restaurer.
Les timestamps sont décalés d’un écart fixe.
Un client externe écrit avec une session hors UTC. Fixez TimeZone=UTC
pour ce rôle ou cette connexion, puis corrigez les lignes faussées à partir
d’un instantané ou d’une réimportation.
Le démarrage du conteneur échoue à l’étape de migration.
Le point d’entrée a tenté trois fois. Lisez les logs du backendà : une migration verrouillée, un problème de permissions ou une base injoignable en sont les causes habituelles.
Voir aussi
Section intitulée « Voir aussi »- Déployer avec des conteneurs — la chaîne du point d’entrée qui applique les migrations.
- Amorçage et tâches CLI —
migrate,seed:coreetdb_reseten contexte. - Prérequis système et topologie — la version de PostgreSQL dont le schéma a besoin.
- Revenir en arrière — le retour arrière des documents, un mécanisme distinct de l’annulation des migrations.
- Faire évoluer un schéma — le flux côté auteur pour les changements de doctypes.
- Internes sur GitHubà : migrations.md, cli.md.