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: refactor cli docs to match latest changes

Browse Source 
GitOrigin-RevId: 4adbc5fbbd60a6e7749f36f3d112c09ba9c4a60a
This commit is contained in:
Aravind K P 2021-03-11 13:42:27 +05:30 committed by hasura-bot
parent 0c1133b393
commit c35e4a26b6
13 changed files with 85 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/graphql/core/hasura-cli/hasura_migrate.rst
View File

@ -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")

2
docs/graphql/core/hasura-cli/hasura_migrate_apply.rst
View File

@ -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")

2
docs/graphql/core/hasura-cli/hasura_migrate_create.rst
View File

@ -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")

2
docs/graphql/core/hasura-cli/hasura_migrate_squash.rst
View File

@ -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")

2
docs/graphql/core/hasura-cli/hasura_migrate_status.rst
View File

@ -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")

2
docs/graphql/core/hasura-cli/hasura_seed.rst
View File

@ -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")

2
docs/graphql/core/hasura-cli/hasura_seed_apply.rst
View File

@ -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")

2
docs/graphql/core/hasura-cli/hasura_seed_create.rst
View File

@ -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")

6
docs/graphql/core/migrations/advanced/resetting-migrations.rst
View File

@ -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 <database-name>
hasura migrate create "init" --from-server --database-name <database-name>
.. code-block:: bash
## note down the version
## mark the migration as applied on this server
hasura migrate apply --version "<version>" --skip-execution --database <database-name>
hasura migrate apply --version "<version>" --skip-execution --database-name <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 <database-name>
hasura migrate status --database-name <database-name>
You should see the new migrations!

4
docs/graphql/core/migrations/advanced/rolling-back-migrations.rst
View File

@ -34,13 +34,13 @@ To roll back a particular migration version:
.. code-block:: bash
hasura migrate apply --version 1550925483858 --type down --database <database-name>
hasura migrate apply --version 1550925483858 --type down --database-name <database-name>
To roll back the last 2 migration versions:
.. code-block:: bash
hasura migrate apply --down 2 --database <database-name>
hasura migrate apply --down 2 --database-name <database-name>
.. note::

4
docs/graphql/core/migrations/advanced/writing-migrations-manually.rst
View File

@ -27,7 +27,7 @@ Create migration manually
.. code-block:: bash
hasura migrate create <name-of-migration> --database <database-name>
hasura migrate create <name-of-migration> --database-name <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 <database-name>
hasura migrate apply --database-name <database-name>
hasura metadata reload
.. admonition:: Additional Resources

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

@ -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 <database-name>
hasura migrate create "init" --from-server --database-name <database-name>
# note down the version
# mark the migration as applied on this server
hasura migrate apply --version "<version>" --skip-execution --database <database-name>
hasura migrate apply --version "<version>" --skip-execution --database-name <database-name>
This command will create a new directory named ``<timestamp>_init`` inside the ``migrations/<database-name>`` 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 <database-name>
hasura migrate create "init" --from-server --schema "public" --schema "schema1" --schema "schema2" --database-name <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 "<feature-name>" --from <start-migration-version> --database <database-name>
hasura migrate squash --name "<feature-name>" --from <start-migration-version> --database-name <database-name>
# note down the version
# mark the squashed migration as applied on this server
hasura migrate apply --version "<squash-migration-version>" --skip-execution --database <database-name>
hasura migrate apply --version "<squash-migration-version>" --skip-execution --database-name <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 <database-name>
hasura migrate apply --endpoint http://another-graphql-instance.hasura.app --database-name <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 <database-name>
hasura migrate status --database-name <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 <database-name>
$ hasura migrate status --database-name <database-name>
VERSION NAME SOURCE STATUS DATABASE STATUS
1590493510167 init Present Present
1590497881360 create_table_public_address Present Present

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

@ -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>
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
``<project-directory>/metadata/databases/<database-name>/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 <database-name>
hasura migrate apply --database-name <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
-------------