mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-15 09:22:43 +03:00
721ea64cc0
<!-- The PR description should answer 2 important questions: --> ### What Running `docker compose up` is a generally accepted way to try a project out, and ours was broken. This fixes ours so that running `docker compose up` builds engine and runs it with a sample schema for `ndc-postgres`. This will allow users to get a flavour for DDN as a consumer. We also remove a bunch of outdated and frankly confusing stuff from the readme, instead directing users to the docs. V3_GIT_ORIGIN_REV_ID: 77c817d1738efafe4027c7d0da1aa21bcf78dd9d
108 lines
3.7 KiB
Markdown
108 lines
3.7 KiB
Markdown
# Hasura GraphQL Engine V3
|
|
|
|
[](https://hasura.io/docs/3.0/index/)
|
|
|
|
Hasura V3 is the API execution engine, based over the Open Data Domain
|
|
Specification (OpenDD spec) and Native Data Connector Specifications (NDC spec),
|
|
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.
|
|
|
|
## Data connectors
|
|
|
|
Hasura v3-engine does not execute queries directly - instead it sends IR
|
|
(abstracted, intermediate query) to NDC agents (aka data connectors). To run
|
|
queries on a database, we'll need to run the data connector that supports the
|
|
database.
|
|
|
|
Available data connectors are listed at the
|
|
[Connector Hub](https://hasura.io/connectors)
|
|
|
|
For local development, we use the reference agent implementation that is a part
|
|
of the [NDC spec](https://github.com/hasura/ndc-spec).
|
|
|
|
To start the reference agent only, you can do:
|
|
|
|
```sh
|
|
docker compose up reference_agent
|
|
```
|
|
|
|
## Run v3-engine (with Postgres)
|
|
|
|
### Building with Docker
|
|
|
|
You can also start v3-engine, along with a Postgres data connector and Jaeger
|
|
for tracing using Docker:
|
|
|
|
```sh
|
|
docker compose up
|
|
```
|
|
|
|
Open <http://localhost:3000> for GraphiQL, or <http://localhost:4002> to view
|
|
traces in Jaeger.
|
|
|
|
Note: you'll need to add `{"x-hasura-role": "admin"}` to the Headers section to
|
|
run queries from GraphiQL.
|
|
|
|
[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).
|
|
|
|
The recommended way to author `metadata.json` for Postgres, is via Hasura DDN.
|
|
|
|
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.
|
|
|
|
## 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
|
|
```
|
|
|
|
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.
|
|
|
|
Running `just watch` will start the Docker dependencies, build the engine, and
|
|
run all the tests.
|
|
|
|
Alternatively, run the tests once with `just test`
|
|
|
|
### Updating goldenfiles
|
|
|
|
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:
|
|
|
|
```sh
|
|
just update-golden-files
|
|
```
|
|
|
|
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`.
|
|
|
|
## Run benchmarks
|
|
|
|
The benchmarks operate against the reference agent using the same test cases as
|
|
the test suite, and need a similar setup.
|
|
|
|
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/.*"
|
|
```
|