hasura/graphql-engine
1
0
Fork 0
mirror of https://github.com/hasura/graphql-engine.git synced 2024-09-11 10:46:25 +03:00
Code Issues Projects Releases Wiki Activity

Refactor HAUSRA_GRAPHQL_DATABASE_URL refs

Browse Source 
[DOCS-1060]: https://hasurahq.atlassian.net/browse/DOCS-1060?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

PR-URL: https://github.com/hasura/graphql-engine-mono/pull/10634
GitOrigin-RevId: bc35c1cc85a49f376ce58aae65f12a73ebc1e136
This commit is contained in:
Rob Dominguez 2024-02-02 04:16:07 -06:00 committed by hasura-bot
parent 2ecf9ab6fb
commit 6831a0adcb
18 changed files with 59 additions and 87 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
docs/docs/databases/database-config/index.mdx
View File

@ -72,9 +72,6 @@ is recommended to use environment variables for better security _(as connection
exposed as part of the Hasura Metadata)_ as well as to allow configuring different databases in different
environments _(like staging or production)_ easily.
A database can be connected to using the `HASURA_GRAPHQL_DATABASE_URL` environment variable as well in which case it
gets added automatically as a database named `default`.
### Allow connections from the Hasura Cloud IP {#cloud-projects-create-allow-nat-ip}
When using Hasura Cloud, you may need to adjust your connection settings of your database provider to allow
@ -114,8 +111,6 @@ is recommended to use environment variables for better security _(as connection
exposed as part of the Hasura Metadata)_ as well as to allow configuring different databases in different
environments _(like staging or production)_ easily.
A database can be connected to using the `HASURA_GRAPHQL_DATABASE_URL` environment variable as well in which case it
gets added automatically as a database named default.
</TabItem>
</Tabs>
@ -127,8 +122,7 @@ gets added automatically as a database named default.
<TabItem value="cli" label="CLI">
In your `config v3` project, head to the `/metadata/databases/databases.yaml` file and add the database configuration as
below. If you're using the `HASURA_GRAPHQL_DATABASE_URL` environment variable then the database will get automatically
added and named default.
below.
```yaml
- name: <db_name>
@ -198,8 +192,7 @@ Engine instance.
When using Hasura Cloud, Metadata is stored for you in separate data storage to your connected database(s). When
using Docker, if you want to
[store the Hasura Metadata on a separate database](/deployment/graphql-engine-flags/reference.mdx#metadata-database-url),
you can use the `HASURA_GRAPHQL_METADATA_DATABASE_URL` env var to specify which database to use. By default, the
Hasura Metadata is stored on the same database as specified in the `HASURA_GRAPHQL_DATABASE_URL` environment variable.
you can use the `HASURA_GRAPHQL_METADATA_DATABASE_URL` env var to specify which database to use.
## Connect different Hasura instances to the same database

6
docs/docs/databases/quickstart.mdx
View File

@ -85,8 +85,7 @@ required to ensure connectivity to your database from Hasura Cloud if needed.
<TabItem value="cli" label="CLI">
In your `config v3` project, head to the `/metadata/databases/databases.yaml` file and add the database configuration as
below. If you're using the `HASURA_GRAPHQL_DATABASE_URL` environment variable then the database will get automatically
added and named default.
below.
```yaml
- name: <db_name>
@ -254,8 +253,7 @@ X-Hasura-Role: admin
When using Hasura Cloud, Metadata is stored for you in separate data storage to your connected database(s). When using
Docker, if you want to
[store the Hasura Metadata on a separate database](/deployment/graphql-engine-flags/reference.mdx#metadata-database-url),
you can use the `HASURA_GRAPHQL_METADATA_DATABASE_URL` env var to specify which database to use. By default, the Hasura
Metadata is stored on the same database as specified in the `HASURA_GRAPHQL_DATABASE_URL` environment variable.
you can use the `HASURA_GRAPHQL_METADATA_DATABASE_URL` env var to specify which database to use.
## Connect different Hasura instances to the same database

13
docs/docs/deployment/deployment-guides/azure-container-instances-postgres.mdx
View File

@ -150,7 +150,7 @@ az container create --resource-group hasura \
--dns-name-label "<dns-name-label>" \
--ports 80 \
--environment-variables "HASURA_GRAPHQL_SERVER_PORT"="80" "HASURA_GRAPHQL_ENABLE_CONSOLE"="true" "HASURA_GRAPHQL_ADMIN_SECRET"="<admin-secret>"\
--secure-environment-variables "HASURA_GRAPHQL_DATABASE_URL"="<database-url>"
--secure-environment-variables "HASURA_METADATA_DATABASE_URL"="<database-url>" "PG_DATABASE_URL"="<database-url>"
```
`<database-url>` should be replaced by the following format:
@ -159,7 +159,9 @@ az container create --resource-group hasura \
postgres://hasura%40<server_name>:<server_admin_password>@<hostname>:5432/hasura
```
If you'd like to connect to an existing database, use that server's database url.
If you'd like to connect to an existing database, use that server's database url. Hasura requires a Postgres database
to store its metadata. You can use the same database for both Hasura and the application data, or you can use a separate
database for Hasura's metadata.
:::info Note
@ -196,9 +198,14 @@ az container create --resource-group hasura \
"HASURA_GRAPHQL_ENABLE_CONSOLE"="true" \
"HASURA_GRAPHQL_ADMIN_SECRET"="<admin-secret>" \
"HASURA_GRAPHQL_JWT_SECRET"= \ "{\"type\": \"RS512\",\"key\": \"-----BEGIN CERTIFICATE-----\\nMIIDBzCCAe+gAwIBAgIJTpEEoUJ/bOElMA0GCSqGSIb3DQEBCwUAMCExHzAdBgNV\\nBAMTFnRyYWNrLWZyOC51cy5hdXRoMC5jb20wHhcNMjAwNzE3MDYxMjE4WhcNMzQw\\nMzI2MDYxMjE4WjAhMR8wHQYDVQQDExZ0cmFjay1mcjgudXMuYXV0aDAuY29tMIIB\\nIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAuK9N9FWK1hEPtwQ8ltYjlcjF\\nX03jhGgUKkLCLxe8q4x84eGJPmeHpyK+iZZ8TWaPpyD3fk+s8BC3Dqa/Sd9QeOBh\\nZH/YnzoB3yKqF/FruFNAY+F3LUt2P2t72tcnuFg4Vr8N9u8f4ESz7OHazn+XJ7u+\\ncuqKulaxMI4mVT/fGinCiT4uGVr0VVaF8KeWsF/EJYeZTiWZyubMwJsaZ2uW2U52\\n+VDE0RE0kz0fzYiCCMfuNNPg5V94lY3ImcmSI1qSjUpJsodqACqk4srmnwMZhICO\\n14F/WUknqmIBgFdHacluC6pqgHdKLMuPnp37bf7ACnQ/L2Pw77ZwrKRymUrzlQID\\nAQABo0IwQDAPBgNVHRMBAf8EBTADAQH/MB0GA1UdDgQWBBSOG3E+4lHiI+l0i91u\\nxG2Rca2NATAOBgNVHQ8BAf8EBAMCAoQwDQYJKoZIhvcNAQELBQADggEBAKgmxr6c\\nYmSNJOTPtjMFFDZHHX/7iwr+vqzC3nalr6ku8E3Zs0/IpwAtzqXp0eVVdPCWUY3A\\nQCUTt63GrqshBHYAxTbT0rlXFkqL8UkJvdZQ3XoQuNsqcp22zlQWGHxsk3YP97rn\\nltPI56smyHqPj+SBqyN/Vs7Vga9G8fHCfltJOdeisbmVHaC9WquZ9S5eyT7JzPAC\\n5dI5ZUunm0cgKFVbLfPr7ykClTPy36WdHS1VWhiCyS+rKeN7KYUvoaQN2U3hXesL\\nr2M+8qaPOSQdcNmg1eMNgxZ9Dh7SXtLQB2DAOuHe/BesJj8eRyENJCSdZsUOgeZl\\nMinkSy2d927Vts8=\\n-----END CERTIFICATE-----\"}"
--secure-environment-variables "HASURA_GRAPHQL_DATABASE_URL"="<database-url>"
--secure-environment-variables "HASURA_METADATA_DATABASE_URL"="<database-url>" "PG_DATABASE_URL"="<database-url>"
```
Above, we're using the `--secure-environment-variables` flag to pass two environment variables that contain sensitive
information. The `--secure-environment-variables` flag ensures that the values of these variables are encrypted at rest
and in transit. Hasura uses the `HASURA_METADATA_DATABASE_URL` variable to store its metadata and the `PG_DATABASE_URL`
variable to connect to the database. These can be the same database or different databases.
:::info Note
Check out the [Running with JWT](/auth/authentication/jwt.mdx#running-with-jwt) section for the usage of

6
docs/docs/deployment/deployment-guides/digital-ocean-one-click.mdx
View File

@ -284,8 +284,10 @@ cd /etc/hasura
vim docker-compose.yaml
...
# change the url to use a different database
HASURA_GRAPHQL_DATABASE_URL: <database-url>
# change the url to use a different database for your metadata
HASURA_METADATA_DATABASE_URL: <database-url>
# and here for your data using the same or different database as above
PG_DATABASE_URL: <database-url>
...
# type ESC followed by :wq to save and quit

2
docs/docs/deployment/deployment-guides/flightcontrol.mdx
View File

@ -56,7 +56,7 @@ Completed, it will look like this:
### Step 3: Configure your database
In the database section, Set the `Env Variable Name for Connection String` in Database settings to be
`HASURA_GRAPHQL_DATABASE_URL` and choose a region:
`HASURA_METADATA_DATABASE_URL` and choose a region:
<Thumbnail src="/img/deployment/flightcontrol-env-variable-name.png" alt="flightcontol enable console" />

7
docs/docs/deployment/deployment-guides/koyeb.mdx
View File

@ -32,7 +32,7 @@ To deploy Hasura to Koyeb quickly, click the button below:
[![Deploy to Koyeb](https://www.koyeb.com/static/images/deploy/button.svg)](https://app.koyeb.com/deploy?name=hasura-demo&type=docker&image=hasura/graphql-engine&env[HASURA_GRAPHQL_DATABASE_URL]=CHANGE_ME&env[HASURA_GRAPHQL_ENABLE_CONSOLE]=true&env[HASURA_GRAPHQL_ADMIN_SECRET]=CHANGE_ME&ports=8080;http;/)
On the configuration screen, set the `HASURA_GRAPHQL_DATABASE_URL` environment variable to the connection string for your database and the `HASURA_GRAPHQL_ADMIN_SECRET` environment variable to a secret value to access the Hasura Console.
On the configuration screen, set the `HASURA_METADATA_DATABASE_URL` (depicted as `HASURA_GRAPHQL_ENGINE_DATABASE_URL` in this screenshot) environment variable to the connection string for your database and the `HASURA_GRAPHQL_ADMIN_SECRET` environment variable to a secret value to access the Hasura Console.
Click the **Deploy** button when you are finished. When the deployment completes, you can [access the Hasura Console](#access-the-hasura-console).
@ -52,9 +52,10 @@ On the [Koyeb control panel](https://app.koyeb.com/), click the **Create App** b
4. In the **Environment variables** section, configure the environment variables required to properly run the Hasura GraphQL Engine:
- `HASURA_GRAPHQL_DATABASE_URL`: The environment variable containing the PostgreSQL URL, i.e. `postgres://<user>:<password>@<host>:<port>/<database>`. Since this value contains sensitive information, select the "Secret" type. Secrets are encrypted at rest and are ideal for storing sensitive data like API keys, OAuth tokens, etc. Choose "Create secret" in the "Value" drop-down menu and enter the secret value in the "Create secret" form.
- `HASURA_METADATA_DATABASE_URL`: Hasura requires a PostgreSQL database to store its metadata. This can be the same database as `PG_DATABASE_URL` or a different one. We strongly recommend using a secret to store this value.
- `PG_DATABASE_URL`: The environment variable containing the PostgreSQL URL, i.e. `postgres://<user>:<password>@<host>:<port>/<database>`. Since this value contains sensitive information, select the "Secret" type. Secrets are encrypted at rest and are ideal for storing sensitive data like API keys, OAuth tokens, etc. Choose "Create secret" in the "Value" drop-down menu and enter the secret value in the "Create secret" form.
- `HASURA_GRAPHQL_ENABLE_CONSOLE`: Set to `true`. This will expose and allow you to access the Hasura Console.
- `HASURA_GRAPHQL_ADMIN_SECRET`: The secret to access the Hasura Console. As with the `HASURA_GRAPHQL_DATABASE_URL`, we strongly recommend using a secret to store this value.
- `HASURA_GRAPHQL_ADMIN_SECRET`: The secret to access the Hasura Console. As with the other environment variables, we strongly recommend using a secret to store this value.
5. In the **Exposing your service** section, change the `Port` from `80` to `8080` to match the port that the `hasura/graphql-engine` Docker image app listens on. Koyeb uses this setting to perform application health checks and to properly route incoming HTTP requests. If you want the Hasura GraphQL Engine to be available on a specific path, you can change the default one (`/`) to the path of your choice.

8
docs/docs/deployment/deployment-guides/kubernetes.mdx
View File

@ -37,11 +37,11 @@ Edit `deployment.yaml` and set the right database url:
```yaml {2}
env:
- name: HASURA_GRAPHQL_DATABASE_URL
- name: HASURA_METADATA_DATABASE_URL
value: postgres://<username>:<password>@hostname:<port>/<dbname>
```
Examples of `HASURA_GRAPHQL_DATABASE_URL`:
Examples of `HASURA_METADATA_DATABASE_URL`:
- `postgres://admin:password@localhost:5432/my-db`
- `postgres://admin:@localhost:5432/my-db` _(if there is no password)_
@ -49,7 +49,7 @@ Examples of `HASURA_GRAPHQL_DATABASE_URL`:
:::info Note
- If your **password contains special characters** (e.g. #, %, $, @, etc.), you need to URL encode them in the
`HASURA_GRAPHQL_DATABASE_URL` env var (e.g. %40 for @).
`HASURA_METADATA_DATABASE_URL` env var (e.g. %40 for @).
You can check the [logs](#kubernetes-logs) to see if the database credentials are proper and if Hasura is able to
connect to the database.
@ -104,7 +104,7 @@ spec:
command: ["graphql-engine"]
args: ["serve", "--enable-console"]
env:
- name: HASURA_GRAPHQL_DATABASE_URL
- name: HASURA_METADATA_DATABASE_URL
value: postgres://<username>:<password>@hostname:<port>/<dbname>
- name: HASURA_GRAPHQL_ADMIN_SECRET
value: mysecretkey

2
docs/docs/deployment/downgrading.mdx
View File

@ -49,7 +49,7 @@ command on `graphql-engine` itself. The way to execute this command is
to run:
```bash
docker run -e HASURA_GRAPHQL_DATABASE_URL=$DATABASE_URL hasura/graphql-engine:<VERSION> graphql-engine downgrade --to-<NEW-VERSION>
docker run -e HASURA_METADATA_DATABASE_URL=$DATABASE_URL hasura/graphql-engine:<VERSION> graphql-engine downgrade --to-<NEW-VERSION>
```
You need to use a newer version of `graphql-engine` to downgrade to an

29
docs/docs/deployment/graphql-engine-flags/config-examples.mdx
View File

@ -259,7 +259,7 @@ provided to the server**
```bash
# env var
HASURA_GRAPHQL_METADATA_DATABASE_URL=postgres://<user>:<password>@<host>:<port>/<metadata-db-name>
HASURA_GRAPHQL_DATABASE_URL=postgres://<user>:<password>@<host>:<port>/<db-name>
PG_DATABASE_URL=postgres://<user>:<password>@<host>:<port>/<db-name>
# flag
--metadata-database-url=postgres://<user>:<password>@<host>:<port>/<metadata-db-name>
@ -269,7 +269,7 @@ HASURA_GRAPHQL_DATABASE_URL=postgres://<user>:<password>@<host>:<port>/<db-name>
In this case, Hasura GraphQL Engine will use the
`HASURA_GRAPHQL_METADATA_DATABASE_URL` to store the `metadata catalogue`
and starts the server with the database provided in the
`HASURA_GRAPHQL_DATABASE_URL`.
`PG_DATABASE_URL`.
**2. Only** `metadata database` **is provided to the server**
@ -285,27 +285,4 @@ In this case, Hasura GraphQL Engine will use the
`HASURA_GRAPHQL_METADATA_DATABASE_URL` to store the `metadata catalogue`
and starts the server without tracking/managing any database. _i.e_ a
Hasura GraphQL server will be started with no database. The user could
then manually track/manage databases at a later time.
**3. Only** `primary database` **is provided to the server**
```bash
# env var
HASURA_GRAPHQL_DATABASE_URL=postgres://<user>:<password>@<host>:<port>/<db-name>
# flag
--database-url=postgres://<user>:<password>@<host>:<port>/<db-name>
```
In this case, Hasura GraphQL Engine server will start with the database
provided in the `HASURA_GRAPHQL_DATABASE_URL` and will also use the
_same database_ to store the `metadata catalogue`.
**4. Neither** `primary database` **nor** `metadata database` **is
provided to the server**
Hasura GraphQL Engine will fail to startup and will throw an error
```bash
Fatal Error: Either of --metadata-database-url or --database-url option expected
```
then manually track/manage databases at a later time.

11
docs/docs/deployment/graphql-engine-flags/reference.mdx
View File

@ -44,15 +44,16 @@ the list of connected data sources.
:::info Note
This config option is supported to maintain backwards compatibility with `v1.x` Hasura instances. In versions `v2.0` and
above, databases can be connected using any custom environment variables of your choice.
This config option is supported to maintain backwards compatibility with `v1.x` Hasura instances. **In versions `v2.0`
and above, databases can be connected using any custom environment variables of your choice. Our `docker-compose.yaml`
files in the install manifests reference `PG_DATABASE_URL` as the environment variable to use for connecting to a
database, but this can be any plaintext value which does not start with `HASURA_`.**
:::
### Metadata Database URL
This Postgres database URL is used to store Hasura's Metadata. By default, the database configured using
`HASURA_GRAPHQL_DATABASE_URL` / `--database_url` will be used to store the Metadata. This can also be a URI of the form
This Postgres database URL is used to store Hasura's Metadata. This can also be a URI of the form
`dynamic-from-file:///path/to/file`, where the referenced file contains a postgres connection string, which will be read
dynamically every time a new connection is established. This allows the server to be used in an environment where
secrets are rotated frequently.
@ -68,7 +69,7 @@ secrets are rotated frequently.
:::info Note
Either one of the Metadata Database URL or the Database URL needs to be provided for Hasura to start.
THe metadata database URL needs to be set for Hasura to start.
:::

3
docs/docs/enterprise/sso/adfs.mdx
View File

@ -306,7 +306,8 @@ services:
environment:
HASURA_GRAPHQL_EE_LICENSE_KEY: <YOUR_EE_LICENSE_KEY>
HASURA_GRAPHQL_ADMIN_SECRET: <YOUR_ADMIN_SECRET>
HASURA_GRAPHQL_DATABASE_URL: postgres://postgres:postgrespassword@postgres:5432/postgres?sslmode=disable
HASURA_METADATA_DATABASE_URL: postgres://postgres:postgrespassword@postgres:5432/postgres?sslmode=disable
PG_DATABASE_URL: postgres://postgres:postgrespassword@postgres:5432/postgres?sslmode=disable
HASURA_GRAPHQL_ENABLE_CONSOLE: 'true'
HASURA_GRAPHQL_DEV_MODE: 'true'
HASURA_GRAPHQL_ENABLED_LOG_TYPES: startup,http-log,webhook-log,websocket-log,query-log

3
docs/docs/enterprise/sso/auth0.mdx
View File

@ -427,7 +427,8 @@ services:
environment:
HASURA_GRAPHQL_EE_LICENSE_KEY: <YOUR_EE_LICENSE_KEY>
HASURA_GRAPHQL_ADMIN_SECRET: <YOUR_ADMIN_SECRET>
HASURA_GRAPHQL_DATABASE_URL: postgres://postgres:postgrespassword@postgres:5432/postgres?sslmode=disable
HASURA_METADATA_DATABASE_URL: postgres://postgres:postgrespassword@postgres:5432/postgres?sslmode=disable
PG_DATABASE_URL: postgres://postgres:postgrespassword@postgres:5432/postgres?sslmode=disable
HASURA_GRAPHQL_ENABLE_CONSOLE: 'true'
HASURA_GRAPHQL_DEV_MODE: 'true'
HASURA_GRAPHQL_ENABLED_LOG_TYPES: startup,http-log,webhook-log,websocket-log,query-log

3
docs/docs/enterprise/sso/google-workspace.mdx
View File

@ -281,7 +281,8 @@ services:
environment:
HASURA_GRAPHQL_EE_LICENSE_KEY: <YOUR_EE_LICENSE_KEY>
HASURA_GRAPHQL_ADMIN_SECRET: <YOUR_ADMIN_SECRET>
HASURA_GRAPHQL_DATABASE_URL: postgres://postgres:postgrespassword@postgres:5432/postgres?sslmode=disable
HASURA_METADATA_DATABASE_URL: postgres://postgres:postgrespassword@postgres:5432/postgres?sslmode=disable
PG_DATABASE_URL: postgres://postgres:postgrespassword@postgres:5432/postgres?sslmode=disable
HASURA_GRAPHQL_ENABLE_CONSOLE: 'true'
HASURA_GRAPHQL_DEV_MODE: 'true'
HASURA_GRAPHQL_ENABLED_LOG_TYPES: startup,http-log,webhook-log,websocket-log,query-log

3
docs/docs/enterprise/sso/ldap.mdx
View File

@ -403,7 +403,8 @@ services:
environment:
HASURA_GRAPHQL_EE_LICENSE_KEY: <YOUR_EE_LICENSE_KEY>
HASURA_GRAPHQL_ADMIN_SECRET: <YOUR_ADMIN_SECRET>
HASURA_GRAPHQL_DATABASE_URL: postgres://postgres:postgrespassword@postgres:5432/postgres?sslmode=disable
HASURA_METADATA_DATABASE_URL: postgres://postgres:postgrespassword@postgres:5432/postgres?sslmode=disable
PG_DATABASE_URL: postgres://postgres:postgrespassword@postgres:5432/postgres?sslmode=disable
HASURA_GRAPHQL_ENABLE_CONSOLE: 'true'
HASURA_GRAPHQL_DEV_MODE: 'true'
HASURA_GRAPHQL_ENABLED_LOG_TYPES: startup,http-log,webhook-log,websocket-log,query-log

3
docs/docs/hasura-cli/quickstart.mdx
View File

@ -117,8 +117,7 @@ PG_DATABASE_URL: postgres://postgres:postgres@postgres:5432/postgres
```
We'll enter the name `default` for the ` Database Display Name` field. This name is used to identify the data source in
Hasura's Metadata and is not your database's name. Should you choose to use the `HASURA_GRAPHQL_DATABASE_URL`
environment variable instead, `default` is the default name assigned to your data source by Hasura.
Hasura's Metadata and is not your database's name.
Next, we'll choose `Environment Variable` from the `Connect Database Via` options; enter `PG_DATABASE_URL` as the name:

2
docs/docs/migrations-metadata-seeds/legacy-configs/config-v2/advanced/auto-apply-migrations.mdx
View File

@ -58,7 +58,7 @@ Example:
docker run -p 8080:8080 \
-v /home/me/my-project/migrations:/hasura-migrations \
-v /home/me/my-project/metadata:/hasura-metadata \
-e HASURA_GRAPHQL_DATABASE_URL=postgres://postgres:@postgres:5432/postgres \
-e HASURA_METADATA_DATABASE_URL=postgres://postgres:@postgres:5432/postgres \
hasura/graphql-engine:v1.2.0.cli-migrations-v2
```

4
docs/docs/migrations-metadata-seeds/legacy-configs/upgrade-v3.mdx
View File

@ -241,9 +241,7 @@ hasura scripts update-project-v3
Your project directory and `config.yaml` should be updated to v3.
The update script will ask for the name of database the current
Migrations and seeds correspond to. If you are starting Hasura with a
`HASURA_GRAPHQL_DATABASE_URL` then the name of the database should be
`default`.
Migrations and seeds correspond to.
## Continue using config v2

30
docs/docs/resources/upgrade-hasura-v2.mdx
View File

@ -173,26 +173,20 @@ A detailed changelog with all the new features introduced in Hasura v2 is availa
with Hasura v2 instances. Hasura v2 will assume the `v2` Metadata and Migrations belong to a database connected with
the name `default`.
- A new optional env var `HASURA_GRAPHQL_METADATA_DATABASE_URL` is now introduced. When set, this Postgres database is
used to store the Hasura Metadata. If not set, the database set using `HASURA_GRAPHQL_DATABASE_URL` is used to store
the Hasura Metadata.
Either one of `HASURA_GRAPHQL_METADATA_DATABASE_URL` or `HASURA_GRAPHQL_DATABASE_URL` needs to be set with a Postgres
database to start a Hasura v2 instance as Hasura always needs a Postgres database to store its metadata.
- The database set using the `HASURA_GRAPHQL_DATABASE_URL` env var is connected automatically with the name `default` in
Hasura v2 while updating an existing instance or while starting a fresh instance.
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.
- A new mandatory env var `HASURA_GRAPHQL_METADATA_DATABASE_URL` is now introduced and is mandatory for storing Hasura
Metadata.
- Custom env vars can now be used to connect databases dynamically at runtime.
- With support for multiple databases, older database specific env vars have been deprecated.
[See details](#hasura-v2-env-changes)
:::info Existing Metadata
`HASURA_GRAPHQL_METADATA_DATABASE_URL` must be the connection string for where your metadata existed previously.
:::
## Moving from Hasura v1 to Hasura v2 {#moving-from-hasura-v1-to-v2}
### Hasura v1 and Hasura v2 compatibility {#hasura-v1-v2-compatibility}
@ -206,14 +200,12 @@ instance**.
Post adding a database named `default`, the Hasura v2 instance should behave equivalently to the Hasura v1 instance and
all previous workflows will continue working as they were.
Refer to [connecting databases](/databases/overview.mdx) to add a database to Hasura v2.
Refer to [connecting databases](/databases/quickstart.mdx) to add a database to Hasura v2.
### Migrate Hasura v1 instance to Hasura v2
Hasura v2 is backwards compatible with Hasura v1. Hence simply updating the Hasura docker image version number and
restarting your Hasura instance should work seamlessly. The database connected using the `HASURA_GRAPHQL_DATABASE_URL`
env var will be added as a database with the name `default` automatically and all existing Metadata and Migrations will
be assumed to belong to it.
restarting your Hasura instance should work seamlessly.
:::info Note
@ -282,7 +274,7 @@ by reverting the Hasura docker image version and using the [downgrade command](/
the Hasura Metadata catalogue changes:
```bash
docker run -e HASURA_GRAPHQL_DATABASE_URL=$POSTGRES_URL hasura/graphql-engine:v2.0.0 graphql-engine downgrade --to-v1.3.3
docker run -e HASURA_METADATA_DATABASE_URL=$POSTGRES_URL hasura/graphql-engine:v2.0.0 graphql-engine downgrade --to-v1.3.3
```
:::info Note