Guide · Open source
How to use PostgREST: set up a REST API on PostgreSQL
Updated · written with AI from the project's own documentation and checked against our catalogue data
PostgREST is an open-source server that reads an existing PostgreSQL database and serves a RESTful HTTP API from it, so you can avoid writing custom API code for common create, read, update and delete operations. This guide is for developers who already have a PostgreSQL database and want an HTTP API on top of it. By the end you will know what you need before starting, how to get the program running, and how authentication, authorization, versioning and data integrity fit together.
PostgRESTPostgREST/postgrest · ★ 27.7k · MIT Install options & downloads Quick start
- 1Check your database. Confirm you have a running PostgreSQL database, since PostgREST only serves APIs from PostgreSQL.
- 2Install PostgREST. Follow the install guide for your platform or use the Docker option described in the documentation.
- 3Confirm the install. Run postgrest --help to see the available options.
- 4Set up database roles. Define the roles and permissions in your database, since authorization relies on them.
- 5Configure JWT authentication. Set up JSON Web Token authentication as described in the authentication docs.
- 6Expose tables and views. Use schemas and views to decide what the API exposes and to version it.
What you need before you start
PostgREST only works with PostgreSQL. The README describes it as a way to serve an API from any existing PostgreSQL database, so you need a running database first. Setup also involves database roles, JWT configuration and some SQL familiarity.
- A PostgreSQL database
- Familiarity with SQL and database roles
- Basic understanding of JSON Web Tokens if you plan to use authentication
Install PostgREST on your platform
The README points to the install documentation for your platform. You can also run PostgREST with Docker, as described in the same install guide. Once installed, check that the program is available by asking for its help output.
- Follow the install guide at docs.postgrest.org for your operating system, or use the Docker option described there.
- Confirm the install by running the help command below.
postgrest --helpUnderstand how authentication and authorization work
PostgREST handles authentication through JSON Web Tokens. Authorization is delegated to the role information defined in your database, so the database is the single declarative source of truth for security. When handling a request, the server assumes the identity of the authenticated user, and for the duration of that connection it cannot do anything that user could not do themselves.
Other forms of authentication can be built on top of the JWT primitive. The README refers you to the authentication docs for details.
- Authentication: JSON Web Tokens
- Authorization: database roles and their permissions
- Database rules act as the access control layer
Use database schemas and views for versioning
PostgREST handles API versioning through database schemas. You can expose tables and views while keeping the underlying tables flexible. Underlying tables can be superseded and hidden behind public-facing views, which helps the API stay stable as the schema changes.
- Create a schema for each API version you want to expose.
- Put public-facing views in front of underlying tables.
Rely on the database for validation and integrity
PostgREST expects you to put declarative constraints directly into the database rather than in an Object Relational Mapper or custom imperative code. According to the README, this means no application can corrupt your data, including the API server. The server also enforces safeguards such as idempotent PUT requests.
The README links to examples of PostgreSQL constraints and to the API guide for further detail.
- Use PostgreSQL constraints for validation.
- Expect PUT requests to be idempotent, as the README describes.
Read the API docs and OpenAPI output
PostgREST uses the OpenAPI standard to generate documentation for your API. The README notes that you can render this with a tool such as Swagger-UI to get interactive documentation against the live server. Row counts are reported and limited through HTTP range headers.
- Generated OpenAPI documentation reflects the API.
- Swagger-UI can render interactive docs against the live server.
- Row counts and limits use range headers.
What people use it for
- Serving a REST API for an existing PostgreSQL application without writing CRUD endpoints by hand
- Keeping access control in database roles so the API and database share one set of rules
- Versioning an API by exposing public views over changing underlying tables
- Building an API where constraints and validation live in the database itself
Frequently asked questions
Is PostgREST free to use?
PostgREST is released under the MIT licence, according to the project summary. The README also asks for donations via Patreon to support ongoing maintenance, but donating is optional.
What do I need to run PostgREST?
You need a PostgreSQL database. Setup requires database roles, JWT configuration and familiarity with SQL, so it is best suited to developers rather than non-developers.
How do I install PostgREST?
The README directs you to the install guide for your platform on docs.postgrest.org, and notes that Docker is also an option. After installing, run postgrest --help to confirm it works.
How does PostgREST handle login and permissions?
Authentication uses JSON Web Tokens. Authorization relies on the roles defined in your database, and the server acts with the permissions of the authenticated user.
Does PostgREST work with databases other than PostgreSQL?
No. The README describes PostgREST only for PostgreSQL databases.
How does PostgREST compare to Hasura, Supabase, PostGraphile or pREST?
These are comparable projects, according to the project summary. PostgREST suits teams that want database rules and permissions as the source of truth and little custom application logic in the API layer. Teams needing heavy custom logic in the API may find it less suitable.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
PostgREST suits developers who already run PostgreSQL and want a quick, standards-based HTTP API driven by database roles, schemas and constraints. It is a poor fit for non-PostgreSQL projects, teams that need a lot of custom application logic in the API layer, or people who are not comfortable with SQL and JWT setup.
Install options & downloads