module

Beryl::CLI::PgUpgrade

beryl pg-upgrade <host> [--to NN] [--apply] — migre le serveur PostgreSQL d'un hôte FreeBSD d'une version MAJEURE à une autre (ex. 18 → 19). Générique : aucune application en dur, les services clients à arrêter sont donnés par --stop-services.

Procédure = celle du fichier UPDATING des ports FreeBSD (entrée « The default version of PostgreSQL has been switched from 17 to 18 ») : pkg create des anciens paquets, extraction des anciens binaires dans /tmp/pg-upgrade, pkg delete -f des anciens, pkg install des nouveaux, initdb du nouveau cluster, pg_upgrade -b <anciens binaires> …, start. beryl y ajoute les gardes qu'une procédure manuelle oublie :

  • dépendants (paquets construits contre l'ancien client : extensions, pilotes Ruby/Python…) : refus si le dépôt ne les propose pas déjà reconstruits pour la nouvelle majeure (sinon pkg les casserait) ;
  • sauvegarde pg_dumpall AVANT tout, espace disque vérifié ;
  • initdb aux options de l'ANCIEN cluster (encodage, locale, data checksums, taille des segments WAL) — pg_upgrade exige qu'elles correspondent ;
  • pg_upgrade --check d'abord, retour arrière automatique en cas d'échec AVANT le démarrage du nouveau serveur.

DRY-RUN par défaut (lectures seules : détection + plan). --apply exécute. L'ancien data dir est CONSERVÉ ; --cleanup (dry-run puis --apply) le supprime une fois la nouvelle version en service.

Constants

BASE = "postgresql"

Préfixe des ports : databases/postgresql<NN>-{server,client,contrib…}.

BINDIR = "/usr/local/bin"

Binaires installés par les paquets (PREFIX par défaut des ports).

DEFAULT_DUMP_DIR = "/var/db/postgres"

Défaut de --dump-dir : HOME de l'utilisateur postgres créé par le port (UID 770, home /var/db/postgres). Persistant au reboot (≠ /tmp), même système de fichiers que les data dirs par défaut (un seul contrôle d'espace), et déjà réservé aux données PostgreSQL (droits restreints).

EXIT_FAILED = 2
EXIT_OK = 0
EXIT_REFUSED = 3
EXIT_USAGE = 1
SAFE_NAME = /\A[A-Za-z0-9_.+-]+\z/

Noms de services / paquets / utilisateurs / chemins acceptés : rien qui puisse s'échapper d'une ligne de commande (tout passe par sh -c).

SAFE_PATH = /\A\/[A-Za-z0-9_.\/-]+\z/
STATE_FILE = "pg-upgrade.state"

Fichier d'état écrit dans --dump-dir après une migration réussie : lu par --cleanup pour savoir quoi supprimer (clé=valeur, une par ligne).

WORK_DIR = "/tmp/pg-upgrade"

Répertoire d'extraction des anciens binaires (chemin de UPDATING).

Class methods

human_kb(kb : Int64) : String

Taille lisible (Ko → Mo/Go).

Source
initdb_flags(locale : Locale, checksums : Bool, new_major : String, wal_segment : Int64 | Nil) : Array(String)

Options d'initdb reproduisant l'ancien cluster. --no-data-checksums n'existe que depuis PostgreSQL 18 (qui active les checksums par défaut) : pour une cible plus ancienne, l'absence de flag suffit.

Source
major_key(code : String) : Float64

Clé de tri d'un numéro de majeure FreeBSD : 96 = 9.6 (avant la numérotation à un chiffre de PostgreSQL 10), sinon le numéro lui-même.

Source
parse_checksums(controldata : String) : Bool | Nil

« Data page checksum version: 1 » (sortie de pg_controldata) → true ; 0 → false ; ligne absente → nil (état inconnu = refus).

Source
parse_df(line : String) : Tuple(String, Int64) | Nil

Ligne de df -kP <dir> | tail -1 → {système de fichiers, Ko disponibles}.

Source
parse_wal_segment(controldata : String) : Int64 | Nil

« Bytes per WAL segment: 16777216 » → 16777216. nil si absent.

Source
run(config_root : String, args : Array(String)) : Int32
Source
safe_dir?(path : String) : Bool

Chemin absolu, caractères sûrs, et au moins deux niveaux (jamais / ni /var : ces chemins finissent dans des rm -rf).

Source
validate(opts : Options) : String | Nil

Contrôle des options AVANT toute connexion. nil si tout va bien.

Source

Nested types