Improve graphile export docs #2167
Conversation
|
|
Thanks so much for contributing some documentation! Just a heads up that this is an unusually busy time for me: I just came back from vacation yesterday and on Saturday I'll be flying to America for GraphQLConf where I have two unfinished talks to present, so it may take me a few weeks to get around to reviewing it fully. I might do a cursory review before then if I get a chance, but it is likely to take a while to get merged. Sorry! |
There was a problem hiding this comment.
Thanks for your work on this! It is a good start; but I put in a lot of effort to make sure that the solutions we build are generally useful where they can be - i.e. someone using any other schema generation framework should be able to export their schema as executable using graphile-export without even having to know PostGraphile exists. Thus any PostGraphile-specific documentation should remain within PostGraphile's documentation.
Similarly, a tool like graphile-export's documentation should detail fully how to use the tool no matter what type of consumer you are; however PostGraphile's documentation should cover specifically how to use the tool with PostGraphile in a simplified form - for example, if we wanted to demonstrate a PostGraphile plugin to automatically export the schema once it's built (like this), that would be in the PostGraphile documentation, not the graphile-export docs.
I hope that makes sense!
(Sorry again that it's taken a while to get around to looking at this.)
|
|
||
| # Troubleshooting | ||
|
|
||
| ## undefined variable `EXPORTABLE` | ||
|
|
||
| Our ESLint plugin isn't smart enough to actually `import` the `EXPORTABLE` | ||
| helper, so after running the autofix you might end up with "undefined variable |
There was a problem hiding this comment.
Let's keep the exportable page so as to not break any hyperlinks; this can also act as a reference. E.g. update the end of this paragraph:
You can either `import { EXPORTABLE } from "graphile-export"`, or you can [implement `EXPORTABLE` in your own code](./exportable).| --- | ||
|
|
||
| # Using EXPORTABLE | ||
| As explained in [how it works](./how-it-works.md), plugins must be made compatible to work with graphile export. *This applies to external (npm) plugins and internal (your own) plugins*. |
There was a problem hiding this comment.
This is in the graphile-export package which is independent of graphile-build/postgraphile/etc, so it has no concept of plugins and shouldn't talk about them.
Maybe something like:
As explained in how it works, GraphQL schemas must be made compatible to work with Graphile Export - this includes everything in the schema, including traditional resolvers, type resolvers, plan resolvers, enum values, default values, and everything else that makes up the schema.
Note: if you're using
graphile-exportto export a PostGraphile schema, you should consult the PostGraphile documentation for specifics - especially regarding how to ensure plugins only make exportable changes to a schema.
| [ 7 ] | ||
| ``` | ||
|
|
||
| Thus everything that can have these kinds of hidden properties must be wrapped |
There was a problem hiding this comment.
| Thus everything that can have these kinds of hidden properties must be wrapped | |
| Thus everything that can reference values from a parent scope must be wrapped |
| The key reason to export your schema is to move schema introspection of postgres | ||
| from runtime to build time. This results in: |
There was a problem hiding this comment.
graphile-export knows nothing of Postgres, and is not specific to PostGraphile.
Schema exporting was designed for systems that generate a GraphQL schema dynamically.
This dynamic generation can often consume a lot of compute, and may not be a cost that
you want to incur on every startup - instead, you can export your dynamically
generated schema as executable code at build time; then at run time you just need to
run the final code without any of the underlying computations that shaped it. This
has many benefits:
| things such as classes). In JavaScript you can see the source code of a function | ||
| by calling `.toString()` on it: | ||
| - Faster startup time | ||
| - Reduced thundering herd on the database in the event of an outage |
There was a problem hiding this comment.
| - Reduced thundering herd on the database in the event of an outage | |
| - Reduced thundering herd in the event of mass server restarts |
| by calling `.toString()` on it: | ||
| - Faster startup time | ||
| - Reduced thundering herd on the database in the event of an outage | ||
| - Much faster cold starts for Lambda |
There was a problem hiding this comment.
| - Much faster cold starts for Lambda | |
| - Much faster cold starts for serverless environments such as AWS Lambda |
| Previously, in Postgraphile 4, export took the form of encoding the Postgres | ||
| schema to JSON. Postgraphile 5 takes this further and generates runtime code, | ||
| further cutting startup times. |
There was a problem hiding this comment.
This should not be part of the graphile-export documentation; add it to the PostGraphile pages if you feel it warrants detail (though I'd personally keep it to the V4 migration guide).
Description
Raising this PR early for visibility. Open to feedback as I go