website: postgraphile.org: Version 4 docs sync up and refresh

postgraphile/website/docusaurus.config.js

@@ -249,7 +249,7 @@ const config = {
       prism: {
         theme: lightCodeTheme,
         darkTheme: darkCodeTheme,
-        additionalLanguages: ["json5"],
+        additionalLanguages: ["docker", "ini", "json5", "plsql"],
       },
       algolia: {
         // The application ID provided by Algolia

postgraphile/website/postgraphile/aggregates.md

@@ -1,18 +1,16 @@
 ---
-layout: page
-path: /postgraphile/aggregates/
 title: Aggregates
 ---
 
-PostGraphile's engine has support for powerful aggregates. The
+PostGraphile’s engine has support for powerful aggregates. The
 [@graphile/pg-aggregates](https://github.com/graphile/pg-aggregates) module
 adds various aggregates to the schema, and gives you the ability to add more
 via plugins. Aggregates are located under connection fields.
 
 ### Aggregates ignore pagination info
 
 Aggregates are performed over the **entire collection** represented by the
-field and its filters - not just the data that would be returned if you were to
+field and its filters — not just the data that would be returned if you were to
 query the nodes. This means they ignore the `first`, `last`, `before`, `after`
 and `offset` arguments. This is deliberate (if you only need aggregates over
 the data that matches your pagination information then you could calculate
@@ -21,7 +19,7 @@ these on the client).
 ### Aggregates only work on Relay connection
 
 Thanks to their expansibility, relay [connections](./connections) were the
-perfect place to add aggregates support. If you're using a behavior
+perfect place to add aggregates support. If you’re using a behavior
 configuration that prefers lists over connections (e.g. `-connection +list`)
 then you can override it on a per-collection basis with the [`@behavior
 +connection` smart tag](./smart-tags/#behavior).

postgraphile/website/postgraphile/background-tasks.md

@@ -1,9 +1,9 @@
 ---
-layout: page
-path: /postgraphile/background-tasks/
-title: Background Tasks in PostGraphile
+title: Background Tasks
 ---
 
+# Background Tasks in PostGraphile
+
 In your GraphQL server typically most processing will be done in the
 "foreground", as part of the request-response cycle. However, since clients
 typically wait for this request cycle to complete before allowing the user to
@@ -32,10 +32,10 @@ workers and handle errors and re-tries.
 
 ### Tasks queues and workers for Postgres
 
-There are several exisiting solutions that can integrate with a PostgreSQL
+There are several existing solutions that can integrate with a PostgreSQL
 database or expose a Node.js-friendly API.
 
-- [Graphile Worker](https://github.com/graphile/worker)
+- [Graphile Worker](https://worker.graphile.org)
 - [GCP Cloud Tasks](https://cloud.google.com/tasks/) (via Graphile Worker)
 - [Faktory](http://contribsys.com/faktory/) (via Graphile Worker)
 - [RabbitMQ](https://www.rabbitmq.com/)
@@ -56,7 +56,7 @@ Other important considerations when choosing a task queue would be:
 - Complexity
 - Throughput requirements
 - DevOps complexity
-- Tracability
+- Traceability
 - Privacy
 
 ### Graphile Worker
@@ -86,13 +86,13 @@ module.exports = async (payload, helpers) => {
 };
 ```
 
-Check the [Graphile Worker docs](https://github.com/graphile/worker) for details
+Check the [Graphile Worker docs](https://worker.graphile.org) for details
 on how to set up and use it.
 
 #### Limitations
 
 Despite all the benefits, Graphile Worker stills lacks some features provided by
 other more mature tasks queues
 
-- Currently Graphile Worker doesn't expose a GUI to monitor or manage tasks.
+- Currently Graphile Worker doesn’t expose a GUI to monitor or manage tasks.
 - ??

postgraphile/website/postgraphile/behavior.md

@@ -2,21 +2,21 @@
 
 For all but the simplest APIs you will want to control which parts of your data
 sources are exposed and how they are exposed. New to PostGraphile version 5 is
-the "behavior" system that gives you granular control over these topics.
+the “behavior” system that gives you granular control over these topics.
 
 ## Terminology
 
-A "behavior string" is a text-based string with a relatively simple syntax; here
+A “behavior string” is a text-based string with a relatively simple syntax; here
 are some examples:
 
 - `insert`
 - `+list -connection -list:filter`
 - `-insert -update -delete query:*:filter +connection -list`
 
-A behavior string is made of a list of "behavior fragments" separated by spaces.
+A behavior string is made of a list of “behavior fragments” separated by spaces.
 Each behavior fragment optionally starts with a `+` or `-` symbol (if neither is
-specified then `+` is inferred) followed by a "scope string." A scope string is
-one or more "scope phrases" joined by colons (`:`). A scope phrase is either a
+specified then `+` is inferred) followed by a “scope string.” A scope string is
+one or more “scope phrases” joined by colons (`:`). A scope phrase is either a
 simple alphanumeric word (in camelCase), or an asterisk (`*`).
 
 ## Determining entity behavior
@@ -25,7 +25,7 @@ Many entities that PostGraphile processes when generating a schema (for example:
 tables, columns, functions, types, etc.) have associated behaviors which
 influence whether and how that entity is exposed. You may influence their
 resulting behaviors by adding your own behavior strings to the entity, either
-directly or via smart tags/smart comments. For example, if you don't want users
+directly or via smart tags/smart comments. For example, if you don’t want users
 to be able to modify entries in the `forums` table, you might add a database
 comment such as `comment on table forums is '@behavior -insert -update
 -delete';` (this is just one of many ways of attaching behaviors).
@@ -44,16 +44,16 @@ strings from various sources; typically this follows the following pattern:
 The highest precedence behaviors are at the end the behavior string, and the
 lowest priority behaviors are at the start.
 
-When determining if an entity possesses a given "filter" behavior, the system
-will scan backwards through the entity's behavior string for the first fragment
+When determining if an entity possesses a given “filter” behavior, the system
+will scan backwards through the entity’s behavior string for the first fragment
 that matches the filter; if the matching fragment has a `-` modifier then the
 entity does not possess that behavior (even if a positive fragment existed
 earlier in the behavior string) otherwise it does.
 
 ## Global default behavior
 
-If you want to make wide-sweeping changes to behaviors, you can add "default
-behaviors" via the `preset.schema.defaultBehavior` setting. For example if you
+If you want to make wide-sweeping changes to behaviors, you can add “default
+behaviors” via the `preset.schema.defaultBehavior` setting. For example if you
 want your schema to use lists by default, eschewing the more verbose (but
 typically superior) connections pattern, you might have a configuration
 something like this:
@@ -72,23 +72,23 @@ const preset = {
 export default preset;
 ```
 
-These global defaults can still be overridden by each entity, so they're a
-good way of making wide ranging "default" behaviors without locking yourself in
+These global defaults can still be overridden by each entity, so they’re a
+good way of making wide ranging “default” behaviors without locking yourself in
 too hard.
 
-:::info
+:::info Global behavior in presets
 
-If you're authoring a preset that is not the final configuration for a schema
+If you’re authoring a preset that is not the final configuration for a schema
 then this default behavior setting is likely to be overridden (replaced) by the
-user's configuration. Instead, preset authors should add a plugin that has a
+user’s configuration. Instead, preset authors should add a plugin that has a
 `schema.globalBehavior` entry. If this entry is a string, the behavior will be
-prepended. If it's a callback, then it should return an array of behavior
+prepended. If it’s a callback, then it should return an array of behavior
 strings to be joined, one of which should be the current (passed in) behavior.
 Typically you want a tuple where the first entry is your new behaviors and the
-second entry is the current (passed-in) behavior (this way the user's
+second entry is the current (passed-in) behavior (this way the user’s
 `defaultBehavior` will have higher precedence to your `globalBehavior`).
 
-A similar "lists by default" plugin might look like this:
+A similar “lists by default” plugin might look like this:
 
 ```js
 const FavourListsPlugin = {
@@ -130,11 +130,11 @@ is narrower than `update`; `constraint:resource:update` is narrower still).
 :::
 
 The following are behaviors that the core
-PostGraphile/graphile-build/graphile-build-pg plugins utilise:
+PostGraphile/graphile-build/graphile-build-pg plugins utilize:
 
 - `select` - can select this resource/column/etc. Note this does not necessarily
-  mean you can do `select * from users` but it might mean that it's possible to
-  see details about a `users` when it's returned by a function or similar. (In
+  mean you can do `select * from users` but it might mean that it’s possible to
+  see details about a `users` when it’s returned by a function or similar. (In
   this case the `codec` has `select` but the `resource` has `-select`.)
 - `resource:select` - can select rows from this resource
 - `insert:resource:select` - can select the row that was inserted (on the mutation payload)
@@ -144,47 +144,47 @@ PostGraphile/graphile-build/graphile-build-pg plugins utilise:
 - `resource:insert` - can insert into this resource
 - `resource:update` - can update a record in this resource
 - `resource:delete` - can delete a record in this resource
-- `resource:list` - "list" field for a resource at any level
-- `resource:connection` - "connection" field for a resource at any level
-- `resource:list:filter` - can we filter this resource's results (when represented as a list)?
-- `resource:list:order` - can we order this resource's results (when represented as a list)?
-- `resource:connection:filter` - can we filter this resource's results (when represented as a connection)?
-- `resource:connection:order`- can we order this resource's results (when represented as a connection)?
-- `resource:connection:backwards` - can we paginate backwards through this resource's results (when represented as a connection)?
+- `resource:list` - “list” field for a resource at any level
+- `resource:connection` - “connection” field for a resource at any level
+- `resource:list:filter` - can we filter this resource’s results (when represented as a list)?
+- `resource:list:order` - can we order this resource’s results (when represented as a list)?
+- `resource:connection:filter` - can we filter this resource’s results (when represented as a connection)?
+- `resource:connection:order`- can we order this resource’s results (when represented as a connection)?
+- `resource:connection:backwards` - can we paginate backwards through this resource’s results (when represented as a connection)?
 - `resource:aggregates` - does this resource support aggregates across its attributes (i.e. does the `aggregates` field get added to connections)
 - `resource:groupedAggregates` - does this resource support grouped aggregates across its attributes (i.e. does the `groupedAggregates` field get added to connections)
-- `resource:groupedAggregates:having` - can groupedAggregates on this resource have a 'having' clause?
-- `sum:resource:groupedAggregates:having` - can groupedAggregates on this resource have a 'having' clause that uses the 'sum' aggregate?
-- `sum:resource:aggregates` - does this resource support 'sum' aggregates across its attributes (replace 'sum' with the aggregate id you care about) (i.e. does the `sum` field get added within the `aggregates` field on connections?)
+- `resource:groupedAggregates:having` - can groupedAggregates on this resource have a ‘having’ clause?
+- `sum:resource:groupedAggregates:having` - can groupedAggregates on this resource have a ‘having’ clause that uses the ‘sum’ aggregate?
+- `sum:resource:aggregates` - does this resource support ‘sum’ aggregates across its attributes (replace ‘sum’ with the aggregate id you care about) (i.e. does the `sum` field get added within the `aggregates` field on connections?)
 - `constraint:resource:update` - can update a record by this constraint
 - `constraint:resource:delete` - can delete a record by this constraint
 - `nodeId:resource:update` - can update a record by its NodeID
 - `nodeId:resource:delete` - can delete a record by its NodeID
 - `attribute:select` - can this attribute be selected?
 - `attribute:insert` - can this attribute be inserted into?
 - `attribute:update` - can this attribute be updated?
-- `attribute:base` - should we add this attribute to the "base" input type?
+- `attribute:base` - should we add this attribute to the “base” input type?
 - `attribute:aggregate` - can we aggregate on this attribute?
-- `sum:attribute:aggregate` - can we perform the 'sum' aggregate on this attribute? (replace 'sum' with the aggregate id you care about) (i.e. does this attribute get added to the `sum` field on the `aggregates` field on connections?)
-- `sum:resource:aggregate` - does this computed-column-like resource support the 'sum' aggregate when acting as an attribute (replace 'sum' with the aggregate id you care about)
+- `sum:attribute:aggregate` - can we perform the ‘sum’ aggregate on this attribute? (replace ‘sum’ with the aggregate id you care about) (i.e. does this attribute get added to the `sum` field on the `aggregates` field on connections?)
+- `sum:resource:aggregate` - does this computed-column-like resource support the ‘sum’ aggregate when acting as an attribute (replace ‘sum’ with the aggregate id you care about)
 - `attribute:groupBy` - can we group by this attribute when performing grouped aggregates?
-- `attribute:havingBy` - can this attribute be used in the 'having' clause of a grouped aggregate?
-- `sum:attribute:havingBy` - can the sum of this attribute be used in the 'having' clause of a grouped aggregate?
-- `resource:havingBy` - can this computed-column-like resource be used in the 'having' clause of a grouped aggregate?
-- `sum:resource:havingBy` - can the sum of this computed-column-like resource be be used in the 'having' clause of a grouped aggregate?
+- `attribute:havingBy` - can this attribute be used in the ‘having’ clause of a grouped aggregate?
+- `sum:attribute:havingBy` - can the sum of this attribute be used in the ‘having’ clause of a grouped aggregate?
+- `resource:havingBy` - can this computed-column-like resource be used in the ‘having’ clause of a grouped aggregate?
+- `sum:resource:havingBy` - can the sum of this computed-column-like resource be be used in the ‘having’ clause of a grouped aggregate?
 - `nodeId:insert` - can we insert to the columns represented by this nodeId which represents a table related via foreign key constraint?
 - `nodeId:update` - can we update the columns represented by this nodeId which represents a table related via foreign key constraint?
-- `nodeId:base` - should we add a nodeId input representing this foreign key constraint to the "base" input type?
+- `nodeId:base` - should we add a nodeId input representing this foreign key constraint to the “base” input type?
 - `type:node` - should the GraphQLObjectType (`type`) this codec represents
   implement the GraphQL Global Object Identification specification
 - `interface:node` - should the GraphQLInterfaceType (`interface`) this codec
   represents implement the GraphQL Global Object Identification specification
 - `list` - list (simple collection)
 - `connection` - connection (GraphQL Cursor Pagination Spec)
-- `query:resource:list` - "list" field for a resource at the root Query level
-- `query:resource:connection` - "connection" field for a resource at the root Query level
-- `query:interface:list` - "list" field for a interface at the root Query level
-- `query:interface:connection` - "connection" field for a interface at the root Query level
+- `query:resource:list` - “list” field for a resource at the root Query level
+- `query:resource:connection` - “connection” field for a resource at the root Query level
+- `query:interface:list` - “list” field for a interface at the root Query level
+- `query:interface:connection` - “connection” field for a interface at the root Query level
 - `queryField` - for procedures: should it become a field on the `Query` type?
 - `typeField` - for procedures: should it become a field on a non-operation
   type?
@@ -202,15 +202,15 @@ PostGraphile/graphile-build/graphile-build-pg plugins utilise:
 - `proc:orderBy` - can we order by the result of this proc (function resource)?
 - `attribute:orderBy` - can we order by this attribute (column, property)?
 - `attribute:aggregate:orderBy` - can we order by aggregates of this attribute (column, property)?
-- `sum:attribute:aggregate:orderBy` - can we order by 'sum' aggregates of this attribute (column, property)?
+- `sum:attribute:aggregate:orderBy` - can we order by ‘sum’ aggregates of this attribute (column, property)?
 - `filterBy` - can we filter by this thing (e.g. column, table, etc)?
 - `proc:filterBy` - can we filter by the result of this proc (function resource)
 - `attribute:filterBy` - can we filter by this attribute (column, property)?
 - `condition:attribute:filterBy` - can we filter by this attribute (column, property) in the `condition` argument?
 - `attribute:aggregate:filterBy` - can we filter by the aggregate of this attribute (column, property)?
-- `sum:attribute:aggregate:filterBy` - can we filter by the 'sum' aggregate of this attribute (column, property)?
+- `sum:attribute:aggregate:filterBy` - can we filter by the ‘sum’ aggregate of this attribute (column, property)?
 - `resource:aggregates:filterBy` - can we filter (a different resource) by this resource's aggregates?
-- `sum:resource:aggregates:filterBy` - can we filter (a different resource) by this resource's 'sum' aggregates?
+- `sum:resource:aggregates:filterBy` - can we filter (a different resource) by this resource's ‘sum’ aggregates?
 - `single` - can we get just one?
 - `query:resource:single` - can we get a single one of these (resource) at the root?
 - `singularRelation:resource:single` - can we get a single one of these (resource) from a
@@ -222,7 +222,7 @@ PostGraphile/graphile-build/graphile-build-pg plugins utilise:
 - `manyRelation:resource:list`
 - `manyRelation:resource:connection`
 - `manyRelation:aggregates:orderBy` - can we order by aggregates of this manyRelation?
-- `sum:manyRelation:aggregates:orderBy` - can we order by 'sum' aggregates of this manyRelation?
+- `sum:manyRelation:aggregates:orderBy` - can we order by ‘sum’ aggregates of this manyRelation?
 - `jwt` - should the given codec behave as if it were a JWT?
 - `insert:input:record` - input to the 'insert' mutation
 - `totalCount` - on a codec, should we add the `totalCount` field?