This is a PostGraphile server plugin that includes a number of optional protections for your production server. Unlike PostGraphile, this plugin is NOT open source software - see "License key" lower down.
- Force pagination caps (require user to supply a 'first' or 'last' argument to collections, customise or disable per table via
@paginationCapsmart comment) - omitting limits from collection fetches is the number one cause of slow queries in PostGraphile applications, this option forces you to use pagination
- Send queries to read replicas to increase scalability
- Limit GraphQL query depth
- GraphQL cost limit (experimental! Estimates the cost of a GraphQL query before sending it to the database, applies a limit)
To read about these protections, see:
yarn add postgraphile @graphile/pro export GRAPHILE_LICENSE="MY_LICENSE_KEY_HERE" yarn postgraphile --plugins @graphile/pro
Optional CLI flags:
--read-only-connection <string>:: pass the PostgreSQL connection string to use for read-only queries (i.e. not mutations) - typically for connecting to replicas via PgBouncer or similar
--default-pagination-cap [int]:: Ensures all connections have first/last specified and are no large than this value (default: 50), set to ' -1' to disable; override via smart comment
--graphql-depth-limit [int]:: ⚡️Validates GraphQL queries cannot be deeper than the specified int (default: 16), set to ' -1' to disable
--graphql-cost-limit [int]:: ⚡️[experimental] Only allows queries with a computed cost below the specified int (default: 30000), set to ' -1' to disable
yarn add postgraphile @graphile/pro
pluginHook and relevant options to your server:
// server.jsconst http = ;const postgraphile makePluginHook = ;const pluginHook = ;http;
Set your GRAPHILE_LICENSE envvar and run the server:
export GRAPHILE_LICENSE="MY_LICENSE_KEY_HERE" node server.js
To override the
--default-pagination-cap option for a specific table or function, you may add a
@paginationCap smart comment to the table/function specifying the replacement cap. Remember, set cap to
-1 to disable. For example:
-- Disable pagination cap on my functioncomment on function my_function() is E'@paginationCap -1';-- Raise pagination cap on forumscomment on table forums is E'@paginationCap 500';
GraphQL cost limit
This feature is experimental; it allows us to estimate the cost of a query before sending it to the database. It has been honed by timing a wide array of varied queries against a database and seeing how nested collections and function calls affect the performance of the query.
Besides being useful if you wish to open your GraphQL API up to the world in production, this feature is also useful in development as it allows you to see how expensive we estimate your query is whilst you compose it in GraphiQL or similar - it's a great way of determining that your query is too complex before you get performance issues in production.
We recommend that you benchmark queries on a full database and then come up
with a query cost that works for you. A value of
2000 should be high enough
for simple workloads that use pagination and don't nest large collections too
The numbers produced by this may change slightly in different versions of @graphile/pro; we recommend that you ensure your queries remain well under the limit you set, and that you have a test suite that ensures all your queries are under the limit before you do a release.
You must specify the license key in an environmental variable
GRAPHILE_LICENSE, or pass it via the
license option to the library. You
can acquire the license key from https://store.graphile.com
If you fail to provide the license key, then the module will throw an error.
0.7.0 - match library defaults to CLI defaults; update README with CLI flags/library options/changelog
0.6.1 - fix the TypeScript definition file locations
0.6.0 - moved license check to runtime; convert to TypeScript; add support for subscriptions/live queries; fix conflicts when handling GraphQL validation errors
0.5.0 - released on NPM