postgres-ts-vectors/docs/exploitation/publication.md

Publication et mises à jour

Les images sont construites, testées et publiées par la CI (.gitea/workflows/docker.yml), jamais à la main. Un push sur main est une publication : il remplace les quatre images, dont latest. Personne ne pousse sans demande explicite de l'utilisateur.

Déclencheurs

Déclencheur	Effet
Push sur main	Construction, tests et publication des quatre versions. Sans effet si tous les fichiers modifiés sont des .md ou sous docs/
Chaque nuit, 3 h 30 UTC	Tests des images publiées ; reconstruction et publication de celles qui ont des mises à jour
Lancement manuel (workflow_dispatch)	Comme un push

Chaîne de publication

Un job par version de PostgreSQL (15, 16, 17, 18), sans action externe (0004) :

1. Récupération du seul commit concerné et connexion au registre.
2. Recherche des mises à jour. L'image publiée est tirée, et apt y simule une mise à niveau. S'il reste des paquets à mettre à niveau, ou si l'image n'a jamais été publiée, une nouvelle clé APT_REFRESH est tirée de l'heure. Sinon la clé de l'image publiée, lue dans son label fr.killinger.apt-refresh, est reprise (0005).
3. Construction avec docker build --pull, par le démon Docker du runner. Avec une clé reprise, tout sort du cache. Avec une clé nouvelle, les paquets sont mis à niveau et TimescaleDB est recompilé. La nuit, cette étape est sautée quand l'image est à jour.
4. Tests par tests.sh, avec l'image publiée comme image précédente : la nouvelle image doit reprendre une base créée par celle qu'elle remplace. La nuit, sans reconstruction, c'est l'image publiée elle-même qui est testée.
5. Publication de pgN, seulement si les tests passent, puis de latest pour PostgreSQL 17 (0006).
6. Nettoyage : cache de construction borné à 8 Go, images sans étiquette supprimées.

La CI ne déclenche aucun déploiement. Un conteneur passe à la nouvelle image quand son exploitant la tire et le recrée.

Secret du dépôt	Usage
secrets.DOCKER_TOKEN	Connexion au registre Gitea (compte maxime.killinger)

Ce qui se met à jour seul, et ce qui ne le fait pas

Composant	Mise à jour
PostgreSQL (version mineure), pgvector, PostGIS, paquets Debian	Automatique, la nuit qui suit leur arrivée dans apt
TimescaleDB, VectorChord	À la main, dans le Dockerfile (0003)
Nouvelle version majeure de PostgreSQL	À la main, dans la matrice de la CI

Une mise à jour automatique ne demande rien à l'exploitant d'une base : le conteneur recréé repart sur ses données. Les extensions installées gardent la version de leurs objets SQL tant qu'on ne les met pas à niveau, ce qui reste facultatif pour pgvector et PostGIS :

ALTER EXTENSION vector UPDATE;
SELECT postgis_extensions_upgrade();

Changer la version de TimescaleDB

1. Construire et tester en local contre l'image publiée, pour chaque version de PostgreSQL :

   docker build --build-arg PG_VERSION=17 --build-arg TIMESCALEDB_VERSION=X.Y.Z -t postgres-ts-vectors:essai .
   docker pull gitea.killinger.fr/maxime.killinger/postgres-ts-vectors:pg17
   ./tests.sh postgres-ts-vectors:essai gitea.killinger.fr/maxime.killinger/postgres-ts-vectors:pg17
   

   Une version de TimescaleDB qui abandonne une version de PostgreSQL échoue à la compilation (Unsupported PostgreSQL version). Cette version de PostgreSQL sort alors de la matrice, ou garde sa propre version de TimescaleDB, comme PostgreSQL 15 (0007).
2. Changer TIMESCALEDB_VERSION dans le Dockerfile, le tableau et le badge du README.md.
3. Prévenir les exploitants avant de pousser. Dès qu'un conteneur est recréé sur la nouvelle image, sa base refuse toute requête jusqu'à l'exécution de :

   docker exec -it <conteneur> psql -X -U <utilisateur> -d <base> -c 'ALTER EXTENSION timescaledb UPDATE'
   

   La commande est à passer dans chaque base du serveur qui a l'extension, postgres comprise si elle l'a. -X et une session neuve sont nécessaires : l'instruction doit être la première de la session. Les bases se relèvent avant de recréer le conteneur, tant que toutes répondent :

   SELECT datname FROM pg_database WHERE datallowconn AND NOT datistemplate;   -- les bases
   SELECT extversion FROM pg_extension WHERE extname = 'timescaledb';          -- dans chacune
   

   Les applications qui gardaient des connexions ouvertes sont à redémarrer.

Changer la version de VectorChord

Elle fait partie de l'étiquette de l'image de base. Vérifier que TensorChord publie tensorchord/vchord-postgres:pgN-vX.Y.Z pour les quatre versions de PostgreSQL, changer VCHORD_VERSION dans le Dockerfile, le tableau et le badge du README.md, puis tester comme pour TimescaleDB. Côté base : ALTER EXTENSION vchord UPDATE.

Vérifier une image publiée

IMAGE=gitea.killinger.fr/maxime.killinger/postgres-ts-vectors:pg17
docker pull "$IMAGE"

# Commit, date de construction, clé de mise à jour, image de base
docker image inspect "$IMAGE" -f '{{json .Config.Labels}}'

# Version du serveur et des paquets d'extensions
docker run --rm --entrypoint sh "$IMAGE" -c \
  'postgres --version; dpkg-query -W -f "\${Package} \${Version}\n" "postgresql-$PG_MAJOR-*" | grep " ."'

# La suite de tests, sur l'image publiée
./tests.sh "$IMAGE"

Label	Contenu
org.opencontainers.image.revision	Commit du dépôt qui a construit l'image
org.opencontainers.image.created	Date de construction
org.opencontainers.image.version	Étiquette pgN
org.opencontainers.image.base.name	Image de VectorChord dont elle part
fr.killinger.apt-refresh	Clé de la dernière mise à niveau des paquets, à l'heure UTC