Introduction
Votre service de tickets doit pouvoir indiquer le niveau d’urgence sans perdre les demandes existantes. Un déploiement de schéma peut échouer si les anciennes lignes ne respectent pas une nouvelle règle. Vous allez créer une migration ordonnée, la tester localement, puis appliquer le même fichier à distance tout en conservant les identifiants et les sujets des tickets.
Ce lab commence indépendamment avec une migration initiale fournie. Il suppose que vous connaissez la création d’une base de données et les notions SQL de base vues dans D01, mais n’utilise aucune VM ni base de données précédente.
Utilisez votre propre compte d’apprentissage et une VM vierge. La configuration installe d’abord Node.js 22.22.0, puis exécute npm install pour installer Wrangler 4.131.1, utilisé uniquement par le projet, ainsi que les dépendances nécessaires à l’évaluation dans /home/labex/project/ticket-database. Les versions des dépendances directes sont verrouillées ; l’installation crée son propre fichier de verrouillage. La configuration n’effectue aucune connexion au cloud ni aucune opération évaluée sur la base de données. Sur une machine personnelle, installez la même version de Wrangler avec npm install --save-dev wrangler@4.131.1 dans votre projet.
Cet exercice utilise de petites données synthétiques dans le cadre des allocations gratuites D1. L’utilisation déjà enregistrée sur votre compte est également comptabilisée dans ces allocations. Aucun domaine acheté n’est nécessaire. Conservez cette VM jusqu’à ce que la suppression des ressources et la déconnexion aient toutes deux été vérifiées.
Autoriser cette VM et sélectionner le compte
Dans cette étape, vous connectez ce terminal vierge à votre propre compte d’apprentissage. Une connexion au Dashboard ne suffit pas à autoriser la VM. Les autorisations D1 permettent de créer, de modifier et de supprimer des bases de données. Consultez la page de consentement réelle, notamment la section Background Access, avant d’autoriser la VM.
Ouvrez le projet préparé et vérifiez la version de la CLI :
cd /home/labex/project/ticket-database
npx wrangler --version
La sortie attendue est 4.131.1. Lancez l’autorisation par appareil ; --device affiche un code à saisir dans le navigateur et --browser=false vous laisse choisir vous-même si vous souhaitez ouvrir le navigateur :
npx wrangler login --device --browser=false --scopes account:read user:read d1:write
Ouvrez l’URL affichée dans votre navigateur, saisissez le code actuel, vérifiez votre compte d’apprentissage et les autorisations demandées, puis autorisez l’accès. Attendez que le terminal confirme la réussite. Ne collez jamais de mots de passe ni de jetons dans les fichiers du projet.
npx wrangler whoami --json
Vérifiez la présence de loggedIn: true, puis lisez les valeurs name et id du compte, même si un seul compte est affiché. Copiez l’identifiant voulu dans la configuration ci-dessous. La variable Shell suivante utilise 6 octets aléatoires, soit 12 caractères hexadécimaux, afin d’éviter les collisions avec les autres apprenants. Un document here-document écrit le JSON situé entre les lignes JSON ; $RUN est développé à l’intérieur de ce document.
La barre oblique inverse devant $schema conserve cette clé JSON littérale ; $RUN est toujours remplacé par le nom unique de cette exécution.
RUN=labex-c04-d03-$(openssl rand -hex 6)
cat > wrangler.jsonc <<JSON
{
"\$schema": "./node_modules/wrangler/config-schema.json",
"name": "$RUN",
"account_id": "YOUR_ACCOUNT_ID",
"main": "src/index.js",
"compatibility_date": "2026-09-15",
"workers_dev": true,
"preview_urls": false
}
JSON
Remplacez YOUR_ACCOUNT_ID avant d’exécuter ce bloc. Gardez ce terminal ouvert afin que RUN reste disponible. La propriété name identifie cette exécution ; account_id sélectionne le compte utilisé pour les opérations cloud. Le fichier est un fichier JSON ordinaire, également valide au format JSONC. Sa création ne déploie aucun Worker.
Établir la base de données de tickets existante
Dans cette étape, vous préparez la version existante de la base de données de l’application. Une migration est un fichier SQL numéroté qui décrit une modification du schéma. Wrangler enregistre les noms des fichiers appliqués dans d1_migrations, ce qui permet aux exécutions suivantes de distinguer le travail déjà effectué du travail restant. La configuration fournit 0001_initial.sql comme ancienne version de l’application ; vous allez créer vous-même la mise à niveau.
Créez une base de données cloud temporaire. --binding DB fournit au code de l’application un nom court, --update-config enregistre son nom réel et son UUID dans wrangler.jsonc, et --use-remote=false conserve le développement en local :
npx wrangler d1 create "$RUN-db" --binding DB --update-config --use-remote=false
Lisez le nom et l’identifiant créés, puis inspectez la liaison enregistrée :
cat wrangler.jsonc
L’entrée DB doit désigner la base de données de cette exécution. Une liaison est une connexion configurée entre le code et une ressource. Son UUID identifie la base de données cloud, tandis que --local utilise une base de données SQLite distincte dans cette VM. Incluez toujours --local ou --remote dans les commandes SQL.
Lisez l’ancien schéma avant de l’appliquer :
cat migrations/0001_initial.sql
Il contient deux tickets existants et aucune colonne de priorité. Appliquez-le séparément aux cibles locale et distante, puis confirmez qu’il s’agit bien de la base de données de ce lab lorsque l’invite vous le demande :
npx wrangler d1 migrations apply DB --local
npx wrangler d1 migrations apply DB --remote
Inspectez les lignes et l’état des migrations appliquées :
npx wrangler d1 execute DB --remote --command "SELECT id, subject, status, source FROM tickets ORDER BY id; SELECT name FROM d1_migrations ORDER BY id;"
Les deux tickets d’origine doivent exister ; la migration appliquée est 0001_initial.sql. Une migration appliquée constitue un historique : créez un nouveau fichier pour les modifications suivantes au lieu de modifier cet historique.
Ajouter une priorité contrainte en local
Dans cette étape, vous attribuez une priorité par défaut aux tickets existants sans supprimer la table. ALTER TABLE ... ADD COLUMN modifie une table sur place. Une colonne ajoutée qui n’autorise pas les valeurs NULL doit avoir une valeur par défaut utile pour les anciennes lignes. CHECK limite les priorités à normal ou urgent.
Créez la migration numérotée suivante :
npx wrangler d1 migrations create DB add_priority
Dans ce projet vierge, cette commande crée migrations/0002_add_priority.sql. Vérifiez ce nom de fichier dans la sortie. Écrivez la modification dans ce nouveau fichier :
cat > migrations/0002_add_priority.sql <<'SQL'
ALTER TABLE tickets ADD COLUMN priority TEXT NOT NULL DEFAULT 'normal' CHECK(priority IN ('normal','urgent'));
SQL
Affichez les migrations en attente, puis appliquez uniquement la migration en local :
npx wrangler d1 migrations list DB --local
npx wrangler d1 migrations apply DB --local
Les deux tickets existants doivent recevoir la priorité normal. Ajoutez un ticket urgent, puis interrogez-le :
npx wrangler d1 execute DB --local --command "INSERT INTO tickets (id, subject, source, priority) VALUES (3, 'Service unavailable', 'local', 'urgent'); SELECT id, subject, priority FROM tickets ORDER BY id;"
Une priorité qui ne fait pas partie des valeurs autorisées doit échouer au lieu d’être insérée silencieusement dans la table :
npx wrangler d1 execute DB --local --command "UPDATE tickets SET priority = 'critical' WHERE id = 3;"
La sortie attendue contient CHECK constraint failed ; cette erreur intentionnelle laisse le ticket 3 avec la priorité urgent. Lisez PRAGMA table_info(tickets) sur la base de données distante pour constater que le schéma cloud est toujours l’ancienne version :
npx wrangler d1 execute DB --remote --command "PRAGMA table_info(tickets);"
La colonne distante priority n’existe pas encore. La réussite d’une migration locale ne met pas à jour le cloud.
Appliquer la migration testée à distance
Dans cette étape, vous déployez à distance le même fichier vérifié. Consultez les travaux en attente avant de confirmer l’application :
npx wrangler d1 migrations list DB --remote
npx wrangler d1 migrations apply DB --remote
Seule 0002_add_priority.sql doit être en attente. Les lignes existantes sont conservées. Ajoutez un ticket urgent à distance, puis inspectez les données et l’historique des migrations :
npx wrangler d1 execute DB --remote --command "INSERT INTO tickets (id, subject, source, priority) VALUES (3, 'Service unavailable', 'remote', 'urgent'); SELECT id, subject, priority FROM tickets ORDER BY id; SELECT name FROM d1_migrations ORDER BY id;"
Les tickets 1 et 2 conservent leurs sujets et reçoivent la priorité normal ; le ticket 3 reçoit la priorité urgent. Les deux noms de fichiers numérotés sont enregistrés. Exécutez une nouvelle fois la commande d’application :
npx wrangler d1 migrations apply DB --remote
La commande doit signaler qu’il n’y a aucune migration en attente et laisser les lignes inchangées. C’est le rôle de la table d’historique : relancer le déploiement n’exécute pas à nouveau les fichiers déjà terminés. Dans le Dashboard, ouvrez la base de données D1 de cette exécution et consultez sa vue du schéma ou des tables afin de faire le lien entre la nouvelle colonne et le résultat de la CLI. Ne modifiez pas le schéma depuis cette interface.
Cet exemple montre les deux tickets d’origine avec la priorité par défaut normal et le nouveau ticket distant avec la priorité urgent. Le nom généré de la base identifie cette exécution d’exemple ; le vôtre sera différent. Les requêtes SQL, l’historique des migrations et les vérifications des contraintes ci-dessus confirment le résultat ; la capture sert de repère visuel.
Supprimer les ressources temporaires
Dans cette étape, vous supprimez uniquement les ressources de ce lab, alors que la VM est encore autorisée. Terminez d’abord toutes les vérifications fonctionnelles. Conservez la configuration jusqu’à la fin de la vérification de la suppression.
npx wrangler d1 delete DB
Lisez l’invite et confirmez qu’elle ne concerne que la base de données de cette exécution. Listez ensuite les bases de données :
npx wrangler d1 list --json
Le nom et l’UUID de la base de données que vous avez notés doivent être absents d’une réponse réussie. D’autres ressources peuvent rester présentes. Une erreur d’authentification ou de réseau ne permet pas de conclure : rétablissez l’accès et répétez la lecture avant de continuer. Effectuez la vérification de cette étape tant que vous êtes encore connecté.
Mettre fin à l’autorisation de cette VM
Dans cette étape, vous mettez fin à l’autorisation uniquement après la réussite de la vérification indépendante de la suppression. La déconnexion supprime l’autorisation Wrangler enregistrée sur cette VM ; fermer une VM ne suffit pas à nettoyer les ressources cloud.
npx wrangler logout
npx wrangler whoami --json
La sortie attendue contient loggedIn: false. Cette requête non authentifiée peut se terminer avec un code différent de zéro ; cela est attendu uniquement si la réponse structurée indique explicitement que vous êtes déconnecté. Terminez la vérification, puis fermez l’environnement du lab.
Résumé
Vous avez appris à faire évoluer un schéma de tickets. Vous avez vérifié les résultats observables dans la base de données, conservé explicitement le compte sélectionné et l’état local, puis supprimé les ressources temporaires avant de vous déconnecter.
