PostgREST is a standalone web server that turns your PostgreSQL database directly into a RESTful API. The structural constraints and permissions in the database determine the API endpoints and operations.
Using PostgREST is an alternative to manual CRUD programming. Custom API servers suffer problems. Writing business logic often duplicates, ignores or hobbles database structure. Object-relational mapping is a leaky abstraction leading to slow imperative code. The PostgREST philosophy establishes a single declarative source of truth: the data itself.
It’s easier to ask PostgreSQL to join data for you and let its query planner figure out the details than to loop through rows yourself. It’s easier to assign permissions to db objects than to add guards in controllers. (This is especially true for cascading permissions in data dependencies.) It’s easier to set constraints than to litter code with sanity checks.
There is no ORM involved. Creating new views happens in SQL with known performance implications. A database administrator can now create an API from scratch with no custom programming.
Embracing the Relational Model¶
In 1970 E. F. Codd criticized the then-dominant hierarchical model of databases in his article A Relational Model of Data for Large Shared Data Banks. Reading the article reveals a striking similarity between hierarchical databases and nested http routes. With PostgREST we attempt to use flexible filtering and embedding rather than nested routes.
One Thing Well¶
PostgREST has a focused scope. It works well with other tools like Nginx. This forces you to cleanly separate the data-centric CRUD operations from other concerns. Use a collection of sharp tools rather than building a big ball of mud.
PostgREST has a growing ecosystem of examples, and libraries, experiments, and users. Here is a selection.
- tomberek/aor-postgrest-client - JS, admin-on-rest
- hugomrdias/postgrest-url - JS, just for generating query URLs
- john-kelly/elm-postgrest - Elm
- mithril.postgrest - JS, Mithril
- lewisjared/postgrest-request - JS, SuperAgent
- JarvusInnovations/jarvus-postgrest-apikit - JS, Sencha framework
- davidthewatson/postgrest_python_requests_client - Python
- calebmer/postgrest-client - JS
- clesiemo3/postgrestR - R
- PierreRochard/postgrest-angular - TypeScript, generate UI from API description
- thejettdurham/postgrest-sharp-client (needs maintainer) - C#, RestSharp
- team142/ng-postgrest - Angular app for browsing, editing data exposed over Postgrest.
These are PostgreSQL bridges that propagate LISTEN/NOTIFY to external queues for further processing. This allows stored procedures to initiate actions outside the database such as sending emails.
- srid/chronicle - tracking a tree of personal memories
- GSA/cloudgov-demo-postgrest - demo for a federally-compliant REST API on cloud.gov
- SocialGouv/code-du-travail-backoffice - data administration portal for the official French Labor Code and Agreements
- mattddowney/compose-postgrest - docker-compose setup with Nginx and HTML example
- delibrium/delibrium-postgrest - example school API and front-end in Vue.js
- diogob/elm-workshop - building a simple database query UI
- benoror/ember-postgrest-dynamic-ui - generating Ember forms to edit data
- Adamant-im/ETH-transactions-storage - indexer for Ethereum to get transaction list by ETH address
- timwis/ext-postgrest-crud - browser-based spreadsheet
- PierreRochard/general - example auth back-end
- tyrchen/goodfilm - example film API
- cardano-community/guild-operators - example queries and functions that the Cardano Community uses for their Guild Operators’ Repository
- timwis/handsontable-postgrest - an excel-like database table editor
- CodeforAustralia/heritage-near-me - Elm and PostgREST with PostGIS
- marmelab/ng-admin-postgrest - automatic database admin panel
- Qu4tro/pgrst-dev-setup - docker-compose and tmuxp setup for experimentation.
- cloudflare/postgres-postgrest-cloudflared-example - docker-compose setup exposing PostgREST using cloudfared
- SMRxT/postgrest-demo - multi-tenant logging system
- begriffs/postgrest-example - sqitch versioning for API
- monacoremo/postgrest-sessions-example - example for cookie-based sessions
- NikolayS/postgrest-translation-proxy - calling to external translation service
- tatut/postgrest-ui - ClojureScript UI components for PostgREST
- seveibar/postgrest-vercel - run PostgREST on Vercel (Serverless/AWS Lambda)
- Recmo/PostgrestSkeleton - Docker Compose, PostgREST, Nginx and Auth0
- priyank-purohit/PostGUI - React Material UI admin panel
- sfcta/prospector - data warehouse and visualization platform
- guyromm/svelte-postgrest-template - Svelte/SvelteKit, PostgREST, EveryLayout and social auth
- diogob/postgrest-ws - expose web sockets for PostgreSQL’s LISTEN/NOTIFY
- pg-safeupdate - Prevent full-table updates or deletes
- srid/spas - allow file uploads and basic auth
- svmnotn/postgrest-auth - OAuth2-inspired external auth server
- nblumoe/postgrest-oauth - OAuth2 WAI middleware
- criles25/postgrest-auth - email based auth/signup
- ppKrauss/PostgREST-writeAPI - generate Nginx rewrite rules to fit an OpenAPI spec
“It’s so fast to develop, it feels like cheating!”
“I just have to say that, the CPU/Memory usage compared to our Node.js/Waterline ORM based API is ridiculous. It’s hard to even push it over 60/70 MB while our current API constantly hits 1GB running on 6 instances (dynos).”