Skip to content

Commit d7bf2a5

Browse files
samrosesamrose
committed
docs: getting started guide
1 parent 5da417f commit d7bf2a5

File tree

2 files changed

+185
-0
lines changed

2 files changed

+185
-0
lines changed

‎GETTING_STARTED.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
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+
Remember: This is the same PostgreSQL build that powers [Supabase](https://supabase.io), battle-tested in production by thousands of projects.

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,10 @@ Unmodified Postgres with some useful plugins. Our goal with this repo is not to
118118
| [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. |
119119
| [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. | -->
120120

121+
## Getting Started
122+
123+
For a comprehensive guide to understanding and working with this project, see our [Getting Started Guide](GETTING_STARTED.md).
124+
121125
## Install
122126

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

0 commit comments

Comments
 (0)