mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-15 09:22:43 +03:00
docs: update database quickstart
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/8585 GitOrigin-RevId: b556d017eba8c73a024b1b430dbaf59cd1be03e5
This commit is contained in:
Rikin Kachhia
hasura-bot
parent
ff759bfbe1
commit
6a75ca1283
@ -7,7 +7,7 @@ keywords:
|
||||
- docs
|
||||
- databases
|
||||
- connect
|
||||
toc_max_heading_level: 2
|
||||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
@ -18,27 +18,41 @@ import Thumbnail from '@site/src/components/Thumbnail';
|
||||
|
||||
## Introduction
|
||||
|
||||
You can quickly and easily connect a new, existing, or demo database to Hasura GraphQL Engine in either Hasura Cloud or
|
||||
you can run Hasura Engine using Docker.
|
||||
You can quickly and easily connect a new, existing, or demo database to Hasura GraphQL Engine using the Hasura Console,
|
||||
CLI or API. You can also connect to multiple databases in order to build a unified GraphQL API.
|
||||
|
||||
:::tip Connect multiple databases
|
||||
:::info On-the-fly connecting and removing of databases
|
||||
|
||||
You can also connect to multiple databases in order to build a unified GraphQL API.
|
||||
In versions `v2.0.0` and above, databases can be connected and removed dynamically without having to restart the Hasura
|
||||
Engine instance.
|
||||
|
||||
:::
|
||||
|
||||
## Connect a database via the Hasura Console {#connect-database-v2-0}
|
||||
:::tip Connection methods
|
||||
|
||||
You can connect to databases by using environment variables, the raw connection string or connection parameters. It is
|
||||
recommended to use environment variables for better security _(as connection details set via a string will be exposed as
|
||||
part of the Hasura Metadata)_ as well as to allow configuring different databases in different environments _(like
|
||||
staging or production)_ easily.
|
||||
|
||||
:::
|
||||
|
||||
## On Hasura Cloud
|
||||
|
||||
<Tabs groupId="user-preference" className="api-tabs">
|
||||
<TabItem value="cloud" label="Hasura Cloud">
|
||||
<TabItem value="console" label="Console">
|
||||
|
||||
Hasura Cloud does not host databases, but does provide integrations with which you can connect databases from many 3rd
|
||||
party managed cloud providers. Check out the [list of supported databases](/databases/overview.mdx).
|
||||
|
||||
If you have [created your project with Hasura Cloud](/hasura-cloud/projects/create.mdx), click on the `Launch Console`
|
||||
button to open the Hasura Console in your browser.
|
||||
|
||||
<Thumbnail src="/img/databases/project_launch-console_2-17-0.png" alt="database setup with new database" />
|
||||
|
||||
Hasura Cloud does not host databases, but does provide integrations with which you can connect databases from many 3rd
|
||||
party managed cloud providers. Check out a [list of supported databases here](/databases/overview.mdx).
|
||||
On the Hasura Console, navigate to `Data -> Manage -> Connect Database`
|
||||
|
||||
### Option 1: Create and connect a new database
|
||||
|
||||
To get started quickly with a Postgres database, choose `Create New Database`:
|
||||
|
||||
@ -48,76 +62,26 @@ To get started quickly with a Postgres database, choose `Create New Database`:
|
||||
database"
|
||||
/>
|
||||
|
||||
Follow the prompts or [check out our detailed Neon connect page](/databases/postgres/neon.mdx). Hasura Cloud will
|
||||
integrate with your Neon account and manage the initial setup of a Postgres instance. You can always upgrade the
|
||||
instance and manage options later through your Neon account.
|
||||
Click on `Connect Neon Database` to create and connect a new Postgres database to your Hasura Project.
|
||||
|
||||
### Connect to an existing database
|
||||
<Thumbnail src="/img/cloud-dbs/neon/connect_neon_database.png" alt="Connect Neon database" width="700px" />
|
||||
|
||||
To use an existing database, choose `Connect existing database` and enter your database connection URL and enter your
|
||||
database connection string.
|
||||
|
||||
For help finding your particular connection string for your database provider check out our
|
||||
[databases page](/databases/overview.mdx).
|
||||
### Option 2: Connect an existing database
|
||||
|
||||
<Thumbnail src="/img/projects/connect-database_console_2.15.png" alt="database setup with new database" />
|
||||
To use an existing database, choose `Connect existing database`.
|
||||
|
||||
You can connect to databases by using environment variables, the raw connection string or connection parameters. It is
|
||||
recommended to use environment variables for better security _(as connection details set via a string will be exposed as
|
||||
part of the Hasura Metadata)_ as well as to allow configuring different databases in different environments _(like
|
||||
staging or production)_ easily.
|
||||
- Give the database a name, say `default`
|
||||
- Choose the database type from the list of [supported databases](/databases/overview.mdx#supported-databases)
|
||||
- Enter your database connection details
|
||||
- Click `Connect Database`
|
||||
|
||||
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`.
|
||||
<Thumbnail src="/img/getting-started/connect-db-cloud.png" alt="Enter URL for existing database" width="700px" />
|
||||
|
||||
### 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 connections
|
||||
from the Hasura Cloud IP address.
|
||||
|
||||
You can copy the IP address of your Hasura Engine instance from the copy icon in the `Hasura Cloud IP` field on the
|
||||
Project's details view which you can shortcut to by clicking on your Project name in the Console.
|
||||
|
||||
<Thumbnail src="/img/databases/cloud-console_shortcut-to-project-settings_2-17-0.png" alt="Hasura Cloud IP field" />
|
||||
|
||||
<Thumbnail src="/img/projects/project-general-ip-address_console_2.12.png" alt="Hasura Cloud IP field" />
|
||||
Check out [this section](#cloud-projects-create-allow-nat-ip) for other steps
|
||||
required to ensure connectivity to your database from Hasura Cloud if needed.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="docker" label="Docker">
|
||||
|
||||
If you've [spun up the Hasura Engine with Docker](/getting-started/docker-simple.mdx), you can access the Hasura Console
|
||||
by accessing it in a browser at the URL of your Hasura Engine instance, usually `http://localhost:8080`.
|
||||
|
||||
:::info Enable Hasura Console
|
||||
|
||||
To access the Hasura Console via and URL and not [via the CLI](/hasura-cli/commands/hasura_console.mdx) the
|
||||
`HASURA_GRAPHQL_ENABLE_CONSOLE` [environment variable](/deployment/graphql-engine-flags/reference.mdx##database-url) or
|
||||
`--enable-console` flag must be set to `true`.
|
||||
|
||||
:::
|
||||
|
||||
On the Hasura Console, navigate to the `Data` tab, you will see the "Connect Database" screen.
|
||||
|
||||
<Thumbnail
|
||||
src="/img/databases/databases_connect-database_2-17-0.png"
|
||||
alt="database setup with new database"
|
||||
width="1686px"
|
||||
/>
|
||||
|
||||
You can connect to databases by using environment variables, the raw connection string or connection parameters. It is
|
||||
recommended to use environment variables for better security _(as connection details set via a string will be 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>
|
||||
|
||||
## Connect a database via the Hasura CLI or API
|
||||
|
||||
<Tabs groupId="user-preference" className="api-tabs">
|
||||
<TabItem value="cli" label="CLI">
|
||||
|
||||
In your `config v3` project, head to the `/metadata/databases/databases.yaml` file and add the database configuration as
|
||||
@ -126,6 +90,7 @@ added and named default.
|
||||
|
||||
```yaml
|
||||
- name: <db_name>
|
||||
kind: postgres
|
||||
configuration:
|
||||
connection_info:
|
||||
database_url:
|
||||
@ -134,8 +99,8 @@ added and named default.
|
||||
idle_timeout: 180
|
||||
max_connections: 50
|
||||
retries: 1
|
||||
tables: []
|
||||
functions: []
|
||||
tables: []
|
||||
functions: []
|
||||
```
|
||||
|
||||
Apply the Metadata by running:
|
||||
@ -180,13 +145,110 @@ X-Hasura-Role: admin
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
:::info On-the-fly connecting and removing of databases
|
||||
### Allow connections from the Hasura Cloud IP {#cloud-projects-create-allow-nat-ip}
|
||||
|
||||
In versions `v2.0.0` and above, databases can be connected and removed dynamically without having to restart the Hasura
|
||||
Engine instance.
|
||||
When using Hasura Cloud, you may need to adjust your connection settings of your database provider to allow connections
|
||||
from the Hasura Cloud IP address.
|
||||
|
||||
You can copy the IP address of your Hasura Engine instance from the copy icon in the `Hasura Cloud IP` field on the
|
||||
Project's details view which you can shortcut to by clicking on your Project name in the Console.
|
||||
|
||||
<Thumbnail src="/img/databases/cloud-console_shortcut-to-project-settings_2-17-0.png" alt="Hasura Cloud IP field" />
|
||||
|
||||
<Thumbnail src="/img/projects/project-general-ip-address_console_2.12.png" alt="Hasura Cloud IP field" />
|
||||
|
||||
## On Hasura deployed via Docker
|
||||
|
||||
<Tabs groupId="user-preference" className="api-tabs">
|
||||
<TabItem value="console" label="Console">
|
||||
|
||||
If you've [spun up the Hasura Engine with Docker](/getting-started/docker-simple.mdx), you can access the Hasura Console
|
||||
by accessing it in a browser at the URL of your Hasura Engine instance, usually `http://localhost:8080`.
|
||||
|
||||
:::info Enable Hasura Console
|
||||
|
||||
To access the Hasura Console via the URL the
|
||||
`HASURA_GRAPHQL_ENABLE_CONSOLE` [environment variable](/deployment/graphql-engine-flags/reference.mdx#database-url) or
|
||||
the `--enable-console` flag must be set to `true`.
|
||||
|
||||
:::
|
||||
|
||||
On the Hasura Console, navigate to the `Data` tab, you will see the "Connect Database" screen.
|
||||
|
||||
- Give the database a name, say `default`
|
||||
- Choose the database type from the list of [supported databases](/databases/overview.mdx#supported-databases)
|
||||
- Enter your database connection details
|
||||
- Click `Connect Database`
|
||||
|
||||
<Thumbnail
|
||||
src="/img/databases/databases_connect-database_2-17-0.png"
|
||||
alt="database setup with new database"
|
||||
width="1686px"
|
||||
/>
|
||||
|
||||
</TabItem>
|
||||
<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.
|
||||
|
||||
```yaml
|
||||
- name: <db_name>
|
||||
kind: postgres
|
||||
configuration:
|
||||
connection_info:
|
||||
database_url:
|
||||
from_env: <DB_URL_ENV_VAR>
|
||||
pool_settings:
|
||||
idle_timeout: 180
|
||||
max_connections: 50
|
||||
retries: 1
|
||||
tables: []
|
||||
functions: []
|
||||
```
|
||||
|
||||
Apply the Metadata by running:
|
||||
|
||||
```bash
|
||||
hasura metadata apply
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="api" label="API">
|
||||
|
||||
Depending on the type of database, you can add a database using the
|
||||
[sources Metadata API](/api-reference/metadata-api/source.mdx).
|
||||
|
||||
For example:
|
||||
|
||||
```http
|
||||
POST /v1/metadata HTTP/1.1
|
||||
Content-Type: application/json
|
||||
X-Hasura-Role: admin
|
||||
|
||||
{
|
||||
"type": "pg_add_source",
|
||||
"args": {
|
||||
"name": "<db_name>",
|
||||
"configuration": {
|
||||
"connection_info": {
|
||||
"database_url": {
|
||||
"from_env": "<DB_URL_ENV_VAR>"
|
||||
},
|
||||
"pool_settings": {
|
||||
"retries": 1,
|
||||
"idle_timeout": 180,
|
||||
"max_connections": 50
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Hasura Metadata storage
|
||||
|
||||
When using Hasura Cloud, Metadata is stored for you in separate data storage to your connected database(s). When using
|
||||
|
||||
Loading…
Reference in New Issue
Block a user