The Rover persisted-queries Command

With GraphOS Enterprise, you can enhance a graph's security by maintaining a persisted query list (PQL) for your graph's self-hosted router. The GraphOS Router checks incoming requests against the PQL, and can be configured to reject operations that aren't registered in the list.

Registering operations to a PQL has two steps:

1. Generate persisted query manifests (PQMs) from client operations

2. Publish PQMs to the PQL using Rover

For more information on persisted query implementation steps, see the GraphOS persisted queries documentation.

Generate a PQM

persisted-queries generate

Use rover persisted-queries generate to generate Apollo PQM from .graphql operation files. This command runs locally and doesn't require an API key.

1rover persisted-queries generate

By default, Rover scans the current directory for all .graphql files and prints the generated manifest to stdout. Pass --manifest-path (-m) to write it to a file instead. This pairs with rover client extract, which extracts operations from client source code into a graphql directory:

1rover client extract --out-dir graphql --overwrite
2rover persisted-queries generate --manifest-path persisted-query-manifest.json
3rover persisted-queries publish my-graph@my-variant \
4  --manifest ./persisted-query-manifest.json

The generated manifest uses the Apollo persisted query manifest format. Each entry has the operation's id (the SHA-256 hash of its body), its name, its type (query, mutation, or subscription), and its body:

1{
2  "format": "apollo-persisted-query-manifest",
3  "version": 1,
4  "operations": [
5    {
6      "id": "e5c9c9f2d1a0a9f4f6b6a1e2d3c4b5a6978869504132a1b2c3d4e5f60718293a",
7      "name": "GetProduct",
8      "type": "query",
9      "body": "query GetProduct($id: ID!) {\n  product(id: $id) {\n    id\n    name\n  }\n}"
10    }
11  ]
12}

persisted-queries generate supports multiple operations in a single .graphql file, emitting one manifest entry per operation. For each operation it removes @client fields and directives (pruning any variables they leave unused), includes the operation's transitively referenced fragment definitions, and generates the operation ID as the SHA-256 hash of the final operation body.

To change the files Rover scans, use --include, --exclude, and --root-dir:

1rover persisted-queries generate \
2  --root-dir ./client \
3  --include "operations/**/*.graphql" \
4  --exclude "operations/**/*.test.graphql"

To change the manifest output path, use --manifest-path (-m):

1rover persisted-queries generate \
2  --manifest-path ./dist/persisted-query-manifest.json

When you write the manifest to a file, add Rover's global --format json flag to report the output path and operation count in Rover's standard JSON envelope:

1rover persisted-queries generate \
2  --manifest-path persisted-query-manifest.json --format json

1{
2  "json_version": "1",
3  "data": {
4    "path": "persisted-query-manifest.json",
5    "operation_count": 1,
6    "success": true
7  },
8  "error": null
9}

Without --manifest-path, the data field contains the full manifest instead of the path and count.

The generate command doesn't write clientName values into the manifest. To associate every generated operation with a client name, use persisted-queries publish --for-client-name.

Publish a PQM

persisted-queries publish

This command requires authenticating Rover with GraphOS.

You can use Rover to publish a PQM for any client to any existing PQL.

Run the persisted-queries publish command, like so:

1rover persisted-queries publish my-graph@my-variant \
2  --manifest ./persisted-query-manifest.json

• The my-graph@my-variant argument is the graph ref of any variant the PQL is linked to.

  • Graph refs have the format graph-id@variant-name.

• Use the --manifest option to provide the path to the manifest you want to publish.

Instead of my-graph@my-variant, you can combine the --graph-id and --list-id options to specify the PQL you want to publish to:

1rover persisted-queries publish \
2  --graph-id my_graph --list-id dc4b4040-30fc-4bd1-94a3-5fc1c722acc9 \
3  --manifest ./persisted-query-manifest.json

• Use --graph-id to provide the graph's ID

• Use --list-id to provide the PQL's UUID

The persisted-queries publish command does the following:

1. Publishes all operations in the provided manifest file to the PQL linked to the specified variant, or to the specified PQL.

   • Publishing a manifest to a PQL is additive. Any existing entries in the PQL remain.

   • You can use the --for-client-name CLIENT-NAME option to associate all operations in the manifest with a given client name, or you can specify clientName on each operation in the JSON file.

   • If you publish an operation with the same id and clientName but different details from an existing entry in the PQL, the entire publish command fails with an error.

2. Updates any other variants that the PQL is applied to so that routers associated with those variants can fetch their updated PQL.

As with generating manifests, it's best to execute this command in your CI/CD pipeline to publish new operations as part of your app release process. This command requires your API key to have the Graph Admin or Persisted Query Publisher role; the latter is a role specifically designed to work with this command without exposing unnecessary information about your graph to users of the API key.

Relay support

The rover persisted-queries command supports publishing persisted queries generated by the Relay compiler.

1. Configure the Relay compiler to output a JSON operation manifest to a specified location according to their documentation.

2. Use the persisted-queries publish command to publish the manifest to Apollo GraphOS. The command usage is the same as when publishing Apollo-generated manifests, but you must include the --manifest-format relay argument:

1rover persisted-queries publish my-graph@my-variant \
2  --manifest ./persisted-queries.json \
3  --manifest-format relay