help migrating from cloud to development ambiguity on databases and meta

[ilovett]

Hello I am confused by the first step in this guide:

https://hasura.io/docs/latest/graphql/cloud/projects/environments.html#step-1-setup-local-development-of-hasura-with-docker

It explains:

Make sure that the ENV variable for database connection in your local setup is same as that in your Cloud project. Also add any other ENV variables that you might have set on the Cloud project.

OK -- so which one is that exactly? I have an extra one in my docker-compose.yml that does not exist on my cloud project...

Do I set up both PG_DATABASE_URL to match cloud project?

What about HASURA_GRAPHQL_METADATA_DATABASE_URL that comes with the docker-compose.yml ?

Does my PG_DATABASE_URL point to my live heroku db? But what about the meta url? Are they the same database? different? Huh?

Is my meta local but pg database is remote?

Then, later on in the instructions at https://hasura.io/docs/latest/graphql/cloud/projects/environments.html#step-4-initialize-the-migration-files

It explains to get the schema from cloud:

hasura migrate create init --from-server --endpoint <hasura-cloud-project-url> --admin-secret <admin-secret> --database-name <database-name>

My thinking is that I am defining my cloud project url here and pulling down everything from this command, and that means that my PG_DATABASE_URL should actually point to a local postgres and not the same one as my cloud ?

So why does the PG_DATABASE_URL actually need to match cloud?

Is my local hasura actually supposed to point to the same one as my cloud project? Or is it actually supposed to point to my local postgres I am setting up?

How is meta different from the actual data database and / or schema?

Thank you in advance!

[rikinsk]

Hey there, sorry for the delayed response and the not-so-clear docs. We'll update them based on your feedback.

Make sure that the ENV variable for database connection in your local setup is same as that in your Cloud project.

This was intended to mean that the same env var name should be used for storing the database url in Cloud and the docker-compose. In your case it seems to be PG_DATABASE_URL. The actual value of the env var will be different for the two envs, cloud would point to the heroku db while the docker-compose will point to the PG database created in the docker-compose. This is the database that stores your appllication data.

What about HASURA_GRAPHQL_METADATA_DATABASE_URL that comes with the docker-compose.yml ?

The metadata database is the database in which Hasura metadata will be stored. Cloud has its own metadata storage db hence the HASURA_GRAPHQL_METADATA_DATABASE_URL env var for the cloud project is managed by Hasura Cloud itself. In your docker-compose the metadata db can be the same PG database created in the docker-compose that we have set as PG_DATABASE_URL (i.e. the metadata is stored in the same database as application data)

How is meta different from the actual data database and / or schema?

Hasura metadata is the configuration Hasura needs to generate your GraphQL API, e,g. your list of tracked tables, permission rules, etc. It is stored in a dedicated db schema called hdb_catalog to keep it separate from your actual application data and schema. The metadata can be stored in the same db as your application data or can be stored in a different database.

Do let us know if you need any further clarifications.