postgres-ts-vectors/README.md

<h1 align="center">postgres-ts-vectors</h1>
<p align="center">Image Docker de PostgreSQL avec TimescaleDB, VectorChord, pgvector et PostGIS déjà installés.</p>

<p align="center">
  <a href="https://gitea.killinger.fr/maxime.killinger/postgres-ts-vectors/actions?workflow=docker.yml"><img src="https://gitea.killinger.fr/maxime.killinger/postgres-ts-vectors/actions/workflows/docker.yml/badge.svg?branch=main" alt="CI"></a>
  <img src="https://img.shields.io/badge/PostgreSQL-15%20%C2%B7%2016%20%C2%B7%2017%20%C2%B7%2018-4169E1?style=flat-square&logo=postgresql&logoColor=white" alt="PostgreSQL 15, 16, 17 et 18">
  <img src="https://img.shields.io/badge/TimescaleDB-2.28.3-FDB515?style=flat-square&logo=timescale&logoColor=black" alt="TimescaleDB 2.28.3">
  <img src="https://img.shields.io/badge/VectorChord-1.1.1-6E56CF?style=flat-square" alt="VectorChord 1.1.1">
  <img src="https://img.shields.io/badge/pgvector-0.8-336791?style=flat-square" alt="pgvector 0.8">
  <img src="https://img.shields.io/badge/PostGIS-3-5CAE58?style=flat-square" alt="PostGIS 3">
  <img src="https://img.shields.io/badge/Docker-une%20image%20par%20version-2496ED?style=flat-square&logo=docker&logoColor=white" alt="Docker, une image par version de PostgreSQL">
</p>

## Présentation

Une image par version majeure de PostgreSQL, prête à servir des séries temporelles, de la
recherche vectorielle et des données géographiques dans la même base :

- **[TimescaleDB](https://www.timescale.com/)** : séries temporelles (hypertables) ;
- **[VectorChord](https://vectorchord.ai/)** et **[pgvector](https://github.com/pgvector/pgvector)** :
  type `vector` et index de recherche par similarité ;
- **[PostGIS](https://postgis.net/)** : objets géographiques.

Les extensions sont créées au premier démarrage, dans la base du conteneur. L'image part de
celle de VectorChord, mise à niveau à la construction : [docs/architecture.md](docs/architecture.md).

## Images

Publiées sous `gitea.killinger.fr/maxime.killinger/postgres-ts-vectors`.

| Étiquette | PostgreSQL | TimescaleDB | VectorChord | pgvector | PostGIS |
|---|---|---|---|---|---|
| `pg15` | 15 | 2.28.3 | 1.1.1 | 0.8 | 3 |
| `pg16` | 16 | 2.28.3 | 1.1.1 | 0.8 | 3 |
| `pg17`, `latest` | 17 | 2.28.3 | 1.1.1 | 0.8 | 3 |
| `pg18` | 18 | 2.28.3 | 1.1.1 | 0.8 | 3 |

TimescaleDB et VectorChord sont épinglés. PostgreSQL, pgvector et PostGIS suivent leurs
versions mineures : les images sont reconstruites dès qu'apt en propose
([Mises à jour](#mises-à-jour)). Les versions exactes se lisent dans un conteneur :

```bash
docker exec ma-base psql -U postgres -Atc "select version()" \
  -c "select extname, extversion from pg_extension"
```

## Démarrage rapide

```bash
docker run -d \
  --name ma-base \
  -e POSTGRES_PASSWORD=motdepasse \
  -v donnees_pg:/var/lib/postgresql \
  -p 5432:5432 \
  gitea.killinger.fr/maxime.killinger/postgres-ts-vectors:pg18
```

Le point de montage du volume dépend de la version de PostgreSQL :

| Étiquette | Monter le volume sur |
|---|---|
| `pg15`, `pg16`, `pg17`, `latest` | `/var/lib/postgresql/data` |
| `pg18` | `/var/lib/postgresql` |

Sur l'autre chemin, les données d'une image jusqu'à PostgreSQL 17 partent dans un volume
anonyme, perdu quand le conteneur est recréé, et l'image `pg18` refuse de démarrer.

## Configuration

| Variable | Rôle | Défaut |
|---|---|---|
| `POSTGRES_PASSWORD` | Mot de passe, obligatoire | aucun |
| `POSTGRES_USER` | Utilisateur | `postgres` |
| `POSTGRES_DB` | Base, où les extensions sont créées | le nom de l'utilisateur |

Ce sont les variables de l'image officielle `postgres`. Une commande qui remplace celle de
l'image doit garder `-c shared_preload_libraries=timescaledb,vchord`, sans quoi TimescaleDB
et VectorChord ne sont pas chargés.

## Utilisation

```sql
-- Série temporelle
CREATE TABLE mesures (time TIMESTAMPTZ NOT NULL, capteur INTEGER, temperature DOUBLE PRECISION);
SELECT create_hypertable('mesures', 'time');

-- Recherche vectorielle
CREATE TABLE documents (id SERIAL PRIMARY KEY, contenu TEXT, embedding vector(1536));
CREATE INDEX ON documents USING vchordrq (embedding vector_l2_ops);
SELECT * FROM documents ORDER BY embedding <-> '[0.1, 0.2, ...]' LIMIT 10;

-- Géographie
CREATE TABLE lieux (id SERIAL PRIMARY KEY, geom geometry(Point, 4326));
SELECT ST_Distance(a.geom, b.geom) FROM lieux a, lieux b WHERE a.id = 1 AND b.id = 2;
```

## Mises à jour

Chaque nuit, la CI teste les images publiées et reconstruit celles pour lesquelles apt
propose des mises à jour : versions mineures de PostgreSQL, pgvector, PostGIS, correctifs
Debian. Une version de TimescaleDB ou de VectorChord se change à la main, car une base
existante doit alors être mise à niveau :
[docs/exploitation/publication.md](docs/exploitation/publication.md).

## Tests

```bash
docker build --build-arg PG_VERSION=18 -t postgres-ts-vectors:pg18 .
./tests.sh postgres-ts-vectors:pg18
```

`tests.sh` démarre l'image, vérifie les extensions, les exerce, redémarre le serveur et,
avec une seconde image en argument, reprend une base créée par celle-ci. La CI lance la même
commande avant de publier. Détail dans [CLAUDE.md](CLAUDE.md).

## Documentation

- [CLAUDE.md](CLAUDE.md) : commandes, conventions, pièges connus.
- [docs/architecture.md](docs/architecture.md) : étapes de construction, démarrage du
  conteneur, emplacement des données.
- [docs/exploitation/publication.md](docs/exploitation/publication.md) : CI, mises à jour,
  changement de version.
- [docs/decisions/](docs/decisions/) : choix de conception.
- [docs/a-faire.md](docs/a-faire.md) : points ouverts.

## Licences

Le dépôt est sous licence Apache 2.0. Les extensions gardent la leur :
[TimescaleDB](https://github.com/timescale/timescaledb/blob/main/LICENSE),
[VectorChord](https://github.com/tensorchord/VectorChord/blob/main/LICENSE),
[pgvector](https://github.com/pgvector/pgvector/blob/master/LICENSE),
[PostGIS](https://postgis.net/) (GPL v2 ou ultérieure).

Image réalisée par [Maxime Killinger](https://www.linkedin.com/in/maxime-killinger-8504b7b6).