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](../decisions/0004-ci-sans-action-externe.md)) :

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](../decisions/0005-mises-a-jour-nocturnes-pilotees-par-apt.md)).
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](../decisions/0006-latest-reste-sur-postgresql-17.md)).
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](../decisions/0003-versions-de-timescaledb-et-vectorchord-epinglees.md)) |
| 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 :

```sql
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 :
   ```bash
   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](../decisions/0007-postgresql-15-garde-timescaledb-2-28.md)).
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 :
   ```bash
   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 :
   ```sql
   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

```bash
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 |