prototype nix package for supabase postgres

This repository contains experimental code to package PostgreSQL using Nix, and tooling and infrastructure for deploying it. Read the rest of this README for some basic overview of the high level components.

Don't know Nix? Want to understand some of the thinking here? To learn about Nix and some of the design constraints this repository are under, please see the docs/ directory which should help get you up to speed.

If you want to install Nix and play along quickly, check out the Start Here page.

⚠️ 🚧 NOTE 🚧 ⚠️ — This repository is EXPERIMENTAL. It is not an official Supabase project, and may be abandoned or changed at any moment; there is no commitment to any kind of external third party support at this time.

Fundamental components of this repository

This repository contains a few major high level components, which are outlined below.

PostgreSQL Binary Distributions

The following PostgreSQL releases are packaged up, along with extensions (read below) in order to create "fully self contained" binary distributions. In order to get ahold of them, you can use nix build:

nix build .#psql_14/bin -o result-14
nix build .#psql_15/bin -o result-15

This will create two symlinks named result-14 (resp. result-15). You can use the resulting symlinks as a binary distribution; as if they were unpacked tarballs.

PostgreSQL Docker Images

From the binary images generated by nix build, we also create Docker images. You can create and load an image like so:

nix build .#psql_15/docker -o result-15
docker load -i ./result-15

There will then be an image named postgresql-15:latest tagged in local image registry.

This repository also provides pre-packaged docker images hosted via GitHub Packages; simply download them with:

docker pull ghcr.io/supabase/nix-postgres-14:latest
docker pull ghcr.io/supabase/nix-postgres-15:latest

A full suite of extensions

The binary distributions have many extensions enabled; these include:

postgis
pgrouting
pgtap
pg_cron
pgaudit
pgjwt
plpgsql_check
pg_safeupdate
timescaledb
wal2json
plv8
rum
pgvector
pg_repack
pgroonga
pgsql
pg_plan_filter
pg_net
pg_hashids
pgsodium
pg_graphql
pg_stat_monitor
pg_jsonschema
vault
hypopg
pg_tle
wrappers
supautils

You can just use CREATE EXTENSION to enable most of these. Some may require tweaks to postgresql.conf to enable.

Helpful development utilities

Want to start a postgresql-15 server with a bunch of extensions? You don't even need to download this repository; just use nix run:

nix run github:supabase/nix-postgres#start-server 15

This will start PostgreSQL 15 on port 5432 on localhost with a temporary directory created by mktemp -d. Connect to it:

austin@GANON:~$ nix run github:supabase/nix-postgres#start-client 14
Starting server for PSQL 14
psql (14.8, server 15.3)
WARNING: psql major version 14, server major version 15.
         Some psql features might not work.
Type "help" for help.

postgres=#

The first argument of both commands simply specifies 14 or 15 to get the major version. This will be expanded in the future.

Migration testing tools

You can test database migrations (using some artificial data schemas); it uses the following data to set up the database:

Then, run the following:

nix run github:supabase/nix-postgres#migration-test 14 15

This will do a migration between versions 14 and 15, at the time of the latest commit to the nix-postgres repository.

You can also test arbitrary /nix/store paths; for example the following works:

nix run github:supabase/nix-postgres#migration-test \
  $(nix build github:supabase/nix-postgres#psql_14/bin --no-link --print-out-paths) \
  $(nix build github:supabase/nix-postgres#psql_15/bin --no-link --print-out-paths)

Thus, you can arbitrarily mix and match various versions that might have been built in CI, and test their upgrade paths.

Note that the data.sql files and whatnot aren't complete; tweaks are very welcome to cover as many edge cases as possible.

Nix binary cache

There is a nix binary cache located at the following URL:

https://nix-postgres-artifacts.s3.amazonaws.com/

Binaries are signed with the public key:

nix-cache.supabase.com-1:ZfEc7Qb7SN+qOTJGMtCz54rnVQ1W2ZI2ROCSSD6YQYc=

Other notes

samrose/nix-postgres

ErrorLooks like something went wrong!

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Error
Looks like something went wrong!

Packages