mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-14 08:02:15 +03:00
fix typos in documentation (#2562)
This commit is contained in:
parent
1487cc1d26
commit
480b34ea5e
@ -372,7 +372,9 @@ class Schema extends Component {
|
||||
Track
|
||||
</Button>
|
||||
</div>
|
||||
<div className={styles.display_inline}>{displayTableName(table)}</div>
|
||||
<div className={styles.display_inline}>
|
||||
{displayTableName(table)}
|
||||
</div>
|
||||
{gqlCompatibilityWarning}
|
||||
</div>
|
||||
);
|
||||
|
@ -18,7 +18,7 @@ change/task that requires modifications in some component of GraphQL engine and
|
||||
|
||||
Feel free to open pull requests to address these issues or to add/fix docs features/content, even if a
|
||||
corresponding issue doesn't exist. If you are unsure about whether to go ahead and work on something like
|
||||
the latter, please get in touch with the maintainers in the `GraphQL Engine`->`contrib` channel in the
|
||||
the latter, please get in touch with the maintainers in the `GraphQL engine`->`contrib` channel in the
|
||||
community [Discord](https://discord.gg/vBPpJkS).
|
||||
|
||||
## Setup requirements
|
||||
@ -101,6 +101,7 @@ without losing any visible quality.
|
||||
|
||||
### Syntax
|
||||
- Ensure heading underlines are the same length as the headings. Short underlines will throw warnings during builds.
|
||||
- Use bold in headings in place of string literals for aesthetics (i.e. ** in place of ``)
|
||||
- While adding code blocks ensure the right language type is set. Sometimes adding placeholders breaks the language's
|
||||
syntax in which case you'll have to set the language type to `none` to avoid warnings during builds.
|
||||
|
||||
|
@ -1,6 +1,6 @@
|
||||
# Hasura GraphQL Engine Docs
|
||||
|
||||
The documentation accompanying the Hasura GraphQL Engine is written with
|
||||
The documentation accompanying the Hasura GraphQL engine is written with
|
||||
[Sphinx](http://www.sphinx-doc.org/en/master/) and deployed to
|
||||
[docs.hasura.io](https://docs.hasura.io).
|
||||
|
||||
|
2
docs/_theme/djangodocs/layout.html
vendored
2
docs/_theme/djangodocs/layout.html
vendored
@ -138,7 +138,7 @@
|
||||
</div>
|
||||
<br/>
|
||||
<div>
|
||||
<a target="_blank" href="https://github.com/hasura/graphql-engine">Hasura GraphQL Engine</a> is open source. <a target="_blank" href="https://github.com/hasura/graphql-engine/blob/master/LICENSE">See license</a>
|
||||
<a target="_blank" href="https://github.com/hasura/graphql-engine">Hasura GraphQL engine</a> is open source. <a target="_blank" href="https://github.com/hasura/graphql-engine/blob/master/LICENSE">See license</a>
|
||||
</div>
|
||||
<div>
|
||||
Powered by <a target="_blank" href="http://www.sphinx-doc.org">Sphinx</a>.
|
||||
|
6
docs/_theme/djangodocs/pages/landing.html
vendored
6
docs/_theme/djangodocs/pages/landing.html
vendored
@ -4,14 +4,14 @@
|
||||
<div class="box_wrapper">
|
||||
<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>
|
||||
<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">
|
||||
</div>
|
||||
</div>
|
||||
<div class="small_content space_wrapper text_left">
|
||||
This guide covers all Hasura GraphQL Engine concepts and features.
|
||||
This guide covers all Hasura GraphQL engine concepts and features.
|
||||
<br/> <br/>
|
||||
</div>
|
||||
<div class="sign_in_wrapper space_wrapper">
|
||||
|
@ -62,4 +62,4 @@ the list of enabled APIs.
|
||||
--enabled-apis="graphql,metadata"
|
||||
HASURA_GRAPHQL_ENABLED_APIS="graphql,metadata"
|
||||
|
||||
See :doc:`../deployment/graphql-engine-flags/reference` for info on setting the above flag/env var
|
||||
See :doc:`../deployment/graphql-engine-flags/reference` for info on setting the above flag/env var.
|
||||
|
@ -11,12 +11,12 @@ All GraphQL requests for queries, subscriptions and mutations are made to the Gr
|
||||
Endpoint
|
||||
--------
|
||||
|
||||
All requests are ``POST`` requests to ``/v1/graphql`` (or ``/v1alpha1/graphql``) endpoint.
|
||||
All requests are ``POST`` requests to the ``/v1/graphql`` (or ``/v1alpha1/graphql``) endpoint.
|
||||
|
||||
.. note::
|
||||
|
||||
``/v1/graphql`` endpoint returns HTTP 200 status codes for all responses.
|
||||
This is a **breaking** change from ``/v1alpha1/graphql`` behaviour, where
|
||||
The ``/v1/graphql`` endpoint returns HTTP 200 status codes for all responses.
|
||||
This is a **breaking** change from the ``/v1alpha1/graphql`` behaviour, where
|
||||
request errors and internal errors were responded with 4xx and 5xx status
|
||||
codes.
|
||||
|
||||
|
@ -8,8 +8,8 @@ API Reference - Mutation
|
||||
|
||||
.. _insert_upsert_syntax:
|
||||
|
||||
Insert/Upsert syntax
|
||||
--------------------
|
||||
Insert / upsert syntax
|
||||
----------------------
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
@ -31,19 +31,19 @@ Insert/Upsert syntax
|
||||
* - mutation-name
|
||||
- false
|
||||
- Value
|
||||
- Name mutation for observability
|
||||
- Name of mutation for observability
|
||||
* - mutation-field-name
|
||||
- true
|
||||
- Value
|
||||
- name of the auto-generated mutation field. E.g. *insert_author*
|
||||
- Name of the auto-generated mutation field, e.g. *insert_author*
|
||||
* - input-object
|
||||
- true
|
||||
- InputObject_
|
||||
- name of the auto-generated mutation field
|
||||
- Name of the auto-generated mutation field
|
||||
* - mutation-response
|
||||
- true
|
||||
- MutationResponse_
|
||||
- Object to be returned after mutation succeeds.
|
||||
- Object to be returned after mutation succeeds
|
||||
* - on-conflict
|
||||
- false
|
||||
- ConflictClause_
|
||||
@ -120,11 +120,11 @@ Update syntax
|
||||
* - mutation-field-name
|
||||
- true
|
||||
- Value
|
||||
- name of the auto-generated update mutation field. E.g. *update_author*
|
||||
- Name of the auto-generated update mutation field, e.g. *update_author*
|
||||
* - where-argument
|
||||
- true
|
||||
- whereArgExp_
|
||||
- selection criteria for rows to be updated
|
||||
- Selection criteria for rows to be updated
|
||||
* - set-argument
|
||||
- false
|
||||
- setArgExp_
|
||||
@ -144,19 +144,19 @@ Update syntax
|
||||
* - delete-key-argument
|
||||
- false
|
||||
- deleteKeyArgExp_
|
||||
- key to be deleted in the value of JSONB columns in the table
|
||||
- Key to be deleted in the value of JSONB columns in the table
|
||||
* - delete-elem-argument
|
||||
- false
|
||||
- deleteElemArgExp_
|
||||
- array element to be deleted in the value of JSONB columns in the table
|
||||
- Array element to be deleted in the value of JSONB columns in the table
|
||||
* - delete-at-path-argument
|
||||
- false
|
||||
- deleteAtPathArgExp_
|
||||
- element at path to be deleted in the value of JSONB columns in the table
|
||||
- Element at path to be deleted in the value of JSONB columns in the table
|
||||
* - mutation-response
|
||||
- true
|
||||
- MutationResponse_
|
||||
- Object to be returned after mutation succeeds.
|
||||
- Object to be returned after mutation succeeds
|
||||
|
||||
**E.g. UPDATE**:
|
||||
|
||||
@ -199,15 +199,15 @@ Delete syntax
|
||||
* - mutation-field-name
|
||||
- true
|
||||
- Value
|
||||
- name of the auto-generated delete mutation field. E.g. *delete_author*
|
||||
- Name of the auto-generated delete mutation field, e.g. *delete_author*
|
||||
* - where-argument
|
||||
- true
|
||||
- whereArgExp_
|
||||
- selection criteria for rows to delete
|
||||
- Selection criteria for rows to delete
|
||||
* - mutation-response
|
||||
- true
|
||||
- MutationResponse_
|
||||
- Object to be returned after mutation succeeds.
|
||||
- Object to be returned after mutation succeeds
|
||||
|
||||
**E.g. DELETE**:
|
||||
|
||||
@ -234,7 +234,7 @@ Syntax definitions
|
||||
|
||||
.. _MutationResponse:
|
||||
|
||||
Mutation Response
|
||||
Mutation response
|
||||
^^^^^^^^^^^^^^^^^
|
||||
.. code-block:: none
|
||||
|
||||
@ -305,7 +305,7 @@ E.g.:
|
||||
|
||||
**on_conflict** argument
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Conflict clause is used to convert an *insert* query to an *upsert* query. *Upsert* respects the table's *update*
|
||||
The conflict clause is used to convert an *insert* query to an *upsert* query. *Upsert* respects the table's *update*
|
||||
permissions before editing an existing row in case of a conflict. Hence the conflict clause is permitted only if a
|
||||
table has *update* permissions defined.
|
||||
|
||||
|
@ -6,8 +6,8 @@ API Reference - Query / Subscription
|
||||
:depth: 3
|
||||
:local:
|
||||
|
||||
Query/Subscription syntax
|
||||
-------------------------
|
||||
Query / subscription syntax
|
||||
---------------------------
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
@ -75,7 +75,7 @@ Object
|
||||
|
||||
.. _SimpleObject:
|
||||
|
||||
Simple Object
|
||||
Simple object
|
||||
*************
|
||||
|
||||
.. code-block:: none
|
||||
@ -133,7 +133,7 @@ E.g.
|
||||
|
||||
.. _AggregateObject:
|
||||
|
||||
Aggregate Object
|
||||
Aggregate object
|
||||
****************
|
||||
|
||||
.. code-block:: none
|
||||
@ -192,7 +192,7 @@ Aggregate Object
|
||||
}
|
||||
}
|
||||
|
||||
(For more details on aggregate functions, refer to `Postgres docs <https://www.postgresql.org/docs/current/functions-aggregate.html#FUNCTIONS-AGGREGATE-STATISTICS-TABLE>`__.)
|
||||
(For more details on aggregate functions, refer to the `Postgres docs <https://www.postgresql.org/docs/current/functions-aggregate.html#FUNCTIONS-AGGREGATE-STATISTICS-TABLE>`__).
|
||||
|
||||
E.g.
|
||||
|
||||
@ -393,7 +393,7 @@ Operator
|
||||
* - ``_has_keys_all``
|
||||
- ``?&``
|
||||
|
||||
(For more details on what these operators do, refer to `Postgres docs <https://www.postgresql.org/docs/current/static/functions-json.html#FUNCTIONS-JSONB-OP-TABLE>`__.)
|
||||
(For more details on what these operators do, refer to the `Postgres docs <https://www.postgresql.org/docs/current/static/functions-json.html#FUNCTIONS-JSONB-OP-TABLE>`__).
|
||||
|
||||
**PostGIS related operators on GEOMETRY columns:**
|
||||
|
||||
@ -419,12 +419,12 @@ Operator
|
||||
* - ``_st_d_within``
|
||||
- ``ST_DWithin``
|
||||
|
||||
(For more details on what these operators do, refer to `PostGIS docs <http://postgis.net/workshops/postgis-intro/spatial_relationships.html>`__.)
|
||||
(For more details on what these operators do, refer to the `PostGIS docs <http://postgis.net/workshops/postgis-intro/spatial_relationships.html>`__).
|
||||
|
||||
.. note::
|
||||
|
||||
- All operators take a JSON representation of ``geometry/geography`` values as input value.
|
||||
- Input value for ``_st_d_within`` operator is an object:
|
||||
- The input value for ``_st_d_within`` operator is an object:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
@ -578,7 +578,7 @@ Operation aggregate
|
||||
{op_name: TableAggOpOrderBy_}
|
||||
|
||||
Available operations are ``sum``, ``avg``, ``max``, ``min``, ``stddev``, ``stddev_samp``,
|
||||
``stddev_pop``, ``variance``, ``var_samp`` and ``var_pop``
|
||||
``stddev_pop``, ``variance``, ``var_samp`` and ``var_pop``.
|
||||
|
||||
TableAggOpOrderBy
|
||||
&&&&&&&&&&&&&&&&&
|
||||
|
@ -34,19 +34,19 @@ GraphQL API
|
||||
|
||||
All GraphQL requests for queries, subscriptions and mutations are made to the GraphQL API.
|
||||
|
||||
See details at :doc:`graphql-api/index`
|
||||
See details at :doc:`graphql-api/index`.
|
||||
|
||||
.. _schema_metadata_api:
|
||||
|
||||
Schema / Metadata API
|
||||
Schema / metadata API
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Hasura exposes a Schema / Metadata API for managing metadata for permissions/relationships or for directly
|
||||
Hasura exposes a schema / metadata API for managing metadata for permissions/relationships or for directly
|
||||
executing SQL on the underlying Postgres.
|
||||
|
||||
This is primarily intended to be used as an ``admin`` API to manage Hasura schema and metadata.
|
||||
This is primarily intended to be used as an ``admin`` API to manage the Hasura schema and metadata.
|
||||
|
||||
See details at :doc:`schema-metadata-api/index`
|
||||
See details at :doc:`schema-metadata-api/index`.
|
||||
|
||||
.. _version_api:
|
||||
|
||||
@ -66,7 +66,7 @@ Health check API
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
A ``GET`` request to the public ``/healthz`` endpoint will respond with ``200``
|
||||
if GraphQL Engine is ready to serve requests and there are no inconsistencies
|
||||
if the GraphQL engine is ready to serve requests and there are no inconsistencies
|
||||
with the metadata. The response will be ``500`` if there are metadata
|
||||
inconsistencies and you should use the console or check the server logs to find
|
||||
out what the errors are.
|
||||
@ -79,7 +79,7 @@ pg_dump API
|
||||
|
||||
The ``/v1alpha1/pg_dump`` is an admin-only endpoint that can be used to execute
|
||||
``pg_dump`` on the Postgres instance connected to Hasura. The ``pg_dump`` CLI
|
||||
tool's argument can be passed as POST request body to the API and the response
|
||||
tool's argument can be passed as a POST request body to the API and the response
|
||||
is sent back to the client.
|
||||
|
||||
See details at :doc:`pgdump`.
|
||||
|
@ -13,7 +13,7 @@ Postgres instance that Hasura is configured with.
|
||||
|
||||
The primary motive of this API is to provide convenience methods to initialise migrations from an
|
||||
existing Hasura instance. But the functionality can be later expanded to do other things
|
||||
such as taking data dump etc.
|
||||
such as taking a data dump etc.
|
||||
|
||||
Endpoint
|
||||
--------
|
||||
@ -94,4 +94,4 @@ state that this API is not enabled. i.e. remove it from the list of enabled APIs
|
||||
--enabled-apis="graphql,metadata"
|
||||
HASURA_GRAPHQL_ENABLED_APIS="graphql,metadata"
|
||||
|
||||
See :doc:`../deployment/graphql-engine-flags/reference` for info on setting the above flag/env var
|
||||
See :doc:`../deployment/graphql-engine-flags/reference` for info on setting the above flag/env var.
|
@ -304,8 +304,8 @@ variables:
|
||||
|
||||
Implicitly Supported types
|
||||
--------------------------
|
||||
All ``Implicit`` types in the :ref:`above table <types_table>` are implicitly supported by GraphQL Engine. You have to
|
||||
provide the value in **String**.
|
||||
All ``Implicit`` types in the :ref:`above table <types_table>` are implicitly supported by the GraphQL engine. You have to
|
||||
provide the value as a **String**.
|
||||
|
||||
|
||||
E.g. For time without time zone type
|
||||
@ -334,6 +334,6 @@ E.g. For macaddr type
|
||||
|
||||
.. Note::
|
||||
|
||||
You can learn more about PostgreSQL data types `here <https://www.postgresql.org/docs/current/static/datatype.html>`__
|
||||
You can learn more about PostgreSQL data types `here <https://www.postgresql.org/docs/current/static/datatype.html>`__.
|
||||
|
||||
|
||||
|
@ -6,7 +6,7 @@ Schema/Metadata API Reference: Custom Functions
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
Track/untrack a custom SQL function in Hasura GraphQL engine.
|
||||
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.
|
||||
|
||||
@ -24,7 +24,7 @@ Currently, only functions which satisfy the following constraints can be exposed
|
||||
- **Return type**: MUST be ``SETOF <table-name>``
|
||||
- **Argument modes**: ONLY ``IN``
|
||||
|
||||
Add a SQL function ``search_articles``:
|
||||
Add an SQL function ``search_articles``:
|
||||
|
||||
.. code-block:: http
|
||||
|
||||
@ -47,7 +47,7 @@ untrack_function
|
||||
|
||||
``untrack_function`` is used to remove a SQL function from the GraphQL schema.
|
||||
|
||||
Remove a SQL function ``search_articles``:
|
||||
Remove an SQL function ``search_articles``:
|
||||
|
||||
.. code-block:: http
|
||||
|
||||
|
@ -95,7 +95,7 @@ Args syntax
|
||||
* - replace
|
||||
- false
|
||||
- Boolean
|
||||
- If set to true, event trigger is replaced with the new definition
|
||||
- If set to true, the event trigger is replaced with the new definition
|
||||
|
||||
.. _delete_event_trigger:
|
||||
|
||||
@ -200,7 +200,7 @@ OperationSpec
|
||||
* - columns
|
||||
- true
|
||||
- EventTriggerColumns_
|
||||
- List of columns or "*" to listen changes on
|
||||
- List of columns or "*" to listen to changes
|
||||
* - payload
|
||||
- false
|
||||
- EventTriggerColumns_
|
||||
|
@ -8,12 +8,12 @@ Schema / Metadata API Reference
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
The Schema / Metadata API provides the following features:
|
||||
The schema / metadata API provides the following features:
|
||||
|
||||
1. Execute SQL on the underlying Postgres database, supports schema modifying actions.
|
||||
2. Modify Hasura metadata (permissions rules and relationships).
|
||||
2. Modify Hasura metadata (permission rules and relationships).
|
||||
|
||||
This is primarily intended to be used as an ``admin`` API to manage Hasura schema and metadata.
|
||||
This is primarily intended to be used as an ``admin`` API to manage the Hasura schema and metadata.
|
||||
|
||||
Endpoint
|
||||
--------
|
||||
@ -90,11 +90,11 @@ The various types of queries are listed in the following table:
|
||||
|
||||
* - :ref:`track_function`
|
||||
- :ref:`FunctionName <FunctionName>`
|
||||
- Add a SQL function
|
||||
- Add an SQL function
|
||||
|
||||
* - :ref:`untrack_function`
|
||||
- :ref:`FunctionName <FunctionName>`
|
||||
- Remove a SQL function
|
||||
- Remove an SQL function
|
||||
|
||||
* - :ref:`create_object_relationship`
|
||||
- :ref:`create_object_relationship_args <create_object_relationship_syntax>`
|
||||
@ -150,27 +150,27 @@ The various types of queries are listed in the following table:
|
||||
|
||||
* - :ref:`create_event_trigger`
|
||||
- :ref:`create_event_trigger_args <create_event_trigger_syntax>`
|
||||
- Create or replace event trigger
|
||||
|
||||
* - :ref:`invoke_event_trigger`
|
||||
- :ref:`invoke_event_trigger_args <invoke_event_trigger_syntax>`
|
||||
- Invoke trigger manually
|
||||
- Create or replace an event trigger
|
||||
|
||||
* - :ref:`delete_event_trigger`
|
||||
- :ref:`delete_event_trigger_args <delete_event_trigger_syntax>`
|
||||
- Delete existing event trigger
|
||||
- Delete an existing event trigger
|
||||
|
||||
* - :ref:`invoke_event_trigger`
|
||||
- :ref:`invoke_event_trigger_args <invoke_event_trigger_syntax>`
|
||||
- Invoke a trigger manually
|
||||
|
||||
* - :ref:`add_remote_schema`
|
||||
- :ref:`add_remote_schema_args <add_remote_schema_syntax>`
|
||||
- Add a remote GraphQL server as remote schema
|
||||
- Add a remote GraphQL server as a remote schema
|
||||
|
||||
* - :ref:`remove_remote_schema`
|
||||
- :ref:`remove_remote_schema_args <remove_remote_schema_syntax>`
|
||||
- Remove existing remote schema
|
||||
- Remove an existing remote schema
|
||||
|
||||
* - :ref:`reload_remote_schema`
|
||||
- :ref:`reload_remote_schema_args <reload_remote_schema_syntax>`
|
||||
- Reload schema of existing remote server
|
||||
- Reload schema of an existing remote schema
|
||||
|
||||
* - :ref:`export_metadata`
|
||||
- :ref:`Empty Object`
|
||||
@ -206,19 +206,19 @@ The various types of queries are listed in the following table:
|
||||
|
||||
* - :ref:`add_query_to_collection`
|
||||
- :ref:`add_query_to_collection_args <add_query_to_collection_syntax>`
|
||||
- Add a query to given collection
|
||||
- Add a query to a given collection
|
||||
|
||||
* - :ref:`drop_query_from_collection`
|
||||
- :ref:`drop_query_from_collection_args <drop_query_from_collection_syntax>`
|
||||
- Drop a query from given collection
|
||||
- Drop a query from a given collection
|
||||
|
||||
* - :ref:`add_collection_to_allowlist`
|
||||
- :ref:`add_collection_to_allowlist_args <add_collection_to_allowlist_syntax>`
|
||||
- Add a collection to allow-list
|
||||
- Add a collection to the allow-list
|
||||
|
||||
* - :ref:`drop_collection_from_allowlist`
|
||||
- :ref:`drop_collection_from_allowlist_args <drop_collection_from_allowlist_syntax>`
|
||||
- Drop a collection from allow-list
|
||||
- Drop a collection from the allow-list
|
||||
|
||||
**See:**
|
||||
|
||||
@ -283,15 +283,15 @@ Error codes
|
||||
:widths: 10, 20, 70
|
||||
:header-rows: 1
|
||||
|
||||
Disabling Schema/Metadata API
|
||||
-----------------------------
|
||||
Disabling schema / metadata API
|
||||
-------------------------------
|
||||
|
||||
Since this API can be used to make changes to the GraphQL schema, it can be
|
||||
disabled, especially in production deployments.
|
||||
|
||||
The ``enabled-apis`` flag or the ``HASURA_GRAPHQL_ENABLED_APIS`` env var can be used to
|
||||
enable/disable this API. By default, The schema/metadata API is enabled. To disable it, you need
|
||||
to explicitly state that this API is not enabled. i.e. remove it from the list of enabled APIs.
|
||||
enable/disable this API. By default, the schema/metadata API is enabled. To disable it, you need
|
||||
to explicitly state that this API is not enabled i.e. remove it from the list of enabled APIs.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@ -299,7 +299,7 @@ to explicitly state that this API is not enabled. i.e. remove it from the list o
|
||||
--enabled-apis="graphql"
|
||||
HASURA_GRAPHQL_ENABLED_APIS="graphql"
|
||||
|
||||
See :doc:`../../deployment/graphql-engine-flags/reference` for info on setting the above flag/env var
|
||||
See :doc:`../../deployment/graphql-engine-flags/reference` for info on setting the above flag/env var.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
@ -13,8 +13,8 @@ APIs to manage Hasura metadata which is stored in ``hdb_catalog`` schema.
|
||||
export_metadata
|
||||
---------------
|
||||
|
||||
``export_metadata`` is used to export the current metadata from server as a JSON
|
||||
file. Response JSON will be the metadata object.
|
||||
``export_metadata`` is used to export the current metadata from the server as a JSON
|
||||
file. The response JSON will be the metadata object.
|
||||
|
||||
.. code-block:: http
|
||||
|
||||
@ -59,7 +59,7 @@ Args should be the JSON object which is same as the output of
|
||||
reload_metadata
|
||||
---------------
|
||||
|
||||
``reload_metadata`` should be used when there is change in underlying Postgres
|
||||
``reload_metadata`` should be used when there is a change in underlying Postgres
|
||||
database that Hasura should be aware of. Example: a new column is added to a
|
||||
table using ``psql`` and this column should now be added to the GraphQL schema.
|
||||
|
||||
@ -156,7 +156,7 @@ Response:-
|
||||
drop_inconsistent_metadata
|
||||
--------------------------
|
||||
|
||||
``drop_inconsistent_metadata`` can be used to purge all inconsistent objects from metadata.
|
||||
``drop_inconsistent_metadata`` can be used to purge all inconsistent objects from the metadata.
|
||||
|
||||
.. code-block:: http
|
||||
|
||||
|
@ -25,9 +25,9 @@ create_insert_permission
|
||||
An insert permission is used to enforce constraints on the data that is being
|
||||
inserted.
|
||||
|
||||
Let's look at an example, a permission for the ``user`` role to insert into
|
||||
Let's look at an example, a permission for the ``user`` role to insert into the
|
||||
``article`` table. What is the constraint that we would like to enforce here? *A
|
||||
user can only insert articles for themself*
|
||||
user can only insert articles for themselves* .
|
||||
|
||||
.. code-block:: http
|
||||
|
||||
@ -52,7 +52,7 @@ user can only insert articles for themself*
|
||||
}
|
||||
}
|
||||
|
||||
This reads as follows - For the ``user`` role:
|
||||
This reads as follows - for the ``user`` role:
|
||||
|
||||
* For every row that is being inserted into the *article* table, allow insert only if the ``check`` passes i.e. that the ``author_id`` column value is the same as the value in the request header ``X-HASURA-USER-ID``".
|
||||
|
||||
@ -122,7 +122,7 @@ Args syntax
|
||||
* - comment
|
||||
- false
|
||||
- text
|
||||
- comment
|
||||
- Comment
|
||||
|
||||
.. _InsertPermission:
|
||||
|
||||
@ -143,7 +143,7 @@ InsertPermission
|
||||
* - set
|
||||
- false
|
||||
- :ref:`ColumnPresetExp`
|
||||
- Preset values for columns that can sourced from session variables or static values.
|
||||
- Preset values for columns that can be sourced from session variables or static values
|
||||
* - columns
|
||||
- false
|
||||
- :ref:`PGColumn` array (or) ``'*'``
|
||||
@ -189,9 +189,9 @@ create_select_permission
|
||||
|
||||
A select permission is used to restrict access to only the specified columns and rows.
|
||||
|
||||
Let's look at an example, a permission for the ``user`` role to select from
|
||||
``article`` table: all columns can be read, and rows that have been published or
|
||||
authored by themself.
|
||||
Let's look at an example, a permission for the ``user`` role to select from the
|
||||
``article`` table: all columns can be read, as well as the rows that have been published or
|
||||
authored by the user themselves.
|
||||
|
||||
.. code-block:: http
|
||||
|
||||
@ -255,7 +255,7 @@ Args syntax
|
||||
* - comment
|
||||
- false
|
||||
- text
|
||||
- comment
|
||||
- Comment
|
||||
|
||||
.. _SelectPermission:
|
||||
|
||||
@ -348,18 +348,18 @@ An example:
|
||||
}
|
||||
}
|
||||
|
||||
This reads as follows - For the ``user`` role:
|
||||
This reads as follows - for the ``user`` role:
|
||||
|
||||
* Allow updating only those rows where the ``check`` passes i.e. the value of the ``author_id`` column of a row matches the value of the session variable ``X-HASURA-USER-ID`` value.
|
||||
|
||||
* If the above ``check`` passes for a given row, allow updating only the ``title``, ``content`` and ``category`` columns (*as specified in the* ``columns`` *key*)
|
||||
* If the above ``check`` passes for a given row, allow updating only the ``title``, ``content`` and ``category`` columns (*as specified in the* ``columns`` *key*).
|
||||
|
||||
* When this update happens, the value of the column ``id`` will be automatically ``set`` to the value of the resolved session variable ``X-HASURA-USER-ID``.
|
||||
|
||||
.. note::
|
||||
|
||||
It is important to deny updates to columns that will determine the row
|
||||
ownership. In the above example, ``author_id`` column determines the
|
||||
ownership. In the above example, the ``author_id`` column determines the
|
||||
ownership of a row in the ``article`` table. Columns such as this should
|
||||
never be allowed to be updated.
|
||||
|
||||
@ -390,7 +390,7 @@ Args syntax
|
||||
* - comment
|
||||
- false
|
||||
- text
|
||||
- comment
|
||||
- Comment
|
||||
|
||||
.. _UpdatePermission:
|
||||
|
||||
@ -415,7 +415,7 @@ UpdatePermission
|
||||
* - set
|
||||
- false
|
||||
- :ref:`ColumnPresetExp`
|
||||
- Preset values for columns that can sourced from session variables or static values.
|
||||
- Preset values for columns that can be sourced from session variables or static values.
|
||||
|
||||
|
||||
.. _drop_update_permission:
|
||||
@ -476,8 +476,8 @@ An example:
|
||||
|
||||
This reads as follows:
|
||||
|
||||
"``delete`` for ``user`` role on ``article`` table is allowed on rows where
|
||||
``author_id`` is same as the request header ``X-HASURA-USER-ID`` value."
|
||||
"``delete`` for the ``user`` role on the ``article`` table is allowed on rows where
|
||||
``author_id`` is the same as the request header ``X-HASURA-USER-ID`` value."
|
||||
|
||||
.. _create_delete_permission_syntax:
|
||||
|
||||
@ -506,7 +506,7 @@ Args syntax
|
||||
* - comment
|
||||
- false
|
||||
- text
|
||||
- comment
|
||||
- Comment
|
||||
|
||||
.. _DeletePermission:
|
||||
|
||||
@ -607,4 +607,4 @@ Args syntax
|
||||
* - comment
|
||||
- false
|
||||
- Text
|
||||
- comment
|
||||
- Comment
|
||||
|
@ -6,9 +6,9 @@ Schema/Metadata API Reference: Query collections
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
Group queries using Query collections.
|
||||
Group queries using query collections.
|
||||
|
||||
Create/Drop query collections and Add/Drop a query to a collection using following query types.
|
||||
Create/drop query collections and add/drop a query to a collection using the following query types.
|
||||
|
||||
.. _create_query_collection:
|
||||
|
||||
@ -102,14 +102,14 @@ Args syntax
|
||||
* - cascade
|
||||
- true
|
||||
- boolean
|
||||
- When set to ``true``, the collection (if present) is removed from allowlist
|
||||
- When set to ``true``, the collection (if present) is removed from the allowlist
|
||||
|
||||
.. _add_query_to_collection:
|
||||
|
||||
add_query_to_collection
|
||||
-----------------------
|
||||
|
||||
``add_query_to_collection`` is used to add a query to given collection
|
||||
``add_query_to_collection`` is used to add a query to a given collection.
|
||||
|
||||
.. code-block:: http
|
||||
|
||||
@ -156,7 +156,7 @@ Args Syntax
|
||||
drop_query_from_collection
|
||||
--------------------------
|
||||
|
||||
``drop_query_from_collection`` is used to remove a query from given collection
|
||||
``drop_query_from_collection`` is used to remove a query from a given collection.
|
||||
|
||||
.. code-block:: http
|
||||
|
||||
@ -198,7 +198,7 @@ Args Syntax
|
||||
add_collection_to_allowlist
|
||||
----------------------------
|
||||
|
||||
``add_collection_to_allowlist`` is used to add a collection to allow-list
|
||||
``add_collection_to_allowlist`` is used to add a collection to the allow-list.
|
||||
|
||||
.. code-block:: http
|
||||
|
||||
@ -235,7 +235,7 @@ Args Syntax
|
||||
drop_collection_from_allowlist
|
||||
-------------------------------
|
||||
|
||||
``drop_collection_from_allowlist`` is used to remove a collection from allow-list
|
||||
``drop_collection_from_allowlist`` is used to remove a collection from the allow-list.
|
||||
|
||||
.. code-block:: http
|
||||
|
||||
|
@ -125,7 +125,7 @@ Args syntax
|
||||
* - using
|
||||
- true
|
||||
- ObjRelUsing_
|
||||
- Use one of the available ways to define object relationship
|
||||
- Use one of the available ways to define an object relationship
|
||||
* - comment
|
||||
- false
|
||||
- text
|
||||
@ -255,7 +255,7 @@ follows:
|
||||
It is easy to make mistakes while using ``manual_configuration``.
|
||||
One simple check is to ensure that foreign key constraint semantics are valid
|
||||
on the columns being used in ``column_mapping``. In the previous example, if
|
||||
it was allowed, a foreign key constraint could have been defined on
|
||||
it was allowed, a foreign key constraint could have been defined on the
|
||||
``author`` table's ``id`` column to ``article_detail`` view's ``author_id``
|
||||
column.
|
||||
|
||||
@ -282,7 +282,7 @@ Args syntax
|
||||
* - using
|
||||
- true
|
||||
- ArrRelUsing_
|
||||
- Use one of the available ways to define array relationship
|
||||
- Use one of the available ways to define an array relationship
|
||||
* - comment
|
||||
- false
|
||||
- text
|
||||
@ -452,4 +452,4 @@ Args syntax
|
||||
* - comment
|
||||
- false
|
||||
- Text
|
||||
- comment
|
||||
- Comment
|
||||
|
@ -20,11 +20,11 @@ returned.
|
||||
|
||||
This is an admin-only query, i.e. the query can only be executed by a
|
||||
request having ``X-Hasura-Role: admin``. This can be set by passing
|
||||
``X-Hasura-Admin-Secret`` or by setting the right role in Webhook/JWT
|
||||
``X-Hasura-Admin-Secret`` or by setting the right role in webhook/JWT
|
||||
authorization mode.
|
||||
|
||||
This is deliberate as it is hard to enforce any sort of permissions on arbitrary SQL. If
|
||||
you find yourselves in the need of using ``run_sql`` to run custom DML queries,
|
||||
you find yourself in the need of using ``run_sql`` to run custom DML queries,
|
||||
consider creating a view. You can now define permissions on that particular view
|
||||
for various roles.
|
||||
|
||||
@ -50,11 +50,11 @@ An example:
|
||||
}
|
||||
|
||||
While ``run_sql`` lets you run any SQL, it tries to ensure that the Hasura GraphQL engine's
|
||||
state (relationships, permissions etc.) is consistent. i.e., you
|
||||
state (relationships, permissions etc.) is consistent i.e. you
|
||||
cannot drop a column on which any metadata is dependent on (say a permission or
|
||||
a relationship). The effects, however, can be cascaded.
|
||||
|
||||
Example:- If we were to drop 'bio' column from the author table (let's say
|
||||
Example: If we were to drop the 'bio' column from the author table (let's say
|
||||
the column is used in some permission), you would see an error.
|
||||
|
||||
.. code-block:: http
|
||||
@ -108,8 +108,8 @@ We can however, cascade these changes.
|
||||
|
||||
With the above query, the dependent permission is also dropped.
|
||||
|
||||
Example:- If we were to drop a foreign key constraint from the article table
|
||||
(let's say the column involved in foreign key is used to define a relationship),
|
||||
Example: If we were to drop a foreign key constraint from the article table
|
||||
(let's say the column involved in the foreign key is used to define a relationship),
|
||||
you would see an error.
|
||||
|
||||
.. code-block:: http
|
||||
@ -176,10 +176,10 @@ In case of 1, 2 and 3 the dependent objects (if any) can be dropped using ``casc
|
||||
However, when altering type of columns, if any objects are affected, the change
|
||||
cannot be cascaded. So, those dependent objects have to be manually dropped before
|
||||
executing the SQL statement. Dropping SQL functions will cascade the functions in
|
||||
metadata even without using ``cascade`` since no other objects dependant on them.
|
||||
metadata even without using ``cascade`` since no other objects depend on them.
|
||||
Overloading tracked SQL functions is not allowed.
|
||||
|
||||
Set ``check_metadata_consistency`` field to ``false`` to force server to not consider metadata dependencies.
|
||||
Set ``check_metadata_consistency`` field to ``false`` to force the server to not consider metadata dependencies.
|
||||
|
||||
.. _run_sql_syntax:
|
||||
|
||||
|
@ -348,12 +348,12 @@ Operator
|
||||
* - ``_st_d_within``
|
||||
- ``ST_DWithin``
|
||||
|
||||
(For more details on what these operators do, refer to `PostGIS docs <http://postgis.net/workshops/postgis-intro/spatial_relationships.html>`__.)
|
||||
(For more details on what these operators do, refer to `PostGIS docs <http://postgis.net/workshops/postgis-intro/spatial_relationships.html>`__).
|
||||
|
||||
.. note::
|
||||
|
||||
- All operators take a JSON representation of ``geometry/geography`` values as input value.
|
||||
- Input value for ``_st_d_within`` operator is an object:
|
||||
- The input value for ``_st_d_within`` operator is an object:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
@ -395,7 +395,7 @@ An empty JSONObject_
|
||||
|
||||
ColumnPresetsExp
|
||||
^^^^^^^^^^^^^^^^
|
||||
A JSONObject_ of Postgres column name to value mapping, where value can be static or derived from a session variable.
|
||||
A JSONObject_ of a Postgres column name to value mapping, where the value can be static or derived from a session variable.
|
||||
|
||||
.. parsed-literal::
|
||||
:class: haskell-pre
|
||||
@ -406,7 +406,7 @@ A JSONObject_ of Postgres column name to value mapping, where value can be stati
|
||||
..
|
||||
}
|
||||
|
||||
E.g. where ``id`` is derived from session variable and ``city`` is a static value.
|
||||
E.g. where ``id`` is derived from a session variable and ``city`` is a static value.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
|
@ -6,7 +6,7 @@ Schema/Metadata API Reference: Tables/Views
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
Track/untrack a table/view in Hasura GraphQL engine
|
||||
Track/untrack a table/view in Hasura GraphQL engine.
|
||||
|
||||
Only tracked tables/views are available for querying/mutating/subscribing data over the GraphQL API.
|
||||
|
||||
@ -147,4 +147,4 @@ Args syntax
|
||||
* - cascade
|
||||
- false
|
||||
- Boolean
|
||||
- When set to ``true``, the effect (if possible) is cascaded to any metadata dependent objects (relationships, permissions, templates).
|
||||
- When set to ``true``, the effect (if possible) is cascaded to any metadata dependent objects (relationships, permissions, templates)
|
||||
|
@ -9,12 +9,12 @@ Authentication
|
||||
Overview
|
||||
--------
|
||||
|
||||
Authentication is handled outside Hasura. Hasura delegates authentication and resolution of request
|
||||
Authentication is handled outside of Hasura. Hasura delegates authentication and resolution of request
|
||||
headers into session variables to your authentication service *(existing or new)*.
|
||||
|
||||
Your authentication service is required to pass a user's **role** information in the form of session
|
||||
variables like ``X-Hasura-Role``, etc. More often than not, you'll also need to pass user information
|
||||
for your access-control use-cases, like ``X-Hasura-User-Id``, to build permission rules.
|
||||
for your access control use cases, like ``X-Hasura-User-Id``, to build permission rules.
|
||||
|
||||
Authentication options
|
||||
----------------------
|
||||
@ -23,12 +23,12 @@ Hasura supports two modes of authentication configuration:
|
||||
|
||||
1) **Webhook**: Your auth server exposes a webhook that is used to authenticate all incoming requests
|
||||
to the Hasura GraphQL engine server and to get metadata about the request to evaluate access control
|
||||
rules. Here's how a GraphQL request is processed in Webhook mode:
|
||||
rules. Here's how a GraphQL request is processed in webhook mode:
|
||||
|
||||
.. thumbnail:: ../../../../img/graphql/manual/auth/auth-webhook-overview.png
|
||||
|
||||
2) **JWT** (JSON Web Token): Your auth server issues JWTs to your client app, which, when sent as part
|
||||
of the request, are verified and decoded by GraphQL engine to get metadata about the request to
|
||||
of the request, are verified and decoded by the GraphQL engine to get metadata about the request to
|
||||
evaluate access control rules. Here's how a GraphQL query is processed in JWT mode:
|
||||
|
||||
.. thumbnail:: ../../../../img/graphql/manual/auth/auth-jwt-overview.png
|
||||
|
@ -9,10 +9,10 @@ Authentication using JWT
|
||||
Introduction
|
||||
------------
|
||||
|
||||
You can configure GraphQL engine to use JWT authorization mode to authorize all incoming requests to Hasura GraphQL engine server.
|
||||
You can configure the GraphQL engine to use JWT authorization mode to authorize all incoming requests to the Hasura GraphQL engine server.
|
||||
|
||||
The idea is - Your auth server will return JWT tokens, which is decoded and
|
||||
verified by GraphQL engine to authorize and get metadata about the request
|
||||
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).
|
||||
|
||||
|
||||
@ -21,9 +21,9 @@ verified by GraphQL engine to authorize and get metadata about the request
|
||||
|
||||
The JWT is decoded, the signature is verified, then it is asserted that the
|
||||
current role of the user (if specified in the request) is in the list of allowed roles.
|
||||
If current role is not specified in the request, then the default role is picked.
|
||||
If the current role is not specified in the request, then the default role is applied.
|
||||
If the authorization passes, then all of the ``x-hasura-*`` values in the claim
|
||||
is used for the permissions system.
|
||||
are used for the permissions system.
|
||||
|
||||
.. admonition:: Prerequisite
|
||||
|
||||
@ -32,8 +32,8 @@ is used for the permissions system.
|
||||
|
||||
In JWT mode, on a secured endpoint:
|
||||
|
||||
- JWT authentication is **enforced** when ``X-Hasura-Admin-Secret`` header is **not found** in the request.
|
||||
- JWT authentication is **skipped** when ``X-Hasura-Admin-Secret`` header **is found** in the request and
|
||||
- JWT authentication is **enforced** when the ``X-Hasura-Admin-Secret`` header is **not found** in the request.
|
||||
- JWT authentication is **skipped** when the ``X-Hasura-Admin-Secret`` header **is found** in the request and
|
||||
admin access is granted.
|
||||
|
||||
|
||||
@ -57,11 +57,11 @@ the following:
|
||||
2. A ``x-hasura-allowed-roles`` field : a list of allowed roles for the user i.e. acceptable values of the
|
||||
``x-hasura-role`` header
|
||||
|
||||
The claims in the JWT, can have other ``x-hasura-*`` fields where their values
|
||||
The claims in the JWT can have other ``x-hasura-*`` fields where their values
|
||||
can only be strings. You can use these ``x-hasura-*`` fields in your
|
||||
permissions.
|
||||
|
||||
Now, the JWT should be sent by the client to Hasura GraphQL engine via the
|
||||
Now the JWT should be sent by the client to the Hasura GraphQL engine via the
|
||||
``Authorization: Bearer <JWT>`` header.
|
||||
|
||||
Example JWT claim:
|
||||
@ -91,14 +91,14 @@ specific claims have to be present. This value can be configured in the JWT
|
||||
config while starting the server.
|
||||
|
||||
**Note**: ``x-hasura-default-role`` and ``x-hasura-allowed-roles`` are
|
||||
mandatory, while rest of them are optional.
|
||||
mandatory, while the rest of them are optional.
|
||||
|
||||
.. note::
|
||||
|
||||
All ``x-hasura-*`` values should be ``String``, they will be converted to the
|
||||
All ``x-hasura-*`` values should be of type ``String``, they will be converted to the
|
||||
right type automatically.
|
||||
|
||||
The default role can be overridden by ``x-hasura-role`` header, while making a
|
||||
The default role can be overridden by the ``x-hasura-role`` header, while making a
|
||||
request.
|
||||
|
||||
.. code-block:: http
|
||||
@ -156,16 +156,16 @@ the ``jwk_url`` field.
|
||||
^^^^^^^^^^^
|
||||
A URL where a provider publishes their JWKs (which are used for signing the
|
||||
JWTs). The URL **must** publish the JWKs in the standard format as described in
|
||||
https://tools.ietf.org/html/rfc7517
|
||||
https://tools.ietf.org/html/rfc7517.
|
||||
|
||||
This is an optional field. You can also provide the key (certificate, PEM
|
||||
encoded public key) as string as well - under the ``key`` field.
|
||||
|
||||
**Rotating JWKs**:
|
||||
|
||||
Some providers rotate their JWKs (E.g - Firebase). If the provider sends an
|
||||
``Expires`` header with the response of JWK, then graphql-engine will refresh
|
||||
the JWKs automatically. If the provider does not send ``Expires`` header, the
|
||||
Some providers rotate their JWKs (e.g. Firebase). If the provider sends an
|
||||
``Expires`` header with the response of JWK, then the GraphQL engine will refresh
|
||||
the JWKs automatically. If the provider does not send an ``Expires`` header, the
|
||||
JWKs are not refreshed.
|
||||
|
||||
**Example**:
|
||||
@ -178,7 +178,7 @@ JWKs are not refreshed.
|
||||
``claims_namespace``
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
This is an optional field. You can specify the key name
|
||||
inside which the Hasura specific claims will be present. E.g. - ``https://mydomain.com/claims``.
|
||||
inside which the Hasura specific claims will be present, e.g. ``https://mydomain.com/claims``.
|
||||
|
||||
**Default value** is: ``https://hasura.io/jwt/claims``.
|
||||
|
||||
@ -191,10 +191,10 @@ This is an optional field, with only the following possible values:
|
||||
|
||||
Default is ``json``.
|
||||
|
||||
This is to indicate that if the hasura specific claims are a regular JSON object
|
||||
or stringified JSON
|
||||
This is to indicate that if the Hasura specific claims are a regular JSON object
|
||||
or stringified JSON.
|
||||
|
||||
This is required because providers like AWS Cognito only allows strings in the
|
||||
This is required because providers like AWS Cognito only allow strings in the
|
||||
JWT claims. `See #1176 <https://github.com/hasura/graphql-engine/issues/1176>`_.
|
||||
|
||||
Example:-
|
||||
@ -322,7 +322,7 @@ The ``key`` is the actual shared secret, which is used by Hasura and the externa
|
||||
|
||||
RSA based
|
||||
+++++++++
|
||||
If your auth server is using RSA to sign JWTs, and is using a 512-bit key. In this case,
|
||||
If your auth server is using RSA to sign JWTs, and is using a 512-bit key,
|
||||
the JWT config needs to have the only the public key.
|
||||
|
||||
**Example 1**: public key in PEM format (not OpenSSH format):
|
||||
@ -423,7 +423,7 @@ Auth0
|
||||
^^^^^
|
||||
|
||||
Refer the :doc:`Auth0 JWT Integration guide <../../guides/integrations/auth0-jwt>` for a full integration guide
|
||||
with Auth0
|
||||
with Auth0.
|
||||
|
||||
Auth0 publishes their JWK under:
|
||||
|
||||
@ -486,7 +486,7 @@ Here are some sample apps that use JWT authorization. You can follow the instruc
|
||||
repositories to get started.
|
||||
|
||||
- `Auth0 JWT example <https://github.com/hasura/graphql-engine/tree/master/community/sample-apps/todo-auth0-jwt>`__:
|
||||
A todo app that uses Hasura GraphQL Engine and Auth0 JWT
|
||||
A todo app that uses Hasura GraphQL engine and Auth0 JWT
|
||||
|
||||
- `Firebase JWT example <https://github.com/hasura/graphql-engine/tree/master/community/sample-apps/firebase-jwt>`__:
|
||||
Barebones example to show how to have Firebase Auth integrated with Hasura JWT mode
|
||||
|
@ -9,7 +9,7 @@ Authentication using webhooks
|
||||
Introduction
|
||||
------------
|
||||
|
||||
You can configure GraphQL engine to use a webhook to authenticate all incoming requests to the Hasura GraphQL engine server.
|
||||
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
|
||||
|
||||
@ -19,14 +19,14 @@ You can configure GraphQL engine to use a webhook to authenticate all incoming r
|
||||
|
||||
In webhook mode, on a secured endpoint:
|
||||
|
||||
- The configured webhook is **called** when ``X-Hasura-Admin-Secret`` header is not found in the request.
|
||||
- The configured webhook is **ignored** when ``X-Hasura-Admin-Secret`` header is found in the request and
|
||||
- The configured webhook is **called** when the ``X-Hasura-Admin-Secret`` header is not found in the request.
|
||||
- The configured webhook is **ignored** when the ``X-Hasura-Admin-Secret`` header is found in the request and
|
||||
admin access is granted.
|
||||
|
||||
Configuring webhook mode
|
||||
------------------------
|
||||
|
||||
* You can configure Hasura to run in webhook mode by running GraphQL engine with the ``--auth-hook`` flag or the ``HASURA_GRAPHQL_AUTH_HOOK`` environment variable (see :doc:`GraphQL engine server options <../../deployment/graphql-engine-flags/reference>`), the value of which is the webhook endpoint.
|
||||
* You can configure Hasura to run in webhook mode by running the GraphQL engine with the ``--auth-hook`` flag or the ``HASURA_GRAPHQL_AUTH_HOOK`` environment variable (see :doc:`GraphQL engine server options <../../deployment/graphql-engine-flags/reference>`), the value of which is the webhook endpoint.
|
||||
|
||||
* You can configure Hasura to send either a ``GET`` or a ``POST`` request to your auth webhook. The default configuration is ``GET`` and you can override this with ``POST`` by using the ``--auth-hook-mode`` flag or the ``HASURA_GRAPHQL_AUTH_HOOK_MODE`` environment variable (*in addition to those specified above; see* :doc:`GraphQL engine server options <../../deployment/graphql-engine-flags/reference>`).
|
||||
|
||||
@ -78,7 +78,7 @@ POST request
|
||||
}
|
||||
}
|
||||
|
||||
If you configure your webhook to use ``POST``, then Hasura **will send all client headers in payload**
|
||||
If you configure your webhook to use ``POST``, then Hasura **will send all client headers in payload**.
|
||||
|
||||
Response
|
||||
^^^^^^^^
|
||||
@ -105,14 +105,14 @@ You should send the ``X-Hasura-*`` "session variables" to your permission rules
|
||||
|
||||
Failure
|
||||
+++++++
|
||||
If you want to deny the GraphQL request return a ``401 Unauthorized`` exception.
|
||||
If you want to deny the GraphQL request, return a ``401 Unauthorized`` exception.
|
||||
|
||||
.. code-block:: http
|
||||
|
||||
HTTP/1.1 401 Unauthorized
|
||||
|
||||
.. note::
|
||||
Anything other than a ``200`` or ``401`` response from webhook makes server raise a ``500 Internal Server Error``
|
||||
Anything other than a ``200`` or ``401`` response from webhook makes the server raise a ``500 Internal Server Error``
|
||||
exception.
|
||||
|
||||
Auth webhook samples
|
||||
@ -136,4 +136,4 @@ Once deployed, you can use any of the following endpoints as your auth webhook i
|
||||
|
||||
.. note::
|
||||
|
||||
If you are using ``firebase`` you will have to set the associated environment variables.
|
||||
If you are using ``Firebase``, you will have to set the associated environment variables.
|
||||
|
@ -85,8 +85,8 @@ as shown below:
|
||||
.. thumbnail:: ../../../../img/graphql/manual/auth/permission-basics-simple-example.png
|
||||
|
||||
|
||||
This permission rule reads as "*For the role* ``user`` *, table* `` *and operation* ``select``/``query``*,
|
||||
allow access to those rows where the value in the* ``id`` *column is the same as the value in the*
|
||||
This permission rule reads as: "*For the role* ``user`` *, table* ``author`` *and operation* ``select``/``query``,
|
||||
allow access to those rows where the value in the ``id`` *column is the same as the value in the*
|
||||
``X-Hasura-User-ID`` *session variable*".
|
||||
|
||||
Run a query **with** access control
|
||||
@ -111,4 +111,4 @@ Next steps
|
||||
|
||||
Read about roles and session variables at: :doc:`roles-variables`
|
||||
|
||||
See more detailed examples at: :doc:`Common access control examples<common-roles-auth-examples>`
|
||||
See more detailed examples at: :doc:`Common access control examples<common-roles-auth-examples>`
|
||||
|
@ -10,7 +10,7 @@ This is a guide to help you set up a basic authorization architecture for your G
|
||||
that you first check out :doc:`roles-variables` and :doc:`permission-rules`
|
||||
that will be referred to throughout this guide.
|
||||
|
||||
Here are some examples of common use-cases.
|
||||
Here are some examples of common use cases.
|
||||
|
||||
Anonymous (not logged in) users
|
||||
-------------------------------
|
||||
@ -38,7 +38,7 @@ Logged-in users
|
||||
- Set up a permission for insert/select/update/delete that uses said column. E.g.:
|
||||
``author_id: {_eq: "X-Hasura-User-Id"}`` for an article table.
|
||||
- Note that the ``X-Hasura-User-Id`` is a :doc:`dynamic session variable<./roles-variables>` that comes in from
|
||||
your :doc:`auth webhook's <../authentication/webhook>` response, or as a request as a header if you're testing.
|
||||
your :doc:`auth webhook's <../authentication/webhook>` response, or as a request header if you're testing.
|
||||
|
||||
.. thumbnail:: ../../../../img/graphql/manual/auth/user-select-graphiql.png
|
||||
:class: no-shadow
|
||||
@ -125,9 +125,9 @@ Sometimes your data/user model requires that:
|
||||
* Users can have multiple roles.
|
||||
* Each role has access to different parts of your database schema.
|
||||
|
||||
If you have the information about roles and how they map to your data in the same database as the one configured with GraphQL Engine, you can leverage relationships to define permissions that effectively control access to data and the operations each role is allowed to perform.
|
||||
If you have the information about roles and how they map to your data in the same database as the one configured with the GraphQL engine, you can leverage relationships to define permissions that effectively control access to data and the operations each role is allowed to perform.
|
||||
|
||||
To understand how this works, let's model the roles and corresponding permissions in the context of a blog app wth the following roles:
|
||||
To understand how this works, let's model the roles and corresponding permissions in the context of a blog app with the following roles:
|
||||
|
||||
* ``author``: Users with this role can submit **their own** articles.
|
||||
|
||||
@ -223,7 +223,7 @@ Permissions for role ``author``
|
||||
|
||||
* **Allow users with the role** ``author`` **to insert only their own articles**
|
||||
|
||||
For this permission rule, we'll make use of two features of the GraphQL Engine's permissions system:
|
||||
For this permission rule, we'll make use of two features of the GraphQL engine's permissions system:
|
||||
|
||||
a) :ref:`Column-level permissions<col-level-permissions>`: Restrict access to certain columns only.
|
||||
|
||||
@ -252,7 +252,7 @@ Permissions for role ``reviewer``
|
||||
|
||||
.. thumbnail:: ../../../../img/graphql/manual/auth/multirole-example-reviewer-update.png
|
||||
|
||||
The array-relationship based permission rule in the above image reads as "*if the ID of any of reviewers 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.
|
||||
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.
|
||||
|
||||
* **Allow users with the role** ``reviewer`` **to select articles assigned to them for reviews**
|
||||
|
||||
|
@ -11,7 +11,7 @@ Overview
|
||||
|
||||
Hasura supports **role-based** authorization where access control is done by creating rules for each role,
|
||||
table and operation (*insert*, *update*, etc.). These access control rules use dynamic session
|
||||
variables that are passed to GraphQL engine from your :doc:`authentication service <../authentication/index>`
|
||||
variables that are passed to the GraphQL engine from your :doc:`authentication service <../authentication/index>`
|
||||
with every request. Role information is inferred from the ``X-Hasura-Role`` and ``X-Hasura-Allowed-Roles``
|
||||
session variables. Other session variables can be passed by your auth service as per your requirements.
|
||||
|
||||
@ -20,11 +20,11 @@ session variables. Other session variables can be passed by your auth service as
|
||||
.. thumbnail:: ../../../../img/graphql/manual/auth/hasura-perms.png
|
||||
:width: 80 %
|
||||
|
||||
Trying access control out
|
||||
Trying out access control
|
||||
-------------------------
|
||||
|
||||
If you just want to see role-based access control in action, you need not set up or integrate your
|
||||
auth service with GraphQL Engine. You can just:
|
||||
auth service with GraphQL engine. You can just:
|
||||
|
||||
* Define permission rules for a table for a role.
|
||||
|
||||
|
@ -10,7 +10,7 @@ Introduction
|
||||
------------
|
||||
|
||||
Access control rules in Hasura are defined at a role, table and action (*insert, update, select, delete*)
|
||||
level granulaity:
|
||||
level granularity:
|
||||
|
||||
.. thumbnail:: ../../../../img/graphql/manual/auth/permission-rule-granularity.png
|
||||
|
||||
@ -90,7 +90,7 @@ Using operators to build rules
|
||||
******************************
|
||||
|
||||
Type-based operators (*depending on the column type*) are available for constructing row-level permissions.
|
||||
You can use the same operators that you use to :doc:`filtering query results <../../queries/query-filters>`
|
||||
You can use the same operators that you use to :doc:`filter query results <../../queries/query-filters>`
|
||||
to define permission rules.
|
||||
|
||||
See the :ref:`API reference <MetadataOperator>` for a list of all supported operators.
|
||||
@ -112,7 +112,7 @@ the value in the ``id`` column is greater than 10:
|
||||
|
||||
.. thumbnail:: ../../../../img/graphql/manual/auth/simple-boolean-expression.png
|
||||
|
||||
You can construct more complex boolean expression using the ``_and``, ``_or`` and ``not`` operators:
|
||||
You can construct more complex boolean expressions using the ``_and``, ``_or`` and ``not`` operators:
|
||||
|
||||
.. thumbnail:: ../../../../img/graphql/manual/auth/boolean-operators.png
|
||||
|
||||
@ -125,8 +125,8 @@ or "A":
|
||||
Using session variables
|
||||
***********************
|
||||
|
||||
Session variable, that have been resolved from authentication tokens by either your authentication webhook or
|
||||
by Hasura using the JWT configuration, are available for constructing row-level permissions.
|
||||
Session variables that have been resolved from authentication tokens by either your authentication webhook or
|
||||
by Hasura using the JWT configuration are available for constructing row-level permissions.
|
||||
|
||||
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
|
||||
@ -143,7 +143,7 @@ Using relationships or nested objects
|
||||
You can leverage :doc:`relationships <../../schema/relationships/index>` to define permission rules with fields
|
||||
from a nested object.
|
||||
|
||||
For e.g. let's say you have an object relationship called ``agent`` from the ``authors`` table to another table
|
||||
For example, 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:
|
||||
@ -151,10 +151,10 @@ that uses the aforementioned object relationship:
|
||||
.. thumbnail:: ../../../../img/graphql/manual/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*.
|
||||
``id`` *, allow access to the author's details*."
|
||||
|
||||
|
||||
.. admonition:: Array and Object relationships work similarly
|
||||
.. admonition:: Array and object relationships work similarly
|
||||
|
||||
- The above example would have worked even if the relationship were an array relationship. In our example,
|
||||
the corresponding rule for an array relationship would have read "*if any of this author's agents'* ``id``
|
||||
@ -167,7 +167,7 @@ This permission rule reads as "*if the author's agent's* ``id`` *is the same a
|
||||
|
||||
Column-level permissions
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Column-level permissions determine access to columns in the rows that accessible based on row-level
|
||||
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
|
||||
@ -177,7 +177,7 @@ the ``select`` operation.
|
||||
|
||||
.. _limit-rows-permissions:
|
||||
|
||||
Row Fetch Limit
|
||||
Row fetch limit
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
In the case of ``select`` operations, the number of rows to be returned in the response can be limited
|
||||
|
@ -43,7 +43,7 @@ of ``user-id``, the session variable.
|
||||
|
||||
When you are constructing permission rules, however, there might be several variables that represent the business logic
|
||||
of having access to data. For example, if you have a SaaS application, you might restrict access based on a ``client_id``
|
||||
variable. If you want to provide different levels of access on different devices you might restrict access based on a
|
||||
variable. If you want to provide different levels of access on different devices, you might restrict access based on a
|
||||
``device_type`` variable.
|
||||
|
||||
Hasura allows you to create permission rules that can use any dynamic variable that is a property of the request.
|
||||
@ -89,7 +89,7 @@ Modelling Roles in Hasura
|
||||
|
||||
General guidelines for modelling roles in Hasura.
|
||||
|
||||
Roles are typically be modelled in two ways:
|
||||
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:
|
||||
@ -124,7 +124,7 @@ partially captured by the table below (*showing access permissions for the* ``us
|
||||
}
|
||||
|
||||
* - org-member
|
||||
- Allow access to personally created repositories and the organisation's repositories.
|
||||
- Allow access to personally created repositories and the organisation's repositories
|
||||
-
|
||||
.. code-block:: json
|
||||
|
||||
@ -159,7 +159,7 @@ trivial row-level permission like ``"creator_id": {"_eq": "X-Hasura-User-Id"}``
|
||||
our example in the previous section, this user information (*ownership or relationship*) must be available for
|
||||
defining a permission rule.
|
||||
|
||||
These non-trivial use-cases are to handled differently based on whether this information is available in the same
|
||||
These non-trivial use cases are to be handled differently based on whether this information is available in the same
|
||||
database or not.
|
||||
|
||||
Relationship information is available in the same database
|
||||
@ -169,8 +169,8 @@ Let's take a closer look at the permission rule for the ``org-member`` rule in t
|
||||
section. The rule reads as "*allow access to this repository if it was created by this user or if this user is
|
||||
a member of the organisation that this repository belongs to*".
|
||||
|
||||
The crucial piece of user information, that is presumed to be available in the same database, that makes this an
|
||||
effective rule is the mapping of users (*members*) to organizations.
|
||||
The crucial piece of user information that is presumed to be available in the same database and that makes this an
|
||||
effective rule, is the mapping of users (*members*) to organizations.
|
||||
|
||||
Since this information is available in the same database, it can be easily leveraged via
|
||||
:ref:`Relationships in permissions <relationships-in-permissions>` (*see this reference for another
|
||||
@ -181,11 +181,11 @@ Relationship information is **not** available in the same database
|
||||
|
||||
When this user information is not available in the database that Hasura is configured to use, session variables
|
||||
are the only avenue to pass this information to a permission rule. In our example, the mapping of users (members)
|
||||
to organizations may not have been in available in the same database.
|
||||
to organizations may not have been available in the same database.
|
||||
|
||||
To convey this information, a session variable, say ``X-Hasura-Allowed-Organisations`` can be used by the
|
||||
configured authentication to relay this information. We can then check for the following condition to emulate
|
||||
the same rule - *is the organization that this repository belongs to part of the list of the organizations the
|
||||
the same rule: *is the organization that this repository belongs to part of the list of the organizations the
|
||||
user is a member of*.
|
||||
|
||||
The permission for ``org-member`` role changes to this:
|
||||
|
@ -1,7 +1,7 @@
|
||||
Authorization modes
|
||||
===================
|
||||
|
||||
You can run Hasura's GraphQL Engine in three modes:
|
||||
You can run Hasura's GraphQL engine in three modes:
|
||||
|
||||
1. No Authentication mode
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
@ -7,7 +7,7 @@ Authentication & Authorization
|
||||
:local:
|
||||
|
||||
In Hasura, access control or authorization is based on **roles**. Let's take a look at how this works
|
||||
when GraphQL engine receives a request:
|
||||
when the GraphQL engine receives a request:
|
||||
|
||||
.. thumbnail:: ../../../img/graphql/manual/auth/auth-high-level-overview.png
|
||||
|
||||
@ -18,14 +18,14 @@ As you can see from this:
|
||||
|
||||
Your authentication service is required to pass a user's **role** information in the form of session
|
||||
variables like ``X-Hasura-Role``, etc. More often than not, you'll also need to pass user information
|
||||
for your access-control use-cases, like ``X-Hasura-User-Id``, to build permission rules.
|
||||
for your access control use cases, like ``X-Hasura-User-Id``, to build permission rules.
|
||||
|
||||
- For **Authorization** or **Access Control**, Hasura helps you define granular role-based access control
|
||||
rules for every field in your GraphQL schema *(granular enough to control access to any row or
|
||||
column in your database)*.
|
||||
|
||||
Hasura uses the role/user information in the session variables and the actual query itself to validate
|
||||
the query against the rules defined by you. If the query/operation is allowed, it generates a SQL
|
||||
the query against the rules defined by you. If the query/operation is allowed, it generates an SQL
|
||||
query, which includes the row/column-level constraints from the access control rules, and sends it to
|
||||
the database to perform the required operation (*fetch the required rows for queries, insert/edit
|
||||
rows for mutations, etc.*).
|
||||
|
@ -7,8 +7,8 @@ Custom business logic
|
||||
:local:
|
||||
|
||||
For the backends of most apps, you may have to implement custom business logic to complement the CRUD and
|
||||
real-time API provided by GraphQL Engine. Depending on the nature of the use case and its position vis-a-vis
|
||||
GraphQL Engine/Postgres, different avenues are recommended for introducing such business logic in your app's backend:
|
||||
real-time API provided by GraphQL engine. Depending on the nature of the use case and its position vis-a-vis
|
||||
GraphQL engine/Postgres, different avenues are recommended for introducing such business logic in your app's backend:
|
||||
|
||||
|
||||
- **Pre-CRUD**: :ref:`remote-schemas`
|
||||
@ -23,16 +23,16 @@ Custom resolvers in remote schemas
|
||||
----------------------------------
|
||||
|
||||
Merging remote schemas is ideal for adding "pre-CRUD" business logic (*logic to be run before you invoke
|
||||
GraphQL Engine's GraphQL API to insert/modify data in Postgres*) or custom business logic that is not part of
|
||||
your GraphQL Engine schema. Here are some use-cases where remote schemas are ideal:
|
||||
GraphQL engine's GraphQL API to insert/modify data in Postgres*) or custom business logic that is not part of
|
||||
your GraphQL engine schema. Here are some use-cases where remote schemas are ideal:
|
||||
|
||||
- Customizing mutations (e.g. running validations before inserts)
|
||||
- Supporting features like payments, etc. and providing a consistent interface to access them i.e. behind the
|
||||
GraphQL Engine’s API
|
||||
GraphQL engine’s API
|
||||
- Fetching disparate data from other sources (e.g. from a weather API or another database)
|
||||
|
||||
To support these kinds of business logic, a custom GraphQL schema with resolvers that implement said business
|
||||
logic is needed (*see link below for boilerplates*). This remote schema can then be merged with GraphQL Engine's
|
||||
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
|
||||
@ -44,16 +44,16 @@ For more details, links to boilerplates for custom GraphQL servers, etc. please
|
||||
Asynchronous business logic / Events triggers
|
||||
---------------------------------------------
|
||||
|
||||
"post-CRUD" business logic (*follow up logic to be run after GraphQL Engine's GraphQL API has been used to insert
|
||||
"post-CRUD" business logic (*follow up logic to be run after GraphQL engine's GraphQL API has been used to insert
|
||||
or modify data in Postgres*) typically tends to be asynchronous, stateless and is triggered on changes to data
|
||||
relevant to each use case. E.g. for every new user in your database, you may want to send out a notification. This
|
||||
business logic is triggered for every new row in your ``users`` table.
|
||||
|
||||
GraphQL Engine comes with built-in events triggers on tables in the Postgres database. These triggers capture events
|
||||
GraphQL engine comes with built-in events triggers on tables in the Postgres database. These triggers capture events
|
||||
on specified tables and then invoke configured webhooks, which contain your business logic.
|
||||
|
||||
If your business logic is stateful, it can even store its state back in the Postgres instance configured to work
|
||||
with GraphQL Engine, allowing your frontend app to offer a reactive user experience, where the app uses GraphQL
|
||||
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
|
||||
@ -82,7 +82,7 @@ Derived data / Data transformations
|
||||
-----------------------------------
|
||||
|
||||
For some use cases, you may want to transform your data in Postgres or run some predetermined function on it to
|
||||
derive another dataset (*that will be queried using GraphQL Engine*). E.g. let's say you store each user's location
|
||||
derive another dataset (*that will be queried using GraphQL engine*). E.g. let's say you store each user's location
|
||||
data in the database as a ``point`` type. You are interested in calculating the distance (*say the haversine distance*)
|
||||
between each set of two users i.e. you want this derived dataset:
|
||||
|
||||
@ -101,6 +101,6 @@ between each set of two users i.e. you want this derived dataset:
|
||||
|
||||
The easiest way to handle these kinds of use cases is to create a view, which encapsulates your business logic
|
||||
(*in our example, calculating the distance between any two users*), and query your derived/transformed data as you
|
||||
would a table using GraphQL Engine (*with permissions defined explicitly for your view if needed*).
|
||||
would a table using GraphQL engine (*with permissions defined explicitly for your view if needed*).
|
||||
|
||||
For more information on how to do this, please see :doc:`../queries/derived-data`.
|
||||
|
@ -6,8 +6,8 @@ Allow-list for queries
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
**Allow-list** is a list of safe queries (*GraphQL queries, mutations or subscriptions*) that is stored by
|
||||
GraphQL engine in its metadata. When enabled, it can be used to restrict GraphQL engine so that it
|
||||
The **Allow-list** is a list of safe queries (*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 queries that are present in the list *(available after version v1.0.0-beta.1)*.
|
||||
|
||||
Adding or removing a query in allow-list
|
||||
@ -35,7 +35,7 @@ You can add or remove a query in the allow-list in two ways:
|
||||
* You can upload files, like this `sample file <https://gist.github.com/dsandip/8b1b4aa87708289d4c9f8fd9621eb025>`_,
|
||||
to add multiple queries to the allow-list (each query needs to have a name).
|
||||
|
||||
* **Using metadata APIs:** Queries can be stored in collections and a collection(s) can added to or removed
|
||||
* **Using metadata APIs:** Queries can be stored in collections and a collection can be added to or removed
|
||||
from the allow-list. See :doc:`Collections & Allow-list APIs<../api-reference/schema-metadata-api/query-collections>`
|
||||
for API reference.
|
||||
|
||||
@ -46,7 +46,7 @@ You can add or remove a query in the allow-list in two ways:
|
||||
* Any introspection queries that your client apps require will have to be explicitly added to the allow-list
|
||||
to allow running them.
|
||||
|
||||
* The order of fields in a query will be **strictly** compared. E.g. assuming the query in first example
|
||||
* The order of fields in a query will be **strictly** compared. E.g. assuming the query in the first example
|
||||
above is part of the allow-list, the following query will be **rejected**:
|
||||
|
||||
.. code-block:: graphql
|
||||
@ -60,7 +60,7 @@ You can add or remove a query in the allow-list in two ways:
|
||||
}
|
||||
}
|
||||
|
||||
* Allow-list is stored in the metadata. To version control the state of the list, you are required to export
|
||||
* The allow-list is stored in the metadata. To version control the state of the list, you are required to export
|
||||
the metadata. See :doc:`Managing Hasura metadata <../migrations/manage-metadata>` for more details.
|
||||
|
||||
* You can modify the allow-list without actually enabling it on your instance.
|
||||
@ -70,7 +70,7 @@ Enable allow-list
|
||||
-----------------
|
||||
|
||||
The allow-list validation can be enabled by setting the ``HASURA_GRAPHQL_ENABLE_ALLOWLIST`` environment
|
||||
variable to ``true`` or running GraphQL engine with the ``--enable-allowlist`` flag (*default value is*
|
||||
variable to ``true`` or running the GraphQL engine with the ``--enable-allowlist`` flag (*default value is*
|
||||
``false``). See :ref:`reference docs <command-flags>`.
|
||||
|
||||
.. note::
|
||||
@ -84,11 +84,11 @@ The following are the recommended best practises for enabling/disabling allow-li
|
||||
|
||||
* **In development instances**: During development or in dev instances, disable allow-list (*default setting*)
|
||||
to allow complete access to the GraphQL schema. Add/remove queries in the allow-list and then export the
|
||||
metadata for version-control (*so you can apply to it other instances*).
|
||||
metadata for version-control (*so you can apply it to other instances*).
|
||||
|
||||
* **In CI/CD instances**: Enable allow-list for testing.
|
||||
* **In CI/CD instances**: Enable the allow-list for testing.
|
||||
|
||||
* **In production instances**: Enabling allow-list is highly recommended when running GraphQL engine in production.
|
||||
* **In production instances**: Enabling the allow-list is highly recommended when running the GraphQL engine in production.
|
||||
|
||||
|
||||
|
||||
|
@ -1,4 +1,4 @@
|
||||
Run Hasura GraphQL Engine using Docker
|
||||
Run Hasura GraphQL engine using Docker
|
||||
======================================
|
||||
|
||||
.. contents:: Table of contents
|
||||
@ -21,7 +21,7 @@ Step 1: Get the **docker-run.sh** bash script
|
||||
The `hasura/graphql-engine/install-manifests <https://github.com/hasura/graphql-engine/tree/master/install-manifests>`_
|
||||
repo contains all installation manifests required to deploy Hasura anywhere.
|
||||
|
||||
Get the docker run bash script from there:
|
||||
Get the Docker run bash script from there:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@ -30,7 +30,7 @@ Get the docker run bash script from there:
|
||||
Step 2: Configure the **docker-run.sh** script
|
||||
----------------------------------------------
|
||||
|
||||
The ``docker-run.sh`` script has a sample docker run command in it. The following changes have to be
|
||||
The ``docker-run.sh`` script has a sample Docker run command in it. The following changes have to be
|
||||
made to the command:
|
||||
|
||||
- Database URL
|
||||
@ -64,12 +64,12 @@ Examples of ``HASURA_GRAPHQL_DATABASE_URL``:
|
||||
to connect to the database.
|
||||
|
||||
- Hasura GraphQL engine needs access permissions to your Postgres database as described in
|
||||
:doc:`Postgres permissions <../postgres-permissions>`
|
||||
:doc:`Postgres permissions <../postgres-permissions>`.
|
||||
|
||||
Network config
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
If your Postgres instance is running on ``localhost`` the following changes will be needed to the ``docker run``
|
||||
If your Postgres instance is running on ``localhost``, the following changes will be needed to the ``docker run``
|
||||
command to allow the Docker container to access the host's network:
|
||||
|
||||
.. rst-class:: api_tabs
|
||||
@ -118,7 +118,7 @@ command to allow the Docker container to access the host's network:
|
||||
hasura/graphql-engine:latest
|
||||
|
||||
|
||||
Step 3: Run the Hasura docker container
|
||||
Step 3: Run the Hasura Docker container
|
||||
---------------------------------------
|
||||
|
||||
Execute ``docker-run.sh`` & check if everything is running well:
|
||||
|
@ -6,7 +6,7 @@ Hasura GraphQL engine server logs (Docker)
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
You can check logs of Hasura GraphQL engine deployed using Docker by checking the logs of the
|
||||
You can check the logs of the Hasura GraphQL engine deployed using Docker by checking the logs of the
|
||||
GraphQL engine container:
|
||||
|
||||
.. code-block:: bash
|
||||
|
@ -9,7 +9,7 @@ Securing the GraphQL endpoint (Docker)
|
||||
To make sure that your GraphQL endpoint and the Hasura console are not publicly accessible, you need to
|
||||
configure an admin secret key.
|
||||
|
||||
Run the docker command with an admin-secret env var
|
||||
Run the Docker command with an admin-secret env var
|
||||
---------------------------------------------------
|
||||
|
||||
.. code-block:: bash
|
||||
@ -25,6 +25,6 @@ Run the docker command with an admin-secret env var
|
||||
|
||||
.. note::
|
||||
|
||||
The ``HASURA_GRAPHQL_ADMIN_SECRET`` should never be passed from the client to Hasura GraphQL engine as it would
|
||||
The ``HASURA_GRAPHQL_ADMIN_SECRET`` should never be passed from the client to the Hasura GraphQL engine as it would
|
||||
give the client full admin rights to your Hasura instance. See :doc:`../../auth/index` for information on
|
||||
setting up Authentication.
|
||||
setting up authentication.
|
||||
|
@ -6,7 +6,7 @@ Updating Hasura GraphQL engine running with Docker
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
This guide will help you update Hasura GraphQL engine running with Docker. This guide assumes that you already have
|
||||
This guide will help you update the Hasura GraphQL engine running with Docker. This guide assumes that you already have
|
||||
Hasura GraphQL engine running with Docker.
|
||||
|
||||
Step 1: Check the latest release version
|
||||
|
@ -13,7 +13,7 @@ The following are a few configuration use cases:
|
||||
Add an admin secret
|
||||
-------------------
|
||||
|
||||
To add an admin-secret to Hasura, pass the ``--admin-secret`` flag with a secret
|
||||
To add an admin secret to Hasura, pass the ``--admin-secret`` flag with a secret
|
||||
generated by you.
|
||||
|
||||
Run server in this mode using following docker command:
|
||||
@ -35,7 +35,7 @@ Typically, you will also have a webhook for authentication:
|
||||
--admin-secret XXXXXXXXXXXXXXXX
|
||||
--auth-hook https://myauth.mywebsite.com/user/session-info
|
||||
|
||||
In addition to flags, the GraphQL Engine also accepts Environment variables.
|
||||
In addition to flags, the GraphQL engine also accepts environment variables.
|
||||
|
||||
In the above case, for adding an admin secret you will use the ``HASURA_GRAPHQL_ADMIN_SECRET``
|
||||
and for the webhook, you will use the ``HASURA_GRAPHQL_AUTH_HOOK`` environment variables.
|
||||
@ -45,7 +45,7 @@ and for the webhook, you will use the ``HASURA_GRAPHQL_AUTH_HOOK`` environment v
|
||||
Using CLI commands with admin secret
|
||||
------------------------------------
|
||||
|
||||
When you start the GraphQL Engine with an admin secret key, CLI commands will also
|
||||
When you start the GraphQL engine with an admin secret key, CLI commands will also
|
||||
need this admin secret to contact APIs. It can be set in ``config.yaml`` or as an
|
||||
environment variable or as a flag to the command. For example, let's look at the
|
||||
case of the ``console`` command:
|
||||
@ -62,7 +62,7 @@ The console can now contact the GraphQL APIs with the specified admin secret.
|
||||
|
||||
.. note::
|
||||
|
||||
If you're setting ``admin_secret`` in ``config.yaml`` please make sure you do
|
||||
If you're setting an ``admin_secret`` in ``config.yaml`` please make sure you do
|
||||
not check this file into a public repository.
|
||||
|
||||
An alternate and safe way is to pass the admin secret value to the command
|
||||
@ -94,11 +94,11 @@ You can also set the admin secret using a flag to the command:
|
||||
Configure CORS
|
||||
--------------
|
||||
|
||||
By default, all CORS requests to Hasura GraphQL engine are allowed. To run with more restrictive CORS settings,
|
||||
By default, all CORS requests to the Hasura GraphQL engine are allowed. To run with more restrictive CORS settings,
|
||||
use the ``--cors-domain`` flag or the ``HASURA_GRAPHQL_CORS_DOMAIN`` ENV variable. The default value is ``*``,
|
||||
which means CORS headers are sent for all domains.
|
||||
|
||||
Scheme + host with optional wildcard + optional port has to be mentioned.
|
||||
The scheme + host with optional wildcard + optional port have to be mentioned.
|
||||
|
||||
Examples:
|
||||
|
||||
@ -122,7 +122,7 @@ Examples:
|
||||
.. note::
|
||||
|
||||
Top-level domains are not considered as part of wildcard domains. You
|
||||
have to add them separately. E.g - ``https://*.foo.com`` doesn't include
|
||||
have to add them separately. E.g. ``https://*.foo.com`` doesn't include
|
||||
``https://foo.com``.
|
||||
|
||||
|
||||
@ -141,7 +141,7 @@ These files can be found at ``/srv/console-assets``.
|
||||
|
||||
If you're working in an environment with Hasura running locally and have no
|
||||
access to internet, you can configure server/console to load assets from the
|
||||
docker image itself, instead of the CDN.
|
||||
Docker image itself, instead of the CDN.
|
||||
|
||||
Set the following env var or flag on the server:
|
||||
|
||||
@ -153,13 +153,13 @@ Set the following env var or flag on the server:
|
||||
# flag
|
||||
--console-assets-dir=/srv/console-assets
|
||||
|
||||
Once the flag is set, all files in ``/srv/console-assets`` directory of the
|
||||
Docker image will be served at ``/console/assets`` endpoint on the server with
|
||||
Once the flag is set, all files in the ``/srv/console-assets`` directory of the
|
||||
Docker image will be served at the ``/console/assets`` endpoint on the server with
|
||||
the right content-type headers.
|
||||
|
||||
.. note::
|
||||
|
||||
Hasura follows a rolling update pattern for console release where assets for
|
||||
Hasura follows a rolling update pattern for console releases where assets for
|
||||
a ``major.minor`` version is updated continuously across all patches. If
|
||||
you're using the assets on server Docker image, it might not be that latest
|
||||
you're using the assets on the server with a Docker image, it might not be the latest
|
||||
version of console.
|
||||
|
@ -17,7 +17,7 @@ The flags can be passed as ENV variables as well.
|
||||
Server flags
|
||||
^^^^^^^^^^^^
|
||||
|
||||
For ``graphql-engine`` command these are the flags and ENV variables available:
|
||||
For the ``graphql-engine`` command these are the available flags and ENV variables:
|
||||
|
||||
|
||||
.. list-table::
|
||||
@ -36,7 +36,7 @@ For ``graphql-engine`` command these are the flags and ENV variables available:
|
||||
|
||||
Example: ``postgres://admin:mypass@mydomain.com:5432/mydb``
|
||||
|
||||
Or you can specify following options *(only via flags)*
|
||||
Or you can specify the following options *(only via flags)*:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
@ -52,7 +52,7 @@ Or you can specify following options *(only via flags)*
|
||||
Command flags
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
For ``serve`` sub-command these are the flags and ENV variables available:
|
||||
For the ``serve`` sub-command these are the available flags and ENV variables:
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
@ -98,14 +98,14 @@ For ``serve`` sub-command these are the flags and ENV variables available:
|
||||
* - ``--unauthorized-role <ROLE>``
|
||||
- ``HASURA_GRAPHQL_UNAUTHORIZED_ROLE``
|
||||
- Unauthorized role, used when access-key is not sent in access-key only
|
||||
mode or "Authorization" header is absent in JWT mode.
|
||||
Example: ``anonymous``. Now whenever "Authorization" header is
|
||||
absent, request's role will default to "anonymous".
|
||||
mode or the ``Authorization`` header is absent in JWT mode.
|
||||
Example: ``anonymous``. Now whenever the "authorization" header is
|
||||
absent, the request's role will default to ``anonymous``.
|
||||
|
||||
* - ``--cors-domain <DOMAINS>``
|
||||
- ``HASURA_GRAPHQL_CORS_DOMAIN``
|
||||
- CSV of list of domains, excluding scheme (http/https) and including port,
|
||||
to allow CORS for. Wildcard domains are allowed.
|
||||
to allow for CORS. Wildcard domains are allowed.
|
||||
|
||||
* - ``--disable-cors``
|
||||
- N/A
|
||||
@ -148,7 +148,7 @@ For ``serve`` sub-command these are the flags and ENV variables available:
|
||||
|
||||
* - ``-i, --tx-iso <TXISO>``
|
||||
- ``HASURA_GRAPHQL_TX_ISOLATION``
|
||||
- transaction isolation. read-committed / repeatable-read / serializable (default: read-commited)
|
||||
- Transaction isolation. read-committed / repeatable-read / serializable (default: read-commited)
|
||||
|
||||
* - ``--stringify-numeric-types``
|
||||
- ``HASURA_GRAPHQL_STRINGIFY_NUMERIC_TYPES``
|
||||
@ -163,27 +163,27 @@ For ``serve`` sub-command these are the flags and ENV variables available:
|
||||
|
||||
* - ``--live-queries-fallback-refetch-interval``
|
||||
- ``HASURA_GRAPHQL_LIVE_QUERIES_FALLBACK_REFETCH_INTERVAL``
|
||||
- updated results (if any) will be sent at most once in this interval (in milliseconds) for live queries
|
||||
- Updated results (if any) will be sent at most once in this interval (in milliseconds) for live queries
|
||||
which cannot be multiplexed. Default: 1000 (1sec)
|
||||
|
||||
* - ``--live-queries-multiplexed-refetch-interval``
|
||||
- ``HASURA_GRAPHQL_LIVE_QUERIES_MULTIPLEXED_REFETCH_INTERVAL``
|
||||
- updated results (if any) will be sent at most once in this interval (in milliseconds) for live queries
|
||||
- Updated results (if any) will be sent at most once in this interval (in milliseconds) for live queries
|
||||
which can be multiplexed. Default: 1000 (1sec)
|
||||
|
||||
* - ``--live-queries-multiplexed-batch-size``
|
||||
- ``HASURA_GRAPHQL_LIVE_QUERIES_MULTIPLEXED_BATCH_SIZE``
|
||||
- multiplexed live queries are split into batches of the specified size. Default 100.
|
||||
- Multiplexed live queries are split into batches of the specified size. Default: 100
|
||||
|
||||
* - ``--enable-allowlist``
|
||||
- ``HASURA_GRAPHQL_ENABLE_ALLOWLIST``
|
||||
- Restrict queries allowed to be executed by GraphQL engine to those that are part of the configured
|
||||
allow-list. Default ``false``. *(Available for versions > v1.0.0-beta.1)*
|
||||
- Restrict queries allowed to be executed by the GraphQL engine to those that are part of the configured
|
||||
allow-list. Default: ``false`` *(Available for versions > v1.0.0-beta.1)*
|
||||
|
||||
* - ``--console-assets-dir``
|
||||
- ``HASURA_GRAPHQL_CONSOLE_ASSETS_DIR``
|
||||
- Set the value to ``/srv/console-assets`` for the console to load assets from the server itself
|
||||
instead of CDN. *(Available for versions > v1.0.0-beta.1)*
|
||||
instead of CDN *(Available for versions > v1.0.0-beta.1)*
|
||||
|
||||
* - ``--enabled-log-types``
|
||||
- ``HASURA_GRAPHQL_ENABLED_LOG_TYPES``
|
||||
|
@ -1,4 +1,4 @@
|
||||
Run Hasura GraphQL Engine on Heroku
|
||||
Run Hasura GraphQL engine on Heroku
|
||||
===================================
|
||||
|
||||
.. contents:: Table of contents
|
||||
@ -6,7 +6,7 @@ Run Hasura GraphQL Engine on Heroku
|
||||
:depth: 2
|
||||
:local:
|
||||
|
||||
This guide will help you get Hasura GraphQL engine running as a "git push to deploy" app on
|
||||
This guide will help you get the Hasura GraphQL engine running as a "git push to deploy" app on
|
||||
`Heroku <https://www.heroku.com/platform>`_ and connecting it to a `Heroku Postgres <https://www.heroku.com/postgres>`_
|
||||
instance. If you want a simple, quick deployment on Heroku, follow this :doc:`Heroku quickstart
|
||||
guide <../../getting-started/heroku-simple>`.
|
||||
@ -21,7 +21,7 @@ https://github.com/hasura/graphql-engine-heroku
|
||||
Configure database URL
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Edit the command in the ``Dockerfile`` to change which database Hasura GraphQL engine connects to.
|
||||
Edit the command in the ``Dockerfile`` to change which database the Hasura GraphQL engine connects to.
|
||||
By default, it connects to the primary database in your app which is available at ``DATABASE_URL``.
|
||||
|
||||
.. code-block:: dockerfile
|
||||
@ -42,7 +42,7 @@ Read about more configuration options :doc:`here <../graphql-engine-flags/refere
|
||||
.. note::
|
||||
|
||||
Hasura GraphQL engine needs access permissions to your Postgres database as described in
|
||||
:doc:`Postgres permissions <../postgres-permissions>`
|
||||
:doc:`Postgres permissions <../postgres-permissions>`.
|
||||
|
||||
|
||||
Deploying
|
||||
@ -50,8 +50,8 @@ Deploying
|
||||
|
||||
These are some sample deployment instructions while creating a new app.
|
||||
|
||||
Step 1: Create app with **--stack=container**
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Step 1: Create an app with **--stack=container**
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Use the `Heroku CLI <https://devcenter.heroku.com/articles/heroku-cli>`_ to create a new Heroku app. Let's call
|
||||
the app ``graphql-on-postgres``.
|
||||
@ -85,10 +85,10 @@ Create the Postgres add-on in your Heroku app.
|
||||
Created postgresql-angular-20334 as DATABASE_URL
|
||||
Use heroku addons:docs heroku-postgresql to view documentation
|
||||
|
||||
Step 3: git push to deploy
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Step 3: **git push** to deploy
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Remember to change ``HEROKU_GIT_REMOTE`` to your git remote below. In our case:
|
||||
``https://git.heroku.com/graphql-on-postgres.git``
|
||||
``https://git.heroku.com/graphql-on-postgres.git``.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
|
@ -6,8 +6,8 @@ Hasura GraphQL engine server logs (Heroku)
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
You can use the `Heroku CLI <https://devcenter.heroku.com/articles/heroku-cli>`_ to check logs
|
||||
of Hasura GraphQL engine deployed on Heroku:
|
||||
You can use the `Heroku CLI <https://devcenter.heroku.com/articles/heroku-cli>`_ to check the logs
|
||||
of the Hasura GraphQL engine deployed on Heroku:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@ -18,6 +18,6 @@ of Hasura GraphQL engine deployed on Heroku:
|
||||
|
||||
**See:**
|
||||
|
||||
- https://devcenter.heroku.com/articles/logging for more details on logging in Heroku.
|
||||
- https://devcenter.heroku.com/articles/logging for more details on logging on Heroku.
|
||||
|
||||
- :doc:`../logging` for more details on Hasura logs
|
||||
|
@ -26,7 +26,7 @@ prompted for the admin secret key.
|
||||
|
||||
The ``HASURA_GRAPHQL_ADMIN_SECRET`` should never be passed from the client to Hasura GraphQL engine as it would
|
||||
give the client full admin rights to your Hasura instance. See :doc:`../../auth/index` for information on
|
||||
setting up Authentication.
|
||||
setting up authentication.
|
||||
|
||||
|
||||
(optional) Use the admin secret with the CLI
|
||||
|
@ -6,7 +6,7 @@ Updating Hasura GraphQL engine on Heroku
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
This guide will help you update Hasura GraphQL engine running on Heroku. This guide assumes that you already have
|
||||
This guide will help you update the Hasura GraphQL engine running on Heroku. This guide assumes that you already have a
|
||||
Hasura GraphQL engine running on Heroku.
|
||||
|
||||
The current latest version is:
|
||||
@ -21,11 +21,11 @@ Step 1: Clone the Hasura GraphQL engine Heroku app
|
||||
--------------------------------------------------
|
||||
|
||||
The Hasura app with Heroku buildpack/configuration is available at:
|
||||
https://github.com/hasura/graphql-engine-heroku
|
||||
https://github.com/hasura/graphql-engine-heroku.
|
||||
|
||||
Clone the above repository.
|
||||
|
||||
If you already have this, then pull the latest changes which will have the updated GraphQL engine docker image.
|
||||
If you already have this, then pull the latest changes which will have the updated GraphQL engine Docker image.
|
||||
|
||||
Step 2: Attach your Heroku app
|
||||
------------------------------
|
||||
@ -43,8 +43,8 @@ to be able to push to this app.
|
||||
|
||||
You can find your Heroku git repo in your Heroku - Settings - Info - Heroku Git URL
|
||||
|
||||
Step 3: Git push to deploy the latest Hasura GraphQL engine
|
||||
-----------------------------------------------------------
|
||||
Step 3: **git push** to deploy the latest Hasura GraphQL engine
|
||||
---------------------------------------------------------------
|
||||
|
||||
When you ``git push`` to deploy, the Heroku app will get updated with the latest changes:
|
||||
|
||||
@ -52,12 +52,12 @@ When you ``git push`` to deploy, the Heroku app will get updated with the latest
|
||||
|
||||
$ git push heroku master
|
||||
|
||||
Deploy a specific version of Hasura GraphQL engine
|
||||
--------------------------------------------------
|
||||
Deploy a specific version of the Hasura GraphQL engine
|
||||
------------------------------------------------------
|
||||
|
||||
Head to the ``Dockerfile`` in the git repo you cloned in Step 1.
|
||||
Head to the ``Dockerfile`` in the git repo you cloned in step 1.
|
||||
Change the ``FROM`` line to the specific version you want. A list of all releases can be found
|
||||
at https://github.com/hasura/graphql-engine/releases
|
||||
at https://github.com/hasura/graphql-engine/releases.
|
||||
|
||||
.. code-block:: Dockerfile
|
||||
:emphasize-lines: 1
|
||||
|
@ -25,7 +25,7 @@ Deploy Hasura on Heroku by clicking on this button:
|
||||
:class: no-shadow
|
||||
:target: https://heroku.com/deploy?template=https://github.com/hasura/graphql-engine-heroku
|
||||
|
||||
Follow the Heroku instructions to deploy, check if the Hasura console loads up when you **View app** and then head
|
||||
Follow the Heroku instructions to deploy, check if the Hasura console loads up when you click on **View app** and then head
|
||||
to the **Manage App** screen on your Heroku dashboard.
|
||||
|
||||
This will deploy Hasura with a free Postgres add-on automatically provisioned.
|
||||
@ -47,8 +47,8 @@ if you want to secure your endpoint.
|
||||
|
||||
.. note::
|
||||
|
||||
Hasura GraphQL engine needs access permissions to your Postgres database as described in
|
||||
:doc:`Postgres permissions <../postgres-permissions>`
|
||||
The Hasura GraphQL engine needs access permissions to your Postgres database as described in
|
||||
:doc:`Postgres permissions <../postgres-permissions>`.
|
||||
|
||||
Step 4: Track tables and relationships
|
||||
--------------------------------------
|
||||
|
@ -1,4 +1,4 @@
|
||||
Deploying Hasura GraphQL Engine
|
||||
Deploying Hasura GraphQL engine
|
||||
===============================
|
||||
|
||||
.. contents:: Table of contents
|
||||
@ -7,7 +7,7 @@ Deploying Hasura GraphQL Engine
|
||||
:local:
|
||||
|
||||
.. note::
|
||||
This section talks in depth about deploying the Hasura GraphQL engine for a **production like environment**.
|
||||
This section talks in depth about deploying the Hasura GraphQL engine for a **production-like environment**.
|
||||
If you would simply like to take the Hasura GraphQL engine for a quick spin, choose from our
|
||||
:doc:`Getting started guides <../getting-started/index>`.
|
||||
|
||||
@ -28,7 +28,7 @@ Configuration
|
||||
-------------
|
||||
|
||||
By default, Hasura GraphQL engine runs in a very permissive mode for easier development. Check out the below pages
|
||||
to configure Hasura GraphQL engine for your production environment:
|
||||
to configure the Hasura GraphQL engine for your production environment:
|
||||
|
||||
- :doc:`securing-graphql-endpoint`
|
||||
- :doc:`postgres-permissions`
|
||||
|
@ -1,4 +1,4 @@
|
||||
Run Hasura GraphQL Engine on Kubernetes
|
||||
Run Hasura GraphQL engine on Kubernetes
|
||||
=======================================
|
||||
|
||||
.. contents:: Table of contents
|
||||
@ -49,8 +49,8 @@ Examples of ``HASURA_GRAPHQL_DATABASE_URL``:
|
||||
You can check the :doc:`logs <logging>` to see if the database credentials are proper and if Hasura is able
|
||||
to connect to the database.
|
||||
|
||||
- Hasura GraphQL engine needs access permissions to your Postgres database as described in
|
||||
:doc:`Postgres permissions <../postgres-permissions>`
|
||||
- The Hasura GraphQL engine needs access permissions on your Postgres database as described in
|
||||
:doc:`Postgres permissions <../postgres-permissions>`.
|
||||
|
||||
|
||||
Step 3: Create the Kubernetes deployment and service
|
||||
|
@ -6,7 +6,7 @@ Hasura GraphQL engine server logs (Kubernetes)
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
You can check logs of Hasura GraphQL engine deployed on Kubernetes by checking the logs of the GraphQL engine
|
||||
You can check the logs of the Hasura GraphQL engine deployed on Kubernetes by checking the logs of the GraphQL engine
|
||||
service, i.e. ``hasura``:
|
||||
|
||||
.. code-block:: bash
|
||||
|
@ -36,9 +36,9 @@ Update the ``deployment.yaml`` to set the ``HASURA_GRAPHQL_ADMIN_SECRET`` enviro
|
||||
|
||||
.. note::
|
||||
|
||||
The ``HASURA_GRAPHQL_ADMIN_SECRET`` should never be passed from the client to Hasura GraphQL engine as it would
|
||||
The ``HASURA_GRAPHQL_ADMIN_SECRET`` should never be passed from the client to the Hasura GraphQL engine as it would
|
||||
give the client full admin rights to your Hasura instance. See :doc:`../../auth/index` for information on
|
||||
setting up Authentication.
|
||||
setting up authentication.
|
||||
|
||||
|
||||
(optional) Use the admin secret key with the CLI
|
||||
|
@ -6,8 +6,8 @@ Updating Hasura GraphQL engine running on Kubernetes
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
This guide will help you update Hasura GraphQL engine running on Kubernetes. This guide assumes that you already have
|
||||
Hasura GraphQL engine running on Kubernetes.
|
||||
This guide will help you update the Hasura GraphQL engine running on Kubernetes. This guide assumes that you already have
|
||||
the Hasura GraphQL engine running on Kubernetes.
|
||||
|
||||
Step 1: Check the latest release version
|
||||
----------------------------------------
|
||||
@ -18,7 +18,7 @@ The current latest version is:
|
||||
|
||||
<code>hasura/graphql-engine:<span class="latest-release-tag">latest</span></code>
|
||||
|
||||
All the versions can be found at: https://github.com/hasura/graphql-engine/releases
|
||||
All the versions can be found at: https://github.com/hasura/graphql-engine/releases.
|
||||
|
||||
Step 2: Update the container image
|
||||
----------------------------------
|
||||
|
@ -9,7 +9,7 @@ Hasura GraphQL engine logs
|
||||
Accessing logs
|
||||
--------------
|
||||
|
||||
Based on your deployment method, Hasura GraphQL engine logs can be accessed as follows:
|
||||
Based on your deployment method, the Hasura GraphQL engine logs can be accessed as follows:
|
||||
|
||||
- :doc:`On Heroku <heroku/logging>`
|
||||
- :doc:`On Docker <docker/logging>`
|
||||
@ -399,446 +399,4 @@ Monitoring frameworks
|
||||
You can integrate the logs emitted by Hasura GraphQL with external monitoring tools for better visibility as per
|
||||
your convenience.
|
||||
|
||||
For some examples, see :doc:`../guides/monitoring/index`
|
||||
|
||||
Migration path of logs from (<= **v1.0.0-beta.2** to newer)
|
||||
-----------------------------------------------------------
|
||||
|
||||
Previously, there were two main kinds of logs for every request - ``http-log`` and ``ws-handler``
|
||||
for HTTP and websockets respectively. (The other logs being, logs during startup, event-trigger
|
||||
logs, schema-sync logs, jwk-refresh logs etc.).
|
||||
|
||||
The structure of the **http-log** has changed
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Summary of the changes
|
||||
++++++++++++++++++++++
|
||||
|
||||
.. list-table:: **http-log** changes
|
||||
:header-rows: 1
|
||||
|
||||
* - Older
|
||||
- Newer
|
||||
* - ``detail.status``
|
||||
- ``detail.http_info.status``
|
||||
* - ``detail.http_version``
|
||||
- ``detail.http_info.version``
|
||||
* - ``detail.method``
|
||||
- ``detail.http_info.method``
|
||||
* - ``detail.url``
|
||||
- ``detail.http_info.url``
|
||||
* - ``detail.ip``
|
||||
- ``detail.http_info.ip``
|
||||
* - ``detail.query_hash``
|
||||
- removed
|
||||
* - ``detail.query_execution_time``
|
||||
- ``detail.operation.query_execution_time``
|
||||
* - ``detail.request_id``
|
||||
- ``detail.operation.request_id``
|
||||
* - ``detail.response_size``
|
||||
- ``detail.operation.response_size``
|
||||
* - ``detail.user``
|
||||
- ``detail.operation.user_vars``
|
||||
* - ``detail.detail.error`` (only on error)
|
||||
- ``detail.operation.error`` (only on error)
|
||||
* - ``detail.detail.request`` (only on error)
|
||||
- ``detail.operation.query`` (only on error)
|
||||
|
||||
|
||||
Full example logs
|
||||
+++++++++++++++++
|
||||
|
||||
Older, on success :
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"timestamp": "2019-06-07T12:04:16.713+0000",
|
||||
"level": "info",
|
||||
"type": "http-log",
|
||||
"detail": {
|
||||
"status": 200,
|
||||
"query_hash": "e9006e6750ebaa77da775ae4fc60227d3101b03e",
|
||||
"http_version": "HTTP/1.1",
|
||||
"query_execution_time": 0.408548571,
|
||||
"request_id": "1ad0c61b-1431-410e-818e-99b57822bd2b",
|
||||
"url": "/v1/graphql",
|
||||
"ip": "106.51.72.39",
|
||||
"response_size": 204,
|
||||
"user": {
|
||||
"x-hasura-role": "admin"
|
||||
},
|
||||
"method": "POST",
|
||||
"detail": null
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
Newer, on success:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"timestamp": "2019-05-30T23:40:24.654+0530",
|
||||
"level": "info",
|
||||
"type": "http-log",
|
||||
"detail": {
|
||||
"operation": {
|
||||
"query_execution_time": 0.009240042,
|
||||
"user_vars": {
|
||||
"x-hasura-role": "user"
|
||||
},
|
||||
"request_id": "072b3617-6653-4fd5-b5ee-580e9d098c3d",
|
||||
"response_size": 105,
|
||||
"error": null,
|
||||
"query": null
|
||||
},
|
||||
"http_info": {
|
||||
"status": 200,
|
||||
"http_version": "HTTP/1.1",
|
||||
"url": "/v1/graphql",
|
||||
"ip": "127.0.0.1",
|
||||
"method": "POST"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Older, on error:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"timestamp": "2019-06-07T12:24:05.166+0000",
|
||||
"level": "info",
|
||||
"type": "http-log",
|
||||
"detail": {
|
||||
"status": 200,
|
||||
"query_hash": "511894cc797a2b5cef1c84f106a038ea7bc8436d",
|
||||
"http_version": "HTTP/1.1",
|
||||
"query_execution_time": 2.34687e-4,
|
||||
"request_id": "02d695c7-8a2d-4a45-84dd-8b61b7255807",
|
||||
"url": "/v1/graphql",
|
||||
"ip": "106.51.72.39",
|
||||
"response_size": 138,
|
||||
"user": {
|
||||
"x-hasura-role": "admin"
|
||||
},
|
||||
"method": "POST",
|
||||
"detail": {
|
||||
"error": {
|
||||
"path": "$.selectionSet.todo.selectionSet.completedx",
|
||||
"error": "field \"completedx\" not found in type: 'todo'",
|
||||
"code": "validation-failed"
|
||||
},
|
||||
"request": "{\"query\":\"query {\\n todo {\\n id\\n title\\n completedx\\n }\\n}\",\"variables\":null}"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Newer, on error:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"timestamp": "2019-05-29T15:22:37.834+0530",
|
||||
"level": "info",
|
||||
"type": "http-log",
|
||||
"detail": {
|
||||
"operation": {
|
||||
"query_execution_time": 0.000656144,
|
||||
"user_vars": {
|
||||
"x-hasura-role": "user",
|
||||
"x-hasura-user-id": "1"
|
||||
},
|
||||
"error": {
|
||||
"path": "$.selectionSet.profile.selectionSet.usernamex",
|
||||
"error": "field \"usernamex\" not found in type: 'profile'",
|
||||
"code": "validation-failed"
|
||||
},
|
||||
"request_id": "072b3617-6653-4fd5-b5ee-580e9d098c3d",
|
||||
"response_size": 142,
|
||||
"query": {
|
||||
"variables": {
|
||||
"limit": 10
|
||||
},
|
||||
"operationName": "getProfile",
|
||||
"query": "query getProfile($limit: Int!) { profile(limit: $limit, where:{username: {_like: \"%a%\"}}) { usernamex} }"
|
||||
}
|
||||
},
|
||||
"http_info": {
|
||||
"status": 200,
|
||||
"http_version": "HTTP/1.1",
|
||||
"url": "/v1/graphql",
|
||||
"ip": "127.0.0.1",
|
||||
"method": "POST"
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
The structure for **ws-handler** has changed, and has been renamed to **websocket-log**
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Summary of the changes
|
||||
++++++++++++++++++++++
|
||||
|
||||
.. list-table:: **websocket-log** changes
|
||||
:header-rows: 1
|
||||
|
||||
* - Older
|
||||
- Newer
|
||||
* - ``detail.websocket_id``
|
||||
- ``detail.connection_info.websocket_id``
|
||||
* - ``detail.jwt_expiry``
|
||||
- ``detail.connection_info.jwt_expiry``
|
||||
* - ``detail.msg``
|
||||
- ``detail.connection_info.msg``
|
||||
* - ``detail.user``
|
||||
- ``detail.user_vars``
|
||||
* - ``detail.event.detail``:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
[
|
||||
"1",
|
||||
null,
|
||||
{
|
||||
"type": "started"
|
||||
}
|
||||
]
|
||||
- ``detail.event.detail``:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"request_id": "d2ede87d-5cb7-44b6-8736-1d898117722a",
|
||||
"operation_id": "1",
|
||||
"operation_type": {
|
||||
"type": "started"
|
||||
},
|
||||
"operation_name": null
|
||||
}
|
||||
* - ``detail.event.detail`` (on error):
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
[
|
||||
"1",
|
||||
null,
|
||||
{
|
||||
"type": "query_err",
|
||||
"detail": {
|
||||
"path": "$.selectionSet.todo.selectionSet.titlex",
|
||||
"error": "field \"titlex\" not found in type: 'todo'",
|
||||
"code": "validation-failed"
|
||||
}
|
||||
}
|
||||
]
|
||||
- ``detail.event.detail`` (on error):
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"request_id": "150e3e6a-e1a7-46ba-a9d4-da6b192a4005",
|
||||
"operation_id": "1",
|
||||
"query": {
|
||||
"variables": {},
|
||||
"query": "subscription {\n author {\n namex\n }\n}\n"
|
||||
},
|
||||
"operation_type": {
|
||||
"type": "query_err",
|
||||
"detail": {
|
||||
"path": "$.selectionSet.author.selectionSet.namex",
|
||||
"error": "field \"namex\" not found in type: 'author'",
|
||||
"code": "validation-failed"
|
||||
}
|
||||
},
|
||||
"operation_name": null
|
||||
}
|
||||
|
||||
|
||||
Full example logs
|
||||
+++++++++++++++++
|
||||
|
||||
Older, on success:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"timestamp": "2019-06-07T12:35:40.652+0000",
|
||||
"level": "info",
|
||||
"type": "ws-handler",
|
||||
"detail": {
|
||||
"event": {
|
||||
"type": "operation",
|
||||
"detail": ["1", null, {
|
||||
"type": "started"
|
||||
}]
|
||||
},
|
||||
"websocket_id": "11dea559-6554-4598-969a-00b48545950f",
|
||||
"jwt_expiry": null,
|
||||
"msg": null,
|
||||
"user": {
|
||||
"x-hasura-role": "admin"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Newer, on success:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"timestamp": "2019-06-10T10:52:54.247+0530",
|
||||
"level": "info",
|
||||
"type": "websocket-log",
|
||||
"detail": {
|
||||
"event": {
|
||||
"type": "operation",
|
||||
"detail": {
|
||||
"request_id": "d2ede87d-5cb7-44b6-8736-1d898117722a",
|
||||
"operation_id": "1",
|
||||
"query": {
|
||||
"variables": {},
|
||||
"query": "subscription {\n author {\n name\n }\n}\n"
|
||||
},
|
||||
"operation_type": {
|
||||
"type": "started"
|
||||
},
|
||||
"operation_name": null
|
||||
}
|
||||
},
|
||||
"connection_info": {
|
||||
"websocket_id": "f590dd18-75db-4602-8693-8150239df7f7",
|
||||
"jwt_expiry": null,
|
||||
"msg": null
|
||||
},
|
||||
"user_vars": {
|
||||
"x-hasura-role": "admin"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Older, when operation stops:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"timestamp": "2019-06-10T05:30:41.432+0000",
|
||||
"level": "info",
|
||||
"type": "ws-handler",
|
||||
"detail": {
|
||||
"event": {
|
||||
"type": "operation",
|
||||
"detail": ["1", null, {
|
||||
"type": "stopped"
|
||||
}]
|
||||
},
|
||||
"websocket_id": "3f5721ee-1bc6-424c-841f-8ff8a326d9ef",
|
||||
"jwt_expiry": null,
|
||||
"msg": null,
|
||||
"user": {
|
||||
"x-hasura-role": "admin"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Newer, when operations stops:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"timestamp": "2019-06-10T11:01:40.939+0530",
|
||||
"level": "info",
|
||||
"type": "websocket-log",
|
||||
"detail": {
|
||||
"event": {
|
||||
"type": "operation",
|
||||
"detail": {
|
||||
"request_id": null,
|
||||
"operation_id": "1",
|
||||
"query": null,
|
||||
"operation_type": {
|
||||
"type": "stopped"
|
||||
},
|
||||
"operation_name": null
|
||||
}
|
||||
},
|
||||
"connection_info": {
|
||||
"websocket_id": "7f782190-fd58-4305-a83f-8e17177b204e",
|
||||
"jwt_expiry": null,
|
||||
"msg": null
|
||||
},
|
||||
"user_vars": {
|
||||
"x-hasura-role": "admin"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Older, on error:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"timestamp": "2019-06-07T12:38:07.188+0000",
|
||||
"level": "info",
|
||||
"type": "ws-handler",
|
||||
"detail": {
|
||||
"event": {
|
||||
"type": "operation",
|
||||
"detail": ["1", null, {
|
||||
"type": "query_err",
|
||||
"detail": {
|
||||
"path": "$.selectionSet.todo.selectionSet.titlex",
|
||||
"error": "field \"titlex\" not found in type: 'todo'",
|
||||
"code": "validation-failed"
|
||||
}
|
||||
}]
|
||||
},
|
||||
"websocket_id": "77558d9b-99f8-4c6a-b105-a5b08c96543b",
|
||||
"jwt_expiry": null,
|
||||
"msg": null,
|
||||
"user": {
|
||||
"x-hasura-role": "admin"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Newer, on error:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"timestamp": "2019-06-10T10:55:20.650+0530",
|
||||
"level": "info",
|
||||
"type": "websocket-log",
|
||||
"detail": {
|
||||
"event": {
|
||||
"type": "operation",
|
||||
"detail": {
|
||||
"request_id": "150e3e6a-e1a7-46ba-a9d4-da6b192a4005",
|
||||
"operation_id": "1",
|
||||
"query": {
|
||||
"variables": {},
|
||||
"query": "subscription {\n author {\n namex\n }\n}\n"
|
||||
},
|
||||
"operation_type": {
|
||||
"type": "query_err",
|
||||
"detail": {
|
||||
"path": "$.selectionSet.author.selectionSet.namex",
|
||||
"error": "field \"namex\" not found in type: 'author'",
|
||||
"code": "validation-failed"
|
||||
}
|
||||
},
|
||||
"operation_name": null
|
||||
}
|
||||
},
|
||||
"connection_info": {
|
||||
"websocket_id": "49932ddf-e54d-42c6-bffb-8a57a1c6dcbe",
|
||||
"jwt_expiry": null,
|
||||
"msg": null
|
||||
},
|
||||
"user_vars": {
|
||||
"x-hasura-role": "admin"
|
||||
}
|
||||
}
|
||||
}
|
||||
For some examples, see :doc:`../guides/monitoring/index`.
|
||||
|
@ -6,17 +6,17 @@ Postgres permissions
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
If you're running in a controlled environment, you might need to configure Hasura GraphQL engine to use a
|
||||
If you're running in a controlled environment, you might need to configure the Hasura GraphQL engine to use a
|
||||
specific Postgres user that your DBA gives you.
|
||||
|
||||
Hasura GraphQL engine needs access to your Postgres database with the following permissions:
|
||||
The Hasura GraphQL engine needs access to your Postgres database with the following permissions:
|
||||
|
||||
- (required) Read & write access on 2 schemas: ``hdb_catalog`` and ``hdb_views``.
|
||||
- (required) Read access to the ``information_schema`` and ``pg_catalog`` schemas, to query for list of tables.
|
||||
- (required) Read access to the schemas (public or otherwise) if you only want to support queries.
|
||||
- (optional) Write access to the schemas if you want to support mutations as well
|
||||
- (optional) Write access to the schemas if you want to support mutations as well.
|
||||
- (optional) To create tables and views via the Hasura console (the admin UI) you'll need the privilege to create
|
||||
tables/views. This might not be required when you're working with an existing database
|
||||
tables/views. This might not be required when you're working with an existing database.
|
||||
|
||||
|
||||
Here's a sample SQL block that you can run on your database to create the right credentials:
|
||||
|
@ -22,15 +22,15 @@ Unique name for event trigger.
|
||||
|
||||
**Schema/Table**
|
||||
|
||||
The postgres schema and table name on which event trigger needs to be created.
|
||||
The postgres schema and table name on which the event trigger needs to be created.
|
||||
|
||||
**Trigger Operations**
|
||||
|
||||
The table operation on which event trigger will be invoked.
|
||||
The table operation on which the event trigger will be invoked.
|
||||
|
||||
**Webhook URL**
|
||||
|
||||
The HTTP(s) URL which will be called with event payload on configured operation. Must be a ``POST`` handler. This URL
|
||||
The HTTP(s) URL which will be called with the event payload on configured operation. Must be a ``POST`` handler. This URL
|
||||
can be entered manually or can be picked up from an environment variable (*the environment variable needs to be set
|
||||
before using it for this configuration*).
|
||||
|
||||
@ -42,8 +42,8 @@ Advanced Settings
|
||||
Listen columns for update
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Update operations are special because you may want to trigger webhook only if specific columns have changed in a row.
|
||||
Choose the columns here which you want the update operation to listen on.
|
||||
Update operations are special because you may want to trigger a webhook only if specific columns have changed in a row.
|
||||
Choose the columns here which you want the update operation to listen to.
|
||||
|
||||
If a column is not selected here, then an update to that column will not trigger the webhook.
|
||||
|
||||
@ -67,5 +67,5 @@ Each header has 3 parameters:
|
||||
1. ``Key``: Name of the header e.g. Authorization or X-My-Header.
|
||||
2. ``Type``: One of ``static`` or ``from env variable``. ``static`` means the value provided in the ``Value`` field is
|
||||
the raw value of the header. ``from env variable`` means the value provided in the ``Value`` field is the name of
|
||||
the environment variable in the GraphQL Engine which will be resolved before sending the header.
|
||||
3. ``Value``: The value of the header. Either static value or name of an environment variable.
|
||||
the environment variable in the GraphQL engine which will be resolved before sending the header.
|
||||
3. ``Value``: The value of the header. Either a static value or the name of an environment variable.
|
||||
|
@ -17,7 +17,7 @@ Events can be of the following types:
|
||||
- INSERT: When a row is inserted into a table
|
||||
- UPDATE: When a row is updated in a table
|
||||
- DELETE: When a row is deleted from a table
|
||||
- MANUAL: Using the console or API, an event can be triggered manually on a row.
|
||||
- MANUAL: Using the console or API, an event can be triggered manually on a row
|
||||
|
||||
**See:**
|
||||
|
||||
|
@ -7,18 +7,18 @@ Invoke event trigger via console
|
||||
:local:
|
||||
|
||||
You can select the ``Via console`` trigger operation while :doc:`creating an event trigger <./create-trigger>`
|
||||
to allow invoking the event trigger on rows manually using the Hasura console. *(available after version v1.0.0-beta.1)*
|
||||
to allow invoking the event trigger on rows manually using the Hasura console *(available after version v1.0.0-beta.1)*.
|
||||
|
||||
In the ``Data -> [table-name] -> Browse Rows`` tab, clicking the invoke trigger button next to any row lets
|
||||
you invoke manual event triggers configured on the table with that row as payload *(the button will be shown
|
||||
In the ``Data -> [table-name] -> Browse Rows`` tab, clicking the ``invoke trigger`` button next to any row lets
|
||||
you invoke "manual event triggers" configured on the table with that row as payload *(the button will be shown
|
||||
only if you have any triggers configured)*:
|
||||
|
||||
.. thumbnail:: ../../../img/graphql/manual/event-triggers/select-manual-trigger.png
|
||||
|
||||
Click on the event trigger you want to run and a modal will pop-up with the request and response.
|
||||
Click on the event trigger you want to run and a modal will pop up with the request and response.
|
||||
|
||||
.. thumbnail:: ../../../img/graphql/manual/event-triggers/run-manual-trigger.png
|
||||
|
||||
.. note::
|
||||
|
||||
You can also use the :ref:`invoke_event_trigger` metadata API to invoke manual triggers
|
||||
You can also use the :ref:`invoke_event_trigger` metadata API to invoke manual triggers.
|
||||
|
@ -50,7 +50,7 @@ JSON payload
|
||||
- Description
|
||||
* - session-variables
|
||||
- Object_ or NULL
|
||||
- Key-value pairs of session variables (i.e. "x-hasura-\*" variables) and their values. NULL if no session variables found.
|
||||
- Key-value pairs of session variables (i.e. "x-hasura-\*" variables) and their values (NULL if no session variables found)
|
||||
* - op-name
|
||||
- OpName_
|
||||
- Name of the operation. Can only be "INSERT", "UPDATE", "DELETE", "MANUAL"
|
||||
|
@ -10,17 +10,17 @@ Event trigger samples
|
||||
Boilerplates
|
||||
^^^^^^^^^^^^
|
||||
|
||||
Here are few boilerplates you can use to build and deploy event triggers on different cloud providers:
|
||||
Here are a few boilerplates you can use to build and deploy event triggers on different cloud providers:
|
||||
|
||||
* Source code: https://github.com/hasura/graphql-engine/tree/master/community/boilerplates/event-triggers
|
||||
|
||||
There are 2 types of boilerplates:
|
||||
|
||||
**Echo**
|
||||
Returns the event payload with some augmented data. Helps you in understanding the event payload and parsing it.
|
||||
Returns the event payload with some augmented data. It helps you in understanding the event payload and parsing it.
|
||||
|
||||
**Mutation**
|
||||
Makes a mutation based on the event payload. Helps in understanding database access in event trigger.
|
||||
Makes a mutation based on the event payload. It helps in understanding database access inside an event trigger.
|
||||
|
||||
Push Notifications
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
@ -6,7 +6,7 @@ Using serverless functions
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
You can use serverless functions along with Event Triggers to design an async business workflow without
|
||||
You can use serverless functions along with event triggers to design an async business workflow without
|
||||
having to manage any dedicated infrastructure.
|
||||
|
||||
As Hasura event triggers can deliver database events to any webhook, serverless functions can be perfect candidates
|
||||
|
@ -6,7 +6,7 @@ Quickstart with Docker
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
This guide will help you get Hasura GraphQL engine and Postgres running as
|
||||
This guide will help you get the Hasura GraphQL engine and Postgres running as
|
||||
Docker containers using Docker Compose. This is the easiest way to set up
|
||||
Hasura GraphQL engine on your **local environment**.
|
||||
|
||||
|
@ -8,7 +8,7 @@ Making your first GraphQL query
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
Let's create a sample table and query from it using the Hasura console, a UI tool meant for doing exactly this:
|
||||
Let's create a sample table and query data from it using the Hasura console, a UI tool meant for doing exactly this:
|
||||
|
||||
Create a table
|
||||
--------------
|
||||
|
@ -6,8 +6,8 @@ Quickstart with Heroku
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
This guide will help you get Hasura GraphQL engine and Postgres running on `Heroku's free tier <https://www.heroku.com/free>`_.
|
||||
It is the easiest and fastest way of trying Hasura out.
|
||||
This guide will help you get the Hasura GraphQL engine and Postgres running on `Heroku's free tier <https://www.heroku.com/free>`_.
|
||||
It is the easiest and fastest way of trying out Hasura.
|
||||
|
||||
If you'd like to link this to an existing database, please head to this guide instead:
|
||||
:doc:`Using an existing database on Heroku <../deployment/heroku/using-existing-heroku-database>`.
|
||||
@ -52,4 +52,4 @@ Advanced
|
||||
--------
|
||||
|
||||
This was a quickstart guide to get the Hasura GraphQL engine up and running quickly. For more detailed instructions
|
||||
on deploying using Heroku, check out :doc:`../deployment/heroku/index`.
|
||||
on deploying using Heroku, check out :doc:`../deployment/heroku/index`.
|
||||
|
@ -7,9 +7,9 @@ Auditing actions on tables in Postgres
|
||||
:local:
|
||||
|
||||
Typically audit logging is added to some of the tables to comply with various certifications.
|
||||
You may want to capture the user information (role and the session variables) for every change in Postgres that is done through graphql-engine.
|
||||
You may want to capture the user information (role and the session variables) for every change in Postgres that is done through the GraphQL engine.
|
||||
|
||||
For every mutation, hasura roughly executes the following transaction:
|
||||
For every mutation, Hasura roughly executes the following transaction:
|
||||
|
||||
.. code-block:: sql
|
||||
|
||||
|
@ -7,9 +7,9 @@ Guides: Visual Studio Code Setup
|
||||
:local:
|
||||
|
||||
|
||||
If you use `Visual Studio code <https://code.visualstudio.com/>`_, `Apollo GraphQL plugin <https://marketplace.visualstudio.com/items?itemName=apollographql.vscode-apollo>`_ can improve your development experience significantly by enabling a lot of cool features like syntax highlighting for GraphQL, auto completion for GraphQL queries and validating your GraphQL queries against a schema or an endpoint.
|
||||
If you use `Visual Studio code <https://code.visualstudio.com/>`_, the `Apollo GraphQL plugin <https://marketplace.visualstudio.com/items?itemName=apollographql.vscode-apollo>`_ can improve your development experience significantly by enabling a lot of cool features like syntax highlighting for GraphQL, auto completion for GraphQL queries and validating your GraphQL queries against a schema or an endpoint.
|
||||
|
||||
This guide helps you configure Apollo GraphQL plugin with Hasura to make your local development easier.
|
||||
This guide helps you configure the Apollo GraphQL plugin with Hasura to make your local development easier.
|
||||
|
||||
Install the plugin
|
||||
------------------
|
||||
@ -23,7 +23,7 @@ Launch VS Code Quick Open (Ctrl+P), paste the following command, and press enter
|
||||
Configure your project
|
||||
----------------------
|
||||
|
||||
Create a file called `apollo.config.js` in the root of your project and add the following content:
|
||||
Create a file called ``apollo.config.js`` in the root of your project and add the following content:
|
||||
|
||||
.. code-block:: javascript
|
||||
|
||||
@ -41,9 +41,9 @@ Create a file called `apollo.config.js` in the root of your project and add the
|
||||
|
||||
Notes:
|
||||
|
||||
- Replace ``http://localhost:8080/v1/graphql`` with your GraphQL Endpoint
|
||||
- Replace ``http://localhost:8080/v1/graphql`` with your GraphQL endpoint.
|
||||
- You can also add custom headers in the headers object if you wish to emulate the schema for some specific roles or tokens.
|
||||
|
||||
For advanced configuration, check out the `docs for the plugin <https://marketplace.visualstudio.com/items?itemName=apollographql.vscode-apollo>`_.
|
||||
|
||||
Note: The `VSCode GraphQL <https://github.com/prisma/vscode-graphql>`_ plugin by Prisma does not currently work with Hasura because it has a hard dependency on batching and Hasura does not support batching as of now. Batching as a feature in GraphQL Engine is tracked `here <https://github.com/hasura/graphql-engine/issues/1812>`_.
|
||||
Note: The `VSCode GraphQL <https://github.com/prisma/vscode-graphql>`_ plugin by Prisma does not currently work with Hasura because it has a hard dependency on batching and Hasura does not support batching as of now. Batching as a feature in GraphQL engine is tracked `here <https://github.com/hasura/graphql-engine/issues/1812>`_.
|
||||
|
@ -1,6 +1,6 @@
|
||||
.. _deploy_azure_ci_pg:
|
||||
|
||||
Hasura GraphQL Engine on Azure with Container Instances and Postgres
|
||||
Hasura GraphQL engine on Azure with Container Instances and Postgres
|
||||
====================================================================
|
||||
|
||||
.. contents:: Table of contents
|
||||
@ -8,7 +8,7 @@ Hasura GraphQL Engine on Azure with Container Instances and Postgres
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
This guide talks about how to deploy Hasura GraphQL Engine on `Azure
|
||||
This guide talks about how to deploy the Hasura GraphQL engine on `Azure
|
||||
<https://azure.microsoft.com>`__ using `Container Instances
|
||||
<https://azure.microsoft.com/en-us/services/container-instances/>`__ with `Azure
|
||||
Database for PostgreSQL server <https://azure.microsoft.com/en-us/services/postgresql/>`__.
|
||||
@ -31,7 +31,7 @@ All resources mentioned in this guide can be deployed using the one-click button
|
||||
:target: https://portal.azure.com/#create/Microsoft.Template/uri/https%3a%2f%2fraw.githubusercontent.com%2fhasura%2fgraphql-engine%2fmaster%2finstall-manifests%2fazure-container-with-pg%2fazuredeploy.json
|
||||
|
||||
(This button takes you to the Azure Portal, you might want to :kbd:`Ctrl+Click` to
|
||||
open it in a new tab. Read more about this Resource Manager Template `here <https://github.com/hasura/graphql-engine/tree/master/install-manifests/azure-container-with-pg>`__.)
|
||||
open it in a new tab. Read more about this Resource Manager Template `here <https://github.com/hasura/graphql-engine/tree/master/install-manifests/azure-container-with-pg>`__).
|
||||
|
||||
.. tab:: With an existing Postgres Server
|
||||
|
||||
@ -42,19 +42,19 @@ All resources mentioned in this guide can be deployed using the one-click button
|
||||
:target: https://portal.azure.com/#create/Microsoft.Template/uri/https%3a%2f%2fraw.githubusercontent.com%2fhasura%2fgraphql-engine%2fmaster%2finstall-manifests%2fazure-container%2fazuredeploy.json
|
||||
|
||||
(This button takes you to the Azure Portal, you might want to :kbd:`Ctrl+Click` to
|
||||
open it in a new tab. Read more about this Resource Manager Template `here <https://github.com/hasura/graphql-engine/tree/master/install-manifests/azure-container>`__.)
|
||||
open it in a new tab. Read more about this Resource Manager Template `here <https://github.com/hasura/graphql-engine/tree/master/install-manifests/azure-container>`__).
|
||||
|
||||
|
||||
Pre-requisites
|
||||
--------------
|
||||
|
||||
- Valid Azure Subscription with billing enabled or credits. (`click
|
||||
here <https://azure.microsoft.com/en-us/free/>`__ for a free trial)
|
||||
- Valid Azure Subscription with billing enabled or credits (`click
|
||||
here <https://azure.microsoft.com/en-us/free/>`__ for a free trial).
|
||||
- `Azure CLI <https://docs.microsoft.com/en-us/cli/azure/install-azure-cli>`_.
|
||||
|
||||
The actions mentioned below can be executed using Azure Portal and Azure CLI. But,
|
||||
The actions mentioned below can be executed using the Azure Portal and the Azure CLI. But,
|
||||
for the sake of simplicity in documentation, we are going to use Azure CLI, so
|
||||
that commands can be easily copy pasted and executed.
|
||||
that commands can be easily copy-pasted and executed.
|
||||
|
||||
Once the CLI is installed, login to your Azure account:
|
||||
|
||||
@ -97,8 +97,8 @@ Once the resource group is created, we create a Postgres server instance:
|
||||
|
||||
Choose a unique name for ``<server_name>``. Also choose a strong password for
|
||||
``<server_admin_password>``, including uppercase, lowercase and numeric characters.
|
||||
This will be required later to connect to the database.
|
||||
(Make sure you escape the special characters depending on your shell.)
|
||||
This will be required later to connect to the database
|
||||
(make sure you escape the special characters depending on your shell).
|
||||
|
||||
Note down the hostname. It will be shown as below in the output:
|
||||
|
||||
@ -178,7 +178,7 @@ Open the Hasura Console
|
||||
-----------------------
|
||||
|
||||
That's it! Once the deployment is complete, navigate to the container instance's
|
||||
IP or hostname to open Hasura console:
|
||||
IP or hostname to open the Hasura console:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@ -187,10 +187,10 @@ IP or hostname to open Hasura console:
|
||||
--query "{FQDN:ipAddress.fqdn,ProvisioningState:provisioningState}" \
|
||||
--out table
|
||||
|
||||
Output will contain the FQDN in the format
|
||||
The output will contain the FQDN in the format
|
||||
``<dns-name-label>.westus.azurecontainer.io``.
|
||||
|
||||
Visit the following URL for the Hasura Console:
|
||||
Visit the following URL for the Hasura console:
|
||||
|
||||
.. code::
|
||||
|
||||
@ -202,7 +202,7 @@ Replace ``<dns-name-label>`` with the label given earlier.
|
||||
:class: no-shadow
|
||||
:alt: Hasura console
|
||||
|
||||
You can create tables and test your GraphQL queries here. Checkout :ref:`Making
|
||||
You can create tables and test your GraphQL queries here. Check out :ref:`Making
|
||||
your first GraphQL Query <first_graphql_query>` for a detailed guide.
|
||||
|
||||
Troubleshooting
|
||||
@ -221,7 +221,7 @@ the database allow connection for Azure services.
|
||||
Checking logs
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
If the console is not loading, you might want to check logs and see if something
|
||||
If the console is not loading, you might want to check the logs and see if something
|
||||
is wrong:
|
||||
|
||||
.. code-block:: bash
|
||||
|
@ -1,4 +1,4 @@
|
||||
Hasura GraphQL Engine One-click App on DigitalOcean Marketplace
|
||||
Hasura GraphQL engine One-click App on DigitalOcean Marketplace
|
||||
===============================================================
|
||||
|
||||
.. contents:: Table of contents
|
||||
@ -6,7 +6,7 @@ Hasura GraphQL Engine One-click App on DigitalOcean Marketplace
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
Hasura GraphQL Engine is available as a One-click app on the DigitalOcean
|
||||
The Hasura GraphQL engine is available as a One-click app on the DigitalOcean
|
||||
Marketplace. It is packed with a `Postgres <https://www.postgresql.org/>`__
|
||||
database and `Caddy <https://caddyserver.com/>`__ webserver for easy and
|
||||
automatic HTTPS using `Let's Encrypt <https://letsencrypt.org/>`__.
|
||||
@ -17,8 +17,8 @@ Quickstart
|
||||
1. Create a Hasura One-click Droplet
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Click the button below to create a new Hasura GraphQL Engine Droplet through
|
||||
DigitalOcean Marketplace. For first time users, the link also contains a
|
||||
Click the button below to create a new Hasura GraphQL engine Droplet through
|
||||
the DigitalOcean Marketplace. For first time users, the link also contains a
|
||||
referral code with gives you $100 over days. A $5 droplet is good enough to
|
||||
support most workloads. (``Ctrl+Click`` to open in a new tab)
|
||||
|
||||
@ -31,7 +31,7 @@ support most workloads. (``Ctrl+Click`` to open in a new tab)
|
||||
2. Open console
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
Once Hasura GraphQL Engine Droplet is ready, you can visit the Droplet IP to
|
||||
Once the Hasura GraphQL engine Droplet is ready, you can visit the Droplet IP to
|
||||
open the Hasura console, where you can create tables, explore GraphQL APIs etc.
|
||||
Note that it might take 1 or 2 minutes for everything to start running.
|
||||
|
||||
@ -42,7 +42,7 @@ The Hasura console will be at:
|
||||
http://<your_droplet_ip>/console
|
||||
|
||||
|
||||
The GraphQL Endpoint will be:
|
||||
The GraphQL endpoint will be:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@ -119,7 +119,7 @@ to your database using GraphQL. When deploying to production, you should secure
|
||||
the endpoint by adding an admin secret key and then setting up permission rules on
|
||||
tables.
|
||||
|
||||
To add an admin secret key, follow the steps given below:
|
||||
To add an admin secret key, follow the steps described below:
|
||||
|
||||
1. Connect to the Droplet via SSH:
|
||||
|
||||
@ -128,7 +128,7 @@ To add an admin secret key, follow the steps given below:
|
||||
ssh root@<your_droplet_ip>
|
||||
|
||||
|
||||
2. Goto ``/etc/hasura`` directory:
|
||||
2. Go to the ``/etc/hasura`` directory:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@ -166,7 +166,7 @@ following header:
|
||||
X-Hasura-Admin-Secret: myadminsecretkey
|
||||
|
||||
|
||||
Adding a domain & Enabling HTTPS
|
||||
Adding a domain & enabling HTTPS
|
||||
--------------------------------
|
||||
|
||||
If you own a domain, you can enable HTTPS on this Droplet by mapping the domain
|
||||
@ -181,14 +181,14 @@ HTTP/2 web server with automatic HTTPS using Let's Encrypt.
|
||||
ssh root@<your_droplet_ip>
|
||||
|
||||
|
||||
3. Goto ``/etc/hasura`` directory:
|
||||
3. Go to the ``/etc/hasura`` directory:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd /etc/hasura
|
||||
|
||||
|
||||
4. Edit ``Caddyfile`` and change ``:80`` to your domain:
|
||||
4. Edit the ``Caddyfile`` and change ``:80`` to your domain:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@ -212,13 +212,13 @@ HTTP/2 web server with automatic HTTPS using Let's Encrypt.
|
||||
docker-compose restart caddy
|
||||
|
||||
|
||||
Visit ``https://<your_domain>/console`` to visit the Hasura console.
|
||||
Go to ``https://<your_domain>/console`` to visit the Hasura console.
|
||||
|
||||
Updating to the latest version
|
||||
------------------------------
|
||||
|
||||
When a new version of GraphQL Engine is released, you can upgrade to it by just
|
||||
changing the version tag in docker-compose.yaml. You can find the latest
|
||||
When a new version of the GraphQL engine is released, you can upgrade to it by just
|
||||
changing the version tag in ``docker-compose.yaml``. You can find the latest
|
||||
releases on the `GitHub releases page
|
||||
<https://github.com/hasura/graphql-engine/releases>`__.
|
||||
|
||||
@ -229,7 +229,7 @@ releases on the `GitHub releases page
|
||||
ssh root@<your_droplet_ip>
|
||||
|
||||
|
||||
2. Goto ``/etc/hasura`` directory:
|
||||
2. Go to the ``/etc/hasura`` directory:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@ -260,11 +260,11 @@ releases on the `GitHub releases page
|
||||
Using DigitalOcean Managed Postgres Database
|
||||
--------------------------------------------
|
||||
|
||||
1. Create a new Postgres Database from DigitalOcean Console, preferably in the
|
||||
1. Create a new Postgres Database from the DigitalOcean Console, preferably in the
|
||||
same region as the Droplet.
|
||||
2. Once the database is created, under the "Overview" tab, from the "Connection
|
||||
Details" section, choose "Connection string" from the dropdown.
|
||||
3. "Connection string" is the "Database URL" - copy it.
|
||||
3. "Connection string" is the "Database URL". Copy it.
|
||||
4. Connect to the Droplet via SSH:
|
||||
|
||||
.. code-block:: bash
|
||||
@ -272,7 +272,7 @@ Using DigitalOcean Managed Postgres Database
|
||||
ssh root@<your_droplet_ip>
|
||||
|
||||
|
||||
5. Goto ``/etc/hasura`` directory:
|
||||
5. Go to the ``/etc/hasura`` directory:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@ -291,15 +291,15 @@ Using DigitalOcean Managed Postgres Database
|
||||
|
||||
# type ESC followed by :wq to save and quit
|
||||
|
||||
Similarly, database URL can be changed to connect to any other Postgres
|
||||
Similarly, the database URL can be changed to connect to any other Postgres
|
||||
database.
|
||||
|
||||
.. note::
|
||||
|
||||
If you're using Hasura with a restricted database user, make sure you go
|
||||
through :doc:`Postgres permissions <../../deployment/postgres-permissions>`
|
||||
to configure all required permissions. (Not applicable with the default
|
||||
connection string with DO Managed Postgres)
|
||||
to configure all required permissions (not applicable with the default
|
||||
connection string with DO Managed Postgres).
|
||||
|
||||
Logs
|
||||
----
|
||||
@ -312,7 +312,7 @@ Logs
|
||||
ssh root@<your_droplet_ip>
|
||||
|
||||
|
||||
2. Goto ``/etc/hasura`` directory:
|
||||
2. Go to the ``/etc/hasura`` directory:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
|
@ -1,4 +1,4 @@
|
||||
Hasura GraphQL Engine on Google Cloud Platform with Kubernetes Engine and Cloud SQL
|
||||
Hasura GraphQL engine on Google Cloud Platform with Kubernetes engine and Cloud SQL
|
||||
===================================================================================
|
||||
|
||||
.. contents:: Table of contents
|
||||
@ -6,8 +6,8 @@ Hasura GraphQL Engine on Google Cloud Platform with Kubernetes Engine and Cloud
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
This is a guide about deploying Hasura GraphQL Engine on `Google Cloud Platform
|
||||
<https://cloud.google.com/>`__ using `Kuberentes Engine
|
||||
This is a guide on deploying the Hasura GraphQL engine on the `Google Cloud Platform
|
||||
<https://cloud.google.com/>`__ using `Kuberentes engine
|
||||
<https://cloud.google.com/kubernetes-engine/>`__ to run Hasura and PosgreSQL
|
||||
backed by `Cloud SQL <https://cloud.google.com/sql/>`__.
|
||||
|
||||
@ -19,9 +19,9 @@ Prerequisites
|
||||
- ``gcloud`` CLI (`install <https://cloud.google.com/sdk/>`__)
|
||||
- ``kubectl`` CLI (`install <https://kubernetes.io/docs/tasks/tools/install-kubectl/>`__)
|
||||
|
||||
The actions mentioned below can be done using the Google Cloud Console and
|
||||
The actions mentioned below can be done using the Google Cloud Console and the
|
||||
``gcloud`` CLI. But, for the sake of simplicity in documentation, we are going
|
||||
to use ``gcloud`` CLI, so that commands can be easily copy pasted and executed.
|
||||
to use ``gcloud`` CLI, so that commands can be easily copy-pasted and executed.
|
||||
|
||||
Once the CLI is installed, initialize the SDK:
|
||||
|
||||
@ -42,7 +42,7 @@ project called ``hasura`` for this guide.
|
||||
Create a Google Cloud SQL Postgres instance
|
||||
-------------------------------------------
|
||||
|
||||
Create a Cloud SQL Postgres instance called ``hasura-postgres`` at the
|
||||
Create a Cloud SQL Postgres instance called ``hasura-postgres`` in the
|
||||
``asia-south1`` region.
|
||||
|
||||
.. code-block:: bash
|
||||
@ -61,8 +61,8 @@ Make sure you substitute ``[PASSWORD]`` with a strong password.
|
||||
Create a Kubernetes Cluster
|
||||
---------------------------
|
||||
|
||||
Before creating the cluster, we need to enable the Kubernetes Engine API. Visit
|
||||
the following link in a browser to enable the API. Replace ``hasura`` at the end
|
||||
Before creating the cluster, we need to enable the Kubernetes engine API. Visit
|
||||
the below link in a browser to enable the API. Replace ``hasura`` at the end
|
||||
of the URL with your project name, in case you're not using the same name. Note
|
||||
that, you will need a billing account added to the project to enable the API.
|
||||
|
||||
@ -78,12 +78,12 @@ in the ``asia-south1-a`` zone with 1 node.
|
||||
gcloud container clusters create hasura-k8s --zone asia-south1-a \
|
||||
--num-nodes 1 --project hasura
|
||||
|
||||
Setup Cloud SQL Proxy Credentials
|
||||
---------------------------------
|
||||
Set up Cloud SQL Proxy Credentials
|
||||
----------------------------------
|
||||
|
||||
Inorder to connect to the Cloud SQL instance, we need to setup a proxy that will
|
||||
In order to connect to the Cloud SQL instance, we need to set up a proxy that will
|
||||
forward connections from Hasura to the database instance. For that purpose, the
|
||||
credentials to access the instance needs to be added to the cluster.
|
||||
credentials to access the instance need to be added to the cluster.
|
||||
|
||||
Create a service account and download the JSON key file by following `this guide
|
||||
<https://cloud.google.com/sql/docs/postgres/sql-proxy#create-service-account>`__.
|
||||
@ -99,7 +99,7 @@ Or if you're overwhelmed with that guide, ensure the following:
|
||||
4. Click ``Create Key`` to download the JSON file.
|
||||
|
||||
Create a Kubernetes secret with this JSON key file; replace
|
||||
``[JSON_KEY_FILE_PATH]`` with the filename including complete path of the
|
||||
``[JSON_KEY_FILE_PATH]`` with the filename including the complete path of the
|
||||
download JSON key file.
|
||||
|
||||
.. code-block:: bash
|
||||
@ -107,7 +107,7 @@ download JSON key file.
|
||||
kubectl create secret generic cloudsql-instance-credentials \
|
||||
--from-file=credentials.json=[JSON_KEY_FILE_PATH]
|
||||
|
||||
Create another secret with the database username and password (Use the
|
||||
Create another secret with the database username and password (use the
|
||||
``[PASSWORD]`` used earlier):
|
||||
|
||||
.. code-block:: bash
|
||||
@ -115,8 +115,8 @@ Create another secret with the database username and password (Use the
|
||||
kubectl create secret generic cloudsql-db-credentials \
|
||||
--from-literal=username=postgres --from-literal=password=[PASSWORD]
|
||||
|
||||
Deploy Hasura GraphQL Engine
|
||||
----------------------------
|
||||
Deploy the Hasura GraphQL engine
|
||||
--------------------------------
|
||||
|
||||
Download the ``deployment.yaml`` file:
|
||||
|
||||
@ -148,13 +148,13 @@ Ensure the pods are running:
|
||||
|
||||
kubectl get pods
|
||||
|
||||
If there are any errors, check the logs for GraphQL Engine:
|
||||
If there are any errors, check the logs of the GraphQL engine:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
kubectl logs deployment/hasura -c graphql-engine
|
||||
|
||||
Expose GraphQL Engine
|
||||
Expose GraphQL engine
|
||||
---------------------
|
||||
|
||||
Now that we have Hasura running, let's expose it on an IP using a LoadBalancer.
|
||||
@ -166,24 +166,24 @@ Now that we have Hasura running, let's expose it on an IP using a LoadBalancer.
|
||||
--type LoadBalancer
|
||||
|
||||
|
||||
Open Hasura Console
|
||||
Open Hasura console
|
||||
-------------------
|
||||
|
||||
Wait for the external IP to be allocated, check status using the following
|
||||
command. It usually takes a couple of minutes.
|
||||
Wait for the external IP to be allocated, check the status using the
|
||||
command below. It usually takes a couple of minutes.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
kubectl get service
|
||||
|
||||
Once the IP is allocated, visit the IP in a browser and it should open the
|
||||
Console.
|
||||
console.
|
||||
|
||||
Troubleshooting
|
||||
---------------
|
||||
|
||||
Check the status for pods to see if they are running. If there are any errors,
|
||||
check the logs for GraphQL Engine:
|
||||
check the logs of the GraphQL engine:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@ -195,13 +195,13 @@ You might also want to check the logs for cloudsql-proxy:
|
||||
|
||||
kubectl logs deployment/hasura -c cloudsql-proxy
|
||||
|
||||
The username password used by Hasura to connect to the database comes from a
|
||||
The username and password used by Hasura to connect to the database comes from a
|
||||
Kubernetes secret object ``cloudsql-db-credentials`` that we created earlier.
|
||||
|
||||
Tearing down
|
||||
------------
|
||||
|
||||
To clean-up the resources created, just delete the Google Cloud Project:
|
||||
To clean up the resources created, just delete the Google Cloud Project:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
|
@ -8,13 +8,13 @@ Guides: Deployment
|
||||
|
||||
- :doc:`Digital Ocean One-click App on Marketplace <digital-ocean-one-click>`
|
||||
- :doc:`Azure Container Instances with Postgres <azure-container-instances-postgres>`
|
||||
- :doc:`Google Cloud Platform with Kubernetes Engine and Cloud SQL <google-kubernetes-engine-cloud-sql>`
|
||||
- :doc:`Google Cloud Platform with Kubernetes engine and Cloud SQL <google-kubernetes-engine-cloud-sql>`
|
||||
- `Blog: Instant GraphQL on AWS RDS <https://blog.hasura.io/instant-graphql-on-aws-rds-1edfb85b5985>`__
|
||||
|
||||
.. note::
|
||||
The above are guides to deploy Hasura GraphQL engine on some specific platforms.
|
||||
The above are guides to deploy the Hasura GraphQL engine on some specific platforms.
|
||||
|
||||
For more generic guides, see :doc:`../../deployment/index`
|
||||
For more generic guides, see :doc:`../../deployment/index`.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
@ -23,5 +23,5 @@ Guides: Deployment
|
||||
|
||||
DigitalOcean One-click App on Marketplace <digital-ocean-one-click>
|
||||
Azure Container Instances with Postgres <azure-container-instances-postgres>
|
||||
Google Cloud Platform with Kubernetes Engine and Cloud SQL <google-kubernetes-engine-cloud-sql>
|
||||
Google Cloud Platform with Kubernetes engine and Cloud SQL <google-kubernetes-engine-cloud-sql>
|
||||
|
||||
|
@ -33,7 +33,7 @@ Once these packages are installed, import them as follows in the file where you
|
||||
import { InMemoryCache } from 'apollo-cache-inmemory';
|
||||
|
||||
|
||||
below these imports initialise your client to fetch subscriptions along with query and mutation.
|
||||
Below these imports initialise your client to fetch subscriptions along with query and mutation.
|
||||
|
||||
.. code-block:: js
|
||||
|
||||
@ -131,7 +131,7 @@ care of when switching to subscriptions.
|
||||
.. admonition:: Caveat
|
||||
|
||||
If all the 3 changes are not made, **it works like a query instead of a subscription**
|
||||
since, the code that sets up apollo-link doesn't work.
|
||||
since the code that sets up apollo-link doesn't work.
|
||||
|
||||
.. code-block:: js
|
||||
|
||||
|
@ -8,15 +8,15 @@ Auth0 JWT Integration with Hasura GraphQL engine
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
In this guide, we will walk-through on how to set up Auth0 to work with Hasura GraphQL engine.
|
||||
In this guide, we will walk through how to set up Auth0 to work with the Hasura GraphQL engine.
|
||||
|
||||
Create an Auth0 Application
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
- Navigate to the `Auth0 dashboard <https://manage.auth0.com>`__
|
||||
- Navigate to the `Auth0 dashboard <https://manage.auth0.com>`__.
|
||||
- Click on the ``Applications`` menu option on the left and then click the ``+ Create Application`` button.
|
||||
- In the ``Create Application`` window, set a name for your application and select ``Single Page Web Applications``.
|
||||
(Assuming your application is React/Angular/Vue etc).
|
||||
- In the ``Create Application`` window, set a name for your application and select ``Single Page Web Applications``
|
||||
(assuming your application is React/Angular/Vue etc).
|
||||
|
||||
.. thumbnail:: ../../../../img/graphql/manual/guides/create-client-popup.png
|
||||
|
||||
@ -24,7 +24,7 @@ Configure Auth0 Rules & Callback URLs
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
In the settings of the application, add appropriate (e.g: http://localhost:3000/callback) URLs as ``Allowed Callback
|
||||
URLs`` and ``Allowed Web Origins``. Add domain specific URLs as well for production apps. (e.g: https://myapp.com/callback)
|
||||
URLs`` and ``Allowed Web Origins``. Add domain specific URLs as well for production apps (e.g: https://myapp.com/callback).
|
||||
|
||||
In the dashboard, navigate to ``Rules``. Add the following rules to add our custom JWT claims:
|
||||
|
||||
@ -48,12 +48,12 @@ In the dashboard, navigate to ``Rules``. Add the following rules to add our cust
|
||||
Test auth0 login and generate sample JWTs for testing
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
You don't need to integrate your UI with auth0 for testing. You call follow the steps below:
|
||||
You don't need to integrate your UI with auth0 for testing. You can follow the steps below:
|
||||
|
||||
1. Login to your auth0 app by heading to this URL: ``https://<auth0-domain>.auth0.com/login?client=<client_id>&protocol=oauth2&response_type=token%20id_token&redirect_uri=<callback_uri>&scope=openid%20profile``
|
||||
1. Login to your auth0 app by heading to this URL: ``https://<auth0-domain>.auth0.com/login?client=<client_id>&protocol=oauth2&response_type=token%20id_token&redirect_uri=<callback_uri>&scope=openid%20profile``.
|
||||
|
||||
- Replace ``<auth0-domain>`` with your auth0 app domain.
|
||||
- Replace ``<client-id>`` with your auth0 app client id. Get your client id from app settings page on the auth0 dashboard.
|
||||
- Replace ``<client-id>`` with your auth0 app client id. Get your client id from the app settings page on the auth0 dashboard.
|
||||
- Replace ``callback_uri`` with ``https://localhost:3000/callback`` or the URL you entered above. Note that this URL doesn't really need to exist while you are testing.
|
||||
|
||||
2. Once you head to this login page you should see the auth0 login page that you can login with.
|
||||
@ -74,7 +74,7 @@ You don't need to integrate your UI with auth0 for testing. You call follow the
|
||||
:class: no-shadow
|
||||
:alt: JWT from id_token query param
|
||||
|
||||
5. To test this JWT, and to see if all the Hasura claims are added as per the sections above, lets test this out with `jwt.io <https://jwt.io>`__!
|
||||
5. To test this JWT, and to see if all the Hasura claims are added as per the sections above, let's test this out with `jwt.io <https://jwt.io>`__!
|
||||
|
||||
.. image:: https://graphql-engine-cdn.hasura.io/img/jwt-io-debug.png
|
||||
:class: no-shadow
|
||||
@ -132,7 +132,7 @@ An easier way to generate the above config is to use the following UI:
|
||||
https://hasura.io/jwt-config.
|
||||
|
||||
The generated config can be used in env ``HASURA_GRAPHQL_JWT_SECRET`` or ``--jwt-secret`` flag.
|
||||
The config generated from this page can be directly pasted in yaml files and command line arguments as it takes care of
|
||||
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
|
||||
@ -142,13 +142,13 @@ escaping new lines.
|
||||
Add Access Control Rules via Hasura Console
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Auth0 is configured and ready to be used in the application. You can now setup access control rules that
|
||||
Auth0 is configured and ready to be used in the application. You can now set up access control rules that
|
||||
will automatically get applied whenever a client makes a graphql query with the Auth0 token.
|
||||
|
||||
Refer :doc:`../../auth/authorization/basics` for more information.
|
||||
Refer to :doc:`../../auth/authorization/basics` for more information.
|
||||
|
||||
To test this out, add an access control rule that uses ``x-hasura-user-id`` for the role ``user``.
|
||||
Then make a GraphQL query or a mutation, with the Authorization token from the :ref:`previous step <test-auth0>`
|
||||
Then make a GraphQL query or a mutation, with the authorization token from the :ref:`previous step <test-auth0>`
|
||||
where we generated an Auth0 token.
|
||||
|
||||
.. image:: https://graphql-engine-cdn.hasura.io/img/jwt-header-auth-hasura.png
|
||||
|
@ -8,10 +8,10 @@ Guides: Integration/migration tutorials
|
||||
|
||||
- :doc:`auth0-jwt`
|
||||
- :doc:`apollo-subscriptions`
|
||||
- `Blog: Move from firebase to realtime GraphQL on Postgres <https://blog.hasura.io/firebase2graphql-moving-from-firebase-to-realtime-graphql-on-postgres-4d36cb7f4eaf>`__.
|
||||
- `Blog: Create a Gatsby site using GraphQL on Postgres <https://blog.hasura.io/create-gatsby-sites-using-graphql-on-postgres-603b5dd1e516>`__.
|
||||
- `Blog: Instant GraphQL on AWS RDS <https://blog.hasura.io/instant-graphql-on-aws-rds-1edfb85b5985>`__.
|
||||
- `Blog: Using TimescaleDB with Hasura GraphQL <https://blog.hasura.io/using-timescaledb-with-hasura-graphql-d05f030c4b10>`__.
|
||||
- `Blog: Move from firebase to realtime GraphQL on Postgres <https://blog.hasura.io/firebase2graphql-moving-from-firebase-to-realtime-graphql-on-postgres-4d36cb7f4eaf>`__
|
||||
- `Blog: Create a Gatsby site using GraphQL on Postgres <https://blog.hasura.io/create-gatsby-sites-using-graphql-on-postgres-603b5dd1e516>`__
|
||||
- `Blog: Instant GraphQL on AWS RDS <https://blog.hasura.io/instant-graphql-on-aws-rds-1edfb85b5985>`__
|
||||
- `Blog: Using TimescaleDB with Hasura GraphQL <https://blog.hasura.io/using-timescaledb-with-hasura-graphql-d05f030c4b10>`__
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
@ -6,8 +6,8 @@ Guides: Integrating with monitoring frameworks
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
The following demonstrate integrating Hasura GraphQL engine logs with some external
|
||||
The following posts demonstrate integrating the Hasura GraphQL engine logs with some external
|
||||
monitoring frameworks:
|
||||
|
||||
- `Blog: GraphQL Observability with Hasura GraphQL Engine and Honeycomb <https://blog.hasura.io/graphql-observability-with-hasura-graphql-engine-and-honeycomb-ee0a1a836c41>`__
|
||||
- `Blog: Uptime Monitoring for Hasura GraphQL Engine with DataDog on GKE <https://blog.hasura.io/uptime-monitoring-for-hasura-graphql-engine-with-datadog-on-gke-4faff5832e7f>`__
|
||||
- `Blog: GraphQL Observability with Hasura GraphQL engine and Honeycomb <https://blog.hasura.io/graphql-observability-with-hasura-graphql-engine-and-honeycomb-ee0a1a836c41>`__
|
||||
- `Blog: Uptime Monitoring for Hasura GraphQL engine with DataDog on GKE <https://blog.hasura.io/uptime-monitoring-for-hasura-graphql-engine-with-datadog-on-gke-4faff5832e7f>`__
|
||||
|
@ -62,4 +62,4 @@ Videos
|
||||
Boilerplates
|
||||
------------
|
||||
|
||||
For boilerplates, please check our community wiki on `Github <https://github.com/hasura/graphql-engine/wiki/Community#tools-and-boilerplates>`__.
|
||||
For boilerplates, please check our community wiki on `Github <https://github.com/hasura/graphql-engine/wiki/Community#tools-and-boilerplates>`__.
|
||||
|
@ -8,7 +8,7 @@ Telemetry Guide/FAQ
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
The Hasura GraphQL Engine collects anonymous telemetry data that helps the
|
||||
The Hasura GraphQL engine collects anonymous telemetry data that helps the
|
||||
Hasura team in understanding how the product is being used and in deciding
|
||||
what to focus on next.
|
||||
|
||||
@ -32,7 +32,7 @@ Server
|
||||
|
||||
The server periodically sends the number of tables, views, relationships,
|
||||
permission rules, custom SQL functions, event triggers and remote schemas
|
||||
tracked by GraphQL Engine, along with randomly generated UUID per database and
|
||||
tracked by the GraphQL engine, along with randomly generated UUIDs per database and
|
||||
per instance. The name of the current continuous integration environment
|
||||
(if any) and the server version is also sent.
|
||||
|
||||
@ -90,7 +90,7 @@ Here is a sample:
|
||||
"cli_uuid": null
|
||||
}
|
||||
|
||||
Please note, that ``TABLE_NAME`` and ``SCHEMA_NAME`` are not placeholders.
|
||||
Please note that ``TABLE_NAME`` and ``SCHEMA_NAME`` are not placeholders.
|
||||
The actual names of the tables, schemas, remote-schemas and event-triggers that
|
||||
are a part of the URL are not sent.
|
||||
|
||||
@ -100,7 +100,7 @@ CLI
|
||||
The CLI collects each execution event, along with a randomly generated UUID.
|
||||
The execution event contains the command name, timestamp and whether the
|
||||
execution resulted in an error or not. **Error messages, arguments and flags
|
||||
are not recorded**. CLI also collects the server version and UUID that it
|
||||
are not recorded**. The CLI also collects the server version and UUID that it
|
||||
is talking to. The operating system platform and architecture is also
|
||||
noted along with the CLI version.
|
||||
|
||||
@ -133,7 +133,7 @@ The data is sent to Hasura's servers addressed by ``telemetry.hasura.io``.
|
||||
How do I turn off telemetry (opt-out)?
|
||||
--------------------------------------
|
||||
|
||||
You can turn off telemetry on the server and on the console hosted by server
|
||||
You can turn off telemetry on the server and on the console hosted by the server
|
||||
by setting the following environment variable on the server or by using
|
||||
the flag ``--enable-telemetry=false``:
|
||||
|
||||
@ -141,7 +141,7 @@ the flag ``--enable-telemetry=false``:
|
||||
|
||||
HASURA_GRAPHQL_ENABLE_TELEMETRY=false
|
||||
|
||||
In order to turn off telemetry on CLI and on the console served by CLI,
|
||||
In order to turn off telemetry on the CLI and on the console served by the CLI,
|
||||
you can set the same environment varibale on the machine running CLI.
|
||||
You can also set ``"enable_telemetry": false`` in the JSON file created
|
||||
by the CLI at ``~/.hasura/config.json`` to perisist the setting.
|
||||
|
@ -3,7 +3,7 @@
|
||||
Hasura CLI: hasura
|
||||
------------------
|
||||
|
||||
Hasura GraphQL Engine command line tool
|
||||
Hasura GraphQL engine command line tool.
|
||||
|
||||
Synopsis
|
||||
~~~~~~~~
|
||||
@ -37,10 +37,10 @@ SEE ALSO
|
||||
|
||||
* :ref:`hasura completion <hasura_completion>` - Generate auto completion code
|
||||
* :ref:`hasura console <hasura_console>` - Open console to manage database and try out APIs
|
||||
* :ref:`hasura init <hasura_init>` - Initialize directory for Hasura GraphQL Engine migrations
|
||||
* :ref:`hasura metadata <hasura_metadata>` - Manage Hasura GraphQL Engine metadata saved in the database
|
||||
* :ref:`hasura init <hasura_init>` - Initialize directory for Hasura GraphQL engine migrations
|
||||
* :ref:`hasura metadata <hasura_metadata>` - Manage Hasura GraphQL engine metadata saved in the database
|
||||
* :ref:`hasura migrate <hasura_migrate>` - Manage migrations on the database
|
||||
* :ref:`hasura update-cli <hasura_update-cli>` - Update the CLI to latest version
|
||||
* :ref:`hasura update-cli <hasura_update-cli>` - Update the CLI to the latest version
|
||||
* :ref:`hasura version <hasura_version>` - Print the CLI version
|
||||
|
||||
*Auto generated by spf13/cobra*
|
||||
|
@ -3,13 +3,13 @@
|
||||
Hasura CLI: hasura completion
|
||||
-----------------------------
|
||||
|
||||
Generate auto completion code
|
||||
Generate auto completion code.
|
||||
|
||||
Synopsis
|
||||
~~~~~~~~
|
||||
|
||||
|
||||
Output shell completion code for the specified shell (bash or zsh)
|
||||
Output shell completion code for the specified shell (bash or zsh).
|
||||
|
||||
::
|
||||
|
||||
@ -70,6 +70,6 @@ Options inherited from parent commands
|
||||
SEE ALSO
|
||||
~~~~~~~~
|
||||
|
||||
* :ref:`hasura <hasura>` - Hasura GraphQL Engine command line tool
|
||||
* :ref:`hasura <hasura>` - Hasura GraphQL engine command line tool
|
||||
|
||||
*Auto generated by spf13/cobra*
|
||||
|
@ -3,13 +3,13 @@
|
||||
Hasura CLI: hasura console
|
||||
--------------------------
|
||||
|
||||
Open console to manage database and try out APIs
|
||||
Open the console to manage the database and try out APIs.
|
||||
|
||||
Synopsis
|
||||
~~~~~~~~
|
||||
|
||||
|
||||
Run a web server to serve Hasura Console for GraphQL Engine to manage database and build queries
|
||||
Run a web server to serve the Hasura console for the GraphQL engine to manage the database and build queries.
|
||||
|
||||
::
|
||||
|
||||
@ -32,10 +32,10 @@ Options
|
||||
::
|
||||
|
||||
--address string address to serve console and migration API from (default "localhost")
|
||||
--admin-secret string admin secret for Hasura GraphQL Engine
|
||||
--admin-secret string admin secret for Hasura GraphQL engine
|
||||
--api-port string port for serving migrate api (default "9693")
|
||||
--console-port string port for serving console (default "9695")
|
||||
--endpoint string http(s) endpoint for Hasura GraphQL Engine
|
||||
--endpoint string http(s) endpoint for Hasura GraphQL engine
|
||||
-h, --help help for console
|
||||
--no-browser do not automatically open console in browser
|
||||
--static-dir string directory where static assets mentioned in the console html template can be served from
|
||||
@ -52,6 +52,6 @@ Options inherited from parent commands
|
||||
SEE ALSO
|
||||
~~~~~~~~
|
||||
|
||||
* :ref:`hasura <hasura>` - Hasura GraphQL Engine command line tool
|
||||
* :ref:`hasura <hasura>` - Hasura GraphQL engine command line tool
|
||||
|
||||
*Auto generated by spf13/cobra*
|
||||
|
@ -3,13 +3,13 @@
|
||||
Hasura CLI: hasura init
|
||||
-----------------------
|
||||
|
||||
Initialize directory for Hasura GraphQL Engine migrations
|
||||
Initialize a directory for Hasura GraphQL engine migrations.
|
||||
|
||||
Synopsis
|
||||
~~~~~~~~
|
||||
|
||||
|
||||
Create directories and files required for enabling migrations on Hasura GraphQL Engine
|
||||
Create directories and files required for enabling migrations on the Hasura GraphQL engine.
|
||||
|
||||
::
|
||||
|
||||
@ -35,9 +35,9 @@ Options
|
||||
|
||||
::
|
||||
|
||||
--admin-secret string admin secret for Hasura GraphQL Engine
|
||||
--admin-secret string admin secret for Hasura GraphQL engine
|
||||
--directory string name of directory where files will be created
|
||||
--endpoint string http(s) endpoint for Hasura GraphQL Engine
|
||||
--endpoint string http(s) endpoint for Hasura GraphQL engine
|
||||
-h, --help help for init
|
||||
|
||||
Options inherited from parent commands
|
||||
@ -52,6 +52,6 @@ Options inherited from parent commands
|
||||
SEE ALSO
|
||||
~~~~~~~~
|
||||
|
||||
* :ref:`hasura <hasura>` - Hasura GraphQL Engine command line tool
|
||||
* :ref:`hasura <hasura>` - Hasura GraphQL engine command line tool
|
||||
|
||||
*Auto generated by spf13/cobra*
|
||||
|
@ -3,13 +3,13 @@
|
||||
Hasura CLI: hasura metadata
|
||||
---------------------------
|
||||
|
||||
Manage Hasura GraphQL Engine metadata saved in the database
|
||||
Manage Hasura GraphQL engine metadata saved in the database.
|
||||
|
||||
Synopsis
|
||||
~~~~~~~~
|
||||
|
||||
|
||||
Manage Hasura GraphQL Engine metadata saved in the database
|
||||
Manage Hasura GraphQL engine metadata saved in the database.
|
||||
|
||||
Options
|
||||
~~~~~~~
|
||||
@ -30,10 +30,10 @@ Options inherited from parent commands
|
||||
SEE ALSO
|
||||
~~~~~~~~
|
||||
|
||||
* :ref:`hasura <hasura>` - Hasura GraphQL Engine command line tool
|
||||
* :ref:`hasura <hasura>` - Hasura GraphQL engine command line tool
|
||||
* :ref:`hasura metadata apply <hasura_metadata_apply>` - Apply Hasura metadata on a database
|
||||
* :ref:`hasura metadata clear <hasura_metadata_clear>` - Clear Hasura GraphQL Engine metadata on the database
|
||||
* :ref:`hasura metadata export <hasura_metadata_export>` - Export Hasura GraphQL Engine metadata from the database
|
||||
* :ref:`hasura metadata reload <hasura_metadata_reload>` - Reload Hasura GraphQL Engine metadata on the database
|
||||
* :ref:`hasura metadata clear <hasura_metadata_clear>` - Clear Hasura GraphQL engine metadata on the database
|
||||
* :ref:`hasura metadata export <hasura_metadata_export>` - Export Hasura GraphQL engine metadata from the database
|
||||
* :ref:`hasura metadata reload <hasura_metadata_reload>` - Reload Hasura GraphQL engine metadata on the database
|
||||
|
||||
*Auto generated by spf13/cobra*
|
||||
|
@ -3,13 +3,13 @@
|
||||
Hasura CLI: hasura metadata apply
|
||||
---------------------------------
|
||||
|
||||
Apply Hasura metadata on a database
|
||||
Apply Hasura metadata on a database.
|
||||
|
||||
Synopsis
|
||||
~~~~~~~~
|
||||
|
||||
|
||||
Apply Hasura metadata on a database
|
||||
Apply Hasura metadata on a database.
|
||||
|
||||
::
|
||||
|
||||
@ -20,7 +20,7 @@ Examples
|
||||
|
||||
::
|
||||
|
||||
# Apply Hasura GraphQL Engine metadata present in metadata.[yaml|json] file:
|
||||
# Apply Hasura GraphQL engine metadata present in metadata.[yaml|json] file:
|
||||
hasura metadata apply
|
||||
|
||||
Options
|
||||
@ -28,8 +28,8 @@ Options
|
||||
|
||||
::
|
||||
|
||||
--admin-secret string admin secret for Hasura GraphQL Engine
|
||||
--endpoint string http(s) endpoint for Hasura GraphQL Engine
|
||||
--admin-secret string admin secret for Hasura GraphQL engine
|
||||
--endpoint string http(s) endpoint for Hasura GraphQL engine
|
||||
-h, --help help for apply
|
||||
|
||||
Options inherited from parent commands
|
||||
@ -44,6 +44,6 @@ Options inherited from parent commands
|
||||
SEE ALSO
|
||||
~~~~~~~~
|
||||
|
||||
* :ref:`hasura metadata <hasura_metadata>` - Manage Hasura GraphQL Engine metadata saved in the database
|
||||
* :ref:`hasura metadata <hasura_metadata>` - Manage Hasura GraphQL engine metadata saved in the database
|
||||
|
||||
*Auto generated by spf13/cobra*
|
||||
|
@ -3,13 +3,13 @@
|
||||
Hasura CLI: hasura metadata clear
|
||||
---------------------------------
|
||||
|
||||
Clear Hasura GraphQL Engine metadata on the database
|
||||
Clear Hasura GraphQL engine metadata on the database.
|
||||
|
||||
Synopsis
|
||||
~~~~~~~~
|
||||
|
||||
|
||||
Clear Hasura GraphQL Engine metadata on the database
|
||||
Clear Hasura GraphQL engine metadata on the database.
|
||||
|
||||
::
|
||||
|
||||
@ -30,8 +30,8 @@ Options
|
||||
|
||||
::
|
||||
|
||||
--admin-secret string admin secret for Hasura GraphQL Engine
|
||||
--endpoint string http(s) endpoint for Hasura GraphQL Engine
|
||||
--admin-secret string admin secret for Hasura GraphQL engine
|
||||
--endpoint string http(s) endpoint for Hasura GraphQL engine
|
||||
-h, --help help for clear
|
||||
|
||||
Options inherited from parent commands
|
||||
@ -46,6 +46,6 @@ Options inherited from parent commands
|
||||
SEE ALSO
|
||||
~~~~~~~~
|
||||
|
||||
* :ref:`hasura metadata <hasura_metadata>` - Manage Hasura GraphQL Engine metadata saved in the database
|
||||
* :ref:`hasura metadata <hasura_metadata>` - Manage Hasura GraphQL engine metadata saved in the database
|
||||
|
||||
*Auto generated by spf13/cobra*
|
||||
|
@ -3,15 +3,15 @@
|
||||
Hasura CLI: hasura metadata export
|
||||
----------------------------------
|
||||
|
||||
Export Hasura GraphQL Engine metadata from the database
|
||||
Export Hasura GraphQL engine metadata from the database
|
||||
|
||||
Synopsis
|
||||
~~~~~~~~
|
||||
|
||||
|
||||
Export Hasura metadata and save it in migrations/metadata.yaml file.
|
||||
Export Hasura metadata and save it in the ``migrations/metadata.yaml`` file.
|
||||
The output is a yaml file which captures all the metadata required
|
||||
by GraphQL Engine. This includes info about tables that are tracked,
|
||||
by the GraphQL engine. This includes info about tables that are tracked,
|
||||
permission rules, relationships and event triggers that are defined
|
||||
on those tables.
|
||||
|
||||
@ -32,8 +32,8 @@ Options
|
||||
|
||||
::
|
||||
|
||||
--admin-secret string admin secret for Hasura GraphQL Engine
|
||||
--endpoint string http(s) endpoint for Hasura GraphQL Engine
|
||||
--admin-secret string admin secret for Hasura GraphQL engine
|
||||
--endpoint string http(s) endpoint for Hasura GraphQL engine
|
||||
-h, --help help for export
|
||||
|
||||
Options inherited from parent commands
|
||||
@ -48,6 +48,6 @@ Options inherited from parent commands
|
||||
SEE ALSO
|
||||
~~~~~~~~
|
||||
|
||||
* :ref:`hasura metadata <hasura_metadata>` - Manage Hasura GraphQL Engine metadata saved in the database
|
||||
* :ref:`hasura metadata <hasura_metadata>` - Manage Hasura GraphQL engine metadata saved in the database
|
||||
|
||||
*Auto generated by spf13/cobra*
|
||||
|
@ -3,13 +3,13 @@
|
||||
Hasura CLI: hasura metadata reload
|
||||
----------------------------------
|
||||
|
||||
Reload Hasura GraphQL Engine metadata on the database
|
||||
Reload Hasura GraphQL engine metadata on the database.
|
||||
|
||||
Synopsis
|
||||
~~~~~~~~
|
||||
|
||||
|
||||
Reload Hasura GraphQL Engine metadata on the database
|
||||
Reload Hasura GraphQL engine metadata on the database.
|
||||
|
||||
::
|
||||
|
||||
@ -28,8 +28,8 @@ Options
|
||||
|
||||
::
|
||||
|
||||
--admin-secret string admin secret for Hasura GraphQL Engine
|
||||
--endpoint string http(s) endpoint for Hasura GraphQL Engine
|
||||
--admin-secret string admin secret for Hasura GraphQL engine
|
||||
--endpoint string http(s) endpoint for Hasura GraphQL engine
|
||||
-h, --help help for reload
|
||||
|
||||
Options inherited from parent commands
|
||||
@ -44,6 +44,6 @@ Options inherited from parent commands
|
||||
SEE ALSO
|
||||
~~~~~~~~
|
||||
|
||||
* :ref:`hasura metadata <hasura_metadata>` - Manage Hasura GraphQL Engine metadata saved in the database
|
||||
* :ref:`hasura metadata <hasura_metadata>` - Manage Hasura GraphQL engine metadata saved in the database
|
||||
|
||||
*Auto generated by spf13/cobra*
|
||||
|
@ -3,13 +3,13 @@
|
||||
Hasura CLI: hasura migrate
|
||||
--------------------------
|
||||
|
||||
Manage migrations on the database
|
||||
Manage migrations on the database.
|
||||
|
||||
Synopsis
|
||||
~~~~~~~~
|
||||
|
||||
|
||||
Manage migrations on the database
|
||||
Manage migrations on the database.
|
||||
|
||||
Options
|
||||
~~~~~~~
|
||||
@ -30,7 +30,7 @@ Options inherited from parent commands
|
||||
SEE ALSO
|
||||
~~~~~~~~
|
||||
|
||||
* :ref:`hasura <hasura>` - Hasura GraphQL Engine command line tool
|
||||
* :ref:`hasura <hasura>` - Hasura GraphQL engine command line tool
|
||||
* :ref:`hasura migrate apply <hasura_migrate_apply>` - Apply migrations on the database
|
||||
* :ref:`hasura migrate create <hasura_migrate_create>` - Create files required for a migration
|
||||
* :ref:`hasura migrate status <hasura_migrate_status>` - Display current status of migrations on a database
|
||||
|
@ -3,13 +3,13 @@
|
||||
Hasura CLI: hasura migrate apply
|
||||
--------------------------------
|
||||
|
||||
Apply migrations on the database
|
||||
Apply migrations on the database.
|
||||
|
||||
Synopsis
|
||||
~~~~~~~~
|
||||
|
||||
|
||||
Apply migrations on the database
|
||||
Apply migrations on the database.
|
||||
|
||||
::
|
||||
|
||||
@ -20,9 +20,9 @@ Options
|
||||
|
||||
::
|
||||
|
||||
--admin-secret string admin secret for Hasura GraphQL Engine
|
||||
--admin-secret string admin secret for Hasura GraphQL engine
|
||||
--down string apply all or N down migration steps
|
||||
--endpoint string http(s) endpoint for Hasura GraphQL Engine
|
||||
--endpoint string http(s) endpoint for Hasura GraphQL engine
|
||||
-h, --help help for apply
|
||||
--skip-execution skip executing the migration action, but mark them as applied
|
||||
--type string type of migration (up, down) to be used with version flag (default "up")
|
||||
|
@ -3,13 +3,13 @@
|
||||
Hasura CLI: hasura migrate create
|
||||
---------------------------------
|
||||
|
||||
Create files required for a migration
|
||||
Create files required for a migration.
|
||||
|
||||
Synopsis
|
||||
~~~~~~~~
|
||||
|
||||
|
||||
Create sql and yaml files required for a migration
|
||||
Create ``sql`` and ``yaml`` files required for a migration.
|
||||
|
||||
::
|
||||
|
||||
@ -20,8 +20,8 @@ Options
|
||||
|
||||
::
|
||||
|
||||
--admin-secret string admin secret for Hasura GraphQL Engine
|
||||
--endpoint string http(s) endpoint for Hasura GraphQL Engine
|
||||
--admin-secret string admin secret for Hasura GraphQL engine
|
||||
--endpoint string http(s) endpoint for Hasura GraphQL engine
|
||||
-h, --help help for create
|
||||
--metadata-from-file string path to a hasura metadata file to be used for up actions
|
||||
--metadata-from-server take metadata from the server and write it as an up migration file
|
||||
|
@ -3,13 +3,13 @@
|
||||
Hasura CLI: hasura migrate status
|
||||
---------------------------------
|
||||
|
||||
Display current status of migrations on a database
|
||||
Display current status of migrations on a database.
|
||||
|
||||
Synopsis
|
||||
~~~~~~~~
|
||||
|
||||
|
||||
Display current status of migrations on a database
|
||||
Display current status of migrations on a database.
|
||||
|
||||
::
|
||||
|
||||
@ -20,8 +20,8 @@ Options
|
||||
|
||||
::
|
||||
|
||||
--admin-secret string admin secret for Hasura GraphQL Engine
|
||||
--endpoint string http(s) endpoint for Hasura GraphQL Engine
|
||||
--admin-secret string admin secret for Hasura GraphQL engine
|
||||
--endpoint string http(s) endpoint for Hasura GraphQL engine
|
||||
-h, --help help for status
|
||||
|
||||
Options inherited from parent commands
|
||||
|
@ -3,13 +3,13 @@
|
||||
Hasura CLI: hasura update-cli
|
||||
-----------------------------
|
||||
|
||||
Update the CLI to latest version
|
||||
Update the CLI to the latest version.
|
||||
|
||||
Synopsis
|
||||
~~~~~~~~
|
||||
|
||||
|
||||
Update the CLI to latest version
|
||||
Update the CLI to the latest version.
|
||||
|
||||
::
|
||||
|
||||
@ -47,6 +47,6 @@ Options inherited from parent commands
|
||||
SEE ALSO
|
||||
~~~~~~~~
|
||||
|
||||
* :ref:`hasura <hasura>` - Hasura GraphQL Engine command line tool
|
||||
* :ref:`hasura <hasura>` - Hasura GraphQL engine command line tool
|
||||
|
||||
*Auto generated by spf13/cobra*
|
||||
|
@ -3,13 +3,13 @@
|
||||
Hasura CLI: hasura version
|
||||
--------------------------
|
||||
|
||||
Print the CLI version
|
||||
Print the CLI version.
|
||||
|
||||
Synopsis
|
||||
~~~~~~~~
|
||||
|
||||
|
||||
Print the CLI version
|
||||
Print the CLI version.
|
||||
|
||||
::
|
||||
|
||||
@ -34,6 +34,6 @@ Options inherited from parent commands
|
||||
SEE ALSO
|
||||
~~~~~~~~
|
||||
|
||||
* :ref:`hasura <hasura>` - Hasura GraphQL Engine command line tool
|
||||
* :ref:`hasura <hasura>` - Hasura GraphQL engine command line tool
|
||||
|
||||
*Auto generated by spf13/cobra*
|
||||
|
@ -68,6 +68,4 @@ Install
|
||||
(Optional) Add shell completion
|
||||
-------------------------------
|
||||
|
||||
To add command auto completion in the shell
|
||||
|
||||
Refer to :ref:`hasura completion <hasura_completion>`
|
||||
To add command auto completion in the shell, refer to :ref:`hasura completion <hasura_completion>`.
|
||||
|
@ -6,26 +6,26 @@ How Hasura GraphQL engine works
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
Given a Postgres database, Hasura GraphQL engine can automatically generate a GraphQL schema and process GraphQL
|
||||
queries, subscriptions and mutations. Here’s what Hasura GraphQL engine does under the hood.
|
||||
Given a Postgres database, the Hasura GraphQL engine can automatically generate a GraphQL schema and process GraphQL
|
||||
queries, subscriptions and mutations. Here’s what the Hasura GraphQL engine does under the hood.
|
||||
|
||||
Schema generation
|
||||
-----------------
|
||||
|
||||
Hasura GraphQL engine automatically generates GraphQL schema components when you track a
|
||||
The Hasura GraphQL engine automatically generates GraphQL schema components when you track a
|
||||
Postgres table/view in Hasura and create relationships between them.
|
||||
|
||||
Tables
|
||||
^^^^^^
|
||||
|
||||
When you track a Postgres table in Hasura GraphQL engine, it automatically generates the following for it:
|
||||
When you track a Postgres table in the Hasura GraphQL engine, it automatically generates the following for it:
|
||||
|
||||
- A GraphQL type definition for the table
|
||||
- A Query field with ``where``, ``order_by``, ``limit`` and ``offset`` arguments
|
||||
- A Subscription field with ``where``, ``order_by``, ``limit`` and ``offset`` arguments
|
||||
- An Insert mutation field with ``on_conflict`` argument that supports upsert and bulk inserts
|
||||
- An Update mutation field with ``where`` argument that supports bulk updates
|
||||
- A Delete mutation field with ``where`` argument that supports bulk deletes
|
||||
- A query field with ``where``, ``order_by``, ``limit`` and ``offset`` arguments
|
||||
- A subscription field with ``where``, ``order_by``, ``limit`` and ``offset`` arguments
|
||||
- An insert mutation field with ``on_conflict`` argument that supports upsert and bulk inserts
|
||||
- An update mutation field with ``where`` argument that supports bulk updates
|
||||
- A delete mutation field with ``where`` argument that supports bulk deletes
|
||||
|
||||
Views
|
||||
^^^^^
|
||||
@ -33,15 +33,15 @@ Views
|
||||
When you track a Postgres view in Hasura GraphQL engine, it automatically generates the following for it:
|
||||
|
||||
- A GraphQL type definition for the view
|
||||
- A Query field with ``where``, ``order_by``, ``limit`` and ``offset`` arguments
|
||||
- A Subscription field with ``where``, ``order_by``, ``limit`` and ``offset`` arguments
|
||||
- A query field with ``where``, ``order_by``, ``limit`` and ``offset`` arguments
|
||||
- A subscription field with ``where``, ``order_by``, ``limit`` and ``offset`` arguments
|
||||
|
||||
Essentially Hasura GraphQL engine does the same thing it would do for a table, but without creating the insert, update
|
||||
Essentially the Hasura GraphQL engine does the same thing it would do for a table, but without creating the insert, update
|
||||
and delete mutations.
|
||||
|
||||
Relationships
|
||||
^^^^^^^^^^^^^
|
||||
When you create a relationship between a table/view with another table/view in Hasura GraphQL engine, it does the
|
||||
When you create a relationship between a table/view with another table/view in the Hasura GraphQL engine, it does the
|
||||
following:
|
||||
|
||||
- Augments the type of the table/view by adding a reference to the nested type to allow fetching nested objects.
|
||||
@ -50,7 +50,8 @@ following:
|
||||
Resolvers
|
||||
---------
|
||||
|
||||
Hasura GraphQL engine does not have any resolvers. The Hasura GraphQL engine is actually a compiler that compiles your GraphQL query into an efficient SQL query.
|
||||
The Hasura GraphQL engine does not have any resolvers. The Hasura GraphQL engine is actually a compiler that compiles
|
||||
your GraphQL query into an efficient SQL query.
|
||||
|
||||
Hasura's GraphQL syntax is also optimized to expose the power of the underlying SQL so that you can make powerful
|
||||
queries via GraphQL.
|
||||
@ -58,11 +59,11 @@ queries via GraphQL.
|
||||
Metadata
|
||||
--------
|
||||
|
||||
All the information required for schema generation is stored by Hasura GraphQL engine as metadata in a specific
|
||||
All the information required for schema generation is stored by the Hasura GraphQL engine as metadata in a specific
|
||||
Postgres schema in the database. See :doc:`metadata schema <metadata-schema>` for more details.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:hidden:
|
||||
|
||||
Metadata schema <metadata-schema>
|
||||
Metadata schema <metadata-schema>
|
||||
|
@ -8,21 +8,21 @@ Hasura GraphQL engine metadata schema
|
||||
:depth: 2
|
||||
:local:
|
||||
|
||||
Hasura GraphQL engine uses a set of internal tables to manage the state of the database and the
|
||||
The Hasura GraphQL engine uses a set of internal tables to manage the state of the database and the
|
||||
GraphQL schema. It uses the data in these tables to generate the GraphQL API which then can be accessed
|
||||
from different clients.
|
||||
|
||||
Hasura GraphQL engine when initialized, creates a schema called ``hdb_catalog`` in the Postgres database and
|
||||
The Hasura GraphQL engine when initialized, creates a schema called ``hdb_catalog`` in the Postgres database and
|
||||
initializes a few tables under it as described below.
|
||||
|
||||
**hdb_catalog** schema
|
||||
----------------------
|
||||
|
||||
This schema is created by Hasura GraphQL Engine to manage its internal state. Whenever a
|
||||
table/permission/relationship is created/updated using the Hasura console or the metadata API. Hasura GraphQL engine
|
||||
This schema is created by the Hasura GraphQL engine to manage its internal state. Whenever a
|
||||
table/permission/relationship is created/updated using the Hasura console or the metadata API, the Hasura GraphQL engine
|
||||
captures that information and stores it in the corresponding tables.
|
||||
|
||||
The following tables are used by Hasura GraphQL engine:
|
||||
The following tables are used by the Hasura GraphQL engine:
|
||||
|
||||
**hdb_table** table
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
@ -1,6 +1,6 @@
|
||||
.. title:: Hasura GraphQL Engine Documentation
|
||||
.. title:: Hasura GraphQL engine Documentation
|
||||
|
||||
Hasura GraphQL Engine documentation
|
||||
Hasura GraphQL engine documentation
|
||||
===================================
|
||||
|
||||
.. contents:: Table of contents
|
||||
@ -8,7 +8,7 @@ Hasura GraphQL Engine documentation
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
The Hasura GraphQL engine lets you setup a GraphQL server and event triggers over a Postgres database in minutes.
|
||||
The Hasura GraphQL engine lets you set up a GraphQL server and event triggers over a Postgres database in minutes.
|
||||
|
||||
|
||||
.. toctree::
|
||||
|
@ -6,31 +6,31 @@ Rolling back applied migrations
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
If there is some issue with the migrations that are applied, you can
|
||||
rollback the database and Hasura metadata to a desired version using the
|
||||
If there are any issues with the migrations that are applied, you can
|
||||
roll back the database and Hasura metadata to a desired version using the
|
||||
``down`` migrations.
|
||||
|
||||
.. note::
|
||||
|
||||
Rollbacks will only work if there are ``down`` migrations defined. Console
|
||||
Rollbacks will only work if there are ``down`` migrations defined. The console
|
||||
will not generate ``down`` migrations for SQL statements executed from the
|
||||
``SQL`` tab, even though you can add them as an ``up`` migration.
|
||||
|
||||
Rollback also means applying down migrations. Here are some example scenarios:
|
||||
|
||||
To rollback all the applied migrations, execute:
|
||||
To roll back all the applied migrations, execute:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
hasura migrate apply --down
|
||||
|
||||
To rollback the last 2 migration versions:
|
||||
To roll back the last 2 migration versions:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
hasura migrate apply --down 2
|
||||
|
||||
To rollback a particular migration version:
|
||||
To roll back a particular migration version:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
|
@ -8,8 +8,8 @@ Writing migrations manually
|
||||
|
||||
While the Hasura Console can auto generate migrations for every action,
|
||||
sometimes you might want to write the migrations yourself, by hand. Using the
|
||||
Hasura CLI, you can bootstrap these migration files and write the SQL for
|
||||
Postgres Schema and YAML for Hasura metadata actions.
|
||||
Hasura CLI, you can bootstrap these migration files and write the SQL for the
|
||||
Postgres schema and YAML for Hasura metadata actions.
|
||||
|
||||
#. Set up the migration files:
|
||||
|
||||
|
@ -1,14 +1,14 @@
|
||||
.. _auto_apply_migrations:
|
||||
|
||||
Auto-apply migrations/metadata when server starts
|
||||
=================================================
|
||||
Auto-apply migrations/metadata when the server starts
|
||||
=====================================================
|
||||
|
||||
.. contents:: Table of contents
|
||||
:backlinks: none
|
||||
:depth: 1
|
||||
:local:
|
||||
|
||||
Hasura ships a special docker container which can be used to
|
||||
Hasura ships a special Docker container which can be used to
|
||||
automatically apply migrations/metadata when the server starts:
|
||||
|
||||
.. code-block:: bash
|
||||
@ -17,16 +17,16 @@ automatically apply migrations/metadata when the server starts:
|
||||
|
||||
.. note::
|
||||
|
||||
This container image includes Hasura CLI at ``/bin/hasura-cli`` and can be
|
||||
This container image includes the Hasura CLI at ``/bin/hasura-cli`` and can be
|
||||
used for running any other CI/CD scripts in your workflow.
|
||||
|
||||
Applying migrations
|
||||
-------------------
|
||||
|
||||
The ``migrations`` directory created by Hasura CLI (the one next to
|
||||
``config.yaml``) can be mounted at ``/hasura-migrations`` path of this docker
|
||||
The ``migrations`` directory created by the Hasura CLI (the one next to
|
||||
``config.yaml``) can be mounted at the ``/hasura-migrations`` path of this Docker
|
||||
container and the container's entry point script will apply the migrations before
|
||||
starting the server. If no directory is mounted at the designated path, server
|
||||
starting the server. If no directory is mounted at the designated path, the server
|
||||
will start ignoring migrations.
|
||||
|
||||
If you want to mount the migrations directory at some location other than
|
||||
@ -37,7 +37,7 @@ If you want to mount the migrations directory at some location other than
|
||||
HASURA_GRAPHQL_MIGRATIONS_DIR=/custom-path-for-migrations
|
||||
|
||||
Once the migrations are applied, the container resumes operation as a normal
|
||||
Hasura GraphQL Engine server.
|
||||
Hasura GraphQL engine server.
|
||||
|
||||
Example:
|
||||
|
||||
|
@ -10,16 +10,16 @@ This guide is to be followed if you already have set up a database and Hasura
|
||||
instance and now want to start using migrations to help you track the database
|
||||
and GraphQL schema changes.
|
||||
|
||||
Step 0: Disable console on Server
|
||||
---------------------------------
|
||||
Step 0: Disable console on the server
|
||||
-------------------------------------
|
||||
|
||||
To use migrations effectively, console on the Server (which is served at
|
||||
To use migrations effectively, the console on the server (which is served at
|
||||
``/console``) should be disabled and all changes must go through the console
|
||||
served by CLI. Otherwise, changes could be made through the server-console and
|
||||
served by CLI. Otherwise, changes could be made through the server console and
|
||||
they will not be tracked by migrations.
|
||||
|
||||
So, the first step is to disable console served by the GraphQL Engine server. In
|
||||
order to do that remove ``--enable-console`` flag from the command that starts
|
||||
So, the first step is to disable the console served by the GraphQL engine server. In
|
||||
order to do that, remove the ``--enable-console`` flag from the command that starts
|
||||
the server or set the following environment variable to false:
|
||||
|
||||
.. code-block:: bash
|
||||
@ -39,7 +39,7 @@ Follow the instructions in :ref:`install_hasura_cli`.
|
||||
Step 2: Set up a project directory
|
||||
----------------------------------
|
||||
|
||||
Execute the following command. For the endpoint referred here, let's say you've
|
||||
Execute the command below. For the endpoint referred here, let's say you've
|
||||
deployed the GraphQL engine on Heroku, then this endpoint is:
|
||||
``https://my-graphql.herokuapp.com``. In case you've deployed this using Docker,
|
||||
the URL might be ``http://xx.xx.xx.xx:8080``. This endpoint should not contain
|
||||
@ -53,21 +53,21 @@ sub-path if it is configured that way.
|
||||
cd my-project
|
||||
|
||||
This will create a new directory called ``my-project`` with a ``config.yaml``
|
||||
file and ``migrations`` directory. This directory structure is mandatory to use
|
||||
file and a ``migrations`` directory. This directory structure is mandatory to use
|
||||
Hasura migrations. You can commit this directory to version control.
|
||||
|
||||
.. note::
|
||||
|
||||
In case there is an admin secret set, you can set it as an environment
|
||||
variable ``HASURA_GRAPHQL_ADMIN_SECRET=<your-admin-secret>`` on the local
|
||||
machine and the the CLI will use it. You can also use it as a flag to CLI:
|
||||
machine and the CLI will use it. You can also use it as a flag to CLI:
|
||||
``--admin-secret '<your-admin-secret>'``.
|
||||
|
||||
Step 3: Initialize the migrations as per your current state
|
||||
-----------------------------------------------------------
|
||||
|
||||
Create a migration called ``init`` by exporting the current Postgres schema and
|
||||
metadata from server:
|
||||
metadata from the server:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@ -103,7 +103,7 @@ Step 4: Use the console from the CLI
|
||||
------------------------------------
|
||||
|
||||
From this point onwards, instead of using the console at
|
||||
``http://my-graphql.herokuapp.com/console`` you should use the console from CLI
|
||||
``http://my-graphql.herokuapp.com/console`` you should use the console from the CLI
|
||||
by running:
|
||||
|
||||
.. code-block:: bash
|
||||
@ -121,8 +121,8 @@ in the ``migrations/`` directory in your project.
|
||||
|
||||
Migrations are only created when using the console through CLI.
|
||||
|
||||
Step 6: Apply the migrations on another instance of GraphQL engine
|
||||
------------------------------------------------------------------
|
||||
Step 6: Apply the migrations on another instance of the GraphQL engine
|
||||
----------------------------------------------------------------------
|
||||
|
||||
Apply all migrations present in the ``migrations/`` directory on a new
|
||||
instance at ``http://another-graphql-instance.herokuapp.com``:
|
||||
@ -133,12 +133,12 @@ instance at ``http://another-graphql-instance.herokuapp.com``:
|
||||
hasura migrate apply --endpoint http://another-graphql-instance.herokuapp.com
|
||||
|
||||
In case you need an automated way of applying the migrations, take a look at the
|
||||
:doc:`CLI-Migrations <auto-apply-migrations>` docker image, which can start
|
||||
GraphQL Engine after automatically applying the migrations which are
|
||||
:doc:`CLI-Migrations <auto-apply-migrations>` Docker image, which can start the
|
||||
GraphQL engine after automatically applying the migrations which are
|
||||
mounted into a directory.
|
||||
|
||||
Step 7: Check status of migrations
|
||||
----------------------------------
|
||||
Step 7: Check the status of migrations
|
||||
--------------------------------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@ -158,13 +158,13 @@ For example,
|
||||
1550931962927 Present Present
|
||||
1550931970826 Present Present
|
||||
|
||||
Such a migration status indicate that there are 3 migration versions in the
|
||||
Such a migration status indicates that there are 3 migration versions in the
|
||||
local directory and all of them are applied on the database.
|
||||
|
||||
If ``SOURCE STATUS`` indicates ``Not Present``, it means that the migration
|
||||
version is present on the server, but not on the current user's local directory.
|
||||
This typically happens if multiple people are collaborating on a project and one
|
||||
of the collaborator forgot to pull the latest changes which included the latest
|
||||
of the collaborators forgot to pull the latest changes which included the latest
|
||||
migration files or another collaborator forgot to push the latest migration
|
||||
files that were applied on the database. Syncing of the files would fix the
|
||||
issue.
|
||||
|
@ -14,7 +14,7 @@ Introduction
|
||||
It is typical for developers to use some kind of "migration" tool to track
|
||||
changes to the Postgres schema. Usually the SQL statements used to create the
|
||||
tables, views etc. are stored as a single file or multiple files. Certain tools
|
||||
also let you add an "up" and a "down" step so that you can roll-back the
|
||||
also let you add an "up" and a "down" step so that you can roll back the
|
||||
changes.
|
||||
|
||||
When you connect Hasura to a Postgres database and use the console to "track" a
|
||||
@ -22,7 +22,7 @@ table, a piece of information is added to the Hasura "metadata" (configuration)
|
||||
indicating this table in Postgres should be exposed via GraphQL. Similarly,
|
||||
most of the actions on the console update the Hasura metadata.
|
||||
|
||||
In the development phase, you'll be using the Hasura Console to create and track
|
||||
In the development phase, you'll be using the Hasura console to create and track
|
||||
tables, create relationships, add permissions etc. When you need to move to a
|
||||
new environment, it will become quite hard to re-do all these operations using
|
||||
the console again on a fresh database. You might be looking for a way to export
|
||||
|
@ -1,6 +1,6 @@
|
||||
.. _manage_hasura_metadata:
|
||||
|
||||
Managing Hasura Metadata
|
||||
Managing Hasura metadata
|
||||
========================
|
||||
|
||||
.. contents:: Table of contents
|
||||
@ -9,16 +9,16 @@ Managing Hasura Metadata
|
||||
:local:
|
||||
|
||||
If your Postgres schema is already managed with a tool like knex, TypeORM,
|
||||
Django/Rails Migrations, you will still need a way to export the actions you
|
||||
Django/Rails migrations, you will still need a way to export the actions you
|
||||
performed on the Hasura console to apply it later on another Hasura instance.
|
||||
|
||||
All the actions performed on the console, like tracking tables/views/functions,
|
||||
creating relationships, configuring permissions, creating event triggers and remote
|
||||
schemas, etc. can be exported as a JSON file which can be version
|
||||
controlled. The contents of this JSON file is called "Hasura metadata". The
|
||||
controlled. The content of this JSON file is called "Hasura metadata". The
|
||||
metadata file can be later imported to another Hasura instance to get the same
|
||||
configuration. You can also manually edit the JSON file to add more objects to
|
||||
it and then use it update the instance.
|
||||
it and then use it to update the instance.
|
||||
|
||||
Exporting Hasura metadata
|
||||
-------------------------
|
||||
@ -28,8 +28,8 @@ Exporting Hasura metadata
|
||||
|
||||
.. tab:: Console
|
||||
|
||||
1. Click on the Settings gear icon at the top right corner of the console screen.
|
||||
2. In the Settings page that open, click on the ``Export Metadata`` button.
|
||||
1. Click on the settings (⚙) icon at the top right corner of the console screen.
|
||||
2. In the Hasura metadata actions page that opens, click on the ``Export Metadata`` button.
|
||||
3. This will prompt a file download for ``metadata.json``. Save the file.
|
||||
|
||||
.. tab:: API
|
||||
@ -47,19 +47,20 @@ Exporting Hasura metadata
|
||||
add ``-H 'X-Hasura-Admin-Secret: <your-admin-secret>'`` as the API is an
|
||||
admin-only API.
|
||||
|
||||
Importing Hasura Metadata
|
||||
Importing Hasura metadata
|
||||
-------------------------
|
||||
|
||||
The exported metadata can be imported on another instance of Hasura to replicate
|
||||
the metadata. The import can be done on the same instance and it will overwrite
|
||||
the existing metadata with that instance.
|
||||
You can apply exported metadata from one Hasura GraphQL engine instance to another. You can also apply an older or
|
||||
modified version of an instance's metadata onto itself.
|
||||
|
||||
Importing completely replaces the metadata on that instance. ie: you lose any metadata that was already present
|
||||
|
||||
.. rst-class:: api_tabs
|
||||
.. tabs::
|
||||
|
||||
.. tab:: Console
|
||||
|
||||
1. Click on the Settings gear icon at the top right corner of the console screen.
|
||||
1. Click on the settings (⚙) icon at the top right corner of the console screen.
|
||||
2. Click on ``Import Metadata`` button.
|
||||
3. Choose a ``metadata.json`` file that was exported earlier.
|
||||
4. A notification should appear indicating the success or error.
|
||||
@ -74,8 +75,8 @@ the existing metadata with that instance.
|
||||
|
||||
curl -d'{"type":"replace_metadata", "args":'$(cat metadata.json)'}' http://localhost:8080/v1/query
|
||||
|
||||
This command will read ``metadata.json`` file and makes a POST request to
|
||||
replace the metadata. If admin secret is set, add ``-H
|
||||
This command will read the ``metadata.json`` file and makes a POST request to
|
||||
replace the metadata. If an admin secret is set, add ``-H
|
||||
'X-Hasura-Admin-Secret: <your-admin-secret>'`` as the API is an admin-only
|
||||
API.
|
||||
|
||||
@ -89,5 +90,5 @@ the existing metadata with that instance.
|
||||
|
||||
The ``curl`` based API calls can be easily integrated with your CI/CD workflows.
|
||||
In case you need an automated way of applying/importing the metadata, take a
|
||||
look at the :doc:`CLI-Migrations <auto-apply-migrations>` docker image, which
|
||||
can start GraphQL Engine after automatically importing a mounted metadata file.
|
||||
look at the :doc:`CLI-Migrations <auto-apply-migrations>` Docker image, which
|
||||
can start the GraphQL engine after automatically importing a mounted metadata file.
|
||||
|
@ -1,6 +1,6 @@
|
||||
.. _postgres_schema_metadata:
|
||||
|
||||
Managing Postgres Schema and Hasura Metadata
|
||||
Managing Postgres schema and Hasura metadata
|
||||
============================================
|
||||
|
||||
.. contents:: Table of contents
|
||||
@ -15,7 +15,7 @@ modifying SQL statements, as YAML files. These files are called migrations and
|
||||
they can be applied and rolled back step-by-step. These files can be version
|
||||
controlled and can be used with your CI/CD system to make incremental updates.
|
||||
|
||||
When you're looking to setup migrations, there are two scenarios:
|
||||
When you're looking to set up migrations, there are two scenarios:
|
||||
|
||||
#. :doc:`You already have a database and Hasura setup <existing-database>`.
|
||||
#. :doc:`You're starting from scratch - an empty database and a fresh Hasura instance <new-database>`.
|
||||
|
@ -11,16 +11,16 @@ scratch. You can use migrations to help track the database and GraphQL schema
|
||||
changes.
|
||||
|
||||
|
||||
Step 0: Disable console on Server
|
||||
---------------------------------
|
||||
Step 0: Disable the console on the server
|
||||
-----------------------------------------
|
||||
|
||||
To use migrations effectively, console on the Server (which is served at
|
||||
To use migrations effectively, the console on the server (which is served at
|
||||
``/console``) should be disabled and all changes must go through the console
|
||||
served by CLI. Otherwise, changes could be made through the server-console and
|
||||
served by the CLI. Otherwise, changes could be made through the server console and
|
||||
they will not be tracked by migrations.
|
||||
|
||||
So, the first step is to disable console served by the GraphQL Engine server. In
|
||||
order to do that remove ``--enable-console`` flag from the command that starts
|
||||
So, the first step is to disable the console served by the GraphQL engine server. In
|
||||
order to do that, remove the ``--enable-console`` flag from the command that starts
|
||||
the server or set the following environment variable to false:
|
||||
|
||||
.. code-block:: bash
|
||||
@ -40,7 +40,7 @@ Follow the instructions in :ref:`install_hasura_cli`.
|
||||
Step 2: Set up a project directory
|
||||
----------------------------------
|
||||
|
||||
Execute the following command. For the endpoint referred here, let's say you've
|
||||
Execute the command below. For the endpoint referred here, let's say you've
|
||||
deployed the GraphQL engine on Heroku, then this endpoint is:
|
||||
``https://my-graphql.herokuapp.com``. In case you've deployed this using Docker,
|
||||
the URL might be ``http://xx.xx.xx.xx:8080``. This endpoint should not contain
|
||||
@ -54,18 +54,18 @@ sub-path if it is configured that way.
|
||||
cd my-project
|
||||
|
||||
This will create a new directory called ``my-project`` with a ``config.yaml``
|
||||
file and ``migrations`` directory. This directory structure is mandatory to use
|
||||
file and a ``migrations`` directory. This directory structure is mandatory to use
|
||||
Hasura migrations. You can commit this directory to version control.
|
||||
|
||||
.. note::
|
||||
|
||||
In case there is an admin secret set, you can set it as an environment
|
||||
variable ``HASURA_GRAPHQL_ADMIN_SECRET=<your-admin-secret`` on the local
|
||||
machine and the the CLI will use it. You can also use it as a flag to CLI:
|
||||
machine and the CLI will use it. You can also use it as a flag to CLI:
|
||||
``--admin-secret "<your-admin-secret>"``.
|
||||
|
||||
Step 3: Open console from CLI
|
||||
-----------------------------
|
||||
Step 3: Open the console from the CLI
|
||||
-------------------------------------
|
||||
|
||||
Instead of using the console at ``http://my-graphql.herokuapp.com/console`` you
|
||||
should now use the console by running:
|
||||
@ -81,8 +81,8 @@ Step 4: Add a new table and see how a migration is added
|
||||
As you use the Hasura console UI to make changes to your schema, migration files
|
||||
are automatically generated in the ``migrations/`` directory in your project.
|
||||
|
||||
Step 5: Apply the migrations on another instance of GraphQL engine
|
||||
------------------------------------------------------------------
|
||||
Step 5: Apply the migrations on another instance of the GraphQL engine
|
||||
----------------------------------------------------------------------
|
||||
|
||||
Apply all migrations present in the ``migrations/`` directory on a new
|
||||
instance at ``http://another-graphql-instance.herokuapp.com``:
|
||||
@ -93,12 +93,12 @@ instance at ``http://another-graphql-instance.herokuapp.com``:
|
||||
hasura migrate apply --endpoint http://another-graphql-instance.herokuapp.com
|
||||
|
||||
In case you need an automated way of applying the migrations, take a look at the
|
||||
:doc:`CLI-Migrations <auto-apply-migrations>` docker image, which can start
|
||||
GraphQL Engine after automatically applying the migrations which are
|
||||
:doc:`CLI-Migrations <auto-apply-migrations>` Docker image, which can start the
|
||||
GraphQL engine after automatically applying the migrations which are
|
||||
mounted into a directory.
|
||||
|
||||
Step 6: Check status of migrations
|
||||
----------------------------------
|
||||
Step 6: Check the status of migrations
|
||||
--------------------------------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@ -118,13 +118,13 @@ For example,
|
||||
1550931962927 Present Present
|
||||
1550931970826 Present Present
|
||||
|
||||
Such a migration status indicate that there are 3 migration versions in the
|
||||
Such a migration status indicates that there are 3 migration versions in the
|
||||
local directory and all of them are applied on the database.
|
||||
|
||||
If ``SOURCE STATUS`` indicates ``Not Present``, it means that the migration
|
||||
version is present on the server, but not on the current user's local directory.
|
||||
This typically happens if multiple people are collaborating on a project and one
|
||||
of the collaborator forgot to pull the latest changes which included the latest
|
||||
of the collaborators forgot to pull the latest changes which included the latest
|
||||
migration files or another collaborator forgot to push the latest migration
|
||||
files that were applied on the database. Syncing of the files would fix the
|
||||
issue.
|
||||
|
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue
Block a user