mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-15 01:12:56 +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
|
- docs
|
||||||
- databases
|
- databases
|
||||||
- connect
|
- connect
|
||||||
toc_max_heading_level: 2
|
toc_max_heading_level: 3
|
||||||
---
|
---
|
||||||
|
|
||||||
import Tabs from '@theme/Tabs';
|
import Tabs from '@theme/Tabs';
|
||||||
@ -18,27 +18,41 @@ import Thumbnail from '@site/src/components/Thumbnail';
|
|||||||
|
|
||||||
## Introduction
|
## Introduction
|
||||||
|
|
||||||
You can quickly and easily connect a new, existing, or demo database to Hasura GraphQL Engine in either Hasura Cloud or
|
You can quickly and easily connect a new, existing, or demo database to Hasura GraphQL Engine using the Hasura Console,
|
||||||
you can run Hasura Engine using Docker.
|
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">
|
<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`
|
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.
|
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" />
|
<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
|
On the Hasura Console, navigate to `Data -> Manage -> Connect Database`
|
||||||
party managed cloud providers. Check out a [list of supported databases here](/databases/overview.mdx).
|
|
||||||
|
### Option 1: Create and connect a new database
|
||||||
|
|
||||||
To get started quickly with a Postgres database, choose `Create 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"
|
database"
|
||||||
/>
|
/>
|
||||||
|
|
||||||
Follow the prompts or [check out our detailed Neon connect page](/databases/postgres/neon.mdx). Hasura Cloud will
|
Click on `Connect Neon Database` to create and connect a new Postgres database to your Hasura Project.
|
||||||
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.
|
|
||||||
|
|
||||||
### 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
|
### Option 2: Connect an existing database
|
||||||
[databases page](/databases/overview.mdx).
|
|
||||||
|
|
||||||
<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
|
- Give the database a name, say `default`
|
||||||
recommended to use environment variables for better security _(as connection details set via a string will be exposed as
|
- Choose the database type from the list of [supported databases](/databases/overview.mdx#supported-databases)
|
||||||
part of the Hasura Metadata)_ as well as to allow configuring different databases in different environments _(like
|
- Enter your database connection details
|
||||||
staging or production)_ easily.
|
- Click `Connect Database`
|
||||||
|
|
||||||
A database can be connected to using the `HASURA_GRAPHQL_DATABASE_URL` environment variable as well in which case it
|
<Thumbnail src="/img/getting-started/connect-db-cloud.png" alt="Enter URL for existing database" width="700px" />
|
||||||
gets added automatically as a database named `default`.
|
|
||||||
|
|
||||||
### Allow connections from the Hasura Cloud IP {#cloud-projects-create-allow-nat-ip}
|
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.
|
||||||
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" />
|
|
||||||
|
|
||||||
</TabItem>
|
</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">
|
<TabItem value="cli" label="CLI">
|
||||||
|
|
||||||
In your `config v3` project, head to the `/metadata/databases/databases.yaml` file and add the database configuration as
|
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
|
```yaml
|
||||||
- name: <db_name>
|
- name: <db_name>
|
||||||
|
kind: postgres
|
||||||
configuration:
|
configuration:
|
||||||
connection_info:
|
connection_info:
|
||||||
database_url:
|
database_url:
|
||||||
@ -180,13 +145,110 @@ X-Hasura-Role: admin
|
|||||||
</TabItem>
|
</TabItem>
|
||||||
</Tabs>
|
</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
|
When using Hasura Cloud, you may need to adjust your connection settings of your database provider to allow connections
|
||||||
Engine instance.
|
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
|
## Hasura Metadata storage
|
||||||
|
|
||||||
When using Hasura Cloud, Metadata is stored for you in separate data storage to your connected database(s). When using
|
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