PostgREST Starter Kit
Base project and tooling for authoring REST API backends with PostgREST.
PostgREST enables a different way of building data driven API backends. It does "one thing well" and that is to provide you with a REST api over your database, however to build a complex production system that does things like talk to 3rd party systems, sends emails, implements real time updates for browsers, write integration tests, implement authentication, you need additional components. For this reason, some developers either submit feature requests that are not the scope of PostgREST or think of it just as a prototyping utility and not a powerful/flexible production component with excellent performance. This repository aims to be a starting point for all PostgREST based projects and bring all components together under a well defined structure. We also provide tooling that will aid you with iterating on your project and tools/scripts to enable a build pipeline to push everything to production. There are quite a few components in the stack but you can safely comment out pg_amqp_bridge/rabbitmq (or even openresty) instances in docker-compose.yml if you don't need the features/functionality they provide.
✓ Cross-platform development on macOS, Windows or Linux inside Docker
✓ PostgreSQL database schema boilerplate with authentication and authorization flow
✓ OpenResty configuration files for the reverse proxy
✓ RabbitMQ integration through pg-amqp-bridge
✓ Lua functions to hook into each stage of the HTTP request and add custom logic (integrate 3rd party systems)
✓ Debugging and live code reloading (sql/configs/lua) functionality using subzero-cli
✓ Full migration management (migration files are automatically created) through subzero-cli/sqitch/apgdiff
✓ SQL unit test using pgTAP
✓ Integration tests with SuperTest / Mocha
✓ Docker files for building production images
✓ Community support on Slack
✓ Compatible with subZero Starter Kit if you need a GraphQL API and a few more features with no additional work
. ├── db # Database schema source files and tests │ └── src # Schema definition │ ├── api # Api entities avaiable as REST endpoints │ ├── data # Definition of source tables that hold the data │ ├── libs # A collection modules of used throughout the code │ ├── authorization # Application level roles and their privileges │ ├── sample_data # A few sample rows │ └── init.sql # Schema definition entry point ├── openresty # Reverse proxy configurations and Lua code │ ├── lualib │ │ └── user_code # Application Lua code │ ├── nginx # Nginx files │ │ ├── conf # Configuration files │ │ └── html # Static frontend files │ ├── Dockerfile # Dockerfile definition for production │ └── entrypoint.sh # Custom entrypoint ├── tests # Tests for all the components │ ├── db # pgTap tests for the db │ └── rest # REST interface tests ├── docker-compose.yml # Defines Docker services, networks and volumes └── .env # Project configurations
Create a New Project
subzero-cli provides you with a
base-project command that lets you create a new project structure:
subzero base-project ? Enter the directory path where you want to create the project . ? Choose the starter kit (Use arrow keys) subzero-starter-kit (REST & GraphQL) ❯ postgrest-starter-kit (REST)
After the files have been created, you can bring up your application (API). In the root folder of application, run the docker-compose command
docker-compose up -d
The API server will become available at the following endpoint:
Try a simple request
Development workflow and debugging
subzero dashboard in the root of your project.
After this step you can view the logs of all the stack components (SQL queries will also be logged) and if you edit a sql/conf/lua file in your project, the changes will immediately be applied.
Here is how you run them
npm install # Install test dependencies npm test # Run all tests (db, rest) npm run test_db # Run pgTAP tests npm run test_rest # Run integration tests
Anyone and everyone is welcome to contribute.
Support and Documentation
- PostgREST API Referance
- PostgreSQL Manual
- Slack — Get help, share ideas and feedback
- GitHub Issues — Check open issues, send feature requests