From c35e4a26b69c4ded06fb7647a51a1150bdfa1b86 Mon Sep 17 00:00:00 2001 From: Aravind K P Date: Thu, 11 Mar 2021 13:42:27 +0530 Subject: [PATCH] docs: refactor cli docs to match latest changes GitOrigin-RevId: 4adbc5fbbd60a6e7749f36f3d112c09ba9c4a60a --- .../core/hasura-cli/hasura_migrate.rst | 2 +- .../core/hasura-cli/hasura_migrate_apply.rst | 2 +- .../core/hasura-cli/hasura_migrate_create.rst | 2 +- .../core/hasura-cli/hasura_migrate_squash.rst | 2 +- .../core/hasura-cli/hasura_migrate_status.rst | 2 +- docs/graphql/core/hasura-cli/hasura_seed.rst | 2 +- .../core/hasura-cli/hasura_seed_apply.rst | 2 +- .../core/hasura-cli/hasura_seed_create.rst | 2 +- .../advanced/resetting-migrations.rst | 6 +- .../advanced/rolling-back-migrations.rst | 4 +- .../advanced/writing-migrations-manually.rst | 4 +- .../core/migrations/migrations-setup.rst | 16 ++-- docs/graphql/core/migrations/upgrade-v3.rst | 78 +++++++++++++++---- 13 files changed, 85 insertions(+), 39 deletions(-) diff --git a/docs/graphql/core/hasura-cli/hasura_migrate.rst b/docs/graphql/core/hasura-cli/hasura_migrate.rst index 5eb9ea0170b..33fbd5403d4 100644 --- a/docs/graphql/core/hasura-cli/hasura_migrate.rst +++ b/docs/graphql/core/hasura-cli/hasura_migrate.rst @@ -22,7 +22,7 @@ Options --admin-secret string admin secret for Hasura GraphQL engine (env "HASURA_GRAPHQL_ADMIN_SECRET") --certificate-authority string path to a cert file for the certificate authority (env "HASURA_GRAPHQL_CERTIFICATE_AUTHORITY") - --database string database on which operation should be applied + --database-name string database on which operation should be applied --endpoint string http(s) endpoint for Hasura GraphQL engine (env "HASURA_GRAPHQL_ENDPOINT") -h, --help help for migrate --insecure-skip-tls-verify skip TLS verification and disable cert checking (default: false) (env "HASURA_GRAPHQL_INSECURE_SKIP_TLS_VERIFY") diff --git a/docs/graphql/core/hasura-cli/hasura_migrate_apply.rst b/docs/graphql/core/hasura-cli/hasura_migrate_apply.rst index fae79c83931..08278c49e56 100644 --- a/docs/graphql/core/hasura-cli/hasura_migrate_apply.rst +++ b/docs/graphql/core/hasura-cli/hasura_migrate_apply.rst @@ -81,7 +81,7 @@ Options inherited from parent commands --admin-secret string admin secret for Hasura GraphQL engine (env "HASURA_GRAPHQL_ADMIN_SECRET") --certificate-authority string path to a cert file for the certificate authority (env "HASURA_GRAPHQL_CERTIFICATE_AUTHORITY") - --database string database on which operation should be applied + --database-name string database on which operation should be applied --endpoint string http(s) endpoint for Hasura GraphQL engine (env "HASURA_GRAPHQL_ENDPOINT") --envfile string .env filename to load ENV vars from (default ".env") --insecure-skip-tls-verify skip TLS verification and disable cert checking (default: false) (env "HASURA_GRAPHQL_INSECURE_SKIP_TLS_VERIFY") diff --git a/docs/graphql/core/hasura-cli/hasura_migrate_create.rst b/docs/graphql/core/hasura-cli/hasura_migrate_create.rst index 560e65a03a1..771088c4677 100644 --- a/docs/graphql/core/hasura-cli/hasura_migrate_create.rst +++ b/docs/graphql/core/hasura-cli/hasura_migrate_create.rst @@ -65,7 +65,7 @@ Options inherited from parent commands --admin-secret string admin secret for Hasura GraphQL engine (env "HASURA_GRAPHQL_ADMIN_SECRET") --certificate-authority string path to a cert file for the certificate authority (env "HASURA_GRAPHQL_CERTIFICATE_AUTHORITY") - --database string database on which operation should be applied + --database-name string database on which operation should be applied --endpoint string http(s) endpoint for Hasura GraphQL engine (env "HASURA_GRAPHQL_ENDPOINT") --envfile string .env filename to load ENV vars from (default ".env") --insecure-skip-tls-verify skip TLS verification and disable cert checking (default: false) (env "HASURA_GRAPHQL_INSECURE_SKIP_TLS_VERIFY") diff --git a/docs/graphql/core/hasura-cli/hasura_migrate_squash.rst b/docs/graphql/core/hasura-cli/hasura_migrate_squash.rst index 3862077d535..e560b33ba73 100644 --- a/docs/graphql/core/hasura-cli/hasura_migrate_squash.rst +++ b/docs/graphql/core/hasura-cli/hasura_migrate_squash.rst @@ -49,7 +49,7 @@ Options inherited from parent commands --admin-secret string admin secret for Hasura GraphQL engine (env "HASURA_GRAPHQL_ADMIN_SECRET") --certificate-authority string path to a cert file for the certificate authority (env "HASURA_GRAPHQL_CERTIFICATE_AUTHORITY") - --database string database on which operation should be applied + --database-name string database on which operation should be applied --endpoint string http(s) endpoint for Hasura GraphQL engine (env "HASURA_GRAPHQL_ENDPOINT") --envfile string .env filename to load ENV vars from (default ".env") --insecure-skip-tls-verify skip TLS verification and disable cert checking (default: false) (env "HASURA_GRAPHQL_INSECURE_SKIP_TLS_VERIFY") diff --git a/docs/graphql/core/hasura-cli/hasura_migrate_status.rst b/docs/graphql/core/hasura-cli/hasura_migrate_status.rst index ac9d3e5aa78..686707065b2 100644 --- a/docs/graphql/core/hasura-cli/hasura_migrate_status.rst +++ b/docs/graphql/core/hasura-cli/hasura_migrate_status.rst @@ -44,7 +44,7 @@ Options inherited from parent commands --admin-secret string admin secret for Hasura GraphQL engine (env "HASURA_GRAPHQL_ADMIN_SECRET") --certificate-authority string path to a cert file for the certificate authority (env "HASURA_GRAPHQL_CERTIFICATE_AUTHORITY") - --database string database on which operation should be applied + --database-name string database on which operation should be applied --endpoint string http(s) endpoint for Hasura GraphQL engine (env "HASURA_GRAPHQL_ENDPOINT") --envfile string .env filename to load ENV vars from (default ".env") --insecure-skip-tls-verify skip TLS verification and disable cert checking (default: false) (env "HASURA_GRAPHQL_INSECURE_SKIP_TLS_VERIFY") diff --git a/docs/graphql/core/hasura-cli/hasura_seed.rst b/docs/graphql/core/hasura-cli/hasura_seed.rst index a38b625e797..c1b3d59a38e 100644 --- a/docs/graphql/core/hasura-cli/hasura_seed.rst +++ b/docs/graphql/core/hasura-cli/hasura_seed.rst @@ -24,7 +24,7 @@ Options --admin-secret string admin secret for Hasura GraphQL engine (env "HASURA_GRAPHQL_ADMIN_SECRET") --certificate-authority string path to a cert file for the certificate authority (env "HASURA_GRAPHQL_CERTIFICATE_AUTHORITY") - --database string database on which operation should be applied + --database-name string database on which operation should be applied --endpoint string http(s) endpoint for Hasura GraphQL engine (env "HASURA_GRAPHQL_ENDPOINT") -h, --help help for seed --insecure-skip-tls-verify skip TLS verification and disable cert checking (default: false) (env "HASURA_GRAPHQL_INSECURE_SKIP_TLS_VERIFY") diff --git a/docs/graphql/core/hasura-cli/hasura_seed_apply.rst b/docs/graphql/core/hasura-cli/hasura_seed_apply.rst index 62d1ad24c8e..772a3eb4e01 100644 --- a/docs/graphql/core/hasura-cli/hasura_seed_apply.rst +++ b/docs/graphql/core/hasura-cli/hasura_seed_apply.rst @@ -45,7 +45,7 @@ Options inherited from parent commands --admin-secret string admin secret for Hasura GraphQL engine (env "HASURA_GRAPHQL_ADMIN_SECRET") --certificate-authority string path to a cert file for the certificate authority (env "HASURA_GRAPHQL_CERTIFICATE_AUTHORITY") - --database string database on which operation should be applied + --database-name string database on which operation should be applied --endpoint string http(s) endpoint for Hasura GraphQL engine (env "HASURA_GRAPHQL_ENDPOINT") --envfile string .env filename to load ENV vars from (default ".env") --insecure-skip-tls-verify skip TLS verification and disable cert checking (default: false) (env "HASURA_GRAPHQL_INSECURE_SKIP_TLS_VERIFY") diff --git a/docs/graphql/core/hasura-cli/hasura_seed_create.rst b/docs/graphql/core/hasura-cli/hasura_seed_create.rst index 43be754551f..ee09f5b0614 100644 --- a/docs/graphql/core/hasura-cli/hasura_seed_create.rst +++ b/docs/graphql/core/hasura-cli/hasura_seed_create.rst @@ -48,7 +48,7 @@ Options inherited from parent commands --admin-secret string admin secret for Hasura GraphQL engine (env "HASURA_GRAPHQL_ADMIN_SECRET") --certificate-authority string path to a cert file for the certificate authority (env "HASURA_GRAPHQL_CERTIFICATE_AUTHORITY") - --database string database on which operation should be applied + --database-name string database on which operation should be applied --endpoint string http(s) endpoint for Hasura GraphQL engine (env "HASURA_GRAPHQL_ENDPOINT") --envfile string .env filename to load ENV vars from (default ".env") --insecure-skip-tls-verify skip TLS verification and disable cert checking (default: false) (env "HASURA_GRAPHQL_INSECURE_SKIP_TLS_VERIFY") diff --git a/docs/graphql/core/migrations/advanced/resetting-migrations.rst b/docs/graphql/core/migrations/advanced/resetting-migrations.rst index bbff55f942a..2863e8a8d98 100644 --- a/docs/graphql/core/migrations/advanced/resetting-migrations.rst +++ b/docs/graphql/core/migrations/advanced/resetting-migrations.rst @@ -45,14 +45,14 @@ If the migrations were reset, then we will set up fresh migrations by pulling th ## create migration files - "this will only export public schema from postgres" - hasura migrate create "init" --from-server --database + hasura migrate create "init" --from-server --database-name .. code-block:: bash ## note down the version ## mark the migration as applied on this server - hasura migrate apply --version "" --skip-execution --database + hasura migrate apply --version "" --skip-execution --database-name .. code-block:: bash @@ -71,7 +71,7 @@ Run the following command to verify the migration status: .. code-block:: bash - hasura migrate status --database + hasura migrate status --database-name You should see the new migrations! diff --git a/docs/graphql/core/migrations/advanced/rolling-back-migrations.rst b/docs/graphql/core/migrations/advanced/rolling-back-migrations.rst index f2634d4698e..7a17c15f0a8 100644 --- a/docs/graphql/core/migrations/advanced/rolling-back-migrations.rst +++ b/docs/graphql/core/migrations/advanced/rolling-back-migrations.rst @@ -34,13 +34,13 @@ To roll back a particular migration version: .. code-block:: bash - hasura migrate apply --version 1550925483858 --type down --database + hasura migrate apply --version 1550925483858 --type down --database-name To roll back the last 2 migration versions: .. code-block:: bash - hasura migrate apply --down 2 --database + hasura migrate apply --down 2 --database-name .. note:: diff --git a/docs/graphql/core/migrations/advanced/writing-migrations-manually.rst b/docs/graphql/core/migrations/advanced/writing-migrations-manually.rst index 3041baed98a..d0f316efa0b 100644 --- a/docs/graphql/core/migrations/advanced/writing-migrations-manually.rst +++ b/docs/graphql/core/migrations/advanced/writing-migrations-manually.rst @@ -27,7 +27,7 @@ Create migration manually .. code-block:: bash - hasura migrate create --database + hasura migrate create --database-name This command will create up and down migration SQL files in the ``migrations`` directory. @@ -45,7 +45,7 @@ Create migration manually .. code-block:: bash hasura metadata apply - hasura migrate apply --database + hasura migrate apply --database-name hasura metadata reload .. admonition:: Additional Resources diff --git a/docs/graphql/core/migrations/migrations-setup.rst b/docs/graphql/core/migrations/migrations-setup.rst index 17ed3471286..c03ceb162a6 100644 --- a/docs/graphql/core/migrations/migrations-setup.rst +++ b/docs/graphql/core/migrations/migrations-setup.rst @@ -121,12 +121,12 @@ Create a migration called ``init`` by exporting the current Postgres schema from # create migration files (note that this will only export the public schema from postgres) # if you started hasura with HASURA_GRAPHQL_DATABASE_URL environment variable, the database name should be default - hasura migrate create "init" --from-server --database + hasura migrate create "init" --from-server --database-name # note down the version # mark the migration as applied on this server - hasura migrate apply --version "" --skip-execution --database + hasura migrate apply --version "" --skip-execution --database-name This command will create a new directory named ``_init`` inside the ``migrations/`` directory. In the newly created directory, there's a file named ``up.sql``. @@ -146,7 +146,7 @@ The apply command will mark this migration as "applied" on the server. .. code-block:: bash - hasura migrate create "init" --from-server --schema "public" --schema "schema1" --schema "schema2" --database + hasura migrate create "init" --from-server --schema "public" --schema "schema1" --schema "schema2" --database-name Step 3.2: Initialize Hasura metadata ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -229,12 +229,12 @@ migration into a single migration file. .. code-block:: bash - hasura migrate squash --name "" --from --database + hasura migrate squash --name "" --from --database-name # note down the version # mark the squashed migration as applied on this server - hasura migrate apply --version "" --skip-execution --database + hasura migrate apply --version "" --skip-execution --database-name Commit the project status into version control. @@ -258,7 +258,7 @@ in the ``metadata/`` directory on a new instance at ``http://another-graphql-ins # in project dir hasura metadata apply --endpoint http://another-graphql-instance.hasura.app - hasura migrate apply --endpoint http://another-graphql-instance.hasura.app --database + hasura migrate apply --endpoint http://another-graphql-instance.hasura.app --database-name 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 @@ -279,7 +279,7 @@ Step 8: Check the status of migrations .. code-block:: bash # in project dir - hasura migrate status --database + hasura migrate status --database-name This command will print out each migration version present in the ``migrations`` directory along with its name, source status and database status. @@ -288,7 +288,7 @@ For example, .. code-block:: bash - $ hasura migrate status --database + $ hasura migrate status --database-name VERSION NAME SOURCE STATUS DATABASE STATUS 1590493510167 init Present Present 1590497881360 create_table_public_address Present Present diff --git a/docs/graphql/core/migrations/upgrade-v3.rst b/docs/graphql/core/migrations/upgrade-v3.rst index 6e667b0ce21..5faf2c98f08 100644 --- a/docs/graphql/core/migrations/upgrade-v3.rst +++ b/docs/graphql/core/migrations/upgrade-v3.rst @@ -40,12 +40,22 @@ The following is a sample metadata directory when using ``config v3``. ├── cron_triggers.yaml ├── databases │   ├── databases.yaml - │   └── default + │   └── s1 + │   ├── functions + │   │   ├── functions.yaml + │   │   └── public_search_artists.yaml │   └── tables │   ├── public_albums.yaml │   ├── public_artists.yaml + │   ├── public_genres.yaml + │   ├── public_media_types.yaml + │   ├── public_playlists.yaml + │   ├── public_playlist_track.yaml + │   ├── public_tracks.yaml + │   └── tables.yaml ├── query_collections.yaml ├── remote_schemas.yaml + ├── rest_endpoints.yaml └── version.yaml @@ -56,27 +66,63 @@ Now let's looks at the contents of ``databases/databases.yaml`` .. code-block:: yaml - - name: default + - name: s1 + kind: postgres configuration: connection_info: - database_url: + database_url: + from_env: DATABASE_URL pool_settings: idle_timeout: 180 max_connections: 50 retries: 1 - tables: - - "!include public_albums.yaml" - - "!include public_artists.yaml" - functions: [] + tables: "!include s1/tables/tables.yaml" + functions: "!include s1/functions/functions.yaml" -We can see that we have a database called `default`, with it's configuration information and other metadata. -Take a a look at the first element under ``tables`` key. This is a special syntax/directive to hasura CLI to "include" -and inline the contents of a file called ``public_albums.yaml``. The location at which the CLI looks for this file is -``/metadata/databases//tables`` +We can see that we have a database called ``s1``, with it's configuration information and other metadata. Notice the peculiarity +of values of ``tables`` and ``functions`` keys. CLI now uses a special syntax to "include" contents from another file to use it +as the value for a particular key. Here it is ``!include s1/tables/tables.yaml`` , which means that CLI will try to fill in value +of ``tables`` from ``s1/tables/tables.yaml``. -Therefore when doing a ``hasura metadata apply`` CLI will inline elements of ``tables`` key in ``databases.yaml`` with -content sourced from ``metadata/databases/default/tables``. This allows managing metadata related a table easier since -it'll have a file of it's own. +Now, If we look at the contents of ``s1/tables/tables.yaml`` (as shown below) we understand that it is array whose values are again +similarly sourced from different files. + +.. code-block:: yaml + + - "!include public_albums.yaml" + - "!include public_artists.yaml" + - "!include public_genres.yaml" + - "!include public_media_types.yaml" + - "!include public_playlist_track.yaml" + - "!include public_playlists.yaml" + - "!include public_tracks.yaml" + +Let's look at ``public_albums.yaml`` from the first line above. + +.. code-block:: yaml + + array_relationships: + - name: tracks + using: + foreign_key_constraint_on: + column: album_id + table: + name: tracks + schema: public + object_relationships: + - name: artist + using: + foreign_key_constraint_on: artist_id + table: + name: albums + schema: public + +This file specifies the metadata related to a table called ``tracks`` in ``public`` schema. This means that each table will have it's own +file for it's metadata specifically. This makes understanding and managing metadata related to tables a lot easier. + +Also note that Metadata related to functions is also managed in a similar fashion. + +When doing a ``hasura metadata apply`` CLI will inline ``!include`` directives with the appropriate contents. .. note:: @@ -109,7 +155,7 @@ The steps to apply migrations and metadata to a new hasura instance will be: # first apply metadata, this will populate hasura with configuration of connected databases hasura metadata apply # now we can apply migrations - hasura migrate apply --database + hasura migrate apply --database-name # follow it with a metadata reload to make sure hasura is aware of the changes hasura metadata reload @@ -117,7 +163,7 @@ The reason why we have to do ``metadata apply`` first instead of ``migrate apply 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. -Also, ``hasura seeds`` and ``hasura migrate`` now accepts a required flag ``--database``. +Also, ``hasura seeds`` and ``hasura migrate`` now accepts a required flag ``--database-name``. Upgrade steps -------------