Skip to content

Configuration ​

Depuis le dossier du projet, générez puis modifiez migration_config.yml :

sh
migrate new config

Connexion à la base ​

Cette configuration PostgreSQL lit la connexion dans DATABASE_DSN :

yaml
# Type de base
dialect: postgres
# Définir DATABASE_DSN avant l’exécution
data_source_name: "${DATABASE_DSN}"
# Dossier des fichiers de migration
migration_source: migrations
# Table des versions appliquées
schema_name: migration_schema
ChampRôleValeur par défaut
dialectType de basepostgres
data_source_nameConnexion unique, incompatible avec data_sourcesObligatoire en mode unique
data_sourcesConnexions nomméesDésactivé
migration_sourceDossier des migrationsmigrations
schema_nameTable d’historiquemigration_schema
working_directoryBase de recherche des fichiersDossier courant
migrate_out_of_orderAppliquer les versions en attente plus anciennesfalse
logger_leveldebug, info, warn, errorinfo

Exemples de connexion ​

Adaptez hôte, port, base ou service Oracle et définissez DB_USER et DB_PASSWORD. SQLite utilise directement un chemin de fichier.

yaml
dialect: postgres
data_source_name: "postgres://${DB_USER}:${DB_PASSWORD}@db.example:5432/app?sslmode=require"
yaml
dialect: mysql
data_source_name: "${DB_USER}:${DB_PASSWORD}@tcp(db.example:3306)/app?parseTime=true"
yaml
dialect: mariadb
data_source_name: "${DB_USER}:${DB_PASSWORD}@tcp(db.example:3306)/app?parseTime=true"
yaml
dialect: sqlite
data_source_name: "./demo.sqlite"
yaml
dialect: oracle
data_source_name: "oracle://${DB_USER}:${DB_PASSWORD}@db.example:1521/FREEPDB1"
yaml
dialect: mssql
data_source_name: "sqlserver://${DB_USER}:${DB_PASSWORD}@db.example:1433?database=app"
yaml
dialect: clickhouse
data_source_name: "clickhouse://${DB_USER}:${DB_PASSWORD}@db.example:9000/app"
yaml
dialect: tidb
data_source_name: "${DB_USER}:${DB_PASSWORD}@tcp(db.example:4000)/app?parseTime=true"
yaml
dialect: redshift
data_source_name: "postgres://${DB_USER}:${DB_PASSWORD}@cluster.example:5439/app?sslmode=require"

Dans une URL, encodez les caractères spéciaux du nom et du mot de passe (@, :, /). Les variables ne sont pas encodées automatiquement. Le format user:password@tcp(...) de MySQL/MariaDB/TiDB n’utilise pas cet encodage. Réglez TLS/SSL selon les exigences du serveur.

Niveaux de journalisation ​

ValeurMessages affichés
debugDébogage, informations, avertissements, erreurs
infoInformations, avertissements, erreurs
warnAvertissements et erreurs ; alias warning
errorErreurs uniquement
yaml
logger_level: debug # Afficher les messages de débogage

Variables d’environnement ​

${DATABASE_DSN} exige une variable définie. ${DB_NAME:app} utilise app si la variable manque. Réutilisez le YAML entre environnements, en fournissant les identifiants par variables ou coffre de secrets. Hôte SSH, utilisateur et adresse du proxy acceptent aussi ces modèles.

Ordre de recherche ​

Dans le dossier de travail, le premier fichier existant est utilisé :

  1. migration_config.yml
  2. migration_config.yaml
  3. migration_config.json

Les fichiers ne sont pas fusionnés. Un fichier sélectionné invalide ou illisible provoque une erreur. Avec -c, seul le fichier indiqué est consulté, même s’il manque.

sh
migrate -c ./configs/dev.yml status

Générer selon le besoin ​

BesoinCommande
Une basemigrate new config
Nom personnalisémigrate new config dev.yml
Plusieurs basesmigrate new config --multi
Quatre basesmigrate new config --multi --shards 4
SSH Agentmigrate new config --ssh-tunnel
Clé privéemigrate new config --ssh-tunnel --ssh-auth private_key
Mot de passe SSHmigrate new config --ssh-tunnel --ssh-auth password
Proxy SOCKS5migrate new config --ssh-tunnel --proxy socks5
Proxy HTTP CONNECTmigrate new config --ssh-tunnel --proxy http

Combinez les options. L’écrasement exige --force. Toutes les options sont dans migrate new config --help.

sh
migrate new config shards.yml --multi --shards 4 --ssh-tunnel --proxy socks5

Plusieurs bases ​

Remplacez data_source_name par data_sources. Type de base, fichiers et nom de table d’historique sont partagés. Les noms générés commencent à shard_0, avec les variables SHARD_0_DSN, etc.

yaml
dialect: postgres
migration_source: migrations
schema_name: migration_schema
data_sources:
  shard_0:
    data_source_name: "${SHARD_0_DSN}" # Connexion à la première base
  shard_1:
    data_source_name: "${SHARD_1_DSN}" # Connexion à la seconde base

Fichiers → shard_0 / shard_1 → Résultats

sh
migrate create
migrate up --dry-run
migrate up
migrate status

Chaque base choisit les versions en attente selon son propre historique et les applique dans l’ordre. Les versions réussies sont ignorées aux exécutions suivantes. new version crée un seul fichier partagé. Au plus 8 bases sont traitées simultanément par défaut ; --parallel 1 impose un traitement séquentiel.

sh
migrate up --parallel 4
migrate status --output json

Une erreur n’arrête pas les autres bases. Les résultats sont regroupés par nom et toute erreur produit un code de sortie non nul. Ce n’est pas une transaction entre bases : les changements ailleurs restent appliqués. Ctrl+C arrête les nouveaux traitements et annule ceux en cours.

Un ssh_tunnel global sert de configuration commune. Un objet SSH local le remplace entièrement ; absent ou null, il l’hérite. Voir SSH. Ne configurez chaque base réelle qu’une fois, ne lancez pas de migrations concurrentes dessus et ne modifiez pas les dépendances pendant l’exécution. Vérifiez données et historique avant de relancer après un échec.

Dossier de travail ​

sh
migrate -w ./deploy up
migrate -w ./deploy -c configs/dev.yml status

-w détermine la recherche de configuration et remplace working_directory. migration_source relatif est résolu depuis ce dossier ; -c seul ne le déplace pas. Les chemins SSH relatifs partent du dossier du fichier de configuration.