hasura/graphql-engine
1
0
Fork 0
mirror of https://github.com/hasura/graphql-engine.git synced 2024-12-14 17:02:49 +03:00
Code Issues Projects Releases Wiki Activity

Merge branch 'master' into webdeb-remove-dublicate-section

Browse Source
This commit is contained in:
Marion Schleifer 2020-09-04 07:36:08 +02:00 committed by GitHub
commit c3c9e2983e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
534 changed files with 3068 additions and 494 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
.circleci/config.yml
View File

@ -1,9 +1,7 @@
# anchor refs to be used elsewhere
refs:
constants:
# TODO upload to hasura docker hub:
# - &server_builder_image hasura/graphql-engine-server-builder:2020-01-14
- &server_builder_image jberryman/graphql-engine-server-builder-8.10:2020-04-29
- &server_builder_image hasura/graphql-engine-server-builder:2020-08-26
skip_job_on_ciignore: &skip_job_on_ciignore
run:
name: checking if job should be terminated or not
@ -165,10 +163,10 @@ jobs:
- checkout
- restore_cache:
keys:
- cabal-store-v2-{{ checksum "server/cabal.project" }}-{{ checksum "server/graphql-engine.cabal" }}-{{ checksum "server/cabal.project.freeze" }}
- cabal-store-v2-{{ checksum "server/cabal.project" }}-{{ checksum "server/graphql-engine.cabal" }}-
- cabal-store-v2-{{ checksum "server/cabal.project" }}-
- cabal-store-v2-
- cabal-store-v3-{{ checksum "server/cabal.project" }}-{{ checksum "server/graphql-engine.cabal" }}-{{ checksum "server/cabal.project.freeze" }}
- cabal-store-v3-{{ checksum "server/cabal.project" }}-{{ checksum "server/graphql-engine.cabal" }}-
- cabal-store-v3-{{ checksum "server/cabal.project" }}-
- cabal-store-v3-
- run:
name: Install latest postgresql client tools
command: |
@ -187,7 +185,7 @@ jobs:
make enable_coverage=true ci-build
fi
- save_cache:
key: cabal-store-v2-{{ checksum "server/cabal.project" }}-{{ checksum "server/graphql-engine.cabal" }}-{{ checksum "server/cabal.project.freeze" }}
key: cabal-store-v3-{{ checksum "server/cabal.project" }}-{{ checksum "server/graphql-engine.cabal" }}-{{ checksum "server/cabal.project.freeze" }}
paths:
- ~/.cabal/packages
- ~/.cabal/store

9
.circleci/server-builder.dockerfile
View File

@ -1,8 +1,6 @@
# Don't update this without updating the
# packager imager of graphql-engine
FROM phadej/ghc:8.10.1-stretch
# TODO https://github.com/haskell/docker-haskell/issues/17
#FROM haskell:8.10.1
FROM haskell:8.10.2-stretch
ARG docker_ver="17.09.0-ce"
ARG postgres_ver="12"
@ -14,7 +12,10 @@ RUN apt-get -y update \
&& echo "deb http://apt.postgresql.org/pub/repos/apt/ stretch-pgdg main" > /etc/apt/sources.list.d/pgdg.list \
&& curl -s https://www.postgresql.org/media/keys/ACCC4CF8.asc | apt-key add - \
&& apt-get -y update \
&& apt-get install -y g++ gcc libc6-dev libpq-dev libffi-dev libgmp-dev make xz-utils zlib1g-dev git gnupg upx netcat python3 python3-pip postgresql-client-${postgres_ver} postgresql-client-common \
&& apt-get install -y \
g++ gcc git gnupg libc6-dev libffi-dev libgmp-dev libkrb5-dev \
libpq-dev libssl-dev make netcat postgresql-client-${postgres_ver} \
postgresql-client-common python3 python3-pip upx xz-utils zlib1g-dev \
&& curl -sL https://deb.nodesource.com/setup_${node_ver} | bash - \
&& apt-get install -y nodejs \
&& curl -Lo /tmp/docker-${docker_ver}.tgz https://download.docker.com/linux/static/stable/x86_64/docker-${docker_ver}.tgz \

45
.circleci/test-server.sh
View File

@ -383,6 +383,51 @@ kill_hge_servers
unset HASURA_GRAPHQL_JWT_SECRET
# test JWT with Claims map
echo -e "\n$(time_elapsed): <########## TEST GRAPHQL-ENGINE WITH ADMIN SECRET AND JWT (with claims_map and values are json path) #####################################>\n"
TEST_TYPE="jwt-claims-map-with-json-path-values"
export HASURA_GRAPHQL_JWT_SECRET="$(jq -n --arg key "$(cat $OUTPUT_FOLDER/ssl/jwt_public.key)" '{ type: "RS512", key: $key , claims_map: {"x-hasura-user-id": {"path":"$.['"'"'https://myapp.com/jwt/claims'"'"'].user.id"}, "x-hasura-allowed-roles": {"path":"$.['"'"'https://myapp.com/jwt/claims'"'"'].role.allowed"}, "x-hasura-default-role": {"path":"$.['"'"'https://myapp.com/jwt/claims'"'"'].role.default"}}}')"
run_hge_with_args serve
wait_for_port 8080
pytest -n 1 -vv --hge-urls "$HGE_URL" --pg-urls "$HASURA_GRAPHQL_DATABASE_URL" --hge-key="$HASURA_GRAPHQL_ADMIN_SECRET" --hge-jwt-key-file="$OUTPUT_FOLDER/ssl/jwt_private.key" --hge-jwt-conf="$HASURA_GRAPHQL_JWT_SECRET" test_jwt_claims_map.py::TestJWTClaimsMapBasic
kill_hge_servers
unset HASURA_GRAPHQL_JWT_SECRET
echo -e "\n$(time_elapsed): <########## TEST GRAPHQL-ENGINE WITH ADMIN SECRET AND JWT (with claims_map and values are json path with default values set) #####################################>\n"
TEST_TYPE="jwt-claims-map-with-json-path-values-with-default-values"
export HASURA_GRAPHQL_JWT_SECRET="$(jq -n --arg key "$(cat $OUTPUT_FOLDER/ssl/jwt_public.key)" '{ type: "RS512", key: $key , claims_map: {"x-hasura-user-id": {"path":"$.['"'"'https://myapp.com/jwt/claims'"'"'].user.id", "default":"1"}, "x-hasura-allowed-roles": {"path":"$.['"'"'https://myapp.com/jwt/claims'"'"'].role.allowed", "default":["user","editor"]}, "x-hasura-default-role": {"path":"$.['"'"'https://myapp.com/jwt/claims'"'"'].role.default","default":"user"}}}')"
run_hge_with_args serve
wait_for_port 8080
pytest -n 1 -vv --hge-urls "$HGE_URL" --pg-urls "$HASURA_GRAPHQL_DATABASE_URL" --hge-key="$HASURA_GRAPHQL_ADMIN_SECRET" --hge-jwt-key-file="$OUTPUT_FOLDER/ssl/jwt_private.key" --hge-jwt-conf="$HASURA_GRAPHQL_JWT_SECRET" test_jwt_claims_map.py::TestJWTClaimsMapBasic
kill_hge_servers
unset HASURA_GRAPHQL_JWT_SECRET
echo -e "\n$(time_elapsed): <########## TEST GRAPHQL-ENGINE WITH ADMIN SECRET AND JWT (with claims_map and values are literal values) #####################################>\n"
TEST_TYPE="jwt-claims-map-with-literal-values"
export HASURA_GRAPHQL_JWT_SECRET="$(jq -n --arg key "$(cat $OUTPUT_FOLDER/ssl/jwt_public.key)" '{ type: "RS512", key: $key , claims_map: {"x-hasura-user-id": {"path":"$.['"'"'https://myapp.com/jwt/claims'"'"'].user.id"}, "x-hasura-allowed-roles": ["user","editor"], "x-hasura-default-role": "user","x-hasura-custom-header":"custom-value"}}')"
run_hge_with_args serve
wait_for_port 8080
pytest -n 1 -vv --hge-urls "$HGE_URL" --pg-urls "$HASURA_GRAPHQL_DATABASE_URL" --hge-key="$HASURA_GRAPHQL_ADMIN_SECRET" --hge-jwt-key-file="$OUTPUT_FOLDER/ssl/jwt_private.key" --hge-jwt-conf="$HASURA_GRAPHQL_JWT_SECRET" test_jwt_claims_map.py::TestJWTClaimsMapWithStaticHasuraClaimsMapValues
kill_hge_servers
unset HASURA_GRAPHQL_JWT_SECRET
# test with CORS modes
echo -e "\n$(time_elapsed): <########## TEST GRAPHQL-ENGINE WITH CORS DOMAINS ########>\n"

37
CHANGELOG.md
View File

@ -2,6 +2,41 @@
## Next release
### Server - Support for mapping session variables to default JWT claims
Some auth providers do not let users add custom claims in JWT. In such cases, the server can take a JWT configuration option called `claims_map` to specify a mapping of Hasura session variables to values in existing claims via JSONPath or literal values.
Example:-
Consider the following JWT claim:
```
{
"sub": "1234567890",
"name": "John Doe",
"admin": true,
"iat": 1516239022,
"user": {
"id": "ujdh739kd",
"appRoles": ["user", "editor"]
}
}
```
The corresponding JWT config can be:
```
{
"type":"RS512",
"key": "<The public Key>",
"claims_map": {
"x-hasura-allowed-roles": {"path":"$.user.appRoles"},
"x-hasura-default-role": {"path":"$.user.appRoles[0]","default":"user"},
"x-hasura-user-id": {"path":"$.user.id"}
}
}
```
### Breaking changes
This release contains the [PDV refactor (#4111)](https://github.com/hasura/graphql-engine/pull/4111), a significant rewrite of the internals of the server, which did include some breaking changes:
@ -11,7 +46,6 @@ This release contains the [PDV refactor (#4111)](https://github.com/hasura/graph
- if a query selects table `bar` through table `foo` via a relationship, the required permissions headers will be the union of the required headers of table `foo` and table `bar` (we used to only check the headers of the root table);
- if an insert does not have an `on_conflict` clause, it will not require the update permissions headers.
### Bug fixes and improvements
(Add entries here in the order of: server, console, cli, docs, others)
@ -19,6 +53,7 @@ This release contains the [PDV refactor (#4111)](https://github.com/hasura/graph
- server: some mutations that cannot be performed will no longer be in the schema (for instance, `delete_by_pk` mutations won't be shown to users that do not have select permissions on all primary keys) (#4111)
- server: miscellaneous description changes (#4111)
- server: treat the absence of `backend_only` configuration and `backend_only: false` equally (closing #5059) (#4111)
- server: allow remote relationships joining `type` column with `[type]` input argument as spec allows this coercion (fixes #5133)
- console: allow user to cascade Postgres dependencies when dropping Postgres objects (close #5109) (#5248)
- console: mark inconsistent remote schemas in the UI (close #5093) (#5181)
- cli: add missing global flags for seeds command (#5565)

18
community/sample-apps/svelte-apollo/README.md
View File

@ -1,22 +1,19 @@
# svelte-graphql-app
A sample [Svelte 3](https://svelte.dev) app to demonstrate usage of GraphQL Queries, Mutations and Subscriptions with [svelte-apollo](https://github.com/timhall/svelte-apollo), Hasura GraphQL engine and Postgres as database. Forked from the standard svelte [template](https://github.com/sveltejs/template)
A sample [Svelte 3](https://svelte.dev) app to demonstrate usage of GraphQL Queries, Mutations and Subscriptions with [svelte-apollo](https://github.com/timhall/svelte-apollo), Hasura Cloud and Postgres as database. Forked from the standard svelte [template](https://github.com/sveltejs/template)
[![Edit svelte-graphql](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/github/hasura/graphql-engine/tree/master/community/sample-apps/svelte-apollo?fontsize=14)
## Deploy Hasura
## Create new Hasura Cloud project
- Deploy Postgres and GraphQL Engine on Heroku:
- Create new Hasura Cloud project with the `Try a free database with Heroku` option.
[![Deploy to
heroku](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/hasura/graphql-engine-heroku)
Please check out our [docs](https://hasura.io/docs/cloud/1.0/manual/getting-started/index.html) for the detailed steps.
Please checkout our [docs](https://hasura.io/docs/1.0/graphql/manual/deployment/index.html) for other deployment methods
- Get the Heroku app URL (say `my-app.herokuapp.com`)
- Get the app URL (something like `https://<my-project-name>.hasura.app`)
- Create `author` table:
Open Hasura console: visit https://my-app.herokuapp.com on a browser
Open your Hasura Cloud project's console: visit `https://<my-project-name>.hasura.app` on a browser
Navigate to `Data` section in the top nav bar and create a table as follows:
![Create author table](../gatsby-postgres-graphql/assets/add_table.jpg)
@ -72,7 +69,7 @@ npm install
});
```
Replace the `uri` argument with your Hasura GraphQL Endpoint for both `wsLink` and `httpLink`
Replace the `uri` argument with your Hasura GraphQL Endpoint (something like `https://<my-project-name>.hasura.app/v1/graphql`) for both `wsLink` and `httpLink`
Start [Rollup](https://rollupjs.org):
@ -99,4 +96,3 @@ now
```
This will deploy the app on Now 2.0 Platform and you have the Svetle app running live :)

2
console/src/components/Services/Data/Schema/Schema.js
View File

@ -692,7 +692,7 @@ class Schema extends Component {
className={styles.add_mar_top}
key={'non-trackable-custom-functions'}
>
<CollapsibleToggle title={heading} isOpen>
<CollapsibleToggle title={heading}>
<div className={`${styles.padd_left_remove} col-xs-12`}>
{getNonTrackableFuncList()}
</div>

2
console/src/components/Services/Data/TableRelationships/RelationshipEditor.js
View File

@ -112,11 +112,11 @@ class RelationshipEditor extends React.Component {
<div className={styles.display_flex}>
{getEditBtn()}
<b className={styles.textNoNewLine}>{relName}</b>
</div>
<GqlCompatibilityWarning
identifier={relName}
className={styles.add_mar_left_small}
/>
</div>
<div className={tableStyles.relationshipTopPadding}>
<p className={styles.textNoNewLine}>{getRelDef(relConfig)}</p>
</div>

2
docs/404.rst
View File

@ -1,5 +1,7 @@
.. title:: 404 - Page Not Found
:orphan:
404 - Page Not Found
---------------------

4
docs/_static/scripts/hdocs.js vendored
View File

@ -14,8 +14,8 @@ window.hdocs = (function () {
docsearch({
appId: 'WCBB1VVLRC',
apiKey: '298d448cd9d7ed93fbab395658da19e8',
indexName: 'graphql-docs-prod',
apiKey: HDOCS_ALGOLIA_API_KEY,
indexName: HDOCS_ALGOLIA_INDEX,
inputSelector: '#search_element',
transformData: hdocs.transformSearchData,
debug: false

6
docs/_static/styles/landing.css vendored
View File

@ -15,13 +15,11 @@
}
.body_content {
font-family: 'Gudea';
font-size: 15px;
color: #333;
}
.small_content {
font-family: 'Gudea';
font-size: 14px;
color: #333;
}
@ -101,6 +99,10 @@
padding-bottom: 0;
}
.description {
margin-bottom: 20px;
}
.text_left {
text-align: left;
}

4
docs/_static/styles/main.css vendored
View File

@ -640,6 +640,10 @@ article ol ol {
margin: 15px;
}
.sphinxsidebarwrapper > ul:not(.current) {
display: none;
}
#sidebar {
background-color: #001934;
width: 24% !important;

22
docs/_theme/djangodocs/layout.html vendored
View File

@ -4,6 +4,16 @@
{% set is_landing_page = true %}
{%- endif %}
{%- if pagename.startswith('graphql/core') %}
{% set is_core = true %}
{% set ALGOLIA_INDEX = 'graphql-docs-prod' %}
{% set ALGOLIA_API_KEY = '298d448cd9d7ed93fbab395658da19e8' %}
{%- elif pagename.startswith('graphql/cloud') %}
{% set is_cloud = true %}
{% set ALGOLIA_INDEX = 'cloud-docs-prod' %}
{% set ALGOLIA_API_KEY = 'cf84f05a225bedb72ce472dada63d29f' %}
{%- endif %}
{% set css_files = css_files + ['_static/graphiql/graphiql.css', '_static/styles/main.css'] %}
{%- if is_landing_page %}
@ -105,7 +115,7 @@
</a>
</li>
<li>
<a href='https://hasura.io/docs/1.0/graphql/manual/getting-started/index.html'>
<a href='https://hasura.io/docs/1.0/graphql/core/getting-started/index.html'>
<button class="commonBtn navBtnHome">
Get Started
</button>
@ -162,7 +172,7 @@
</a>
</li>
<li>
<a class="menuLink" href='https://hasura.io/docs/1.0/graphql/manual/getting-started/index.html'>
<a class="menuLink" href='https://hasura.io/docs/1.0/graphql/core/getting-started/index.html'>
<button class='commonBtn navBtnHome'>
Get Started
</button>
@ -187,12 +197,12 @@
<img src="{{ pathto('_images/layout/close-icon.svg', 1) }}" alt="Close"/>
</div>
<div class="tabbarContainerWrapper blueBgColor boderBottom">
<a href="" class="tabbarTabActive">
<a href="{{ pathto('graphql/core/index.html', 1) }}" {%- if is_core %} class="tabbarTabActive" {%- endif %}>
<span>
Hasura Core
</span>
</a>
<a href="https://hasura.io/docs/cloud/1.0/manual/index.html">
<a href="{{ pathto('graphql/cloud/index.html', 1) }}" {%- if is_cloud %} class="tabbarTabActive" {%- endif %}>
<span>
Hasura Cloud
</span>
@ -283,7 +293,7 @@
<div id="mc_embed_signup">
<div class="subscribe-form-content">
Stay up to date with product & security news
<a target="_blank" class="newsletter-link" href="https://us13.campaign-archive.com/home/?u=9b63e92a98ecdc99732456b0e&id=f5c4f66bcf" rel="noopener">See past editions</a>
<!-- <a target="_blank" class="newsletter-link" href="https://us13.campaign-archive.com/home/?u=9b63e92a98ecdc99732456b0e&id=f5c4f66bcf" rel="noopener">See past editions</a> -->
</div>
<form id="mc-embedded-subscribe-form" name="mc-embedded-subscribe-form" class="validate post-subscription-form newsletter-form" target="_blank" rel="noopener" novalidate>
<div class="full-width">
@ -344,6 +354,8 @@
<script type="text/javascript">
const HDOCS_BASE_DOMAIN = "{{ BASE_DOMAIN }}";
const HDOCS_GRAPHIQL_DEFAULT_ENDPOINT = "{{ GRAPHIQL_DEFAULT_ENDPOINT }}";
const HDOCS_ALGOLIA_INDEX = "{{ALGOLIA_INDEX}}";
const HDOCS_ALGOLIA_API_KEY = "{{ALGOLIA_API_KEY}}";
document.addEventListener('DOMContentLoaded', function () {
hdocs && hdocs.setup();

21
docs/_theme/djangodocs/localtoc.html vendored
View File

@ -1,24 +1,3 @@
{%- if display_toc %}
<!--
<div class="header_main_logo inline-block mobile-hide">
<a href="https://{{ BASE_DOMAIN }}/" target="_blank" rel="noopener">
<div class="img_wrapper inline-block">
<img class="responsive logo_img" src="{{ pathto('_images/layout/logo-lite.svg', 1) }}" alt="Hasura Logo Light" />
</div>
</a>
<a class="docs_label" href="{{ pathto('', 1) }}">
<div class="inline-block hero"> docs </div>
</a>
<a class="version_txt">
<select value="{{ version }}" onchange="location = this.value;" class="selected" aria-label="Select Version">
{%- if version == '1.0' %}
<option class="option_val" value="https://{{ BASE_DOMAIN }}/docs/1.0/graphql/manual/index.html" selected="selected">v1.x</option>
{%- else -%}
<option class="option_val" value="https://{{ BASE_DOMAIN }}/docs/1.0/graphql/manual/index.html">v1.x</option>
{% endif %}
</select>
</a>
</div>
-->
{{ toc_full }}
{%- endif %}

30
docs/_theme/djangodocs/pages/landing.html vendored
View File

@ -5,25 +5,23 @@
<div class="box_head_wrapper">
<div class="box_head">
<img src="{{ pathto('_images/landing/graphql.svg', 1) }}" alt="GraphQL engine"/>
<h3 class="head_wrapper">1. The Hasura GraphQL engine</h3>
</div>
<div class="view_all_wrapper small_content">
<h3 class="head_wrapper">Hasura docs</h3>
</div>
</div>
<div class="small_content space_wrapper text_left">
This guide covers all Hasura GraphQL engine concepts and features.
<br/> <br/>
</div>
<div class="sign_in_wrapper space_wrapper">
<div class="get_start">
<img src="{{ pathto('_images/landing/manual.svg', 1) }}" alt="Manual"/>
</div>
<a href="{{ pathto('graphql/manual/index.html', 1) }}">
<div class="docs_link body_content">
Open manual
<img src="{{ pathto('_images/landing/right-arrow.svg', 1) }}" alt="Right Arrow" />
</div>
<div class="space_wrapper text_left">
<p class="description">This guide covers all Hasura concepts and features.</p>
<ul>
<li>
<a class="docs_link" href="{{ pathto('graphql/core/index.html', 1) }}">
Core docs
</a>
</li>
<li>
<a class="docs_link" href="{{ pathto('graphql/cloud/index.html', 1) }}">
Cloud docs
</a>
</li>
</ul>
</div>
</div>
</div>

34
docs/graphql/cloud/allow-lists.rst Normal file
View File

@ -0,0 +1,34 @@
.. meta::
:description: Hasura Cloud allow lists
:keywords: hasura, docs, cloud, security, allow
.. _allow_lists:
Allow lists
===========
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Introduction
------------
You can specify a list of safe operations (GraphQL queries, mutations or subscriptions) for your project. This list restricts your project's GraphQL Engine to execute only queries that are present in the list.
Manage the allow list
---------------------
The manager view offers inspection, export, or removal of operations in the allow list:
.. thumbnail:: /img/graphql/cloud/security/pro-tabs-allowlist.png
:alt: Hasura Cloud Console allow list tab
Quick-create allowed operations
-------------------------------
This Pro feature lets you add to the allow list with one click from the record of past operations. (With Core, allow lists must be :ref:`managed manually <allow_list>`.)
.. thumbnail:: /img/graphql/cloud/security/allowlist-add-new-op.png
:alt: Hasura Cloud Console create new allowed operation

49
docs/graphql/cloud/api-limits.rst Normal file
View File

@ -0,0 +1,49 @@
.. meta::
:description: Hasura Cloud API limits
:keywords: hasura, docs, cloud, security, limits
.. _api_limits:
API limits
==========
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Introduction
------------
Limiting the depth and/or rate of API requests can help prevent API performance issues caused by malicious or poorly implemented queries.
Configuring an API limit
------------------------
**Rate limits**
Restricts number of GraphQL operations per minute. This uses a sliding window approach. This means whenever Hasura Pro receives a request, it will count the rate of that client starting from the current time to last one minute.
**Depth limits**
Restricts a GraphQL operation based on its depth, preventing deeply nested queries.
API limits are defined by **role** (anonymous, user) and can restrict request rate, depth, or both. Unique request parameters can include IP address or session variables (*x-hasura-user-id*, *x-hasura-org-id*, etc.)
Manage API limits
-----------------
API limits can have a *global* or *per role* configuration. If an incoming request does not contain a valid role then the global limit is applied.
.. thumbnail:: /img/graphql/cloud/security/pro-tab-apilimits.png
:alt: Hasura Cloud Console api limit tab
.. admonition:: Admin & IntrospectionQuery exemptions
All API limits are **not** applied for the admin role, and depth limits are **NOT** applied to introspection queries
Quick-create limits
-------------------
Hasura Cloud lets you add limits with one click from the list of past operations.
.. thumbnail:: /img/graphql/cloud/security/pro-tab-apilimit-config.png
:alt: Hasura Cloud Console create new api limit

140
docs/graphql/cloud/api-reference.rst Normal file
View File

@ -0,0 +1,140 @@
.. meta::
:description: Hasura Cloud API reference
:keywords: hasura, cloud, docs, API, API reference
.. _cloud_api_reference:
API Reference
=============
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Introduction
------------
Hasura Cloud provides a GraphQL API to interact with the services to create
and manage your projects.
You can use any GraphQL client and use the API with the right authentication header.
.. note::
Please note that the API is still in beta and might change before the
stable release.
Endpoint
--------
API endpoint is ``https://data.pro.hasura.io/v1/graphql``.
Authentication
--------------
Authentication is done using a Personal Access Token that you can create from
the Hasura Cloud Dashboard. You can find this option under the "Settings" tab.
Once you have the token it can be used with the header:
``Authorization: pat <token>``.
.. note::
This token can be used to authenticate against Hasura Cloud APIs and your Hasura Cloud projects.
Make sure you keep it secure. The token will be valid until you delete it from the dashboard.
APIs
----
Each Hasura Cloud project is backed by an API entity called "Tenant", with a
distinct "Tenant ID" which is different from "Project ID". Each Project is
associated with a Tenant. In some cases, like Metrics API, the Project ID is
used instead of Tenant ID.
List of APIs:
.. contents::
:backlinks: none
:depth: 1
:local:
Create a Tenant
^^^^^^^^^^^^^^^
.. code-block:: graphql
mutation createProject {
createTenant(
cloud: "aws"
region: "us-east-2"
databaseUrl: "postgres://username:password@database-host.com:5432/dbname"
) {
id
name
}
}
Get Tenant details
^^^^^^^^^^^^^^^^^^
.. code-block:: graphql
query getTenantDetails {
tenant_by_pk(
id: "7a79cf94-0e53-4520-a560-1b02bf522f08"
) {
id
slug
project {
id
endpoint
}
}
}
Delete a Tenant
^^^^^^^^^^^^^^^
.. code-block:: graphql
mutation deleteTenant {
deleteTenant(
tenantId: "7a79cf94-0e53-4520-a560-1b02bf522f08"
) {
status
}
}
Get ENV Vars
^^^^^^^^^^^^
.. code-block:: graphql
query getTenantENV {
getTenantEnv(
tenantId: "7a79cf94-0e53-4520-a560-1b02bf522f08"
) {
hash
envVars
}
}
Update ENV Vars
^^^^^^^^^^^^^^^
.. code-block:: graphql
mutation updateTenantEnv {
updateTenantEnv(
tenantId: "7a79cf94-0e53-4520-a560-1b02bf522f08"
currentHash: "6902a395d70072fbf8d36288f0eacc36c9d82e68"
envs: [
{key: "HASURA_GRAPHQL_ENABLE_CONSOLE", value: "true"},
{key: "ACTIONS_ENDPOINT", value: "https://my-actions-endpoint.com/actions"}
]
) {
hash
envVars
}
}

93
docs/graphql/cloud/getting-started/index.rst Normal file
View File

@ -0,0 +1,93 @@
.. meta::
:description: Hasura Cloud getting started
:keywords: hasura, docs, cloud, signup
.. _cloud_getting_started:
Getting Started with Hasura Cloud
=================================
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Step 1: Create an account
-------------------------
Navigate to `cloud.hasura.io
<https://cloud.hasura.io/login>`__, and create a new Hasura Cloud account.
.. _cloud_connect_db:
Step 2: Connect new/existing database
-------------------------------------
- To use an existing database, choose ``I have an existing Postgres database``.
- To create a new database, choose ``Try a free database with Heroku``.
.. thumbnail:: /img/graphql/cloud/getting-started/connect-db.png
:alt: Connect new or existing database
:width: 591px
Step 2a: Enter database URL (for existing database)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you chose ``I have an existing Postgres database`` in :ref:`Step 2 <cloud_connect_db>`, enter a database URL.
.. thumbnail:: /img/graphql/cloud/getting-started/connect-existing-db.png
:alt: Enter URL for existing database
:width: 556px
Step 3: Create project
----------------------
Click ``Create Project``.
.. thumbnail:: /img/graphql/cloud/getting-started/create-project-new-db.png
:alt: Create project for new database
:width: 539px
:group: create
:class: inline-block
.. thumbnail:: /img/graphql/cloud/getting-started/create-project-existing-db.png
:alt: Create project for existing database
:width: 552px
:group: create
:class: inline-block
Next steps
----------
Once you've created your project, you can get started with building with Hasura or manage your project.
.. contents::
:backlinks: none
:depth: 1
:local:
.. thumbnail:: /img/graphql/cloud/getting-started/project-functionalities.png
:alt: Project actions
:width: 860px
Explore the Hasura console
^^^^^^^^^^^^^^^^^^^^^^^^^^
Click ``Launch Console`` to open the Hasura console in your browser and :ref:`make your first GraphQL query <first_graphql_query>` or :ref:`set up your first event trigger <first_event_trigger>`.
You can navigate to the ``Pro`` tab to check out the Pro features that Hasura Cloud has set up for you.
.. thumbnail:: /img/graphql/cloud/metrics/pro-tab-overview.png
:alt: Hasura Console: Pro tab
:width: 1118px
Manage your project
^^^^^^^^^^^^^^^^^^^
Click the gear icon to :ref:`manage your project <manage_project>` (e.g. add collaborators, env vars or custom domains).
Add an admin secret
^^^^^^^^^^^^^^^^^^^
:ref:`Add an admin secret <secure_project>` to make sure that your GraphQL endpoint and the Hasura console are not publicly accessible.

66
docs/graphql/cloud/glossary.rst Normal file
View File

@ -0,0 +1,66 @@
.. meta::
:description: Hasura Cloud glossary
:keywords: hasura, docs, cloud, glossary
.. _glossary:
Glossary
========
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Hasura Cloud Project
--------------------
A Project is an individual GraphQL API hosted by Hasura Cloud. You
can create a Project by going to the cloud dashboard and providing
a PostgreSQL database URL. You can also provision a database on
cloud platforms like Heroku from the Hasura Cloud Dashboard itself.
Each project is allocated a unique auto-generated name and an ID.
You can use this name or ID while communicating to Hasura team
regarding this project. Each project is also assigned a GraphQL API
endpoint of the format ``https://<project-name>.hasura.app/v1/graphql``.
Editing the Project name and adding custom domains will be available soon.
For example, a project might be called ``usable-cobra-29`` with ID
``bf0ea856-76a2-42c2-8a91-66ca9b9206e8``.
Hasura Cloud IP
---------------
A Hasura Cloud IP will be listed on the Hasura Cloud Dashboard for
each project. Hasura will be connecting to your database from this IP address.
If your database is not exposed to the internet, you must allow connections
from this IP address on your firewall settings
for Hasura Cloud Project to function properly. Otherwise, Hasura will not
be able to connect to your database and the GraphQL API will not be available.
Hasura Collaborator Token
-------------------------
When you open the Hasura Console on a Cloud Project, you will not be asked to
enter the admin secret like Hasura Core version. Instead, you will be
automatically logged into the Console via an OAuth2.0 based authorization flow.
You will be given the right access based on your permissions for the particular
Hasura Cloud Project.
After the login process is complete, you'll see a new header called
``Hasura-Collaborator-Token`` in the "Request Headers" section of GraphiQL.
This token is used instead of admin secret to authenticate and authorize
all the requests made from the Console. The token is only valid for 5mins
and is refreshed silently by the Console. It is to be used only from Console.
For accessing the API from other clients, use the admin secret or create
a Personal Access Token.
Hasura Client Name
------------------
``Hasura-Client-Name`` will be set to ``hasura-console`` by default. It is
used to identify the client who is making the request in Hasura Pro metrics
and monitoring tools.

70
docs/graphql/cloud/hasurapro-cli/index.rst Normal file
View File

@ -0,0 +1,70 @@
.. meta::
:description: Hasura Pro CLI
:keywords: hasura, docs, command line interface, cli
.. _hasurapro_cli:
Hasura Pro CLI
==============
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Installing the Hasura Pro CLI
-----------------------------
Hasura Pro CLI is distributed as a plugin to the :ref:`Hasura Core CLI <hasuracli_manual>`
- Follow the instructions :ref:`here <install_hasura_cli>` to install Hasura Core CLI
- Then execute the following command to install the Hasura Pro CLI plugin:
.. code-block:: bash
hasura plugins install pro
- You can verify the installation by executing the ``help`` command:
.. code-block:: bash
hasura pro --help
Authentication with the Hasura Pro CLI
--------------------------------------
All interactions from the CLI to Hasura’s APIs are authenticated using a personal access token generated for your user account.
To set up a token, execute the following command on the CLI:
.. code-block:: bash
hasura pro login
This command will show a prompt for entering the personal access token.
Head to your `Hasura Cloud account settings <https://cloud.hasura.io>`_ to create a new token. You can name it something like "cli". Note that the token will be shown only once and as soon as you copy the token, paste it in your terminal prompt.
.. admonition:: Keep this token secure!
This token can be used to authenticate against Hasura Pro APIs and your Hasura Cloud projects. Make sure you keep it secure. This is a one-time operation. The token will be valid until you delete it.
Upgrading the CLI
-----------------
To upgrade to a newer version, you can use the ``upgrade`` command:
.. code-block:: bash
hasura plugins upgrade pro
Uninstalling the CLI
--------------------
To uninstall the CLI, use the ``uninstall`` command:
.. code-block:: bash
hasura plugins uninstall pro

74
docs/graphql/cloud/index.rst Normal file
View File

@ -0,0 +1,74 @@
.. meta::
:description: Hasura Cloud documentation
:keywords: hasura, docs, manual, graphql engine, cloud, hosted
.. title:: Hasura Cloud Documentation
.. _cloud_docs:
Hasura Cloud Documentation
==========================
`Hasura Cloud <https://cloud.hasura.io/>`__ offers hosted `GraphQL Engine <https://github.com/hasura/graphql-engine>`__
projects with extra features for reliability and security. It includes all the :ref:`core features <core_docs>`
of GraphQL Engine, while taking care of infrastructure concerns, such as the number of instances, cores, memory, concurrent users, high-availability,
realtime monitoring, caching, tracing, and rate-limiting. It supports both new and existing PostgreSQL databases.
.. container:: toc-list
.. container:: toc-list-section
.. container:: toc-list-head
Basics
.. container:: toc-list-content
- :ref:`cloud_getting_started`
- :ref:`projects`
.. container:: toc-list-section
.. container:: toc-list-head
Features
.. container:: toc-list-content
- :ref:`metrics`
- :ref:`api_limits`
- :ref:`allow_lists`
- :ref:`regression_tests`
- :ref:`read_replicas`
- :ref:`response_caching`
- :ref:`tracing`
.. container:: toc-list-section
.. container:: toc-list-head
Reference
.. container:: toc-list-content
- :ref:`cloud_api_reference`
- :ref:`glossary`
- :ref:`hasurapro_cli`
.. toctree::
:maxdepth: 1
:titlesonly:
:hidden:
Getting Started <getting-started/index>
projects/index
metrics/index
api-limits
allow-lists
regression-tests
read-replicas
response-caching
tracing
hasurapro-cli/index
api-reference
glossary

23
docs/graphql/cloud/metrics/errors.rst Normal file
View File

@ -0,0 +1,23 @@
.. meta::
:description: Hasura Cloud error analysis
:keywords: hasura, docs, cloud, reliability, errors
.. _errors:
Errors
======
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Troubleshoot errors quickly with powerful analytical tools and filters:
.. thumbnail:: /img/graphql/cloud/metrics/pro-tab-errors.png
:alt: Hasura Cloud Console errors tab
Drill into a specific operation via the magnifying-glass icon next to the operation summary in the 'Frequent errors' table. You'll be taken to a list of the failed operations, and can choose one to inspect the specific operation content, metadata, and error generated:
.. thumbnail:: /img/graphql/cloud/metrics/inspect-error.png
:alt: Hasura Cloud Console inspect a failed operation

35
docs/graphql/cloud/metrics/index.rst Normal file
View File

@ -0,0 +1,35 @@
.. meta::
:description: Hasura Cloud metrics
:keywords: hasura, docs, cloud, metrics
.. _metrics:
Metrics
=======
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Introduction
------------
Hasura Cloud projects include Pro features for enhanced reliability and performance
.. thumbnail:: /img/graphql/cloud/metrics/pro-tab-overview.png
:alt: Hasura Cloud Console overview tab
Learn more
----------
.. toctree::
:maxdepth: 1
:titlesonly:
overview
errors
usage
operations
websockets
subscription-workers

119
docs/graphql/cloud/metrics/operations.rst Normal file
View File

@ -0,0 +1,119 @@
.. meta::
:description: Hasura Cloud operation analysis
:keywords: hasura, docs, cloud, reliability, operations
.. _operations:
Operations
==========
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Terminology
-----------
**Operation**
Any GraphQL (query, mutation, subscription) request made to v1/graphql endpoint of a GraphQL engine instance
**Operation name**
(Optional) Any GraphQL request can be labelled with a name by the client making the query. In this example, *getPollOptions* is the operation name:
.. code-block:: graphql
query getPollOptions (
poll {
options {
id
name
description
}
}
}
**Operation ID**
A unique, auto-generated hash for each Operation name; can distinguish between different operations executed with the same name
**Operation type**
Whether the operation is a query, mutation, or subscription
**Request ID**
A unique, auto-generated ID for each request, comes from x-request-id HTTP header
**Websocket ID**
A unique ID generated by the server when a websocket connection is established by the client
**Websocket Operation ID**
A unique ID generated by the websocket client for each operation it is sending to the server
Operations
----------
Processed realtime logs of all requests to the GraphQL Engine. View all and inspect individual operations:
.. thumbnail:: /img/graphql/cloud/metrics/pro-tab-operations.png
:alt: Hasura Cloud Console list operations
.. thumbnail:: /img/graphql/cloud/metrics/pro-tab-operations-inspect.png
:alt: Hasura Cloud Console inspect operation
Filtering operations
--------------------
Click on the **Filter** header to open the menu of filter options
.. list-table::
:header-rows: 1
* - Filter option
- Filter type
- Example or options
* - Time range
- timestamps
- last hour, last 6 hours, last 12 hours, last 24 hours, or custom range
* - Operation ID
- string (text field)
- 5284946f4e15aa81bc868316d56aa68f
* - Operation Name
- string (text field)
- getPollOptions
* - Request ID
- string (text field)
- e15f7bj9-3b9f-4152-92a4-e745471514af
* - Show only errors
- boolean (checkbox field)
- true or false (default false)
* - Websocket ID
- string (text field)
- def703fc-851f-48e8-8e5c-cbdead37b2fe
* - Websocket Operation ID
- string (text field)
- 110
* - Hide introspection query
- boolean (checkbox field)
- true or false (default false)
* - Operation Type
- enum (select field)
- query, mutation, subscription, all
* - Role
- enum (select field)
- from *x-hasura-user-role*: no role, admin, user, ...
* - Error Code
- enum (select field)
- no error code, access-denied, depth-limit-exceeded, ...
* - Client Name
- enum (select field)
- no client name, hasura-console, hasura-test-runner, ...
* - Transport
- enum (select field)
- http or ws
* - Status
- enum (select field)
- started or closed
Sorting operations
------------------
Each column in the **Operations List** can be sorted (ascending or descending) just by clicking on it. Very useful for identifying operations with unusually high execution time or response size!

18
docs/graphql/cloud/metrics/overview.rst Normal file
View File

@ -0,0 +1,18 @@
.. meta::
:description: Hasura Cloud overview
:keywords: hasura, docs, cloud, overview
.. _overview:
Overview
========
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
The Overview displays aggregate stats over the last hour:
.. thumbnail:: /img/graphql/cloud/metrics/pro-tab-overview.png
:alt: Hasura Cloud Console overview tab

18
docs/graphql/cloud/metrics/subscription-workers.rst Normal file
View File

@ -0,0 +1,18 @@
.. meta::
:description: Hasura Cloud subscription workers
:keywords: hasura, docs, cloud, reliability, subscriptions
.. _subscription_workers:
Subscription workers
====================
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Subscription workers offers a subscription-worker-specific version of usage statistics:
.. thumbnail:: /img/graphql/cloud/metrics/pro-tab-subscription-workers.png
:alt: Hasura Cloud Console subscription workers tab

23
docs/graphql/cloud/metrics/usage.rst Normal file
View File

@ -0,0 +1,23 @@
.. meta::
:description: Hasura Cloud usage analysis
:keywords: hasura, docs, cloud, reliability, usage
.. _usage:
Usage
=====
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Learn about usage with aggregate summaries and filtering tools:
.. thumbnail:: /img/graphql/cloud/metrics/pro-tab-usage.png
:alt: Hasura Cloud Console usage tab
Drill into an operation via its magnifying-glass icon in the 'Query List' table. You'll be taken to a list of similar operations, and can choose one to inspect for content, metadata, and error generated:
.. thumbnail:: /img/graphql/cloud/metrics/pro-tab-operations-inspect.png
:alt: Hasura Cloud Console inspect an operation

18
docs/graphql/cloud/metrics/websockets.rst Normal file
View File

@ -0,0 +1,18 @@
.. meta::
:description: Hasura Cloud websockets analysis
:keywords: hasura, docs, cloud, reliability, websockets
.. _websockets:
Websockets
==========
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Websockets is a ws-specific version of usage statistics:
.. thumbnail:: /img/graphql/cloud/metrics/pro-tab-websockets.png
:alt: Hasura Cloud Console websockets tab

89
docs/graphql/cloud/projects/create.rst Normal file
View File

@ -0,0 +1,89 @@
.. meta::
:description: Creating projects on Hasura Cloud
:keywords: hasura, cloud, docs, start
.. _create_project:
Creating projects
=================
.. contents:: Table of contents
:backlinks: none
:depth: 2
:local:
Introduction
------------
You can create a new Hasura Cloud project with either a new Postgres database, or an existing Postgres database with a publicly available IP address.
To begin, navigate to the ``Projects`` page, and click the ``New Project`` link.
.. thumbnail:: /img/graphql/cloud/projects/create-new-project.png
:alt: create new project button
:width: 400
Creating a project with a new database
--------------------------------------
Hasura Cloud does not host databases, but does provide integrations with which you can create databases on managed cloud providers like Heroku. Integrations for AWS, GCP, and Azure are coming soon.
To get started, click ``Try with Heroku``, and follow the prompts to authenticate with Heroku. Hasura Cloud will integrate with your Heroku account and manage the initial setup of a dev-tier Postgres instance. You can always upgrade the instance and manage options later through your Heroku account.
.. thumbnail:: /img/graphql/cloud/projects/create-project-heroku.png
:alt: create new hosted project
Creating a project with an existing database
--------------------------------------------
To create a new Hasura Cloud project connected to an existing Postgres database, click ``Enter Database URL``, and enter your database connection string (looks like ``postgres://username:password@hostname:port/dbname``).
.. thumbnail:: /img/graphql/cloud/projects/new-project-hosted.png
:alt: create new hosted project
Allowing connections from Hasura Cloud IP
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
For some cloud services, like GCP, you'll need to adjust your Postgres connection settings to allow connections from the Hasura Cloud IP address. You can copy the IP address from either the copy icon in the ``Database Setup`` window, or the ``Hasura Cloud IP`` field on the project's details view. You may also need to disable SSL. Adding custom cert information to a Hasura Cloud instance is not yet available.
.. thumbnail:: /img/graphql/cloud/projects/existing-db-setup.png
:alt: Existing database setup
:width: 568px
.. thumbnail:: /img/graphql/cloud/projects/hasura-cloud-ip.png
:alt: Hasura Cloud IP field
:width: 1200px
.. thumbnail:: /img/graphql/cloud/projects/gcp-postgres-authorized-network.png
:alt: whitelist Hasura instance IP in Postgres settings
:width: 727px
Connecting to a database not exposed over the internet
------------------------------------------------------
`Contact us <https://hasura.io/contact-us/>`__ for VPC peering and on-premise solutions.
.. _cloud_postgres_permissions:
Postgres permissions
--------------------
Hasura Cloud works with **Postgres versions 9.5 and above**.
If you’re running in a controlled environment, you might need to configure
Hasura Cloud to use a specific Postgres user that your DBA gives you.
Apart from the :ref:`Hasura Core Postgres permissions <postgres_permissions>`,
Hasura Cloud needs the following extra permissions:
- (required) Read and write access to ``hdb_pro_catalog`` schema.
.. code-block:: sql
-- execute these statements after executing the ones mentioned in Hasura Core docs
-- create the schemas required by the hasura cloud system
CREATE SCHEMA IF NOT EXISTS hdb_pro_catalog;
-- make the user an owner of system schemas
ALTER SCHEMA hdb_pro_catalog OWNER TO hasurauser;

19
docs/graphql/cloud/projects/delete.rst Normal file
View File

@ -0,0 +1,19 @@
.. meta::
:description: Deleting projects on Hasura Cloud
:keywords: hasura, docs, delete
.. _delete_project:
Deleting projects
=================
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
You can delete a project with the ``Delete Project`` button at the bottom of the project's details view.
.. thumbnail:: /img/graphql/cloud/projects/projects-delete.png
:alt: delete a project
:width: 1199px

52
docs/graphql/cloud/projects/index.rst Normal file
View File

@ -0,0 +1,52 @@
.. meta::
:description: Managing teams in Hasura Cloud
:keywords: hasura, docs, cloud, teams
.. _projects:
Projects & teams
================
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Introduction
------------
The ``Projects`` page show a list of your projects.
.. thumbnail:: /img/graphql/cloud/projects/projects-list.png
:alt: Projects list
:width: 1200px
For each project, you can:
- Click the gear icon to :ref:`manage your project <manage_project>`, or
- Click ``Launch Console`` to open the Hasura console in your browser, and navigate to the ``Pro`` tab to check out the Pro features that Hasura Cloud has set up for you.
.. thumbnail:: /img/graphql/cloud/getting-started/project-actions.png
:alt: Project actions
:width: 860px
.. thumbnail:: /img/graphql/cloud/metrics/pro-tab-overview.png
:alt: Hasura Console: Pro tab
:width: 1118px
.. note::
Please see the :ref:`API reference <cloud_api_reference>` to create and manage Hasura Cloud projects programmatically.
Dig deeper
----------
.. toctree::
:maxdepth: 1
:titlesonly:
Creating projects <create>
Managing projects <manage-projects/index>
Securing projects <secure>
Deleting projects <delete>

71
docs/graphql/cloud/projects/manage-projects/domains.rst Normal file
View File

@ -0,0 +1,71 @@
.. meta::
:description: Managing domains on Hasura Cloud
:keywords: hasura, docs, project, domains
.. _manage_project_domains:
Domains tab
===========
.. contents:: Table of contents
:backlinks: none
:depth: 2
:local:
Introduction
------------
In the ``Domains`` tab, you can see the default Hasura domain, and you have the possibility to add custom domains.
Adding a custom domain
----------------------
You can add a custom domain to your Hasura Cloud project by following the steps below.
Step 1: Navigate to add a custom domain
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
On the ``Domains`` tab, click on the ``New Custom Domain`` button.
.. thumbnail:: /img/graphql/cloud/projects/add-custom-domain.png
:alt: Add custom domain
:width: 727px
Step 2: Add your custom domain
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Enter your custom domain and click the ``Add`` button.
.. thumbnail:: /img/graphql/cloud/projects/choose-custom-domain.png
:alt: Choose custom domain
:width: 727px
Step 3: Add the record to your DNS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
After adding a custom domain, the following window will show up:
.. thumbnail:: /img/graphql/cloud/projects/dns-settings.png
:alt: DNS settings
:width: 727px
If you haven't already done so, add the default Hasura domain as a ``CNAME`` record to your DNS.
Until this is done, the dashboard will show a notice that the DNS validation is pending.
.. thumbnail:: /img/graphql/cloud/projects/dns-validation-pending.png
:alt: DNS validation pending
:width: 727px
.. note::
Depending on your DNS provider, it might take up to 24 hours for the DNS record to be added.
DNS validated
-------------
Once the DNS is validated, the dashboard will update the status with the following notice:
.. thumbnail:: /img/graphql/cloud/projects/dns-validated.png
:alt: DNS validated
:width: 727px

27
docs/graphql/cloud/projects/manage-projects/env-vars.rst Normal file
View File

@ -0,0 +1,27 @@
.. meta::
:description: Managing env vars on Hasura Cloud
:keywords: hasura, docs, project, env vars
.. _manage_project_env_vars:
Env vars tab
============
.. contents:: Table of contents
:backlinks: none
:depth: 2
:local:
Introduction
------------
The ``Env vars`` tab allows setting :ref:`Hasura GraphQL Engine env variables <command-flags>` and adding other custom env variables as well.
Adding an env var
-----------------
Click on the ``New Env Var`` button and either choose an env var from the dropdown or add a custom env var.
.. thumbnail:: /img/graphql/cloud/projects/add-env-var.png
:alt: add env var options
:width: 1200px

31
docs/graphql/cloud/projects/manage-projects/general.rst Normal file
View File

@ -0,0 +1,31 @@
.. meta::
:description: Managing projects on Hasura Cloud
:keywords: hasura, docs, project, general
.. _manage_project_general:
General tab
===========
.. contents:: Table of contents
:backlinks: none
:depth: 2
:local:
Introduction
------------
The ``General`` tab shows the project's general settings.
General settings
----------------
- **Name**: Unique auto-generated name for the project
- **ID**: Unique auto-generated ID for the project
- **GraphQL API**: GraphQL endpoint for the project
- **Admin Secret**: Secret for securing the GraphQL endpoint
- **Owner**: Email of the project owner
.. thumbnail:: /img/graphql/cloud/projects/project-details.png
:alt: General tab
:width: 1163px

36
docs/graphql/cloud/projects/manage-projects/index.rst Normal file
View File

@ -0,0 +1,36 @@
.. meta::
:description: Managing projects on Hasura Cloud
:keywords: hasura, docs, project
.. _manage_project:
Managing projects
=================
.. contents:: Table of contents
:backlinks: none
:depth: 2
:local:
Introduction
------------
To view a project's details, and manage its teams and environment variables, navigate to the ``Projects`` page and click the gear icon on the project.
.. thumbnail:: /img/graphql/cloud/projects/manage-project.png
:alt: Manage project
:width: 865px
Managing projects
-----------------
See the below pages for detailed guides on managing projects:
.. toctree::
:maxdepth: 1
:titlesonly:
General tab <general>
Team tab <team>
Env vars tab <env-vars>
Domains tab <domains>

46
docs/graphql/cloud/projects/manage-projects/team.rst Normal file
View File

@ -0,0 +1,46 @@
.. meta::
:description: Managing teams on Hasura Cloud
:keywords: hasura, docs, project, team
.. _manage_project_team:
Team tab
========
.. contents:: Table of contents
:backlinks: none
:depth: 2
:local:
Introduction
------------
The ``Team`` tab shows the current people with access to the project.
Add a collaborator
------------------
Click ``New Collaborator`` to invite a new team member.
.. thumbnail:: /img/graphql/cloud/projects/team-view.png
:alt: Team tab
:width: 1146px
Team roles
^^^^^^^^^^
Team members can have different levels of access in the Hasura console.
- **Admin** has complete access to all project tools and configurations.
- **User** has limited privileges:
- The ``Execute GraphQL`` permission allows running queries, mutations, and subscriptions.
- The ``View Metrics`` permission allows inspecting operation data and the performance dashboard.
.. thumbnail:: /img/graphql/cloud/projects/add-collaborator.png
:alt: Add collaborator
:width: 437px
.. note::
Invitations can be accepted or declined via the ``Invitations`` tab of your Hasura Cloud settings.

59
docs/graphql/cloud/projects/secure.rst Normal file
View File

@ -0,0 +1,59 @@
.. meta::
:description: Securing projects on Hasura Cloud
:keywords: hasura, docs, project
.. _secure_project:
Securing projects
=================
.. contents:: Table of contents
:backlinks: none
:depth: 2
:local:
Introduction
------------
To make sure that your GraphQL endpoint and the Hasura console are not publicly accessible, you need to configure an admin secret key.
Adding an admin secret
----------------------
Step 1: Go to settings
^^^^^^^^^^^^^^^^^^^^^^
On the project overview, click on the settings icon on the top right of the relevant project.
.. thumbnail:: /img/graphql/cloud/projects/secure-settings.png
:alt: Go to settings
:width: 865px
Step 2: Navigate to env vars
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
On the ``Env vars`` tab, click the button to add a new env var.
.. thumbnail:: /img/graphql/cloud/projects/secure-envvars.png
:alt: Navigate to env vars
:width: 865px
Step 3: Add an admin secret
^^^^^^^^^^^^^^^^^^^^^^^^^^^
In the ``Key`` dropdown, choose ``ADMIN_SECRET`` and add the secret in the ``Value`` field. Then click the ``Add`` button.
.. thumbnail:: /img/graphql/cloud/projects/secure-add-envvar.png
:alt: Navigate to env vars
:width: 865px
Accessing Hasura
----------------
After setting an admin secret, when you launch the console from the Hasura Cloud dashboard, you'll be authenticated as an admin.
If you want to make API calls from outside the console, you need to pass the admin secret as the `x-hasura-admin-secret` request header.
.. note::
The admin secret should be treated like a password i.e. it should be kept secret and shouldn't be passed from frontend clients.
Refer :ref:`this <authentication>` to set up user authentication.

42
docs/graphql/cloud/read-replicas.rst Normal file
View File

@ -0,0 +1,42 @@
.. meta::
:description: Hasura Cloud read replicas
:keywords: hasura, docs, cloud, read replicas, connections, pool
.. _read_replicas:
Read replicas
=============
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Introduction
------------
Hasura Cloud can load balance queries and subscriptions across read replicas while sending all mutations and metadata API calls to the master.
Adding read replica urls
------------------------
If you have configured your Postgres instances with replicas, the replica URLs can be added to Hasura using the following environment variable in your project ENV Vars tab:
.. code-block:: bash
HASURA_GRAPHQL_READ_REPLICA_URLS=postgres://user:password@replica-host:5432/db
If you have multiple replicas, their urls can be added as comma separated values.
Connection pool parameters
--------------------------
Additional environment variables for connection pools, and for read replicas specifically:
``HASURA_GRAPHQL_PG_STRIPES``
``HASURA_GRAPHQL_PG_CONNECTIONS``
``HASURA_GRAPHQL_CONNECTIONS_PER_READ_REPLICA``
``HASURA_GRAPHQL_STRIPES_PER_READ_REPLICA``

97
docs/graphql/cloud/regression-tests.rst Normal file
View File

@ -0,0 +1,97 @@
.. meta::
:description: Hasura Cloud regression tests
:keywords: hasura, docs, cloud, reliability, regression, migration
.. _regression_tests:
Regression tests
================
.. contents:: Table of contents
:backlinks: none
:depth: 2
:local:
Introduction
------------
Hasura Cloud includes a comprehensive test bench that lets you seamlessly compile a test suite on each project, executable on any GraphQL Engine instance (ex: staging, prod).
Here's a reference development workflow that is enabled by Hasura Cloud:
#. Build your database schema and configure Hasura as required by your frontend apps or public GraphQL API.
#. Deploy changes to production after testing them.
#. Create a regression suite on production.
#. Iterate on your GraphQL schema to support new features or edits.
- Test changes in your dev instance against the production instance’s regression test suite. Fix any issues highlighted by the tests or plan to communicate regressions to affected stakeholders.
#. Run all changes through a CI/CD pipeline
- Run Regression tests programmatically for all changes in the team
#. Promote changes to prod
.. thumbnail:: /img/graphql/cloud/reliability/regression-testing-diagram.png
:alt: Regression testing process diagram
Manage test suites
------------------
Each Hasura Cloud project can be configured with a separate test suite. Ideally, you want to create a regression test suite on an project which has received requests with operations you’d like to continue supporting or ensure are not “broken” - production or a shared QA project which receives operations in your app or, if you have a public GraphQL API, those from your consumers.
.. thumbnail:: /img/graphql/cloud/reliability/regression-tests-suites.png
:alt: Manage regression test suites
Quick-create tests
------------------
Add important operations to your test suite with one click by adding them from your project's operation history:
.. thumbnail:: /img/graphql/cloud/reliability/regression-tests-add-operations.png
:alt: Add tests to regression test suites
Run test suites
---------------
A good development workflow would require that tests be run 1) early in the dev process, and 2) automatically with changes, to ensure changes to the schema don't break functionality.
A test suite configured on a Hasura Cloud project can be run on the same instance or any other Hasura Cloud project registered to your team, including local ones. This is how we recommend that you incorporate regression tests into your GraphQL engine workflows:
Run regression tests manually
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Let’s say you’re a developer iterating on a feature and, as part of your work, need to modify your Postgres schema or the Hasura configuration. It is likely that you are doing so by running the console via the Hasura CLI to generate migrations that you can version control. Before committing your changes in git, you should run tests to get an early warning for potential regressions. Your team may want to designate the test suite from your production instance (or a suitable alternative) as the default suite to be used for this, and you can choose to run this test suite on your local or development instance.
.. thumbnail:: /img/graphql/cloud/reliability/regressions-run-prod-tests-on-dev.png
:alt: Run regression tests
For example, if the column ‘title’ (in a typical authors and articles schema) has been modified as part of a feature iteration. Assuming the operation from the previous example is part of the test suite on production, here’s how the feedback on this change looks like:
.. thumbnail:: /img/graphql/cloud/reliability/regression-tests-results.png
:alt: Regression test results
As you can see, one of the tests fails because it expects a field, title, to be part of the type articles - which is something our proposed change just modified and removed support for.
Run regression tests in CI/CD flow
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. thumbnail:: /img/graphql/cloud/reliability/regression-tests-run-cli.png
:alt: Run regression tests via CLI
This command will fetch the entire test suite from Hasura Pro and run the tests against given endpoint using the admin secret and report the result on the terminal. The test run and the results will also be available on the Hasura Console.
You can use the Hasura Pro CLI to programmatically trigger execution of a test suite in your automated testing setup, typically in CI scripts.
In order to communicate with Hasura’s APIs, the CLI needs to be configured with an API access token (which you can create via your Hasura Cloud settings). If you want to set the token up on a non-interactive environment, like a CI pipeline, you can obtain a token and then add to ``~/.hasura/pro_config.yaml`` with the following format:
.. code-block:: bash
pat: <token>
View test suite results
-----------------------
.. thumbnail:: /img/graphql/cloud/reliability/regression-tests-past-runs.png
:alt: Regression tests past results

66
docs/graphql/cloud/response-caching.rst Normal file
View File

@ -0,0 +1,66 @@
.. meta::
:description: Query response caching in Hasura Cloud
:keywords: hasura, docs, cloud, response, caching
.. _response_caching:
Query response caching
======================
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Introduction
------------
Hasura Cloud provides support for caching query responses, in order to
improve performance for queries which are executed frequently.
Cached responses are stored in for a period of time in a LRU (least-recently
used) cache, and removed from the cache as needed based on usage.
A query's response can be cached only if the following conditions hold:
- The query does not make use of remote schemas or remote joins
- The query and any related user permissions do not make use of session variables
- The response JSON is under 100KB in size
Enable caching
--------------
In order to enable caching for a query response, or to return an existing
response from the cache (if one exists), simply add the ``@cached`` directive
to your query:
.. code-block:: graphql
query MyCachedQuery @cached {
users {
id
name
}
}
If the response was cached successfully, the HTTP response will include a
``X-Hasura-TTL`` header, whose value indicates the maximum number of seconds
for the returned response to remain in the cache.
Controlling cache lifetime
--------------------------
The maximum lifetime of an entry in the cache can be controlled using the ``ttl``
argument to the ``@cached`` query directive. The value is an integer number of seconds:
.. code-block:: graphql
query MyCachedQuery @cached(ttl: 120) {
users {
id
name
}
}
By default, a response will be cached with a maximum lifetime of 60 seconds.
The maximum allowed value is 300 seconds (5 minutes).

98
docs/graphql/cloud/tracing.rst Normal file
View File

@ -0,0 +1,98 @@
.. meta::
:description: Distributed tracing with Hasura Cloud
:keywords: hasura, docs, cloud, tracing
.. _tracing:
Distributed tracing
=======================
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Introduction
------------
Hasura Cloud has support for *distributed tracing*, a technique for
debugging Hasura in production in the context of the services it works
with. These services might include your own Postgres database, any
remote schemas, event trigger webhook providers, action providers or
authentication hooks. Distributed tracing attempts to give a unified
view into the performance characteristics of all of these components of
your architecture.
Visualizing traces
------------------
The Hasura Pro console makes it possible to view Hasura's own tracing
data, by opening the details view for an operation in the Operations
tab:
.. thumbnail:: /img/graphql/cloud/tracing/tracing-operations-timing.png
:alt: View timing data in the Operations tab
Given that other system components will report their own tracing data to
your APM system, and not to Hasura, it is not possible to give a
complete picture of a trace, but since Hasura sits in a central position
in the architecture of many systems, it can often give a reasonably
comprehensive view of the provenance of data in your system.
For example, Hasura can report interactions with Postgres, remote
schemas, event trigger webhooks and action handlers.
APM system integration
----------------------
Hasura will report trace information to your APM or *application
performance monitoring* system, where it can be correlated with similar
sources of data from other components of your service architecture.
If you are considering integrating Hasura with your APM system, please
get in touch so that we can help to coordinate that effort.
Trace propagation
-----------------
At the boundaries between different services, tracing information needs
to be shared in order for trace fragments from different systems to be
correlated with each other in the APM system. This is called *trace
propagation*.
There are several subtly-incompatible proposals for trace propagation,
which can make it difficult to arrange for any two services to work
together.
Propagation to web services
~~~~~~~~~~~~~~~~~~~~~~~~~~~
For propagation during a call to a web service over HTTP, Hasura
currently implements the `B3 propagation
specification <https://github.com/openzipkin/b3-propagation>`__. This
means that we send trace information in various HTTP headers, which
should be read and handled by any compatible web services.
If you are unsure how to implement B3 propagation in your own web
service, the simplest thing to do is to read these headers and pass them
along to any HTTP services you call which also support B3 propagation,
including Hasura itself.
In particular, if an event trigger webhook or action handler propagates
these B3 headers back to Hasura, we will be able to trace the entire
interaction.
Propagation via Postgres
~~~~~~~~~~~~~~~~~~~~~~~~
There is no standard method for trace propagation via Postgres
transactions. For example, event triggers can be invoked by mutations,
and so their traces should be correlated.
For this reason, we have adopted our own method of propagating a trace
context in Postgres transactions.
The trace context will be serialized during mutations as a
transaction-local variable, ``hasura.tracecontext``. This value has the
Postgres type ``json``, and it can be read in trigger functions and
propagated to any downstream services.

8
docs/graphql/manual/actions/action-examples.rst.wip → docs/graphql/core/actions/action-examples.rst.wip
View File

@ -34,14 +34,14 @@ This page provides reference examples of typical action use cases.
Now we have an action ``updateAddress`` that looks as follows:
.. thumbnail:: /img/graphql/manual/actions/update-address-action-definition.png
.. thumbnail:: /img/graphql/core/actions/update-address-action-definition.png
:alt: Update address action
:width: 65%
We can now add an object relationship from the ``updateAddress`` action to the ``authors`` table in our schema.
We call it ``updatedAddressAuthor``.
.. thumbnail:: /img/graphql/manual/actions/action-object-relationship.png
.. thumbnail:: /img/graphql/core/actions/action-object-relationship.png
:alt: Object relationship from action
:width: 65%
@ -90,14 +90,14 @@ This page provides reference examples of typical action use cases.
Now we have an action ``updateAuthor`` that looks as follows:
.. thumbnail:: /img/graphql/manual/actions/update-author-action-definition.png
.. thumbnail:: /img/graphql/core/actions/update-author-action-definition.png
:alt: Update author action
:width: 65%
We can now add an array relationship from the ``updateAuthor`` action to the ``articles`` table in our schema.
We call it ``updatedAuthorArticles``.
.. thumbnail:: /img/graphql/manual/actions/action-array-relationship.png
.. thumbnail:: /img/graphql/core/actions/action-array-relationship.png
:alt: Array relationship from action
:width: 65%

2
docs/graphql/manual/actions/action-handlers.rst → docs/graphql/core/actions/action-handlers.rst
View File

@ -183,7 +183,7 @@ For your action, add a header that will act as an action secret.
Head to the ``Actions -> [action-name]`` tab in the console and scroll down to ``Headers``.
You can now configure an action secret by adding a header:
.. thumbnail:: /img/graphql/manual/actions/action-secret-header.png
.. thumbnail:: /img/graphql/core/actions/action-secret-header.png
:alt: Console action secret
:width: 75%

2
docs/graphql/manual/actions/action-permissions.rst → docs/graphql/core/actions/action-permissions.rst
View File

@ -29,7 +29,7 @@ Set action permissions
Head to the ``Actions -> [action-name] -> Permissions`` tab in the
console.
.. thumbnail:: /img/graphql/manual/actions/actions-permissions.png
.. thumbnail:: /img/graphql/core/actions/actions-permissions.png
:alt: Console action permission
Hit ``Save`` to give the role permission to access the action.

0
docs/graphql/manual/actions/async-actions.rst → docs/graphql/core/actions/async-actions.rst
View File

8
docs/graphql/manual/actions/codegen.rst → docs/graphql/core/actions/codegen.rst
View File

@ -41,7 +41,7 @@ Generating handler code for your action
You can select the framework of your choice to get the corresponding
handler boilerplate code.
.. thumbnail:: /img/graphql/manual/actions/console-codegen-tab.png
.. thumbnail:: /img/graphql/core/actions/console-codegen-tab.png
:alt: Console codegen tab
@ -59,17 +59,17 @@ Generating handler code for your action
1. Choose which framework you want to codegen for:
.. thumbnail:: /img/graphql/manual/actions/cli-framework-prompt.png
.. thumbnail:: /img/graphql/core/actions/cli-framework-prompt.png
:alt: CLI Framework Prompt
2. Choose if you also wish to clone a starter kit for the chosen framework:
.. thumbnail:: /img/graphql/manual/actions/cli-starter-kit-prompt.png
.. thumbnail:: /img/graphql/core/actions/cli-starter-kit-prompt.png
:alt: CLI Starter Kit Prompt
3. Choose a path where you want to output the auto-generated code files
.. thumbnail:: /img/graphql/manual/actions/cli-output-dir-prompt.png
.. thumbnail:: /img/graphql/core/actions/cli-output-dir-prompt.png
:alt: CLI Starter Kit Prompt

4
docs/graphql/manual/actions/create.rst → docs/graphql/core/actions/create.rst
View File

@ -96,7 +96,7 @@ in the GraphQL schema.
Go to the ``Actions`` tab on the console and click on ``Create``. This will
take you to a page like this:
.. thumbnail:: /img/graphql/manual/actions/mutation-action-create.png
.. thumbnail:: /img/graphql/core/actions/mutation-action-create.png
:alt: Console action create
:width: 70%
@ -275,7 +275,7 @@ the GraphQL schema.
Go to the ``Actions`` tab on the console and click on ``Create``. This will
take you to a page like this:
.. thumbnail:: /img/graphql/manual/actions/query-action-create.png
.. thumbnail:: /img/graphql/core/actions/query-action-create.png
:alt: Console action create
:width: 70%

0
docs/graphql/manual/actions/debugging.rst → docs/graphql/core/actions/debugging.rst
View File

6
docs/graphql/manual/actions/derive.rst → docs/graphql/core/actions/derive.rst
View File

@ -75,13 +75,13 @@ derive our action:
Next hit the ``Derive action`` button as shown below:
.. thumbnail:: /img/graphql/manual/actions/actions-derive-button.png
.. thumbnail:: /img/graphql/core/actions/actions-derive-button.png
:alt: Console derive action button
This will redirect you to the ``Add a new action`` page with the action
definition auto filled.
.. thumbnail:: /img/graphql/manual/actions/actions-derive-types.png
.. thumbnail:: /img/graphql/core/actions/actions-derive-types.png
:alt: Console derived action types
@ -149,7 +149,7 @@ the action back to the original operation.
You can select the framework of your choice to get the corresponding
handler boilerplate code.
.. thumbnail:: /img/graphql/manual/actions/actions-derive-codegen.png
.. thumbnail:: /img/graphql/core/actions/actions-derive-codegen.png
:alt: Console derived action codegen
.. note::

2
docs/graphql/manual/actions/index.rst → docs/graphql/core/actions/index.rst
View File

@ -20,7 +20,7 @@ logic using custom queries and mutations. Actions can be
added to Hasura to handle various use cases such as data validation, data
enrichment from external sources and any other complex business logic.
.. thumbnail:: /img/graphql/manual/actions/actions-arch.png
.. thumbnail:: /img/graphql/core/actions/actions-arch.png
:class: no-shadow
:alt: Actions high level architecture

2
docs/graphql/manual/actions/reuse-types-actions.rst → docs/graphql/core/actions/reuse-types-actions.rst
View File

@ -98,7 +98,7 @@ You can create relationships for custom output types by:
Set the output type relationship as shown below:
.. thumbnail:: /img/graphql/manual/actions/actions-relationship.png
.. thumbnail:: /img/graphql/core/actions/actions-relationship.png
:alt: Console action relationship
Hit ``Save`` to create the relationship.

0
docs/graphql/manual/actions/types/index.rst → docs/graphql/core/actions/types/index.rst
View File

3
docs/graphql/manual/api-reference/config.rst → docs/graphql/core/api-reference/config.rst
View File

@ -12,6 +12,9 @@ Config API Reference
:depth: 1
:local:
Introduction
------------
The Config API is an admin only endpoint which gives info on the server
configuration.

3
docs/graphql/manual/api-reference/explain.rst → docs/graphql/core/api-reference/explain.rst
View File

@ -12,6 +12,9 @@ Explain API Reference
:depth: 1
:local:
Introduction
------------
The Explain API is used to analyse queries and subscriptions. It returns a list of Postgres plans for a query and a single Postgres plan for a subscription, based
on the defined permissions.

3
docs/graphql/manual/api-reference/graphql-api/index.rst → docs/graphql/core/api-reference/graphql-api/index.rst
View File

@ -12,6 +12,9 @@ GraphQL API Reference
:depth: 1
:local:
Introduction
------------
All GraphQL requests for queries, subscriptions and mutations are made to the GraphQL API.
Endpoint

0
docs/graphql/manual/api-reference/graphql-api/mutation.rst → docs/graphql/core/api-reference/graphql-api/mutation.rst
View File

0
docs/graphql/manual/api-reference/graphql-api/query.rst → docs/graphql/core/api-reference/graphql-api/query.rst
View File

3
docs/graphql/manual/api-reference/health.rst → docs/graphql/core/api-reference/health.rst
View File

@ -12,6 +12,9 @@ Health check API Reference
:depth: 1
:local:
Introduction
------------
The Health API is a public endpoint which gives info on the server health.
Endpoint

0
docs/graphql/manual/api-reference/index.rst → docs/graphql/core/api-reference/index.rst
View File

3
docs/graphql/manual/api-reference/pgdump.rst → docs/graphql/core/api-reference/pgdump.rst
View File

@ -12,6 +12,9 @@ PG Dump API Reference
:depth: 1
:local:
Introduction
------------
The PG Dump API is an admin-only endpoint that can be used to execute ``pg_dump`` on the
Postgres instance that Hasura is configured with.

0
docs/graphql/manual/api-reference/pgtypes.csv → docs/graphql/core/api-reference/pgtypes.csv
View File

3
docs/graphql/manual/api-reference/postgresql-types.rst → docs/graphql/core/api-reference/postgresql-types.rst
View File

@ -14,6 +14,9 @@ API Reference - Supported PostgreSQL Types
.. _types_table:
Introduction
------------
List of PostgreSQL types supported by the Hasura GraphQL engine with their equivalent Hasura types:
.. csv-table::

3
docs/graphql/manual/api-reference/schema-metadata-api/actions.rst → docs/graphql/core/api-reference/schema-metadata-api/actions.rst
View File

@ -12,6 +12,9 @@ Schema/Metadata API Reference: Actions
:depth: 1
:local:
Introduction
------------
**actions** are user defined mutations with custom business logic.
.. _create_action:

3
docs/graphql/manual/api-reference/schema-metadata-api/computed-field.rst → docs/graphql/core/api-reference/schema-metadata-api/computed-field.rst
View File

@ -12,6 +12,9 @@ Schema/Metadata API Reference: Computed Fields
:depth: 1
:local:
Introduction
------------
**computed field** is an extra field added to a table, its value is
computed via an SQL function which has the table row type as an input argument.
Currenty, the Hasura GraphQL engine supports functions returning

3
docs/graphql/manual/api-reference/schema-metadata-api/custom-functions.rst → docs/graphql/core/api-reference/schema-metadata-api/custom-functions.rst
View File

@ -12,6 +12,9 @@ Schema/Metadata API Reference: Custom Functions
:depth: 1
:local:
Introduction
------------
Track/untrack a custom SQL function in the Hasura GraphQL engine.
Only tracked custom functions are available for querying/mutating/subscribing data over the GraphQL API.

8
docs/graphql/manual/api-reference/schema-metadata-api/custom-types.rst → docs/graphql/core/api-reference/schema-metadata-api/custom-types.rst
View File

@ -7,6 +7,14 @@
Schema/Metadata API Reference: Custom Types
===========================================
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Introduction
------------
**Custom Types** are user-defined GraphQL types which help to define :ref:`Actions <api_actions>`.
.. _set_custom_types:

0
docs/graphql/manual/api-reference/schema-metadata-api/dataerrors.csv → docs/graphql/core/api-reference/schema-metadata-api/dataerrors.csv
View File

3
docs/graphql/manual/api-reference/schema-metadata-api/event-triggers.rst → docs/graphql/core/api-reference/schema-metadata-api/event-triggers.rst
View File

@ -12,6 +12,9 @@ Schema/Metadata API Reference: Event Triggers
:depth: 1
:local:
Introduction
------------
Event triggers are used to capture database changes and send them to a configured webhook.
.. _create_event_trigger:

3
docs/graphql/manual/api-reference/schema-metadata-api/index.rst → docs/graphql/core/api-reference/schema-metadata-api/index.rst
View File

@ -12,6 +12,9 @@ Schema / Metadata API Reference
:depth: 1
:local:
Introduction
------------
The schema / metadata API provides the following features:
1. Execute SQL on the underlying Postgres database, supports schema modifying actions.

3
docs/graphql/manual/api-reference/schema-metadata-api/manage-metadata.rst → docs/graphql/core/api-reference/schema-metadata-api/manage-metadata.rst
View File

@ -12,6 +12,9 @@ Schema/Metadata API Reference: Manage metadata
:depth: 1
:local:
Introduction
------------
APIs to manage Hasura metadata which is stored in ``hdb_catalog`` schema.
.. _export_metadata:

3
docs/graphql/manual/api-reference/schema-metadata-api/permission.rst → docs/graphql/core/api-reference/schema-metadata-api/permission.rst
View File

@ -12,6 +12,9 @@ Schema/Metadata API Reference: Permissions
:depth: 1
:local:
Introduction
------------
The permission layer is designed to restrict the operations that can be
performed by various users. Permissions can be defined on various operations
(insert/select/update/delete) at a role level granularity. By default, the ``admin``

3
docs/graphql/manual/api-reference/schema-metadata-api/query-collections.rst → docs/graphql/core/api-reference/schema-metadata-api/query-collections.rst
View File

@ -12,6 +12,9 @@ Schema/Metadata API Reference: Query collections
:depth: 1
:local:
Introduction
------------
Group queries using query collections.
Create/drop query collections and add/drop a query to a collection using the following query types.

3
docs/graphql/manual/api-reference/schema-metadata-api/relationship.rst → docs/graphql/core/api-reference/schema-metadata-api/relationship.rst
View File

@ -12,6 +12,9 @@ Schema/Metadata API Reference: Relationships
:depth: 1
:local:
Introduction
------------
When retrieving data from tables, it is very helpful if we can also
fetch the related data alongside the columns. This is where relationships come
in. They can be considered as pseudo columns for a table to access the related

3
docs/graphql/manual/api-reference/schema-metadata-api/remote-relationships.rst → docs/graphql/core/api-reference/schema-metadata-api/remote-relationships.rst
View File

@ -10,6 +10,9 @@ Schema/Metadata API Reference: Remote Relationships
:depth: 1
:local:
Introduction
------------
Remote Relationships allow you to join tables with remote schemas.
.. _create_remote_relationship:

3
docs/graphql/manual/api-reference/schema-metadata-api/remote-schemas.rst → docs/graphql/core/api-reference/schema-metadata-api/remote-schemas.rst
View File

@ -12,6 +12,9 @@ Schema/Metadata API Reference: Remote schemas
:depth: 1
:local:
Introduction
------------
Add/Remove a remote GraphQL server as remote schema in Hasura GraphQL engine.
.. _add_remote_schema:

0
docs/graphql/manual/api-reference/schema-metadata-api/run-sql.rst → docs/graphql/core/api-reference/schema-metadata-api/run-sql.rst
View File

3
docs/graphql/manual/api-reference/schema-metadata-api/scheduled-triggers.rst → docs/graphql/core/api-reference/schema-metadata-api/scheduled-triggers.rst
View File

@ -10,6 +10,9 @@ Schema/Metadata API Reference: Scheduled Triggers
:depth: 1
:local:
Introduction
------------
Scheduled triggers are used to invoke webhooks based on a timestamp or cron.
.. _create_cron_trigger:

0
docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst → docs/graphql/core/api-reference/schema-metadata-api/syntax-defs.rst
View File

3
docs/graphql/manual/api-reference/schema-metadata-api/table-view.rst → docs/graphql/core/api-reference/schema-metadata-api/table-view.rst
View File

@ -12,6 +12,9 @@ Schema/Metadata API Reference: Tables/Views
:depth: 1
:local:
Introduction
------------
Track/untrack a table/view in Hasura GraphQL engine.
Only tracked tables/views are available for querying/mutating/subscribing data over the GraphQL API.

2
docs/graphql/manual/api-reference/version.rst → docs/graphql/core/api-reference/version.rst
View File

@ -12,6 +12,8 @@ Version API Reference
:depth: 1
:local:
Introduction
------------
The ``/v1/version`` is a public endpoint that responds with the current server version in JSON format.

4
docs/graphql/manual/auth/authentication/index.rst → docs/graphql/core/auth/authentication/index.rst
View File

@ -39,7 +39,7 @@ rules.
Here's how a GraphQL request is processed in webhook mode:
.. thumbnail:: /img/graphql/manual/auth/auth-webhook-overview.png
.. thumbnail:: /img/graphql/core/auth/auth-webhook-overview.png
:alt: Authentication using webhooks
2. JWT (JSON Web Token)
@ -51,7 +51,7 @@ evaluate access control rules.
Here's how a GraphQL query is processed in JWT mode:
.. thumbnail:: /img/graphql/manual/auth/auth-jwt-overview.png
.. thumbnail:: /img/graphql/core/auth/auth-jwt-overview.png
:alt: Authentication using JWT
**See more details at:**

133
docs/graphql/manual/auth/authentication/jwt.rst → docs/graphql/core/auth/authentication/jwt.rst
View File

@ -21,7 +21,7 @@ The idea is that your auth server will return JWT tokens, which are decoded and
verified by the GraphQL engine, to authorize and get metadata about the request
(``x-hasura-*`` values).
.. thumbnail:: /img/graphql/manual/auth/jwt-auth.png
.. thumbnail:: /img/graphql/core/auth/jwt-auth.png
:alt: Authentication using JWT
The JWT is decoded, the signature is verified, then it is asserted that the
@ -133,7 +133,8 @@ JSON object:
"claims_namespace_path":"<optional-json-path-to-the-claims>",
"claims_format": "json|stringified_json",
"audience": <optional-string-or-list-of-strings-to-verify-audience>,
"issuer": "<optional-string-to-verify-issuer>"
"issuer": "<optional-string-to-verify-issuer>",
"claims_map": "<optional-object-of-session-variable-to-claim-jsonpath-or-literal-value>"
}
(``type``, ``key``) pair or ``jwk_url``, **one of them has to be present**.
@ -255,8 +256,6 @@ set to ``$.hasura.claims``:
values set. If neither keys are set, then the default value of
``claims_namespace`` i.e. https://hasura.io/jwt/claims will be used.
``claims_format``
^^^^^^^^^^^^^^^^^
This is an optional field, with only the following possible values:
- ``json``
- ``stringified_json``
@ -371,6 +370,130 @@ Examples:
that you can set this field to the appropriate value.
``claims_map``
^^^^^^^^^^^^^^
This is an optional field. Certain providers might not allow adding custom claims.
In such a case, you can map Hasura session variables with existing JWT claims
using ``claims_map``. The ``claims_map`` is a JSON object where keys are session
variables and values can be a JSON path (with a default value option, when the key
specified by the JSON path doesn't exist) or a literal value.
The literal values should be a ``String``, except for the ``x-hasura-allowed-roles`` claim
which expects a ``String`` array.
The value of a claim referred by a JSON path must be a ``String``.
To use the JSON path value, the path needs to be given in a JSON object with ``path``
as the key and the JSON path as the value:
.. code-block:: json
{
"path" : "$.user.all_roles",
}
.. code-block:: json
{
"path" : "$.roles.default",
"default": "user"
}
**Example: JWT config with JSON path values**
.. code-block:: json
{
"sub": "1234567890",
"name": "John Doe",
"admin": true,
"iat": 1516239022,
"user": {
"id": "ujdh739kd"
},
"hasura": {
"all_roles": ["user", "editor"],
}
}
The mapping for ``x-hasura-allowed-roles``, ``x-hasura-default-role`` and ``x-hasura-user-id`` session
variables can be specified in the ``claims_map`` configuration as follows:
.. code-block:: json
{
"type":"RS512",
"key": "-----BEGIN PUBLIC KEY-----\nMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDdlatRjRjogo3WojgGHFHYLugd\nUWAY9iR3fy4arWNA1KoS8kVw33cJibXr8bvwUAUparCwlvdbH6dvEOfou0/gCFQs\nHUfQrSDv+MuSUMAe8jzKE4qW+jK+xQU9a03GUnKHkkle+Q0pX/g6jXZ7r1/xAK5D\no2kQ+X5xK9cipRgEKwIDAQAB\n-----END PUBLIC KEY-----\n",
"claims_map": {
"x-hasura-allowed-roles": {"path":"$.hasura.all_roles"},
"x-hasura-default-role": {"path":"$.hasura.all_roles[0]"},
"x-hasura-user-id": {"path":"$.user.id"}
}
}
**Example: JWT config with JSON path values and default values**
.. code-block:: json
{
"sub": "1234567890",
"name": "John Doe",
"admin": true,
"iat": 1516239022,
"hasura": {
"all_roles": ["user", "editor"],
}
}
.. code-block:: json
{
"type":"RS512",
"key": "-----BEGIN PUBLIC KEY-----\nMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDdlatRjRjogo3WojgGHFHYLugd\nUWAY9iR3fy4arWNA1KoS8kVw33cJibXr8bvwUAUparCwlvdbH6dvEOfou0/gCFQs\nHUfQrSDv+MuSUMAe8jzKE4qW+jK+xQU9a03GUnKHkkle+Q0pX/g6jXZ7r1/xAK5D\no2kQ+X5xK9cipRgEKwIDAQAB\n-----END PUBLIC KEY-----\n",
"claims_map": {
"x-hasura-allowed-roles": {"path":"$.hasura.all_roles"},
"x-hasura-default-role": {"path":"$.hasura.all_roles[0]"},
"x-hasura-user-id": {"path":"$.user.id","default":"ujdh739kd"}
}
}
In the above case, since the ``$.user.id`` doesn't exist in the JWT token, the default
value of the ``x-hasura-user-id`` i.e "ujdh739kd" will be used
**Example: JWT config containing literal values**
.. code-block:: json
{
"sub": "1234567890",
"name": "John Doe",
"admin": true,
"iat": 1516239022,
"user": {
"id": "ujdh739kd"
}
}
The corresponding JWT config should be:
.. code-block:: json
{
"type":"RS512",
"key": "-----BEGIN PUBLIC KEY-----\nMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDdlatRjRjogo3WojgGHFHYLugd\nUWAY9iR3fy4arWNA1KoS8kVw33cJibXr8bvwUAUparCwlvdbH6dvEOfou0/gCFQs\nHUfQrSDv+MuSUMAe8jzKE4qW+jK+xQU9a03GUnKHkkle+Q0pX/g6jXZ7r1/xAK5D\no2kQ+X5xK9cipRgEKwIDAQAB\n-----END PUBLIC KEY-----\n",
"claims_map": {
"x-hasura-allowed-roles": ["user","editor"],
"x-hasura-default-role": "user",
"x-hasura-user-id": {"path":"$.user.id"}
}
}
In the above example, the ``x-hasura-allowed-roles`` and ``x-hasura-default-role`` values are set in the JWT
config and the value of the ``x-hasura-user-id`` is a JSON path to the value in the JWT token.
Examples
^^^^^^^^
@ -543,7 +666,7 @@ https://hasura.io/jwt-config.
The config generated from this page can be directly pasted in yaml files and command line arguments as it takes
care of escaping new lines.
.. thumbnail:: /img/graphql/manual/auth/jwt-config-generated.png
.. thumbnail:: /img/graphql/core/auth/jwt-config-generated.png
:width: 75%
:alt: Generating JWT config

0
docs/graphql/manual/auth/authentication/unauthenticated-access.rst → docs/graphql/core/auth/authentication/unauthenticated-access.rst
View File

2
docs/graphql/manual/auth/authentication/webhook.rst → docs/graphql/core/auth/authentication/webhook.rst
View File

@ -17,7 +17,7 @@ Introduction
You can configure the GraphQL engine to use a webhook to authenticate all incoming requests to the Hasura GraphQL engine server.
.. thumbnail:: /img/graphql/manual/auth/webhook-auth.png
.. thumbnail:: /img/graphql/core/auth/webhook-auth.png
:alt: Authentication using webhooks
.. admonition:: Prerequisite

8
docs/graphql/manual/auth/authorization/basics.rst → docs/graphql/core/auth/authorization/basics.rst
View File

@ -18,7 +18,7 @@ Introduction
To understand the basics of access control in Hasura, let's take a look at this analogy to a SQL query:
.. thumbnail:: /img/graphql/manual/auth/permissions-rule-analogy.png
.. thumbnail:: /img/graphql/core/auth/permissions-rule-analogy.png
:width: 70%
:alt: Understanding access control in Hasura
@ -80,7 +80,7 @@ Head to the ``GraphiQL`` tab in your console and try out the below query:
You'll see that this results in a response that contains all the authors because by default the GraphQL
query is accepted with **admin** permissions.
.. thumbnail:: /img/graphql/manual/auth/fetch-authors.png
.. thumbnail:: /img/graphql/core/auth/fetch-authors.png
:alt: Run a query without access control
Define access control rules
@ -90,7 +90,7 @@ Now let's define an access control rule for the ``author`` table for a role ``us
**Permissions** section of the table (``Data`` --> <table> --> ``Permissions`` tab) and define permissions
as shown below:
.. thumbnail:: /img/graphql/manual/auth/permission-basics-simple-example.png
.. thumbnail:: /img/graphql/core/auth/permission-basics-simple-example.png
:alt: Define access control rules
This permission rule reads as: "*For the role* ``user`` *, table* ``author`` *and operation* ``select``/``query``,
@ -103,7 +103,7 @@ Let's run the same query as above but now with the ``X-Hasura-Role`` and ``X-Has
variables also included to indicate role and user information. These session variables are passed in
the ``Request Headers`` section of ``GraphiQL`` as highlighted below:
.. thumbnail:: /img/graphql/manual/auth/permission-basics-query-with-access-control.png
.. thumbnail:: /img/graphql/core/auth/permission-basics-query-with-access-control.png
:alt: Run a query with access control
As you can see, the results are now filtered based on the access control rule for the role ``user``

27
docs/graphql/manual/auth/authorization/common-roles-auth-examples.rst → docs/graphql/core/auth/authorization/common-roles-auth-examples.rst
View File

@ -12,6 +12,9 @@ Access control examples
:depth: 1
:local:
Introduction
------------
This is a guide to help you set up a basic authorization architecture for your GraphQL fields. It is recommended
that you first check out :ref:`roles_variables` and :ref:`permission_rules`
that will be referred to throughout this guide.
@ -31,7 +34,7 @@ Anonymous (not logged in) users
- Choose the right set of columns that will get exposed in the GraphQL schema as fields. Ensure that sensitive
information will not be exposed.
.. thumbnail:: /img/graphql/manual/auth/anonymous-role-examples.png
.. thumbnail:: /img/graphql/core/auth/anonymous-role-examples.png
:class: no-shadow
:alt: Access control for an anonymous role
@ -47,7 +50,7 @@ Logged-in users
- Note that the ``X-Hasura-User-Id`` is a :ref:`dynamic session variable<roles_variables>` that comes in from
your :ref:`auth webhook's <auth_webhooks>` response, or as a request header if you're testing.
.. thumbnail:: /img/graphql/manual/auth/user-select-graphiql.png
.. thumbnail:: /img/graphql/core/auth/user-select-graphiql.png
:class: no-shadow
:alt: Access control for a logged-in user
@ -64,7 +67,7 @@ organisation either in the same table or via a related table.
- ``X-Hasura-Org-Id`` is a :ref:`dynamic variable <roles_variables>` that is returned by your
:ref:`auth webhook <auth_webhooks>` for an incoming GraphQL request.
.. thumbnail:: /img/graphql/manual/auth/org-manager-graphiql.png
.. thumbnail:: /img/graphql/core/auth/org-manager-graphiql.png
:class: no-shadow
:alt: Access control for a manager of an organisation
@ -84,7 +87,7 @@ Let's say the "ownership" or "visibility" information for a data model (table) i
- This reads as: Allow the role collaborator to select if ``article.collaborators`` has a ``collaborator_id``
equal to that of ``X-Hasura-User-Id``.
.. thumbnail:: /img/graphql/manual/auth/collaborator-relationship.png
.. thumbnail:: /img/graphql/core/auth/collaborator-relationship.png
:class: no-shadow
:alt: Access control for collaborators of an article
@ -149,7 +152,7 @@ Database Schema
The following is a reference database schema for our example:
.. thumbnail:: /img/graphql/manual/auth/multirole-example-db-schema.png
.. thumbnail:: /img/graphql/core/auth/multirole-example-db-schema.png
:alt: Database schema example for multiple roles per user
Based on this schema, we'll create the following tables:
@ -196,7 +199,7 @@ Relationships
Create an array relationship named ``reviewers`` based on the foreign key constraint ``reviewers`` :: ``article_id`` → ``articles`` :: ``id``:
.. thumbnail:: /img/graphql/manual/auth/multirole-example-reviewers-array-relationship.png
.. thumbnail:: /img/graphql/core/auth/multirole-example-reviewers-array-relationship.png
:class: no-shadow
:alt: Create an array relationship
@ -240,7 +243,7 @@ Permissions for role ``author``
b) :ref:`Column presets <column_presets>`: Session-variable-based column preset for the ``author_id`` column to automatically insert the user's ID i.e. the ``X-Hasura-User-Id`` session-variable's value. It also helps us avoid explicitly passing the user's ID in the insert mutation.
.. thumbnail:: /img/graphql/manual/auth/multirole-example-author-insert.png
.. thumbnail:: /img/graphql/core/auth/multirole-example-author-insert.png
:alt: Permissions for the role author
Notice how we don't need to have an explicit row-level permission (*a custom check*) as only authenticated users with the role ``author`` can perform this action. As we have a column preset for the ``author_id`` column that automatically takes the author's ID (*and the* ``id`` *column is an auto-increment integer field*), we only need to allow access to the ``title`` column.
@ -249,7 +252,7 @@ Permissions for role ``author``
Again, we'll use **column-level** permissions to restrict access to certain columns. Additionally, we need to define row-level permissions (*a custom check*) to restrict access to only those articles authored by the current user:
.. thumbnail:: /img/graphql/manual/auth/multirole-example-author-select.png
.. thumbnail:: /img/graphql/core/auth/multirole-example-author-select.png
:alt: Column access for the role author
The row-level permission rule shown here translates to "*if the value in the* ``author_id`` *column of this row is equal to the user's ID i.e. the* ``X-Hasura-User-Id`` *session-variable's value, allow access to it*".
@ -261,7 +264,7 @@ Permissions for role ``reviewer``
For this use-case, we'll use :ref:`relationship or nested-object permissions<relationships-in-permissions>` based on the array relationship ``reviewers`` to restrict access to assigned articles only.
.. thumbnail:: /img/graphql/manual/auth/multirole-example-reviewer-update.png
.. thumbnail:: /img/graphql/core/auth/multirole-example-reviewer-update.png
:alt: Permissions for the role reviewer
The array-relationship based permission rule in the above image reads as "*if the ID of any reviewer assigned to this article is equal to the user's ID i.e. the* ``X-Hasura-User-Id`` *session-variable's value, allow access to it*". The columns' access is restricted using the column-level permissions highlighted above.
@ -270,7 +273,7 @@ Permissions for role ``reviewer``
This permission rule is pretty much the same as the one for update, the only difference being the column-level permissions.
.. thumbnail:: /img/graphql/manual/auth/multirole-example-reviewer-select.png
.. thumbnail:: /img/graphql/core/auth/multirole-example-reviewer-select.png
:alt: Column access for the role reviewer
Permissions for role ``editor``
@ -280,14 +283,14 @@ Permissions for role ``editor``
This is a straightforward rule - there's no need for any row-level permissions since editors have access to all rows and they can *read* all columns.
.. thumbnail:: /img/graphql/manual/auth/multirole-example-editor-select.png
.. thumbnail:: /img/graphql/core/auth/multirole-example-editor-select.png
:alt: Permissions for the role editor
* **Allow editors to update an article**
There's no need for row-level permissions in this case either but we need to restrict access to certain columns only:
.. thumbnail:: /img/graphql/manual/auth/multirole-example-editor-update.png
.. thumbnail:: /img/graphql/core/auth/multirole-example-editor-update.png
:alt: Column access for the role editor

2
docs/graphql/manual/auth/authorization/index.rst → docs/graphql/core/auth/authorization/index.rst
View File

@ -23,7 +23,7 @@ session variables. Other session variables can be passed by your auth service as
**For example:**
.. thumbnail:: /img/graphql/manual/auth/hasura-perms.png
.. thumbnail:: /img/graphql/core/auth/hasura-perms.png
:width: 80 %
:alt: Create a permission rule

2
docs/graphql/manual/auth/authorization/modeling-roles.rst.wip → docs/graphql/core/auth/authorization/modeling-roles.rst.wip
View File

@ -18,7 +18,7 @@ Roles can be typically be modeled in two ways:
1. **Hierarchical roles**: Access scopes are nested depending on available roles. `Roles in Github for organisations <https://help.github.com/en/articles/managing-peoples-access-to-your-organization-with-roles>`_
is a great example of such modelling where access scopes are inherited by deeper roles:
.. thumbnail:: /img/graphql/manual/auth/github-org-hierarchical-roles.png
.. thumbnail:: /img/graphql/core/auth/github-org-hierarchical-roles.png
2. **Flat roles**: Non-hierarchical roles with each role requiring an independent access scope to be defined.

24
docs/graphql/manual/auth/authorization/permission-rules.rst → docs/graphql/core/auth/authorization/permission-rules.rst
View File

@ -18,7 +18,7 @@ Introduction
Access control rules in Hasura are defined at a role, table and action (*insert, update, select, delete*)
level granularity:
.. thumbnail:: /img/graphql/manual/auth/permission-rule-granularity.png
.. thumbnail:: /img/graphql/core/auth/permission-rule-granularity.png
:alt: Access control rules in Hasura
Requests to Hasura should contain the reserved session variable ``X-Hasura-Role`` to indicate the requesting
@ -108,11 +108,11 @@ See the :ref:`API reference <MetadataOperator>` for a list of all supported colu
types:
.. thumbnail:: /img/graphql/manual/auth/operators-for-integer-types.png
.. thumbnail:: /img/graphql/core/auth/operators-for-integer-types.png
:width: 40%
:alt: Column operators for integer types
.. thumbnail:: /img/graphql/manual/auth/operators-for-text-types.png
.. thumbnail:: /img/graphql/core/auth/operators-for-text-types.png
:width: 40%
:alt: Column operators for text types
@ -122,19 +122,19 @@ Using boolean expressions
The following is an example of a simple boolean expression to restrict access for ``select`` to rows where
the value in the ``id`` column is greater than 10:
.. thumbnail:: /img/graphql/manual/auth/simple-boolean-expression.png
.. thumbnail:: /img/graphql/core/auth/simple-boolean-expression.png
:alt: Using boolean expressions to build rules
You can construct more complex boolean expressions using the ``_and``, ``_or`` and ``not`` operators:
.. thumbnail:: /img/graphql/manual/auth/boolean-operators.png
.. thumbnail:: /img/graphql/core/auth/boolean-operators.png
:alt: Using more complex boolean expressions to build rules
**For example**, using the ``_and`` operator, you can construct a rule to restrict access for ``select`` to rows where
the value in the ``id`` column is greater than 10 **and** the value in the ``name`` column starts with "a"
or "A":
.. thumbnail:: /img/graphql/manual/auth/composite-boolean-expression.png
.. thumbnail:: /img/graphql/core/auth/composite-boolean-expression.png
:alt: Example of a rule with the _and operator
Using session variables
@ -148,7 +148,7 @@ to construct a rule to restrict access for ``select`` to rows in the ``articles`
``id`` column is equal to the value in the session variable (*assuming this variable is being used to indicate
the author's ID*):
.. thumbnail:: /img/graphql/manual/auth/session-variables-in-permissions-simple-example.png
.. thumbnail:: /img/graphql/core/auth/session-variables-in-permissions-simple-example.png
:alt: Using session variables to build rules
.. _relationships-in-permissions:
@ -164,7 +164,7 @@ called ``agent`` (*an author can have an agent*) and we want to allow users with
the details of the authors who they manage in ``authors`` table. We can define the following permission rule
that uses the aforementioned object relationship:
.. thumbnail:: /img/graphql/manual/auth/nested-object-permission-simple-example.png
.. thumbnail:: /img/graphql/core/auth/nested-object-permission-simple-example.png
:alt: Using a nested object to build rules
This permission rule reads as "*if the author's agent's* ``id`` *is the same as the requesting user's*
@ -191,7 +191,7 @@ our table.
column in the ``users`` table is set to ``true``. Let's assume the user's id is passed in the ``X-Hasura-User-ID``
session variable.
.. thumbnail:: /img/graphql/manual/auth/exists-permission-example.png
.. thumbnail:: /img/graphql/core/auth/exists-permission-example.png
:alt: Use an unrelated table to build rules
This permission rule reads as "*if there exists a row in the table* ``users`` *whose* ``id`` *is the same as the requesting user's*
@ -204,7 +204,7 @@ Column-level permissions
Column-level permissions determine access to columns in the rows that are accessible based on row-level
permissions. These permissions are simple selections:
.. thumbnail:: /img/graphql/manual/auth/column-level-permissions.png
.. thumbnail:: /img/graphql/core/auth/column-level-permissions.png
:alt: Column level permissions
In this example, the role ``author`` has only partial access to columns of the accessible rows for
@ -218,7 +218,7 @@ Row fetch limit
In the case of ``select`` operations, the number of rows to be returned in the response can be limited
using this configuration:
.. thumbnail:: /img/graphql/manual/auth/limit-rows-for-select.png
.. thumbnail:: /img/graphql/core/auth/limit-rows-for-select.png
:alt: Row fetch limit
In the above example, this configuration restricts the number of accessible rows (*based on the rule*:
@ -232,7 +232,7 @@ Aggregation queries permissions
In the case of ``select`` operations, access to :ref:`aggregation queries <aggregation_queries>`
can be restricted for a given role using this configuration.
.. thumbnail:: /img/graphql/manual/auth/aggregation-query-permissions.png
.. thumbnail:: /img/graphql/core/auth/aggregation-query-permissions.png
:alt: Aggregation queries permissions
In the above example, the role ``user`` is allowed to make aggregation queries.

24
docs/graphql/manual/auth/authorization/reference-permissions.rst.wip → docs/graphql/core/auth/authorization/reference-permissions.rst.wip
View File

@ -13,7 +13,7 @@ How permissions work
Access control rules in Hasura are defined at a role, table and action (*insert, update, select, delete*) level granulaity:
.. thumbnail:: /img/graphql/manual/auth/permission-rule-granularity.png
.. thumbnail:: /img/graphql/core/auth/permission-rule-granularity.png
Requests to Hasura should contain the reserved session variable ``X-Hasura-Role`` to indicate the requesting user's role, and the table and action information is inferred from the request itself. This information is used to determine the right permission rule to be applied (*if one has been defined*) to the incoming request.
@ -65,7 +65,7 @@ If you make this query as an admin in the Graphiql section of the console and cl
Let's say you now define the following permission rule on the ``authors`` table (*as described in the example* :doc:`here <basics>`):
.. thumbnail:: /img/graphql/manual/auth/permission-basics-simple-example.png
.. thumbnail:: /img/graphql/core/auth/permission-basics-simple-example.png
If you were to run the same query with the role ``user`` (``X-Hasura-Role`` = ``user``) and as a user with ``id`` = ``1`` (``X-Hasura-User-ID`` = ``1``) and hit the **Analyze** button, you will see the following generated SQL:
@ -149,24 +149,24 @@ Type-based operators (*depending on the column type*) are available for construc
E.g. the following two images illustrate the different operators available for ``integer`` and ``text`` types:
.. thumbnail:: /img/graphql/manual/auth/operators-for-integer-types.png
.. thumbnail:: /img/graphql/core/auth/operators-for-integer-types.png
.. thumbnail:: /img/graphql/manual/auth/operators-for-text-types.png
.. thumbnail:: /img/graphql/core/auth/operators-for-text-types.png
**Using boolean expressions**
#############################
The following is an example of a simple boolean expression to restrict access for ``select`` to rows where the value in the ``id`` column is greater than 10:
.. thumbnail:: /img/graphql/manual/auth/simple-boolean-expression.png
.. thumbnail:: /img/graphql/core/auth/simple-boolean-expression.png
You can construct more complex boolean expression using the ``_and``, ``_or`` and ``not`` operators:
.. thumbnail:: /img/graphql/manual/auth/boolean-operators.png
.. thumbnail:: /img/graphql/core/auth/boolean-operators.png
E.g. using the ``_and`` operator, you can construct a rule to restrict access for ``select`` to rows where the value in the ``id`` column is greater than 10 **and** the value in the ``name`` column starts with "a" or "A":
.. thumbnail:: /img/graphql/manual/auth/composite-boolean-expression.png
.. thumbnail:: /img/graphql/core/auth/composite-boolean-expression.png
.. Using roles
.. ###########
@ -179,7 +179,7 @@ Session variable, that have been resolved from authentication tokens by either y
E.g. to allow an ``author`` to access only their articles, you can use the ``X-Hasura-User-ID`` session variable to construct a rule to restrict access for ``select`` to rows in the ``articles`` table where the value in the ``id`` column is equal to the value in the session variable (*assuming this variable is being used to indicate the author's ID*):
.. thumbnail:: /img/graphql/manual/auth/session-variables-in-permissions-simple-example.png
.. thumbnail:: /img/graphql/core/auth/session-variables-in-permissions-simple-example.png
.. _relationships-in-permissions:
@ -190,7 +190,7 @@ You can leverage :doc:`relationships <../../schema/relationships/index>` to defi
For e.g. let's say you have an object relationship called ``agent`` from the ``authors`` table to another table called ``agent`` (*an author can have an agent*) and we want to allow users with the role ``agent`` to access the details of the authors who they manage in ``authors`` table. We can define the following permission rule that uses the aforementioned object relationship:
.. thumbnail:: /img/graphql/manual/auth/nested-object-permission-simple-example.png
.. thumbnail:: /img/graphql/core/auth/nested-object-permission-simple-example.png
This permission rule reads as "*if the author's agent's* ``id`` *is the same as the requesting user's* ``id`` *, allow access to the author's details*.
@ -208,7 +208,7 @@ Column-level permissions
^^^^^^^^^^^^^^^^^^^^^^^^
Column-level permissions determine access to columns in the rows that accessible based on row-level permissions. These permissions are simple selections:
.. thumbnail:: /img/graphql/manual/auth/column-level-permissions.png
.. thumbnail:: /img/graphql/core/auth/column-level-permissions.png
In this example, the role ``author`` has only partial access to columns of the accessible rows for the ``select`` operation.
@ -219,7 +219,7 @@ Limiting number of rows
In the case of ``select`` operations, the number of rows to be returned in the response can be limited using this configuration:
.. thumbnail:: /img/graphql/manual/auth/limit-rows-for-select.png
.. thumbnail:: /img/graphql/core/auth/limit-rows-for-select.png
In the above example, this configuration restricts the number of accessible rows (*based on the rule*: ``{"id":{"_eq":"X-Hasura-User-Id"}}``) to 20.
@ -230,7 +230,7 @@ Aggregation queries permissions
In the case of ``select`` operations, access to :doc:`aggregation queries <../../queries/aggregation-queries>` can be restricted for a given role using this configuration.
.. thumbnail:: /img/graphql/manual/auth/aggregation-query-permissions.png
.. thumbnail:: /img/graphql/core/auth/aggregation-query-permissions.png
In the above example, the role ``user`` is allowed to make aggregation queries.

6
docs/graphql/manual/auth/authorization/role-multiple-rules.rst → docs/graphql/core/auth/authorization/role-multiple-rules.rst
View File

@ -53,7 +53,7 @@ Step 2: Create a relationship
For the table ``user_info``, :ref:`create a manual object relationship <create_manual_relationships>` called
``private_info`` using ``user_info : id -> user_private : user_id``:
.. thumbnail:: /img/graphql/manual/auth/multiple-rules-create-manual-relationship.png
.. thumbnail:: /img/graphql/core/auth/multiple-rules-create-manual-relationship.png
:alt: Create a manual object relationship
Step 3: Define permissions
@ -63,13 +63,13 @@ For the role ``user``, create the following permissions for ``select``:
- Table ``user_info``: allow access to ``id``, ``name`` and ``city`` without any row conditions.
.. thumbnail:: /img/graphql/manual/auth/multiple-rules-define-public-permissions.png
.. thumbnail:: /img/graphql/core/auth/multiple-rules-define-public-permissions.png
:alt: Column access for the role user
- View ``user_private``: allow access to ``id``, ``phone``, ``email`` and ``address`` if the ``user-id``
passed in the session variable is equal to the row's ``user_id``.
.. thumbnail:: /img/graphql/manual/auth/multiple-rules-define-private-permissions.png
.. thumbnail:: /img/graphql/core/auth/multiple-rules-define-private-permissions.png
:alt: Column access for the role user based on row level permissions
Step 4: Query with appropriate access control

2
docs/graphql/manual/auth/authorization/roles-variables.rst → docs/graphql/core/auth/authorization/roles-variables.rst
View File

@ -107,7 +107,7 @@ Roles are typically modelled in two ways:
1. **Hierarchical roles**: Access scopes are nested depending on available roles. `Roles in Github for organisations <https://help.github.com/en/articles/managing-peoples-access-to-your-organization-with-roles>`_
is a great example of such modelling where access scopes are inherited by deeper roles:
.. thumbnail:: /img/graphql/manual/auth/github-org-hierarchical-roles.png
.. thumbnail:: /img/graphql/core/auth/github-org-hierarchical-roles.png
:alt: Hierarchical roles
2. **Flat roles**: Non-hierarchical roles with each role requiring an independent access scope to be defined.

18
docs/graphql/manual/auth/authorization/use-cases.rst.wip → docs/graphql/core/auth/authorization/use-cases.rst.wip
View File

@ -18,7 +18,7 @@ Head to the ``Permissions`` tab of the ``author`` table.
Now add a ``select`` access control rule for the ``user`` role on the ``author`` table:
.. thumbnail:: /img/graphql/manual/auth/author-select-perms.png
.. thumbnail:: /img/graphql/core/auth/author-select-perms.png
This rule reads as:
@ -44,7 +44,7 @@ This rule reads as:
Now, let's make the same query as above but also include two dynamic authorization variables ``X-Hasura-Role`` and
``X-Hasura-User-Id`` via request headers. These will automatically get used according to the permission rule we set up.
.. thumbnail:: /img/graphql/manual/auth/query-with-perms.png
.. thumbnail:: /img/graphql/core/auth/query-with-perms.png
You can notice above how the same query now only includes the right slice of data.
@ -83,7 +83,7 @@ We can restrict the columns of a table that a particular role has access to.
Head to the ``Permissions`` tab of the table and edit the ``Select`` permissions for the role:
.. thumbnail:: /img/graphql/manual/auth/restrict-columns.png
.. thumbnail:: /img/graphql/core/auth/restrict-columns.png
.. _limit_rows:
@ -94,7 +94,7 @@ We can set a hard limit on the maximum number of rows that will be returned in a
Head to the ``Permissions`` tab of the table and edit the ``Select`` permissions for the role:
.. thumbnail:: /img/graphql/manual/auth/limit-results.png
.. thumbnail:: /img/graphql/core/auth/limit-results.png
.. _using-relationships-in-permissions:
@ -105,16 +105,16 @@ You can leverage relationships to define permission rules with fields from a nes
* An author/articles schema where an article can have one or more reviewers i.e. users with the role ``reviewer`` can only edit those articles that have been assigned to them:
.. thumbnail:: /img/graphql/manual/auth/schema-for-nested-object-based-permissions.png
.. thumbnail:: /img/graphql/core/auth/schema-for-nested-object-based-permissions.png
* The foreign key constraint from ``reviewers`` :: ``article_id`` → ``articles`` :: ``id`` is used for an array relationship called ``reviewers`` in the ``articles`` table:
.. thumbnail:: /img/graphql/manual/auth/array-relationship-reviewers.png
.. thumbnail:: /img/graphql/core/auth/array-relationship-reviewers.png
:class: no-shadow
We can use this relationship in a permission rule for the ``articles`` table to limit access for users with the role ``reviewer`` to only assigned rows:
.. thumbnail:: /img/graphql/manual/auth/nested-object-permissions-rule.gif
.. thumbnail:: /img/graphql/core/auth/nested-object-permissions-rule.gif
Via the relationship, we are using the ``reviewer_id`` field of the nested object ``reviewers`` in the the above permission rule that reads as "Allow updating an article if the **reviewer_id of any of the reviewers assigned to this article** is the same as the requesting user's id (*which is sent in the resolved session variable* ``X-Hasura-User-ID``)".
@ -144,12 +144,12 @@ Let's say we have the following test data for the list of reviewers:
Applying the above permission rule for "update" to "select" operation also, let's query the ``articles`` table to watch this permission rule in action:
.. thumbnail:: /img/graphql/manual/auth/restricted-data-for-role-reviewer.png
.. thumbnail:: /img/graphql/core/auth/restricted-data-for-role-reviewer.png
:class: no-shadow
As we've made this query with the role ``reviewer`` and user ID ``5`` (*highlighted in the request headers in the above image*), we can only query those articles for which this user is a reviewer. This will be the case for update mutations too. As the user with id ``5`` does not have access to article with id ``2`` (*refer to the table above*), the following mutation will not update any rows of the ``articles`` table:
.. thumbnail:: /img/graphql/manual/auth/unsuccessful-mutation-for-role-reviewer.png
.. thumbnail:: /img/graphql/core/auth/unsuccessful-mutation-for-role-reviewer.png
:class: no-shadow
.. admonition:: Array and Object relationships work similarly

0
docs/graphql/manual/auth/config.rst.wip → docs/graphql/core/auth/config.rst.wip
View File

2
docs/graphql/manual/auth/index.rst → docs/graphql/core/auth/index.rst
View File

@ -15,7 +15,7 @@ Authentication & Authorization
In Hasura, access control or authorization is based on **roles**. Let's take a look at how this works
when the GraphQL engine receives a request:
.. thumbnail:: /img/graphql/manual/auth/auth-high-level-overview.png
.. thumbnail:: /img/graphql/core/auth/auth-high-level-overview.png
:alt: Authentication and authorization with Hasura
As you can see from this:

6
docs/graphql/manual/business-logic/index.rst.wip → docs/graphql/core/business-logic/index.rst.wip
View File

@ -15,7 +15,7 @@ GraphQL engine/Postgres, different avenues are recommended for introducing such
- **Post-CRUD**: :ref:`event-triggers`
- :ref:`derived-data`
.. thumbnail:: /img/graphql/manual/business-logic/custom-business-logic.png
.. thumbnail:: /img/graphql/core/business-logic/custom-business-logic.png
.. _remote-schemas:
@ -35,7 +35,7 @@ To support these kinds of business logic, a custom GraphQL schema with resolvers
logic is needed (*see link below for boilerplates*). This remote schema can then be merged with GraphQL engine's
schema using the console. Here's a reference architecture diagram for such a setup:
.. thumbnail:: /img/graphql/manual/schema/schema-stitching-v1-arch-diagram.png
.. thumbnail:: /img/graphql/core/schema/schema-stitching-v1-arch-diagram.png
For more details, links to boilerplates for custom GraphQL servers, etc. please head to :doc:`../remote-schemas/index`.
@ -56,7 +56,7 @@ If your business logic is stateful, it can even store its state back in the Post
with GraphQL engine, allowing your frontend app to offer a reactive user experience, where the app uses GraphQL
subscriptions to listen to updates from your webhook via Postgres.
.. thumbnail:: /img/graphql/manual/event-triggers/database-event-triggers.png
.. thumbnail:: /img/graphql/core/event-triggers/database-event-triggers.png
Event triggers are ideal for use cases such as the following:

3
docs/graphql/manual/deployment/allow-list.rst → docs/graphql/core/deployment/allow-list.rst
View File

@ -12,6 +12,9 @@ Allow-list of operations
:depth: 1
:local:
Introduction
------------
The **Allow-list** is a list of safe operations (*GraphQL queries, mutations or subscriptions*) that is stored by
the GraphQL engine in its metadata. When enabled, it can be used to restrict the GraphQL engine so that it
executes **only** those operations that are present in the list *(available after version v1.0.0-beta.1)*.

0
docs/graphql/manual/deployment/compression.rst → docs/graphql/core/deployment/compression.rst
View File

0
docs/graphql/manual/deployment/custom-docker-images.rst → docs/graphql/core/deployment/custom-docker-images.rst
View File

0
docs/graphql/manual/deployment/deployment-guides/azure-container-instances-postgres.rst → docs/graphql/core/deployment/deployment-guides/azure-container-instances-postgres.rst
View File

Some files were not shown because too many files have changed in this diff Show More