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

docs: update v2 docs

Browse Source 
- update config availablility/deprecation notes
- add notes on metadata inconsistency during config v3 migrations
- use update instead of upgrade for v2 migration for consistency
- fix external link opening

GitOrigin-RevId: a8ca31948285f55a5fac8d00b93f85007be512cc
This commit is contained in:
Rikin Kachhia 2021-05-18 19:06:19 +05:30 committed by hasura-bot
parent ddad668f07
commit 423f5c6ad5
6 changed files with 67 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -122,7 +122,7 @@ window.hdocs = (function () {
}
},
setExternalLinks: function () {
Array.from(document.getElementsByClassName('.external')).forEach(function (el) { el.setAttribute('target', '_blank') });
Array.from(document.getElementsByClassName('external')).forEach(function (el) { el.setAttribute('target', '_blank') });
},
setupIntercom: function () {
window.intercomSettings = {

42
docs/graphql/core/deployment/graphql-engine-flags/reference.rst
View File

@ -48,12 +48,14 @@ For the ``graphql-engine`` command these are the available flags and ENV variabl
* - ``--metadata-database-url <METADATA-DATABASE-URL>``
- ``HASURA_GRAPHQL_METADATA_DATABASE_URL``
- Postgres database URL that will be used to store the Hasura metadata. By default the database configured using ``HASURA_GRAPHQL_DATABASE_URL``
will be used to store the metadata. *(Available for versions > v2.0.0)*
will be used to store the metadata.
``postgres://<user>:<password>@<host>:<port>/<db-name>``
Example: ``postgres://admin:mypass@mydomain.com:5432/metadata_db``
*(Available for versions > v2.0.0)*
Or you can specify the following options *(only via flags)*:
.. code-block:: none
@ -164,12 +166,16 @@ For the ``serve`` sub-command these are the available flags and ENV variables:
- ``HASURA_GRAPHQL_EVENTS_FETCH_BATCH_SIZE``
- Maximum number of events to be fetched from the DB in a single batch (default: 100)
*(Available for versions > v2.0.0)*
* - ``--async-actions-fetch-interval``
- ``HASURA_GRAPHQL_ASYNC_ACTIONS_FETCH_INTERVAL``
- Interval in milliseconds to sleep before trying to fetch async actions again after a fetch
returned no async actions from metadata storage. Value ``0`` implies completely disable fetching
async actions from the storage.
*(Available for versions > v2.0.0)*
* - ``-s, --stripes <NO_OF_STRIPES>``
- ``HASURA_GRAPHQL_PG_STRIPES``
- Number of stripes (distinct sub-pools) to maintain with Postgres (default: 1).
@ -180,34 +186,40 @@ For the ``serve`` sub-command these are the available flags and ENV variables:
- Maximum number of Postgres connections that can be opened per stripe (default: 50).
When the maximum is reached we will block until a new connection becomes available,
even if there is capacity in other stripes.
(Deprecated in versions > v2.0.0. :ref:`See details <hasura_v2_env_changes>`)
(**Deprecated in versions > v2.0.0**. :ref:`See details <hasura_v2_env_changes>`)
* - ``--timeout <SECONDS>``
- ``HASURA_GRAPHQL_PG_TIMEOUT``
- Each connection's idle time before it is closed (default: 180 sec)
(Deprecated in versions > v2.0.0. :ref:`See details <hasura_v2_env_changes>`)
(**Deprecated in versions > v2.0.0**. :ref:`See details <hasura_v2_env_changes>`)
* - ``--use-prepared-statements <true|false>``
- ``HASURA_GRAPHQL_USE_PREPARED_STATEMENTS``
- Use prepared statements for queries (default: true)
(Deprecated in versions > v2.0.0. :ref:`See details <hasura_v2_env_changes>`)
(**Deprecated in versions > v2.0.0**. :ref:`See details <hasura_v2_env_changes>`)
* - ``-i, --tx-iso <TXISO>``
- ``HASURA_GRAPHQL_TX_ISOLATION``
- Transaction isolation. read-committed / repeatable-read / serializable (default: read-commited)
(Deprecated in versions > v2.0.0. :ref:`See details <hasura_v2_env_changes>`)
(**Deprecated in versions > v2.0.0**. :ref:`See details <hasura_v2_env_changes>`)
* - ``--retries <NO_OF_RETRIES>``
- ``HASURA_GRAPHQL_NO_OF_RETRIES``
- Number of retries if Postgres connection error occurs (default: 1)
(Deprecated in versions > v2.0.0. :ref:`See details <hasura_v2_env_changes>`)
(**Deprecated in versions > v2.0.0**. :ref:`See details <hasura_v2_env_changes>`)
* - ``--conn-lifetime <SECONDS>``
- ``HASURA_GRAPHQL_PG_CONN_LIFETIME``
- Time from connection creation after which the connection should be destroyed and a new one created.
A value of 0 indicates we should never destroy an active connection. If 0 is passed, memory from large query
results may not be reclaimed. (default: 600 sec)
(Deprecated in versions > v2.0.0. :ref:`See details <hasura_v2_env_changes>`)
(**Deprecated in versions > v2.0.0**. :ref:`See details <hasura_v2_env_changes>`)
* - ``--stringify-numeric-types``
- ``HASURA_GRAPHQL_STRINGIFY_NUMERIC_TYPES``
@ -232,12 +244,12 @@ For the ``serve`` sub-command these are the available flags and ENV variables:
* - ``--enable-allowlist``
- ``HASURA_GRAPHQL_ENABLE_ALLOWLIST``
- 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)*
allow-list. Default: ``false``
* - ``--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
* - ``--enabled-log-types``
- ``HASURA_GRAPHQL_ENABLED_LOG_TYPES``
@ -254,14 +266,20 @@ For the ``serve`` sub-command these are the available flags and ENV variables:
- ``HASURA_GRAPHQL_DEV_MODE``
- Set dev mode for GraphQL requests; include the ``internal`` key in the errors extensions of the response (if required).
*(Available for versions > v1.2.0)*
* - ``--admin-internal-errors``
- ``HASURA_GRAPHQL_ADMIN_INTERNAL_ERRORS``
- Include the ``internal`` key in the errors extensions of the response for GraphQL requests with the admin role (if required).
*(Available for versions > v1.2.0)*
* - ``--enable-remote-schema-permissions``
- ``HASURA_GRAPHQL_ENABLE_REMOTE_SCHEMA_PERMISSIONS``
- Enable remote schema permissions (default: ``false``)
*(Available for versions > v2.0.0)*
* - ``--infer-function-permissions``
- ``HASURA_GRAPHQL_INFER_FUNCTION_PERMISSIONS``
- When the ``--infer-function-permissions`` flag is set to ``false``, a function ``f``, stable, immutable or volatile is
@ -278,16 +296,22 @@ For the ``serve`` sub-command these are the available flags and ENV variables:
- ``HASURA_GRAPHQL_SCHEMA_SYNC_POLL_INTERVAL``
- Interval to poll metadata storage for updates in milliseconds - Default 1000 (1s) - Set to 0 to disable.
*(Available for versions > v2.0.0)*
* - ``--experimental-features``
- ``HASURA_GRAPHQL_EXPERIMENTAL_FEATURES``
- List of experimental features to be enabled. A comma separated value is expected. Options: ``inherited_roles``.
*(Available for versions > v2.0.0)*
* - ``--graceful-shutdown-timeout``
- ``HASURA_GRAPHQL_GRACEFUL_SHUTDOWN_TIMEOUT``
- Timeout (in seconds) to wait for the in-flight events (event triggers and scheduled triggers) and async actions to complete before the
server shuts down completely (default: 60 seconds). If the in-flight events are not completed within the
timeout, those events are marked as pending.
*(Available for versions > v2.0.0)*
.. note::
When the equivalent flags for environment variables are used, the flags will take precedence.

26
docs/graphql/core/guides/upgrade-hasura-v2.rst
View File

@ -1,11 +1,11 @@
.. meta::
:description: Upgrading to Hasura GraphQL engine v2
:keywords: hasura, docs, guide, compatibility, upgrade v2
:description: Updating to Hasura GraphQL engine v2
:keywords: hasura, docs, guide, compatibility, update v2
.. _upgrade_hasura_v2:
Upgrading to Hasura GraphQL engine v2
=====================================
Updating to Hasura GraphQL engine v2
====================================
.. contents:: Table of contents
:backlinks: none
@ -16,7 +16,7 @@ Introduction
------------
This page talks about the conceptual changes introduces in Hasura v2 and things to
keep in mind while upgrading from Hasura v1 to v2.
keep in mind while updating from Hasura v1 to v2.
Do reach out to us if you run into any issues while using Hasura v2 or have any questions
regarding any changes introduced.
@ -84,7 +84,7 @@ Breaking behaviour changes
With v2.0, some of the auto-generated schema types have been extended. For example, ``String_comparison_exp`` has an additional ``regex`` input
object field. This means if you have a Hasura API with an older Hasura version added as a remote schema then it will have a type conflict. You
should upgrade all Hasura remote schemas to avoid such type conflicts.
should update all Hasura remote schemas to avoid such type conflicts.
- **Migrations are not executed under a single transaction**
@ -112,9 +112,9 @@ Hasura configuration
its metadata.
- The database set using the ``HASURA_GRAPHQL_DATABASE_URL`` env var is connected automatically with the name
``default`` in Hasura v2 while upgrading an existing instance or while starting a fresh instance.
``default`` in Hasura v2 while updating an existing instance or while starting a fresh instance.
Setting this env var post initial setup/upgrade will have no effect as the Hasura metadata for data sources
Setting this env var post initial setup/update will have no effect as the Hasura metadata for data sources
would already have been initialized and the env var will be treated as any other custom env var.
It is now not mandatory to set this env var if a dedicated ``HASURA_GRAPHQL_METADATA_DATABASE_URL`` is set.
@ -123,8 +123,8 @@ Hasura configuration
.. _hasura_v2_env_changes:
- The values of the following env vars are used to define the connection parameters of the ``default`` database
while upgrading an existing instance or while starting a fresh instance. During metadata initialization, their values
- In v2.0, the values of the following env vars are used to define the connection parameters of the ``default`` database
while updating an existing instance or while starting a fresh instance. During metadata initialization, their values
are moved to the metadata of the ``default`` source as defined :ref:`here <PGConfiguration>`.
- ``HASURA_GRAPHQL_PG_CONNECTIONS``
@ -137,7 +137,7 @@ Hasura configuration
- ``HASURA_GRAPHQL_READ_REPLICA_URLS``
- ``HASURA_GRAPHQL_CONNECTIONS_PER_READ_REPLICA``
**Post the initial setup/upgrade once the metadata is initialized, these env vars can be considered as Deprecated.**
**Post the initial setup/update once the metadata is initialized, these env vars can be considered as Deprecated.**
i.e. Changing or setting values of these env vars will have no impact as the values in the Hasura metadata are
now used to define the connection parameters.
@ -198,8 +198,8 @@ being applied also uses the appropriate env vars.
Though we would recommend to upgrade to ``config v3`` anyway as it includes some useful directory structure changes.
Updates to CI/CD after upgrading to Hasura v2
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Updates to CI/CD after updating to Hasura v2
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following commands need to be executed in the specified order to apply metadata and migrations in CI/CD workflows

2
docs/graphql/core/index.rst
View File

@ -100,7 +100,7 @@ The Hasura GraphQL engine makes your data instantly accessible over a real-time
- `30-Minute Hasura Basics Course <https://hasura.io/learn/graphql/hasura/introduction/>`__
- `GraphQL & Hasura Courses <https://hasura.io/learn/>`__
- :ref:`Guides & Resources <guides>`
- :ref:`Upgrading to Hasura v2 <upgrade_hasura_v2>`
- :ref:`Updating to Hasura v2 <upgrade_hasura_v2>`
.. toctree::

12
docs/graphql/core/migrations/migrations-setup.rst
View File

@ -257,15 +257,23 @@ in the ``metadata/`` directory on a new instance at ``http://another-graphql-ins
.. code-block:: bash
# in project dir
# apply metadata, this will connect Hasura to the configured databases.
hasura metadata apply --endpoint http://another-graphql-instance.hasura.app
hasura migrate apply --endpoint http://another-graphql-instance.hasura.app --database-name <database-name>
hasura metadata reload --endpoint http://another-graphql-instance.hasura.app
# apply migrations to the connected databases.
hasura migrate apply --all-databases --endpoint http://another-graphql-instance.hasura.app
# reload metadata to make sure Hasura is aware of any newly created database objects.
hasura metadata reload --endpoint http://another-graphql-instance.hasura.app
In case you need an automated way of applying the migrations and metadata, take a look at the
:ref:`cli-migrations <auto_apply_migrations>` Docker image, which can start the
GraphQL engine after automatically applying the migrations and metadata which are
mounted onto directories.
As we are applying metadata before migrations, your metadata might be in an **inconsistent state** after the initial
``metadata apply`` till the ``metadata reload`` step as some database objects referred to in metadata might not
be available till the migrations are applied.
If you now open the console of the new instance, you can see that the three tables have
been created and are tracked:

15
docs/graphql/core/migrations/upgrade-v3.rst
View File

@ -146,22 +146,25 @@ has a sub directory ``default`` which corresponds to the connected database.
Changes needed in existing workflows
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
With the introduction of multiple databases and it's configuration being in metadata, it brings a change of workflow with it.
With the introduction of multiple databases and it's configuration being stored in metadata, it brings a change of workflow with it.
The steps to apply migrations and metadata to a new Hasura instance will be:
.. code-block:: bash
# first apply metadata, this will connect Hasura to the configured databases
# first apply metadata, this will connect Hasura to the configured databases.
hasura metadata apply
# now we can apply migrations to the connected databases
# now we can apply migrations to the connected databases.
hasura migrate apply --all-databases
# follow it with a metadata reload to make sure Hasura is aware of any newly created database objects
# follow it with a metadata reload to make sure Hasura is aware of any newly created database objects.
hasura metadata reload
The reason why we have to do ``metadata apply`` first instead of ``migrate apply`` (that we are used to doing in ``config v2``) is that
if we do a ``migrate apply`` first then Hasura might not be aware about the databases it has to connect to. Earlier we could not start Hasura
without a connected database, but now we can.
if we do a ``migrate apply`` first then Hasura might not yet be aware about the databases it has to connect to as that information is present
in metadata. Earlier we could not start Hasura without a connected database, but now we can.
As we are now applying metadata before migrations, your metadata might be in an **inconsistent state** after the initial ``metadata apply``
till the ``metadata reload`` step as some database objects referred to in metadata might not be available till the migrations are applied.
Also, ``hasura seeds`` and ``hasura migrate`` commands now accept a required flag ``--database-name``.