Skip to content
REST API for any Postgres database
Haskell Nix Shell Makefile
Branch: master
Clone or download

Latest commit

monacoremo Nixify io and memory tests (#1538)
* Include tests for io and memory in the Nix environment.
* include spec tests in nix-shell by default
* install the io and memory tests in CI
Latest commit 69b09e3 May 28, 2020

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Nixify io and memory tests (#1538) May 28, 2020
.github Recommend doing make check pre-commit Sep 30, 2019
main Update to protolude 0.3.0 Apr 23, 2020
nix Nixify io and memory tests (#1538) May 28, 2020
src/PostgREST Bump nixpkgs and simplify/clean up nix setup (#1529) May 21, 2020
static Add CYBERTEC as Sponsor Jun 20, 2019
test Nixify io and memory tests (#1538) May 28, 2020
.cirrus.yml Fix Dockerfile May 18, 2020
.gitattributes Use union merge strategy on changelog (#859) Apr 8, 2017
.gitignore Nixify io and memory tests (#1538) May 28, 2020
.stylish-haskell.yaml Update stylish haskell config; apply all; add CI config (#1299) May 23, 2019
.travis.yml Fix #1397, correct compression to XZ for osx bin Oct 24, 2019
BACKERS.md Update BACKERS.md May 4, 2020
CHANGELOG.md Nixify CircleCI setup (#1535) May 25, 2020
LICENSE Update authorship Nov 17, 2019
Makefile Nixify CircleCI setup (#1535) May 25, 2020
README.md Add documentation links Aug 16, 2019
Setup.hs Initial commit Jun 17, 2014
app.json Bump to version v7.0.1 May 18, 2020
appveyor.yml appveyor: specify windows image May 8, 2020
default.nix Nixify io and memory tests (#1538) May 28, 2020
postgrest.cabal Allow aeson 1.5 (#1537) May 26, 2020
shell.nix Nixify io and memory tests (#1538) May 28, 2020
stack.yaml cabal: fix upload to hackage (#1532) May 19, 2020
stack.yaml.lock Update to protolude 0.3.0 Apr 23, 2020

README.md

Logo

Donate Donate Deploy Join the chat at https://gitter.im/begriffs/postgrest Docs Docker Stars Build Status Hackage docs

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

Sponsors

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

Usage

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

  2. Invoke for help:

    postgrest --help

Documentation

Latest documentation is at postgrest.org. You can contribute to the docs in PostgREST/postgrest-docs.

Performance

TLDR; subsecond response times for up to 2000 requests/sec on Heroku free 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 written in Haskell using the Warp HTTP server (aka a compiled language with lightweight threads). Next it delegates as much calculation as possible to the database including

  • 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 the Hasql library by

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

Security

PostgREST handles authentication (via JSON Web Tokens) and delegates authorization to the role information defined in the database. This ensures there is a single declarative source of truth for security. When dealing with the database the server assumes the identity of the currently authenticated user, and for the duration of the connection cannot do anything the user themselves couldn't. Other forms of authentication can be built on top of the JWT primitive. See the docs for more information.

PostgreSQL 9.5 supports true row-level security. In previous versions it can be simulated with triggers and security-barrier views. Because the possible queries to the database are limited to certain templates using leakproof functions, the trigger workaround does not compromise row-level security.

Versioning

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

Self-documentation

PostgREST uses the OpenAPI standard to generate up-to-date documentation for APIs. You can use a tool like Swagger-UI to render interactive documentation for demo requests against the live API server.

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

Data Integrity

Rather than relying on an Object Relational Mapper and custom imperative coding, this system requires you put declarative constraints directly into your database. Hence no application can corrupt your data (including your API server).

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

See examples of PostgreSQL constraints and the API guide.

Supporting development

You can help PostgREST ongoing maintenance and development by:

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

Thanks

The PostgREST organization is grateful to:

  • The project sponsors and backers who support PostgREST's development.
  • The project contributors who have improved PostgREST immensely with their code and good judgement. See more details in the changelog.

The cool logo came from Mikey Casalaina.

You can’t perform that action at this time.