2023-12-19 12:04:02 +03:00
|
|
|
# Hasura GraphQL Engine V3
|
|
|
|
|
|
|
|
[![Docs](https://img.shields.io/badge/docs-v3.x-brightgreen.svg?style=flat)](https://hasura.io/docs/3.0/index/)
|
|
|
|
|
Format everything with Prettier. (#530)
I found myself wanting to rewrite JSON files with `sed`. The problem is,
then I want to run a formatter over them afterwards, and this will
change the whole file, not just the area I touched.
I would like to propose the nuclear option in remedying this: format
everything now. This is a very large change that should make it easier
to keep files to a consistent format in the future.
I have chosen to use Prettier for this because (a) it has a useful
`--write` command and (b) it also does GraphQL, Markdown, YAML, etc.
I've elected to exclude two sets of files:
1. `crates/custom-connector/data/*.json`, because they are actually
multiple JSON objects, one per line, which Prettier cannot parse.
2. `crates/lang-graphql/tests/**/*.graphql`, because it contains invalid
GraphQL, and the parser is intended to work with strangely-formatted
GraphQL.
The main changes are standardizing whitespace, adding a newline at the
end of files, and putting JSON arrays on one line when they fit.
V3_GIT_ORIGIN_REV_ID: 92d4a535c34a3cc00721e8ddc6f17c5717e8ff76
2024-04-30 17:58:09 +03:00
|
|
|
Hasura V3 is the API execution engine, based over the Open Data Domain
|
|
|
|
Specification (OpenDD spec) and Native Data Connector Specifications (NDC spec),
|
2024-05-03 00:39:42 +03:00
|
|
|
which powers the Hasura Data Delivery Network (DDN). The v3-engine expects to
|
|
|
|
run against an OpenDDS metadata file and exposes a GraphQL endpoint according to
|
|
|
|
the specified metadata. The v3-engine needs a data connector to run alongside,
|
|
|
|
for the execution of data source specific queries.
|
2023-12-19 12:04:02 +03:00
|
|
|
|
|
|
|
## Data connectors
|
|
|
|
|
2024-05-03 00:39:42 +03:00
|
|
|
Hasura v3-engine does not execute queries directly - instead it sends IR
|
|
|
|
(abstracted, intermediate query) to NDC agents (aka data connectors). To run
|
Format everything with Prettier. (#530)
I found myself wanting to rewrite JSON files with `sed`. The problem is,
then I want to run a formatter over them afterwards, and this will
change the whole file, not just the area I touched.
I would like to propose the nuclear option in remedying this: format
everything now. This is a very large change that should make it easier
to keep files to a consistent format in the future.
I have chosen to use Prettier for this because (a) it has a useful
`--write` command and (b) it also does GraphQL, Markdown, YAML, etc.
I've elected to exclude two sets of files:
1. `crates/custom-connector/data/*.json`, because they are actually
multiple JSON objects, one per line, which Prettier cannot parse.
2. `crates/lang-graphql/tests/**/*.graphql`, because it contains invalid
GraphQL, and the parser is intended to work with strangely-formatted
GraphQL.
The main changes are standardizing whitespace, adding a newline at the
end of files, and putting JSON arrays on one line when they fit.
V3_GIT_ORIGIN_REV_ID: 92d4a535c34a3cc00721e8ddc6f17c5717e8ff76
2024-04-30 17:58:09 +03:00
|
|
|
queries on a database, we'll need to run the data connector that supports the
|
|
|
|
database.
|
2023-12-19 12:04:02 +03:00
|
|
|
|
2024-05-03 00:39:42 +03:00
|
|
|
Available data connectors are listed at the
|
Format everything with Prettier. (#530)
I found myself wanting to rewrite JSON files with `sed`. The problem is,
then I want to run a formatter over them afterwards, and this will
change the whole file, not just the area I touched.
I would like to propose the nuclear option in remedying this: format
everything now. This is a very large change that should make it easier
to keep files to a consistent format in the future.
I have chosen to use Prettier for this because (a) it has a useful
`--write` command and (b) it also does GraphQL, Markdown, YAML, etc.
I've elected to exclude two sets of files:
1. `crates/custom-connector/data/*.json`, because they are actually
multiple JSON objects, one per line, which Prettier cannot parse.
2. `crates/lang-graphql/tests/**/*.graphql`, because it contains invalid
GraphQL, and the parser is intended to work with strangely-formatted
GraphQL.
The main changes are standardizing whitespace, adding a newline at the
end of files, and putting JSON arrays on one line when they fit.
V3_GIT_ORIGIN_REV_ID: 92d4a535c34a3cc00721e8ddc6f17c5717e8ff76
2024-04-30 17:58:09 +03:00
|
|
|
[Connector Hub](https://hasura.io/connectors)
|
2023-12-19 12:04:02 +03:00
|
|
|
|
Format everything with Prettier. (#530)
I found myself wanting to rewrite JSON files with `sed`. The problem is,
then I want to run a formatter over them afterwards, and this will
change the whole file, not just the area I touched.
I would like to propose the nuclear option in remedying this: format
everything now. This is a very large change that should make it easier
to keep files to a consistent format in the future.
I have chosen to use Prettier for this because (a) it has a useful
`--write` command and (b) it also does GraphQL, Markdown, YAML, etc.
I've elected to exclude two sets of files:
1. `crates/custom-connector/data/*.json`, because they are actually
multiple JSON objects, one per line, which Prettier cannot parse.
2. `crates/lang-graphql/tests/**/*.graphql`, because it contains invalid
GraphQL, and the parser is intended to work with strangely-formatted
GraphQL.
The main changes are standardizing whitespace, adding a newline at the
end of files, and putting JSON arrays on one line when they fit.
V3_GIT_ORIGIN_REV_ID: 92d4a535c34a3cc00721e8ddc6f17c5717e8ff76
2024-04-30 17:58:09 +03:00
|
|
|
For local development, we use the reference agent implementation that is a part
|
|
|
|
of the [NDC spec](https://github.com/hasura/ndc-spec).
|
2023-12-19 12:04:02 +03:00
|
|
|
|
|
|
|
To start the reference agent only, you can do:
|
Format everything with Prettier. (#530)
I found myself wanting to rewrite JSON files with `sed`. The problem is,
then I want to run a formatter over them afterwards, and this will
change the whole file, not just the area I touched.
I would like to propose the nuclear option in remedying this: format
everything now. This is a very large change that should make it easier
to keep files to a consistent format in the future.
I have chosen to use Prettier for this because (a) it has a useful
`--write` command and (b) it also does GraphQL, Markdown, YAML, etc.
I've elected to exclude two sets of files:
1. `crates/custom-connector/data/*.json`, because they are actually
multiple JSON objects, one per line, which Prettier cannot parse.
2. `crates/lang-graphql/tests/**/*.graphql`, because it contains invalid
GraphQL, and the parser is intended to work with strangely-formatted
GraphQL.
The main changes are standardizing whitespace, adding a newline at the
end of files, and putting JSON arrays on one line when they fit.
V3_GIT_ORIGIN_REV_ID: 92d4a535c34a3cc00721e8ddc6f17c5717e8ff76
2024-04-30 17:58:09 +03:00
|
|
|
|
2023-12-19 12:04:02 +03:00
|
|
|
```sh
|
2024-01-30 20:41:48 +03:00
|
|
|
docker compose up reference_agent
|
2023-12-19 12:04:02 +03:00
|
|
|
```
|
Format everything with Prettier. (#530)
I found myself wanting to rewrite JSON files with `sed`. The problem is,
then I want to run a formatter over them afterwards, and this will
change the whole file, not just the area I touched.
I would like to propose the nuclear option in remedying this: format
everything now. This is a very large change that should make it easier
to keep files to a consistent format in the future.
I have chosen to use Prettier for this because (a) it has a useful
`--write` command and (b) it also does GraphQL, Markdown, YAML, etc.
I've elected to exclude two sets of files:
1. `crates/custom-connector/data/*.json`, because they are actually
multiple JSON objects, one per line, which Prettier cannot parse.
2. `crates/lang-graphql/tests/**/*.graphql`, because it contains invalid
GraphQL, and the parser is intended to work with strangely-formatted
GraphQL.
The main changes are standardizing whitespace, adding a newline at the
end of files, and putting JSON arrays on one line when they fit.
V3_GIT_ORIGIN_REV_ID: 92d4a535c34a3cc00721e8ddc6f17c5717e8ff76
2024-04-30 17:58:09 +03:00
|
|
|
|
2024-05-03 00:39:42 +03:00
|
|
|
## Run v3-engine (with Postgres)
|
Format everything with Prettier. (#530)
I found myself wanting to rewrite JSON files with `sed`. The problem is,
then I want to run a formatter over them afterwards, and this will
change the whole file, not just the area I touched.
I would like to propose the nuclear option in remedying this: format
everything now. This is a very large change that should make it easier
to keep files to a consistent format in the future.
I have chosen to use Prettier for this because (a) it has a useful
`--write` command and (b) it also does GraphQL, Markdown, YAML, etc.
I've elected to exclude two sets of files:
1. `crates/custom-connector/data/*.json`, because they are actually
multiple JSON objects, one per line, which Prettier cannot parse.
2. `crates/lang-graphql/tests/**/*.graphql`, because it contains invalid
GraphQL, and the parser is intended to work with strangely-formatted
GraphQL.
The main changes are standardizing whitespace, adding a newline at the
end of files, and putting JSON arrays on one line when they fit.
V3_GIT_ORIGIN_REV_ID: 92d4a535c34a3cc00721e8ddc6f17c5717e8ff76
2024-04-30 17:58:09 +03:00
|
|
|
|
2024-05-03 00:39:42 +03:00
|
|
|
### Building with Docker
|
|
|
|
|
|
|
|
You can also start v3-engine, along with a Postgres data connector and Jaeger
|
|
|
|
for tracing using Docker:
|
2023-12-19 12:04:02 +03:00
|
|
|
|
|
|
|
```sh
|
2024-10-02 13:49:46 +03:00
|
|
|
docker compose up
|
Format everything with Prettier. (#530)
I found myself wanting to rewrite JSON files with `sed`. The problem is,
then I want to run a formatter over them afterwards, and this will
change the whole file, not just the area I touched.
I would like to propose the nuclear option in remedying this: format
everything now. This is a very large change that should make it easier
to keep files to a consistent format in the future.
I have chosen to use Prettier for this because (a) it has a useful
`--write` command and (b) it also does GraphQL, Markdown, YAML, etc.
I've elected to exclude two sets of files:
1. `crates/custom-connector/data/*.json`, because they are actually
multiple JSON objects, one per line, which Prettier cannot parse.
2. `crates/lang-graphql/tests/**/*.graphql`, because it contains invalid
GraphQL, and the parser is intended to work with strangely-formatted
GraphQL.
The main changes are standardizing whitespace, adding a newline at the
end of files, and putting JSON arrays on one line when they fit.
V3_GIT_ORIGIN_REV_ID: 92d4a535c34a3cc00721e8ddc6f17c5717e8ff76
2024-04-30 17:58:09 +03:00
|
|
|
```
|
2023-12-19 12:04:02 +03:00
|
|
|
|
2024-10-02 13:49:46 +03:00
|
|
|
Open <http://localhost:3000> for GraphiQL, or <http://localhost:4002> to view
|
2024-05-03 00:39:42 +03:00
|
|
|
traces in Jaeger.
|
|
|
|
|
|
|
|
Note: you'll need to add `{"x-hasura-role": "admin"}` to the Headers section to
|
|
|
|
run queries from GraphiQL.
|
Format everything with Prettier. (#530)
I found myself wanting to rewrite JSON files with `sed`. The problem is,
then I want to run a formatter over them afterwards, and this will
change the whole file, not just the area I touched.
I would like to propose the nuclear option in remedying this: format
everything now. This is a very large change that should make it easier
to keep files to a consistent format in the future.
I have chosen to use Prettier for this because (a) it has a useful
`--write` command and (b) it also does GraphQL, Markdown, YAML, etc.
I've elected to exclude two sets of files:
1. `crates/custom-connector/data/*.json`, because they are actually
multiple JSON objects, one per line, which Prettier cannot parse.
2. `crates/lang-graphql/tests/**/*.graphql`, because it contains invalid
GraphQL, and the parser is intended to work with strangely-formatted
GraphQL.
The main changes are standardizing whitespace, adding a newline at the
end of files, and putting JSON arrays on one line when they fit.
V3_GIT_ORIGIN_REV_ID: 92d4a535c34a3cc00721e8ddc6f17c5717e8ff76
2024-04-30 17:58:09 +03:00
|
|
|
|
|
|
|
[NDC Postgres](https://github.com/hasura/ndc-postgres) is the official connector
|
|
|
|
by Hasura for Postgres Database. For running V3 engine for GraphQL API on
|
|
|
|
Postgres, you need to run NDC Postgres Connector and have a `metadata.json` file
|
|
|
|
that is authored specifically for your Postgres database and models (tables,
|
|
|
|
views, functions).
|
2023-12-19 12:04:02 +03:00
|
|
|
|
|
|
|
The recommended way to author `metadata.json` for Postgres, is via Hasura DDN.
|
|
|
|
|
Format everything with Prettier. (#530)
I found myself wanting to rewrite JSON files with `sed`. The problem is,
then I want to run a formatter over them afterwards, and this will
change the whole file, not just the area I touched.
I would like to propose the nuclear option in remedying this: format
everything now. This is a very large change that should make it easier
to keep files to a consistent format in the future.
I have chosen to use Prettier for this because (a) it has a useful
`--write` command and (b) it also does GraphQL, Markdown, YAML, etc.
I've elected to exclude two sets of files:
1. `crates/custom-connector/data/*.json`, because they are actually
multiple JSON objects, one per line, which Prettier cannot parse.
2. `crates/lang-graphql/tests/**/*.graphql`, because it contains invalid
GraphQL, and the parser is intended to work with strangely-formatted
GraphQL.
The main changes are standardizing whitespace, adding a newline at the
end of files, and putting JSON arrays on one line when they fit.
V3_GIT_ORIGIN_REV_ID: 92d4a535c34a3cc00721e8ddc6f17c5717e8ff76
2024-04-30 17:58:09 +03:00
|
|
|
Follow the
|
|
|
|
[Hasura DDN Guide](https://hasura.io/docs/3.0/getting-started/overview/) to
|
|
|
|
create a Hasura DDN project, connect your cloud or local Postgres Database
|
|
|
|
(Hasura DDN provides a secure tunnel mechanism to connect your local database
|
|
|
|
easily), and model your GraphQL API. You can then download the authored
|
|
|
|
metadata.json and use the following steps to run GraphQL API on your local
|
|
|
|
Hasura V3 engine.
|
2023-12-19 12:04:02 +03:00
|
|
|
|
|
|
|
## Running tests
|
|
|
|
|
|
|
|
To run the test suite, you need to docker login to `ghcr.io` first:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
docker login -u <username> -p <token> ghcr.io
|
|
|
|
```
|
|
|
|
|
Format everything with Prettier. (#530)
I found myself wanting to rewrite JSON files with `sed`. The problem is,
then I want to run a formatter over them afterwards, and this will
change the whole file, not just the area I touched.
I would like to propose the nuclear option in remedying this: format
everything now. This is a very large change that should make it easier
to keep files to a consistent format in the future.
I have chosen to use Prettier for this because (a) it has a useful
`--write` command and (b) it also does GraphQL, Markdown, YAML, etc.
I've elected to exclude two sets of files:
1. `crates/custom-connector/data/*.json`, because they are actually
multiple JSON objects, one per line, which Prettier cannot parse.
2. `crates/lang-graphql/tests/**/*.graphql`, because it contains invalid
GraphQL, and the parser is intended to work with strangely-formatted
GraphQL.
The main changes are standardizing whitespace, adding a newline at the
end of files, and putting JSON arrays on one line when they fit.
V3_GIT_ORIGIN_REV_ID: 92d4a535c34a3cc00721e8ddc6f17c5717e8ff76
2024-04-30 17:58:09 +03:00
|
|
|
where `username` is your github username, and `token` is your github PAT. The
|
|
|
|
PAT needs to have the `read:packages` scope and `Hasura SSO` configured. See
|
|
|
|
[this](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-with-a-personal-access-token-classic)
|
|
|
|
for more details.
|
2023-12-19 12:04:02 +03:00
|
|
|
|
2024-10-02 13:49:46 +03:00
|
|
|
Running `just watch` will start the Docker dependencies, build the engine, and
|
|
|
|
run all the tests.
|
2023-12-19 12:04:02 +03:00
|
|
|
|
2024-10-02 13:49:46 +03:00
|
|
|
Alternatively, run the tests once with `just test`
|
2023-12-19 12:04:02 +03:00
|
|
|
|
|
|
|
### Updating goldenfiles
|
|
|
|
|
Format everything with Prettier. (#530)
I found myself wanting to rewrite JSON files with `sed`. The problem is,
then I want to run a formatter over them afterwards, and this will
change the whole file, not just the area I touched.
I would like to propose the nuclear option in remedying this: format
everything now. This is a very large change that should make it easier
to keep files to a consistent format in the future.
I have chosen to use Prettier for this because (a) it has a useful
`--write` command and (b) it also does GraphQL, Markdown, YAML, etc.
I've elected to exclude two sets of files:
1. `crates/custom-connector/data/*.json`, because they are actually
multiple JSON objects, one per line, which Prettier cannot parse.
2. `crates/lang-graphql/tests/**/*.graphql`, because it contains invalid
GraphQL, and the parser is intended to work with strangely-formatted
GraphQL.
The main changes are standardizing whitespace, adding a newline at the
end of files, and putting JSON arrays on one line when they fit.
V3_GIT_ORIGIN_REV_ID: 92d4a535c34a3cc00721e8ddc6f17c5717e8ff76
2024-04-30 17:58:09 +03:00
|
|
|
There are some tests where we compare the output of the test against an expected
|
|
|
|
golden file. If you make some changes which expectedly change the goldenfile,
|
|
|
|
you can regenerate them like this:
|
2023-12-19 12:04:02 +03:00
|
|
|
|
|
|
|
```sh
|
2024-10-02 13:49:46 +03:00
|
|
|
just update-golden-files
|
2023-12-19 12:04:02 +03:00
|
|
|
```
|
|
|
|
|
2024-10-02 13:49:46 +03:00
|
|
|
Some other tests use `insta`, and these can be reviewed with
|
|
|
|
`cargo insta review`. If the `cargo insta` command cannot be found, install it
|
|
|
|
with `cargo install cargo-insta`.
|
2023-12-19 12:04:02 +03:00
|
|
|
|
|
|
|
## Run benchmarks
|
|
|
|
|
Format everything with Prettier. (#530)
I found myself wanting to rewrite JSON files with `sed`. The problem is,
then I want to run a formatter over them afterwards, and this will
change the whole file, not just the area I touched.
I would like to propose the nuclear option in remedying this: format
everything now. This is a very large change that should make it easier
to keep files to a consistent format in the future.
I have chosen to use Prettier for this because (a) it has a useful
`--write` command and (b) it also does GraphQL, Markdown, YAML, etc.
I've elected to exclude two sets of files:
1. `crates/custom-connector/data/*.json`, because they are actually
multiple JSON objects, one per line, which Prettier cannot parse.
2. `crates/lang-graphql/tests/**/*.graphql`, because it contains invalid
GraphQL, and the parser is intended to work with strangely-formatted
GraphQL.
The main changes are standardizing whitespace, adding a newline at the
end of files, and putting JSON arrays on one line when they fit.
V3_GIT_ORIGIN_REV_ID: 92d4a535c34a3cc00721e8ddc6f17c5717e8ff76
2024-04-30 17:58:09 +03:00
|
|
|
The benchmarks operate against the reference agent using the same test cases as
|
|
|
|
the test suite, and need a similar setup.
|
2023-12-19 12:04:02 +03:00
|
|
|
|
|
|
|
To run benchmarks for the lexer, parser and validation:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
cargo bench -p lang-graphql "lexer"
|
|
|
|
cargo bench -p lang-graphql "parser"
|
|
|
|
cargo bench -p lang-graphql "validation/.*"
|
|
|
|
```
|