Skip to content

Commit 18473b4

Browse files
samrosesamrose
authored
docs: getting started guide in README (#1805)
* docs: getting started guide * docs: inline getting started into README * docs: run readme update for versions
1 parent 5da417f commit 18473b4

File tree

1 file changed

+195
-15
lines changed

1 file changed

+195
-15
lines changed

‎README.md‎

Lines changed: 195 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,185 @@
1-
# Postgres + goodies
1+
# Getting Started with Supabase Postgres
2+
3+
This guide covers getting up and running with Supabase Postgres. After reading this guide, you will understand:
4+
5+
* What Supabase Postgres provides and why you might want to use it
6+
* How the project is organized and what each directory contains
7+
* How to build and run Postgres with extensions locally
8+
* The basics of working with the extension ecosystem
9+
10+
---
11+
12+
## What is Supabase Postgres?
13+
14+
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:
15+
16+
* Full-text search and indexing
17+
* Geospatial data processing
18+
* Time-series data management
19+
* JSON validation and GraphQL support
20+
* Cryptography and security
21+
* Message queuing
22+
* And much more
23+
24+
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.
25+
26+
## Philosophy
27+
28+
Supabase Postgres follows these core principles:
29+
30+
1. **Unmodified PostgreSQL** - We don't fork or modify PostgreSQL itself. You get standard PostgreSQL with extensions.
31+
2. **Curated Extensions** - We include well-maintained, production-tested extensions that solve real problems.
32+
3. **Multi-version Support** - Currently supporting PostgreSQL 15, 17, and OrioleDB-17.
33+
4. **Ready for Production** - Configured with sensible defaults for replication, security, and performance.
34+
5. **Open Source** - Everything is open source and can be self-hosted.
35+
36+
## Directory Structure
37+
38+
Here's a comprehensive overview of the project's directory structure:
39+
40+
| File/Directory | Purpose |
41+
| -------------- | ------- |
42+
| **nix/** | Core build system directory containing all Nix expressions for building PostgreSQL and extensions |
43+
| nix/postgresql/ | PostgreSQL version configurations, patches, and base package definitions |
44+
| nix/ext/ | Individual extension package definitions and build configurations |
45+
| nix/ext/wrappers/ | Wrapper scripts and utilities for extensions |
46+
| nix/ext/tests/ | Extension-specific test suites |
47+
| nix/overlays/ | Nix overlays for customizing and overriding package definitions |
48+
| nix/tools/ | Build tools, utilities, and helper scripts |
49+
| nix/docker/ | Docker image build definitions using Nix |
50+
| nix/tests/ | Comprehensive integration test suites for validating builds |
51+
| nix/tests/smoke/ | Quick smoke tests for basic functionality |
52+
| nix/tests/migrations/ | Migration and upgrade test scenarios |
53+
| nix/tests/expected/ | Expected `pg_regress` test outputs for validation |
54+
| nix/tests/sql/ | SQL test scripts that are run in `pg_regress` tests |
55+
| nix/docs/ | Build system documentation |
56+
| **ansible/** | Infrastructure as Code for server configuration and deployment of production hosted AWS AMI image |
57+
| ansible/playbook.yml | Main Ansible playbook for PostgreSQL/PostgREST/pgbouncer/Auth server setup |
58+
| ansible/tasks/ | Modular Ansible tasks for specific configuration steps |
59+
| ansible/files/ | Static files, scripts, and templates used by Ansible |
60+
| ansible/vars.yml | AMI version tracking, legacy package version tracking |
61+
| **migrations/** | Database migration management and upgrade tools |
62+
| migrations/db/ | Database schema migrations |
63+
| migrations/db/migrations/ | Individual migration files |
64+
| migrations/db/init-scripts/ | Database initialization scripts |
65+
| migrations/tests/ | Migration testing infrastructure |
66+
| migrations/tests/database/ | Database-specific migration tests |
67+
| migrations/tests/storage/ | Storage-related migration tests |
68+
| migrations/tests/extensions/ | Extension migration tests |
69+
| **docker/** | Container definitions and Docker-related files |
70+
| docker/nix/ | Nix-based Docker build configurations |
71+
| Dockerfile-15 | Docker image definition for PostgreSQL 15 |
72+
| Dockerfile-17 | Docker image definition for PostgreSQL 17 |
73+
| **tests/** | Integration and system tests |
74+
| testinfra/ | Infrastructure tests using pytest framework |
75+
| tests/ | General integration test suites |
76+
| **scripts/** | Utility scripts for development and deployment |
77+
| **docs/** | Additional documentation, images, and resources |
78+
| **ebssurrogate/** | AWS EBS surrogate building for AMI creation |
79+
| **http/** | HTTP-related configurations and files |
80+
| **rfcs/** | Request for Comments - design documents and proposals |
81+
| **db/** | Database-related utilities and configurations |
82+
| **.github/** | GitHub-specific configurations (Actions, templates, etc.) |
83+
| **Root Config Files** | |
84+
| .gitignore | Git ignore patterns |
85+
| .envrc.recommended | Recommended environment variables for development |
86+
| ansible.cfg | Ansible configuration |
87+
| amazon-arm64-nix.pkr.hcl | Packer configuration for AWS ARM64 builds |
88+
| common-nix.vars.pkr.hcl | Common Packer variables |
89+
| development-arm.vars.pkr.hcl | ARM development environment variables |
90+
| CONTRIBUTING.md | Contribution guidelines |
91+
| README.md | Main project documentation |
92+
93+
## Key Concepts
94+
95+
### Extensions
96+
97+
Extensions are the superpower of PostgreSQL. They add functionality without modifying the core database. Supabase Postgres includes dozens of pre-built extensions covering:
98+
99+
* **Data Types & Validation** - pg_jsonschema, pg_hashids
100+
* **Search & Indexing** - pgroonga, rum, hypopg
101+
* **Geospatial** - PostGIS, pgrouting
102+
* **Time-series** - TimescaleDB
103+
* **Security** - pgsodium, vault, pgaudit
104+
* **Development** - pgtap, plpgsql_check
105+
* **And many more...**
106+
107+
### Multi-version Support
108+
109+
The project supports multiple PostgreSQL versions simultaneously:
110+
111+
* **PostgreSQL 15** - Stable, battle-tested version
112+
* **PostgreSQL 17** - Latest features and improvements
113+
* **OrioleDB-17** - Experimental storage engine for PostgreSQL 17
114+
115+
Each version has its own set of compatible extensions defined in the Nix build system.
116+
117+
### Build System (Nix)
118+
119+
The project uses Nix as its build system, which provides:
120+
121+
* **Reproducible Builds** - Same input always produces the same output
122+
* **Declarative Configuration** - Define what you want, not how to build it
123+
* **Dependency Management** - Automatic handling of complex dependency trees
124+
* **Cross-platform Support** - Build for Linux, macOS, and more
125+
126+
## Common Tasks
127+
128+
### Building Locally
129+
130+
To build PostgreSQL with extensions locally:
131+
132+
```bash
133+
# Build PostgreSQL 15 with extensions
134+
nix build .#psql_15/bin
135+
136+
# Build PostgreSQL 17
137+
nix build .#psql_17/bin
138+
139+
# Build a specific extension
140+
nix build .#psql_17/exts/pg_graphql
141+
```
142+
143+
### Running Tests
144+
145+
```bash
146+
# Run all tests
147+
nix flake check -L
148+
149+
# Run specific test suite (for macos apple silicon for example)
150+
nix build .#checks.aarch64-darwin.psql_17 -L
151+
```
152+
153+
### Creating Docker Images
154+
155+
```bash
156+
# Build Docker image for PostgreSQL 15
157+
docker build -f Dockerfile-15 -t supabase-postgres:15 .
158+
159+
# Build Docker image for PostgreSQL 17
160+
docker build -f Dockerfile-17 -t supabase-postgres:17 .
161+
```
162+
163+
## Next Steps
164+
165+
Now that you understand the basics of Supabase Postgres:
166+
167+
* Check the [Installation Guide](https://github.com/supabase/postgres/wiki) for deployment options
168+
* Explore the [Extension Documentation](#) to learn about available extensions
169+
* Review [Contributing Guidelines](CONTRIBUTING.md) if you want to contribute
170+
* Join the [Supabase Community](https://github.com/supabase/postgres/discussions) for questions and discussions
171+
172+
## Getting Help
173+
174+
* **GitHub Issues** - For bugs and feature requests
175+
* **Discussions** - For questions and general discussion
176+
* **Wiki** - For detailed documentation
177+
* **Discord** - For real-time chat with the community
178+
179+
---
180+
181+
This is the same PostgreSQL build that powers [Supabase](https://supabase.io), battle-tested in production by over one million projects.
2182

3-
Unmodified Postgres with some useful plugins. Our goal with this repo is not to modify Postgres, but to provide some of the most common extensions with a one-click install.
4183

5184
## Primary Features
6185
- ✅ Postgres [postgresql-15.14](https://www.postgresql.org/docs/15/index.html)
@@ -14,7 +193,8 @@ Unmodified Postgres with some useful plugins. Our goal with this repo is not to
14193
### PostgreSQL 15 Extensions
15194
| Extension | Version | Description |
16195
| ------------- | :-------------: | ------------- |
17-
| [hypopg](https://github.com/HypoPG/hypopg/archive/refs/tags/1.4.1.tar.gz) | [1.4.1](https://github.com/HypoPG/hypopg/archive/refs/tags/1.4.1.tar.gz) | Hypothetical Indexes for PostgreSQL |
196+
| [http]() | [1.6]() | |
197+
| [hypopg]() | [1.4.1]() | |
18198
| [index_advisor]() | [0.2.0]() | |
19199
| [pg-safeupdate](https://github.com/eradman/pg-safeupdate/archive/1.4.tar.gz) | [1.4](https://github.com/eradman/pg-safeupdate/archive/1.4.tar.gz) | A simple extension to PostgreSQL that requires criteria for UPDATE and DELETE |
20200
| [pg_cron]() | [1.6.4]() | Run Cron jobs through PostgreSQL (multi-version compatible) |
@@ -31,15 +211,14 @@ Unmodified Postgres with some useful plugins. Our goal with this repo is not to
31211
| [pgmq](https://github.com/tembo-io/pgmq/archive/v1.4.4.tar.gz) | [1.4.4](https://github.com/tembo-io/pgmq/archive/v1.4.4.tar.gz) | A lightweight message queue. Like AWS SQS and RSMQ but on Postgres. |
32212
| [pgroonga](https://packages.groonga.org/source/pgroonga/pgroonga-3.2.5.tar.gz) | [3.2.5](https://packages.groonga.org/source/pgroonga/pgroonga-3.2.5.tar.gz) | A PostgreSQL extension to use Groonga as the index |
33213
| [pgrouting](https://github.com/pgRouting/pgrouting/archive/v3.4.1.tar.gz) | [3.4.1](https://github.com/pgRouting/pgrouting/archive/v3.4.1.tar.gz) | A PostgreSQL/PostGIS extension that provides geospatial routing functionality |
34-
| [pgsodium](https://github.com/michelp/pgsodium/archive/refs/tags/v3.1.8.tar.gz) | [3.1.8](https://github.com/michelp/pgsodium/archive/refs/tags/v3.1.8.tar.gz) | Modern cryptography for PostgreSQL |
35-
| [pgsql-http](https://github.com/pramsey/pgsql-http/archive/refs/tags/v1.6.1.tar.gz) | [1.6.1](https://github.com/pramsey/pgsql-http/archive/refs/tags/v1.6.1.tar.gz) | HTTP client for Postgres |
214+
| [pgsodium]() | [3.1.8]() | |
36215
| [pgtap](https://github.com/theory/pgtap/archive/v1.2.0.tar.gz) | [1.2.0](https://github.com/theory/pgtap/archive/v1.2.0.tar.gz) | A unit testing framework for PostgreSQL |
37216
| [plpgsql-check](https://github.com/okbob/plpgsql_check/archive/v2.7.11.tar.gz) | [2.7.11](https://github.com/okbob/plpgsql_check/archive/v2.7.11.tar.gz) | Linter tool for language PL/pgSQL |
38217
| [plv8](https://github.com/plv8/plv8/archive/v3.1.10.tar.gz) | [3.1.10](https://github.com/plv8/plv8/archive/v3.1.10.tar.gz) | V8 Engine Javascript Procedural Language add-on for PostgreSQL |
39218
| [postgis](https://download.osgeo.org/postgis/source/postgis-3.3.7.tar.gz) | [3.3.7](https://download.osgeo.org/postgis/source/postgis-3.3.7.tar.gz) | Geographic Objects for PostgreSQL |
40-
| [rum](https://github.com/postgrespro/rum/archive/1.3.14.tar.gz) | [1.3.14](https://github.com/postgrespro/rum/archive/1.3.14.tar.gz) | Full text search index method for PostgreSQL |
219+
| [rum]() | [1.3]() | |
41220
| [supautils](https://github.com/supabase/supautils/archive/refs/tags/v2.9.4.tar.gz) | [2.9.4](https://github.com/supabase/supautils/archive/refs/tags/v2.9.4.tar.gz) | PostgreSQL extension for enhanced security |
42-
| [timescaledb-apache](https://github.com/timescale/timescaledb/archive/2.16.1.tar.gz) | [2.16.1](https://github.com/timescale/timescaledb/archive/2.16.1.tar.gz) | Scales PostgreSQL for time-series data via automatic partitioning across time and space |
221+
| [timescaledb]() | [2.9.1]() | |
43222
| [vault](https://github.com/supabase/vault/archive/refs/tags/v0.3.1.tar.gz) | [0.3.1](https://github.com/supabase/vault/archive/refs/tags/v0.3.1.tar.gz) | Store encrypted secrets in PostgreSQL |
44223
| [vector]() | [0.8.0]() | |
45224
| [wal2json](https://github.com/eulerto/wal2json/archive/wal2json_2_6.tar.gz) | [2_6](https://github.com/eulerto/wal2json/archive/wal2json_2_6.tar.gz) | PostgreSQL JSON output plugin for changeset extraction |
@@ -48,7 +227,8 @@ Unmodified Postgres with some useful plugins. Our goal with this repo is not to
48227
### PostgreSQL 17 Extensions
49228
| Extension | Version | Description |
50229
| ------------- | :-------------: | ------------- |
51-
| [hypopg](https://github.com/HypoPG/hypopg/archive/refs/tags/1.4.1.tar.gz) | [1.4.1](https://github.com/HypoPG/hypopg/archive/refs/tags/1.4.1.tar.gz) | Hypothetical Indexes for PostgreSQL |
230+
| [http]() | [1.6]() | |
231+
| [hypopg]() | [1.4.1]() | |
52232
| [index_advisor]() | [0.2.0]() | |
53233
| [pg-safeupdate](https://github.com/eradman/pg-safeupdate/archive/1.4.tar.gz) | [1.4](https://github.com/eradman/pg-safeupdate/archive/1.4.tar.gz) | A simple extension to PostgreSQL that requires criteria for UPDATE and DELETE |
54234
| [pg_cron]() | [1.6.4]() | Run Cron jobs through PostgreSQL (multi-version compatible) |
@@ -65,12 +245,11 @@ Unmodified Postgres with some useful plugins. Our goal with this repo is not to
65245
| [pgmq](https://github.com/tembo-io/pgmq/archive/v1.4.4.tar.gz) | [1.4.4](https://github.com/tembo-io/pgmq/archive/v1.4.4.tar.gz) | A lightweight message queue. Like AWS SQS and RSMQ but on Postgres. |
66246
| [pgroonga](https://packages.groonga.org/source/pgroonga/pgroonga-3.2.5.tar.gz) | [3.2.5](https://packages.groonga.org/source/pgroonga/pgroonga-3.2.5.tar.gz) | A PostgreSQL extension to use Groonga as the index |
67247
| [pgrouting](https://github.com/pgRouting/pgrouting/archive/v3.4.1.tar.gz) | [3.4.1](https://github.com/pgRouting/pgrouting/archive/v3.4.1.tar.gz) | A PostgreSQL/PostGIS extension that provides geospatial routing functionality |
68-
| [pgsodium](https://github.com/michelp/pgsodium/archive/refs/tags/v3.1.8.tar.gz) | [3.1.8](https://github.com/michelp/pgsodium/archive/refs/tags/v3.1.8.tar.gz) | Modern cryptography for PostgreSQL |
69-
| [pgsql-http](https://github.com/pramsey/pgsql-http/archive/refs/tags/v1.6.1.tar.gz) | [1.6.1](https://github.com/pramsey/pgsql-http/archive/refs/tags/v1.6.1.tar.gz) | HTTP client for Postgres |
248+
| [pgsodium]() | [3.1.8]() | |
70249
| [pgtap](https://github.com/theory/pgtap/archive/v1.2.0.tar.gz) | [1.2.0](https://github.com/theory/pgtap/archive/v1.2.0.tar.gz) | A unit testing framework for PostgreSQL |
71250
| [plpgsql-check](https://github.com/okbob/plpgsql_check/archive/v2.7.11.tar.gz) | [2.7.11](https://github.com/okbob/plpgsql_check/archive/v2.7.11.tar.gz) | Linter tool for language PL/pgSQL |
72251
| [postgis](https://download.osgeo.org/postgis/source/postgis-3.3.7.tar.gz) | [3.3.7](https://download.osgeo.org/postgis/source/postgis-3.3.7.tar.gz) | Geographic Objects for PostgreSQL |
73-
| [rum](https://github.com/postgrespro/rum/archive/1.3.14.tar.gz) | [1.3.14](https://github.com/postgrespro/rum/archive/1.3.14.tar.gz) | Full text search index method for PostgreSQL |
252+
| [rum]() | [1.3]() | |
74253
| [supautils](https://github.com/supabase/supautils/archive/refs/tags/v2.9.4.tar.gz) | [2.9.4](https://github.com/supabase/supautils/archive/refs/tags/v2.9.4.tar.gz) | PostgreSQL extension for enhanced security |
75254
| [vault](https://github.com/supabase/vault/archive/refs/tags/v0.3.1.tar.gz) | [0.3.1](https://github.com/supabase/vault/archive/refs/tags/v0.3.1.tar.gz) | Store encrypted secrets in PostgreSQL |
76255
| [vector]() | [0.8.0]() | |
@@ -80,7 +259,8 @@ Unmodified Postgres with some useful plugins. Our goal with this repo is not to
80259
### PostgreSQL orioledb-17 Extensions
81260
| Extension | Version | Description |
82261
| ------------- | :-------------: | ------------- |
83-
| [hypopg](https://github.com/HypoPG/hypopg/archive/refs/tags/1.4.1.tar.gz) | [1.4.1](https://github.com/HypoPG/hypopg/archive/refs/tags/1.4.1.tar.gz) | Hypothetical Indexes for PostgreSQL |
262+
| [http]() | [1.6]() | |
263+
| [hypopg]() | [1.4.1]() | |
84264
| [index_advisor]() | [0.2.0]() | |
85265
| [orioledb](https://github.com/orioledb/orioledb/archive/beta12.tar.gz) | [orioledb](https://github.com/orioledb/orioledb/archive/beta12.tar.gz) | orioledb |
86266
| [pg-safeupdate](https://github.com/eradman/pg-safeupdate/archive/1.4.tar.gz) | [1.4](https://github.com/eradman/pg-safeupdate/archive/1.4.tar.gz) | A simple extension to PostgreSQL that requires criteria for UPDATE and DELETE |
@@ -98,12 +278,11 @@ Unmodified Postgres with some useful plugins. Our goal with this repo is not to
98278
| [pgmq](https://github.com/tembo-io/pgmq/archive/v1.4.4.tar.gz) | [1.4.4](https://github.com/tembo-io/pgmq/archive/v1.4.4.tar.gz) | A lightweight message queue. Like AWS SQS and RSMQ but on Postgres. |
99279
| [pgroonga](https://packages.groonga.org/source/pgroonga/pgroonga-3.2.5.tar.gz) | [3.2.5](https://packages.groonga.org/source/pgroonga/pgroonga-3.2.5.tar.gz) | A PostgreSQL extension to use Groonga as the index |
100280
| [pgrouting](https://github.com/pgRouting/pgrouting/archive/v3.4.1.tar.gz) | [3.4.1](https://github.com/pgRouting/pgrouting/archive/v3.4.1.tar.gz) | A PostgreSQL/PostGIS extension that provides geospatial routing functionality |
101-
| [pgsodium](https://github.com/michelp/pgsodium/archive/refs/tags/v3.1.8.tar.gz) | [3.1.8](https://github.com/michelp/pgsodium/archive/refs/tags/v3.1.8.tar.gz) | Modern cryptography for PostgreSQL |
102-
| [pgsql-http](https://github.com/pramsey/pgsql-http/archive/refs/tags/v1.6.1.tar.gz) | [1.6.1](https://github.com/pramsey/pgsql-http/archive/refs/tags/v1.6.1.tar.gz) | HTTP client for Postgres |
281+
| [pgsodium]() | [3.1.8]() | |
103282
| [pgtap](https://github.com/theory/pgtap/archive/v1.2.0.tar.gz) | [1.2.0](https://github.com/theory/pgtap/archive/v1.2.0.tar.gz) | A unit testing framework for PostgreSQL |
104283
| [plpgsql-check](https://github.com/okbob/plpgsql_check/archive/v2.7.11.tar.gz) | [2.7.11](https://github.com/okbob/plpgsql_check/archive/v2.7.11.tar.gz) | Linter tool for language PL/pgSQL |
105284
| [postgis](https://download.osgeo.org/postgis/source/postgis-3.3.7.tar.gz) | [3.3.7](https://download.osgeo.org/postgis/source/postgis-3.3.7.tar.gz) | Geographic Objects for PostgreSQL |
106-
| [rum](https://github.com/postgrespro/rum/archive/1.3.14.tar.gz) | [1.3.14](https://github.com/postgrespro/rum/archive/1.3.14.tar.gz) | Full text search index method for PostgreSQL |
285+
| [rum]() | [1.3]() | |
107286
| [supautils](https://github.com/supabase/supautils/archive/refs/tags/v2.9.4.tar.gz) | [2.9.4](https://github.com/supabase/supautils/archive/refs/tags/v2.9.4.tar.gz) | PostgreSQL extension for enhanced security |
108287
| [vault](https://github.com/supabase/vault/archive/refs/tags/v0.3.1.tar.gz) | [0.3.1](https://github.com/supabase/vault/archive/refs/tags/v0.3.1.tar.gz) | Store encrypted secrets in PostgreSQL |
109288
| [vector]() | [0.8.0]() | |
@@ -118,6 +297,7 @@ Unmodified Postgres with some useful plugins. Our goal with this repo is not to
118297
| [PostgREST](https://postgrest.org/en/stable/) | [v13.0.4](https://github.com/PostgREST/postgrest/releases/tag/v13.0.4) | Instantly transform your database into an RESTful API. |
119298
| [WAL-G](https://github.com/wal-g/wal-g#wal-g) | [v2.0.1](https://github.com/wal-g/wal-g/releases/tag/v2.0.1) | Tool for physical database backup and recovery. | -->
120299

300+
121301
## Install
122302

123303
See all installation instructions in the [repo wiki](https://github.com/supabase/postgres/wiki).

0 commit comments

Comments
 (0)