postgraphile
Version:
A GraphQL schema created by reflection over a PostgreSQL schema 🐘 (previously known as PostGraphQL)
221 lines (148 loc) • 14 kB
Markdown
<img width="120" height="120" title="PostGraphile logo" src="https://cdn.rawgit.com/graphile/graphile.github.io/a6225f8c3052df5c276ecef28aeb0cade1aec16a/logos/postgraphile.optimized.svg" />
# PostGraphile V4
[](https://github.com/sponsors/benjie)
[](https://patreon.com/benjie)
[](http://discord.gg/graphile)
[](https://www.npmjs.com/package/postgraphile)
[](https://twitter.com/GraphileHQ)
_**Instant lightning-fast GraphQL API backed primarily by your PostgreSQL database. Highly customisable and extensible thanks to incredibly powerful plugin system.**_ _Formerly "PostGraphQL"._
## V4 Documentation: [graphile.org/postgraphile](https://graphile.org/postgraphile)
## ANNOUNCEMENT: Version 5 is in **OPEN BETA**
The long awaited PostGraphile Version 5 is now available for you to try out! There's still bugs to work out, types to improve, documentation and examples that need writing; read more about what beta means in our **[Beta announcement on dev.to](https://dev.to/graphile/postgraphile-v5-public-beta-get-involved-1lg9)**.
Other useful resources:
- **[Intro to V5 series](https://dev.to/benjie/series/23459)** on dev.to
- **[V5 Documentation](https://postgraphile.org)** at postgraphile.org
- **[V4 -> V5 migration guide](https://postgraphile.org/postgraphile/next/migrating-from-v4/)** at postgraphile.org
- **[Overview of new features](https://postgraphile.org/postgraphile/next/migrating-from-v4/v5-new-feature-summary)** at postgraphile.org
- **[💖 Sponsor us to help launch V5 sooner! 🚀](https://github.com/sponsors/benjie)**
Now is the perfect time to get your feet wet with V5 — even if you're not yet ready to migrate to it fully. **If you don't try V5 until after its public release then it may be too late to comment on things that could have been improved.** Access is now open to everyone, so dive in!
This release has taken a tremendous amount of work and we've forgone a significant amount of client work to build it for you. If you can afford even a couple dollars a month, please consider becoming a sponsor; we really need your support to help get V5 over the finish line!
And for those of you wondering when V5.0.0 will be released, here are the [issues that need to be solved before the final release](https://github.com/orgs/graphile/projects/3). The more support we get, the faster that day will come — please get involved, or sponsor us!
<!-- SPONSORS_BEGIN -->
## Crowd-funded open-source software
To help us develop this software sustainably, we ask all individuals and
businesses that use it to help support its ongoing maintenance and development
via sponsorship.
### [Click here to find out more about sponsors and sponsorship.](https://www.graphile.org/sponsor/)
And please give some love to our featured sponsors 🤩:
<table><tr>
<td align="center"><a href="https://www.the-guild.dev/"><img src="https://graphile.org/images/sponsors/theguild.png" width="90" height="90" alt="The Guild" /><br />The Guild</a> *</td>
<td align="center"><a href="https://dovetailapp.com/"><img src="https://graphile.org/images/sponsors/dovetail.png" width="90" height="90" alt="Dovetail" /><br />Dovetail</a> *</td>
<td align="center"><a href="https://www.netflix.com/"><img src="https://graphile.org/images/sponsors/Netflix.png" width="90" height="90" alt="Netflix" /><br />Netflix</a> *</td>
<td align="center"><a href=""><img src="https://graphile.org/images/sponsors/chadf.png" width="90" height="90" alt="Chad Furman" /><br />Chad Furman</a> *</td>
</tr><tr>
<td align="center"><a href="https://stellate.co/"><img src="https://graphile.org/images/sponsors/Stellate.png" width="90" height="90" alt="Stellate" /><br />Stellate</a> *</td>
<td align="center"><a href="https://www.accenture.com/"><img src="https://graphile.org/images/sponsors/accenture.svg" width="90" height="90" alt="Accenture" /><br />Accenture</a> *</td>
<td align="center"><a href="https://microteam.io/"><img src="https://graphile.org/images/sponsors/micro.png" width="90" height="90" alt="We Love Micro" /><br />We Love Micro</a> *</td>
<td align="center"><a href="https://politicsrewired.com/"><img src="https://graphile.org/images/sponsors/politics-rewired.png" width="90" height="90" alt="Politics Rewired" /><br />Politics Rewired</a></td>
</tr></table>
<em>\* Sponsors the entire Graphile suite</em>
<!-- SPONSORS_END -->
## About
**GraphQL** is a new way of communicating with your server. It eliminates the problems of over- and under-fetching, incorporates strong data types, has built-in introspection, documentation and deprecation capabilities, and is implemented in many programming languages. This all leads to gloriously low-latency user experiences, better developer experiences, and much increased productivity. Because of all this, GraphQL is typically used as a replacement for (or companion to) RESTful API services.
**PostgreSQL** is the self-proclaimed “world’s most advanced open source database,” with each new release bringing more amazing features and performance gains. Thinking of your database as a plain CRUD store is now an archaic viewpoint as modern PostgreSQL can do so much for you — from authorization with Row-Level Security (RLS, introduced in PG9.5), through Foreign Data Wrappers (FDW), to real time notifications with `LISTEN`/`NOTIFY`.
**PostGraphile** pairs these two incredible technologies together, helping you not only build applications more rapidly, but to build lightning-fast applications. PostGraphile allows you to access the power of PostgreSQL through a well designed, extensible, customisable and incredibly performant GraphQL server. It automatically detects tables, columns, indexes, relationships, views, types, functions, comments, and more - providing a GraphQL server that is highly intelligent about your data, and that automatically updates itself without restarting when you change your database schema.
With PostGraphile, a well designed database schema should serve the basis for a well thought out API. PostgreSQL already has amazing authorization and relationship infrastructure, _why duplicate that logic_ in a custom API? A PostGraphile API is likely to provide a more performant and standards compliant GraphQL API than any created in-house, and can be built in a fraction of the time. Focus on your product and let PostGraphile worry about the API layer. Once you need to expand beyond this, we have a powerful plugin system including many [community contributed plugins](https://www.graphile.org/postgraphile/community-plugins/). For a critical evaluation of PostGraphile to determine if it fits in your tech stack, read [evaluating PostGraphile for your project](https://www.graphile.org/postgraphile/evaluating/).
## Introduction
Watch a talk by the original author [Caleb](https://twitter.com/calebmer) at GraphQL Summit for a walk-through of building an application with PostGraphile in under 7 minutes. This was using v2 (then called PostGraphQL); we're now up to v4 which has many more bells and whistles!
[](https://www.youtube.com/watch?v=b3pwlCDy6vY)
Hear from the current maintainer [Benjie](https://twitter.com/benjie) at GraphQL Finland about the benefits of Database-Driven GraphQL Development:
[](https://www.youtube.com/watch?v=XDOrhTXd4pE)
## Usage
**Documentation: [graphile.org/postgraphile](https://graphile.org/postgraphile)**
You can use PostGraphile via the CLI, as a Node.js middleware, or use the GraphQL schema directly. Make sure to check out the **[full usage instructions](https://graphile.org/postgraphile/usage/)** on the documentation website. We also have a [PostgreSQL schema design guide](https://www.graphile.org/postgraphile/postgresql-schema-design/) you can follow to build a fully functional PostGraphile API.
### CLI
To get started you can install PostGraphile globally:
```bash
npm install -g postgraphile
```
…and then just run it! By default, PostGraphile will connect to your local database at `postgres://localhost:5432` and introspect the `public` schema. See [the available CLI flags](https://www.graphile.org/postgraphile/usage-cli/) with:
```bash
postgraphile --help
```
When you're ready to use PostGraphile for your own project, you're advised to install it locally with `yarn`, and run it with `npx`:
```bash
yarn add postgraphile
npx postgraphile --help
```
**macOS users**: PostGraphile has used port 5000 by default for 5+ years; recently Apple decided to bind the AirPlay service to port 5000 causing a conflict. Please use the `--port` option to bind to a different port.
### Middleware
You can also use PostGraphile as [native HTTP, Connect, Express, or Koa (experimental) middleware](https://www.graphile.org/postgraphile/usage-library/), e.g.:
```bash
yarn add postgraphile
```
```js
import { createServer } from 'http';
import postgraphile from 'postgraphile';
createServer(postgraphile());
```
Check out [hapi-postgraphile](https://github.com/mshick/hapi-postgraphile) if you're interested in using PostGraphile as a [hapi](https://github.com/hapijs/hapi) server plugin.
### Docker
To run via Docker, simply pass the [CLI options](https://www.graphile.org/postgraphile/usage-cli/) to the Docker container:
```bash
docker pull graphile/postgraphile
docker run --init graphile/postgraphile --help
```
E.g. you might run this command (substituting the relevant variables):
```bash
docker run --init -p 5000:5000 graphile/postgraphile --connection postgres://POSTGRES_USER:POSTGRES_PASSWORD@POSTGRES_HOST:POSTGRES_PORT/POSTGRES_DATABASE --schema app_public --watch
```
**macOS users**: Please use a different port to avoid conflict with AirPlay.
## Read More
**Full documentation for PostGraphile is located at [graphile.org/postgraphile](https://graphile.org/postgraphile).**
PostGraphile features include:
- Authorization (security) provided by PostgreSQL:
- [role-based access control (RBAC)](https://www.postgresql.org/docs/10/static/sql-grant.html)
- [row-level security (RLS)][row-level-security]
- [Automatic GraphQL relations from SQL relations](https://www.graphile.org/postgraphile/relations/)
- [PostgreSQL procedure support][procedure documentation]:
- [Custom queries][advanced queries documentation]
- [Custom mutations](https://www.graphile.org/postgraphile/custom-mutations/)
- [Computed columns](https://www.graphile.org/postgraphile/computed-columns/)
- Development UI (GraphiQL) built in
- `--watch` mode, auto-detects changes in SQL schema, hot-reloads changes into GraphiQL
- [Automatic documentation, enhanced by PostgreSQL `COMMENT`s](http://www.postgresql.org/docs/current/static/sql-comment.html)
- [Schema customisation through smart comments](https://www.graphile.org/postgraphile/smart-comments/)
- [Simple JWT authentication straight from the database](https://www.graphile.org/postgraphile/security/)
- [Cursor-based pagination, Relay (classic & modern) compatible](https://www.graphile.org/postgraphile/connections/)
- Global object identifiers (`nodeId` by default, but Relay-favoured `id` with `--classic-ids`)
- Relay-compatible mutations
- [Use direct from the CLI](https://www.graphile.org/postgraphile/usage-cli/)
- [Use as Express, Connect, or Koa middleware](https://www.graphile.org/postgraphile/usage-library/)
- [Just use the generated GraphQL schema](https://www.graphile.org/postgraphile/usage-schema/)
[procedure documentation]: https://www.graphile.org/postgraphile/procedures/
[advanced queries documentation]: https://www.graphile.org/postgraphile/custom-queries/
[row-level-security]: http://www.postgresql.org/docs/current/static/ddl-rowsecurity.html
## Requirements
[Full requirements are on the website](https://www.graphile.org/postgraphile/requirements/), but a basic summary is:
- Node v8.6+
- PostgreSQL 9.6+ (officially; but currently works with 9.4+)
- Linux, macOS or Windows
Caveats:
- PostGraphile does not have automated tests on Windows, if you notice any
issues please file them (or send a PR!)
## Supporting PostGraphile
The fastest and easiest way you can help PostGraphile thrive is by [sponsoring
ongoing development and maintenance](https://graphile.org/sponsor/).
Want to help testing and developing PostGraphile? Check out the [contributing
document](CONTRIBUTING.md) to get started quickly!
Commercial support, consultancy and development services are available direct
from the maintainer; see [Professional Services](https://www.graphile.org/support/)
for more information, or get in touch!
The maintainer of this project is [](https://twitter.com/benjie) -
follow him on Twitter!
## Thanks
Huge thanks to [the individuals and companies who sponsor PostGraphile's
development](SPONSORS.md) - their financial contributions enable more time to
be spent on the project: from bug fixes, to code review, to new features! If
you want to help the project advance more rapidly, please join them in
[supporting this project](https://graphile.org/sponsor/) 🙏
A humongous, heart-felt, thank you to the original author of PostGraphile -
[Caleb Meredith](https://twitter.com/calebmer) - for everything he put into
PostGraphile! He's now graduated from the project and we all wish him the best
for his future ventures!
Thanks also to the people working on
[PostgREST](https://github.com/begriffs/postgrest) which was a huge inspiration
for this project!
Thanks and enjoy 👍