Repository files navigation

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 build PostgreSQL with extensions locally:

# Build PostgreSQL 15 with extensionsnix build .#psql_15/bin# Build PostgreSQL 17nix build .#psql_17/bin# Build a specific extensionnix build .#psql_17/exts/pg_graphql

# Run all testsnix 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 15docker build -f Dockerfile-15 -t supabase-postgres:15.# Build Docker image for PostgreSQL 17docker build -f Dockerfile-17 -t supabase-postgres:17.

Now that you understand the basics of Supabase Postgres:

• Check theInstallation Guide for deployment options
• Explore theExtension Documentation to learn about available extensions
• ReviewContributing Guidelines if you want to contribute
• Join theSupabase Community for questions and discussions

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

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

• ✅ Postgrespostgresql-15.14
• ✅ Postgrespostgresql-17.6
• ✅ Postgresorioledb-postgresql-17_11
• ✅ Ubuntu 24.04 (Noble Numbat).
• ✅wal_level = logical andmax_replication_slots = 5. Ready for replication.
• ✅Large Systems Extensions. Enabled for ARM images.

This is only available for our AWS EC2

See all installation instructions in therepo wiki.

• 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 atSupabase.
• 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.