postgres-ts-vectors
Image Docker de PostgreSQL avec TimescaleDB, VectorChord, pgvector et PostGIS déjà installés.
## 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.30.2 | 1.1.1 | 0.8 | 3 |
| `pg17`, `latest` | 17 | 2.30.2 | 1.1.1 | 0.8 | 3 |
| `pg18` | 18 | 2.30.2 | 1.1.1 | 0.8 | 3 |
TimescaleDB et VectorChord sont épinglés ; `pg15` garde la dernière version de TimescaleDB
qui gère PostgreSQL 15
([0007](docs/decisions/0007-postgresql-15-garde-timescaledb-2-28.md)). 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).