maxime.killinger
a57c520610
🚀 Docker Build and Push / build-and-push (15) (push) Successful in 2m58s
🚀 Docker Build and Push / build-and-push (16) (push) Successful in 3m39s
🚀 Docker Build and Push / build-and-push (17) (push) Successful in 3m37s
🚀 Docker Build and Push / build-and-push (18) (push) Successful in 3m36s
- TIMESCALEDB_VERSION passe de 2.28.3 à 2.30.2. Vérifié pour 16, 17 et 18 : compilation, tests, et reprise d'une base créée par l'image publiée après `ALTER EXTENSION timescaledb UPDATE`. - TimescaleDB 2.29 a retiré PostgreSQL 15 (`Unsupported PostgreSQL version` à la compilation) : `pg15` garde 2.28.3 par TIMESCALEDB_VERSION_PG15. - Décision 0007, tableau et badge du README, procédure de changement de version. Une base existante refuse toute requête sur la nouvelle image tant que l'extension n'est pas mise à niveau : voir docs/exploitation/publication.md.
137 lines
6.1 KiB
Markdown
137 lines
6.1 KiB
Markdown
<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.30.2-FDB515?style=flat-square&logo=timescale&logoColor=black" alt="TimescaleDB 2.30.2">
|
|
<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.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).
|