supabase / postgres

# Getting Started with Supabase Postgres
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
---
## What is Supabase Postgres?
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.
## Philosophy
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.
## Directory Structure
Here's a comprehensive overview of the project's directory structure:
| File/Directory | Purpose |
| -------------- | ------- |
| **nix/** | Core build system directory containing all Nix expressions for building PostgreSQL and extensions |
| nix/postgresql/ | PostgreSQL version configurations, patches, and base package definitions |
| nix/ext/ | Individual extension package definitions and build configurations |
| nix/ext/wrappers/ | Wrapper scripts and utilities for extensions |
| nix/ext/tests/ | Extension-specific integration test suites implemented using nixos-test|
| nix/overlays/ | Nix overlays for customizing and overriding package definitions |
| nix/tools/ | Build tools, utilities, and helper scripts |
| nix/docker/ | Docker image build definitions using Nix |
| nix/tests/ | postgres specific test suites for validating builds, including pg_regress tests |
| nix/tests/smoke/ | Quick smoke tests for basic functionality |
| nix/tests/migrations/ | Migration and upgrade test scenarios |
| nix/tests/expected/ | Expected `pg_regress` test outputs for validation |
| nix/tests/sql/ | SQL test scripts that are run in `pg_regress` tests |
| nix/docs/ | Build system documentation |
| **ansible/** | Infrastructure as Code for server configuration and deployment of production hos