postgresql-maximalism

A repository dedicated to using PostgreSQL for everything.

A docker image will be built based on PostgreSQL 16, containing the following selection of extensions:

Name	Category	Description
pg_jsonschema	Documents	Ensures a JSON schema is respected for JSON or JSONB.
pg_mooncake	Analytics & Time Series	Support for Iceberg and Delta Lake, along with DuckDB based analytics.
timescaledb	Analytics & Time Series	Adds performance improvements, like partitioning or incremental views, to handle large scale time series data efficiently and in real-time.
pgvector	Vectors & AI	Two approximate indexing approaches, along with functions to efficiently compute vector similarities.
pgai	Vectors & AI / Search	Hugging Face dataset loading, text chunking and embedding, LLM support and RAG, similarity search.
pg_search	Search	Extends full-text search capabilities with Lucene-like features, based on Tantivy, like segmented indexing, BM25 scoring, tokenizers, or stemming.
pgrouting	Graphs	While no specialized graph storage is provided (i.e., no index-free adjacency), this adds several useful graph algorithms, like shortest-distance (e.g., Dijkstra, A*, Floyd-Warshall), centralities (betweenness), or minimum spanning tree (Kruskal, Prim).
pgmq	Message Queues	Supports multiple queues, with read/write operations. Similar to AWS SQS or RSMQ.

Requirements

• Docker (>= 20.10.0, with docker compose)
• NVIDIA Container Toolkit (see install instructions)

Note

The NVIDIA Container Toolkit is optional, if you don't want to run the pgai demo queries. Otherwise, you can simply comment out the ollama and pgai-worker services from the docker-compose.yml and launch it that way. You can also run it using the CPU, if you comment out the deploy and runtime sections from ollama, but this will likely be slow.

Setup

After cloning the repository, copy the .env.example to .env and replace the values with your own username, password, and database name:

PGUSER=<username>
PGPASSWORD=<password>
PGDATABASE=<database>

And do the same for the MinIO variables:

MINIO_ROOT_USER=<username>
MINIO_ROOT_PASSWORD=<password>
MINIO_BUCKET_NAME=<bucket>

We create a builder with max-parallelism=1, as most builds are already individually parallelized. Building without this option might result in a freeze due to system overload, but feel free to increase the value, or skip this step altogether. You can build the image and start the containers for WhoDB, MinIO and PostgreSQL 16 by running the following commands:

docker buildx create \
    --name psql-max-builder \
    --driver docker-container \
    --platform linux/amd64 \
    --config buildkitd.toml \
    --use
docker compose up --build -d

Wait until the minio-mc and ollama-models containers terminate. The former will setup the s3://lakehouse bucket to be used with pg_mooncake, and the latter will install the gemma3:1b an nomic-embed-text models to be used with pgai.

You can either monitor this using the CLI and waiting until no container is listed:

docker container ls -f name=minio-mc -f name=ollama-models

Or simply by looking at Docker Desktop to check if the corresponding containers inside postgresql-maximalism have stopped.

Connecting

You can then connect to the database using whichever client you prefer. For example, on Debian 12, you can install the psql client as follows:

sudo curl -o /usr/share/keyrings/apt.postgresql.org.asc --fail https://www.postgresql.org/media/keys/ACCC4CF8.asc

sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'

sudo apt install -y postgresql-client-16

And you establish a link to PostgreSQL by loading the .env and running the following command:

eval export $(cat .env)
psql

This will load the configured PostgreSQL environment variables, which are used by default by most PostgreSQL utilities.

Extensions

All extensions should be created and ready to use. You can list available extensions by typing \dx or by using the following equivalent query:

SELECT
    e.extname AS "Name",
    e.extversion as "Version",
    n.nspname AS "Schema",
    d.description AS "Description"
FROM
    pg_extension e
    LEFT JOIN pg_namespace n
    ON e.extnamespace = n.oid
    LEFT JOIN pg_description d
    ON e.oid = d.objoid
ORDER BY
    e.extname;