diff --git a/docs/_static/scripts/hdocs.js b/docs/_static/scripts/hdocs.js index b18d90b68d2..673810f9c95 100644 --- a/docs/_static/scripts/hdocs.js +++ b/docs/_static/scripts/hdocs.js @@ -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 = { diff --git a/docs/graphql/core/deployment/graphql-engine-flags/reference.rst b/docs/graphql/core/deployment/graphql-engine-flags/reference.rst index 292c5bb21b6..a0384ce8cf1 100644 --- a/docs/graphql/core/deployment/graphql-engine-flags/reference.rst +++ b/docs/graphql/core/deployment/graphql-engine-flags/reference.rst @@ -48,12 +48,14 @@ For the ``graphql-engine`` command these are the available flags and ENV variabl * - ``--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://:@:/`` 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 `` - ``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 `) + + (**Deprecated in versions > v2.0.0**. :ref:`See details `) * - ``--timeout `` - ``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 `) + + (**Deprecated in versions > v2.0.0**. :ref:`See details `) * - ``--use-prepared-statements `` - ``HASURA_GRAPHQL_USE_PREPARED_STATEMENTS`` - Use prepared statements for queries (default: true) - (Deprecated in versions > v2.0.0. :ref:`See details `) + + (**Deprecated in versions > v2.0.0**. :ref:`See details `) * - ``-i, --tx-iso `` - ``HASURA_GRAPHQL_TX_ISOLATION`` - Transaction isolation. read-committed / repeatable-read / serializable (default: read-commited) - (Deprecated in versions > v2.0.0. :ref:`See details `) + + (**Deprecated in versions > v2.0.0**. :ref:`See details `) * - ``--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 `) + + (**Deprecated in versions > v2.0.0**. :ref:`See details `) * - ``--conn-lifetime `` - ``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 `) + + (**Deprecated in versions > v2.0.0**. :ref:`See details `) * - ``--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. diff --git a/docs/graphql/core/guides/upgrade-hasura-v2.rst b/docs/graphql/core/guides/upgrade-hasura-v2.rst index f305ccd6d54..8e406ee64ae 100644 --- a/docs/graphql/core/guides/upgrade-hasura-v2.rst +++ b/docs/graphql/core/guides/upgrade-hasura-v2.rst @@ -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 `. - ``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 diff --git a/docs/graphql/core/index.rst b/docs/graphql/core/index.rst index d7480510588..5cd669eafea 100644 --- a/docs/graphql/core/index.rst +++ b/docs/graphql/core/index.rst @@ -100,7 +100,7 @@ The Hasura GraphQL engine makes your data instantly accessible over a real-time - `30-Minute Hasura Basics Course `__ - `GraphQL & Hasura Courses `__ - :ref:`Guides & Resources ` - - :ref:`Upgrading to Hasura v2 ` + - :ref:`Updating to Hasura v2 ` .. toctree:: diff --git a/docs/graphql/core/migrations/migrations-setup.rst b/docs/graphql/core/migrations/migrations-setup.rst index 0b780f55b35..a5d7385d3b0 100644 --- a/docs/graphql/core/migrations/migrations-setup.rst +++ b/docs/graphql/core/migrations/migrations-setup.rst @@ -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 - 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 ` 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: diff --git a/docs/graphql/core/migrations/upgrade-v3.rst b/docs/graphql/core/migrations/upgrade-v3.rst index e180c4eaddf..b56e1e0f225 100644 --- a/docs/graphql/core/migrations/upgrade-v3.rst +++ b/docs/graphql/core/migrations/upgrade-v3.rst @@ -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``.