Repository files navigation

PostgREST serves a fully RESTful API from any existing PostgreSQLdatabase. It provides a cleaner, more standards-compliant, fasterAPI than you are likely to write from scratch.

Big thanks to our sponsors! You can join them by supporting PostgREST onPatreon.

1. Download the binary (latest release)for your platform.

2. Invoke for help:

   postgrest --help

Latest documentation is atpostgrest.org. You can contribute to the docs inPostgREST/postgrest/docs.

TLDR; subsecond response times for up to 2000 requests/sec on Herokufree tier. If you're used to servers written in interpreted languages,prepare to be pleasantly surprised by PostgREST performance.

Three factors contribute to the speed. First the server is writteninHaskell using theWarpHTTP server (aka a compiled language with lightweight threads).Next it delegates as much calculation as possible to the databaseincluding

• Serializing JSON responses directly in SQL
• Data validation
• Authorization
• Combined row counting and retrieval
• Data post in single command (returning *)

Finally it uses the database efficiently with theHasql libraryby

• Keeping a pool of db connections
• Using the PostgreSQL binary protocol
• Being stateless to allow horizontal scaling

PostgRESThandlesauthentication (via JSON WebTokens) and delegates authorization to the role information defined inthe database. This ensures there is a single declarative source of truthfor security. When dealing with the database the server assumes theidentity of the currently authenticated user, and for the duration ofthe connection cannot do anything the user themselves couldn't. Otherforms of authentication can be built on top of the JWT primitive. Seethe docs for more information.

A robust long-lived API needs the freedom to exist in multipleversions. PostgREST does versioning through database schemas. Thisallows you to expose tables and views without making the app brittle.Underlying tables can be superseded and hidden behind public facingviews.

PostgREST uses theOpenAPI standard togenerate up-to-date documentation for APIs. You can use a tool likeSwagger-UI to renderinteractive documentation for demo requests against the live API server.

This project uses HTTP to communicate other metadata as well. Forinstance the number of rows returned by an endpoint is reported by -and limited with - range headers. More aboutthat.

Rather than relying on an Object Relational Mapper and customimperative coding, this system requires you put declarative constraintsdirectly into your database. Hence no application can corrupt yourdata (including your API server).

The PostgREST exposes HTTP interface with safeguards to preventsurprises, such as enforcing idempotent PUT requests.

See examples ofPostgreSQLconstraintsand theAPI guide.

You can help PostgREST ongoing maintenance and development by making a regular donation through Patreonhttps://www.patreon.com/postgrest

Every donation will be spent on making PostgREST better for the whole community.

The PostgREST organization is grateful to:

• The projectsponsors and backers who support PostgREST's development.
• The projectcontributors who have improved PostgREST immensely with their codeand good judgement. See more details in thechangelog.

The cool logo came fromMikey Casalaina.