gem-hunter

This guide covers getting up and running with Supabase Postgres. After reading this guide, you will understand:

• What Supabase Postgres provides and why you might want to use it
• How the project is organized and what each directory contains
• How to build and run Postgres with extensions locally
• The basics of working with the extension ecosystem

Supabase Postgres is a batteries-included PostgreSQL distribution that provides unmodified PostgreSQL with a curated set of the most useful extensions pre-installed. Think of it as PostgreSQL with superpowers - you get the reliability and power of standard PostgreSQL, plus immediate access to extensions for tasks like:

• Full-text search and indexing
• Geospatial data processing
• Time-series data management
• JSON validation and GraphQL support
• Cryptography and security
• Message queuing
• And much more

The goal is simple: make it fast and easy to get started with a production-ready PostgreSQL setup without having to hunt down, compile, and configure dozens of extensions yourself.

Supabase Postgres follows these core principles:

1. Unmodified PostgreSQL - We don't fork or modify PostgreSQL itself. You get standard PostgreSQL with extensions.
2. Curated Extensions - We include well-maintained, production-tested extensions that solve real problems.
3. Multi-version Support - Currently supporting PostgreSQL 15, 17, and OrioleDB-17.
4. Ready for Production - Configured with sensible defaults for replication, security, and performance.
5. Open Source - Everything is open source and can be self-hosted.

Here's a comprehensive overview of the project's directory structure:

Extensions are the superpower of PostgreSQL. They add functionality without modifying the core database. Supabase Postgres includes dozens of pre-built extensions covering:

• Data Types & Validation - pg_jsonschema, pg_hashids
• Search & Indexing - pgroonga, rum, hypopg
• Geospatial - PostGIS, pgrouting
• Time-series - TimescaleDB
• Security - pgsodium, vault, pgaudit
• Development - pgtap, plpgsql_check
• And many more...

The project supports multiple PostgreSQL versions simultaneously:

• PostgreSQL 15 - Stable, battle-tested version
• PostgreSQL 17 - Latest features and improvements
• OrioleDB-17 - Experimental storage engine for PostgreSQL 17

Each version has its own set of compatible extensions defined in the Nix build system.

The project uses Nix as its build system, which provides:

• Reproducible Builds - Same input always produces the same output
• Declarative Configuration - Define what you want, not how to build it
• Dependency Management - Automatic handling of complex dependency trees
• Cross-platform Support - Build for Linux, macOS, and more

To skip hours of building and download packages instead, start using the Supabase Postgres Nix binary cache: nix/docs/binary-cache.md.

To build PostgreSQL with extensions locally:

# Build PostgreSQL 15 with extensions
nix build .#psql_15/bin

# Build PostgreSQL 17
nix build .#psql_17/bin

# Build a specific extension
nix build .#psql_17/exts/pg_graphql

# Run all tests
nix flake check -L

# Run specific test suite (for macos apple silicon for example)
nix build .#checks.aarch64-darwin.psql_17 -L

# Build Docker image for PostgreSQL 15
docker build -f Dockerfile-15 -t supabase-postgres:15 .

# Build Docker image for PostgreSQL 17
docker build -f Dockerfile-17 -t supabase-postgres:17 .

Now that you understand the basics of Supabase Postgres:

• Check the build guide and Docker docs for deployment options
• Explore the Extension Documentation to learn about available extensions
• Review Contributing Guidelines if you want to contribute
• Join the Supabase Community for questions and discussions

• GitHub Issues - For bugs and feature requests
• Discussions - For questions and general discussion
• nix/docs - For detailed documentation
• Discord - For real-time chat with the community

This is the same PostgreSQL build that powers Supabase, battle-tested in production by over one million projects.

• ✅ Postgres postgresql-15.19
• ✅ Postgres postgresql-17.11
• ✅ Postgres orioledb-postgresql-17_22
• ✅ Ubuntu 24.04 (Noble Numbat).
• ✅ wal_level = logical and max_replication_slots = 5. Ready for replication.
• ✅ Large Systems Extensions. Enabled for ARM images.

Extension versions are pinned per PostgreSQL major version in nix/ext/versions.json.

This is only available for our AWS EC2

See the documentation index for installation instructions.

• Make it fast and simple to get started with Postgres.
• Show off a few of Postgres' most exciting features.
• This is the same build we offer at Supabase.
• Open a github issue if you have a feature request

The PostgreSQL License. We realize that licensing is tricky since we are bundling all the various plugins. If we have infringed on any license, let us know and we will make the necessary changes (or remove that extension from this repo).

We are building the features of Firebase using enterprise-grade, open source products. We support existing communities wherever possible, and if the products don’t exist we build them and open source them ourselves.