hasura/graphql-engine
1
0
Fork 0
mirror of https://github.com/hasura/graphql-engine.git synced 2024-12-14 17:02:49 +03:00
Code Issues Projects Releases Wiki Activity

docs: update database quickstart

Browse Source 
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/8585
GitOrigin-RevId: b556d017eba8c73a024b1b430dbaf59cd1be03e5
This commit is contained in:
Rikin Kachhia 2023-04-03 13:41:19 +05:30 committed by hasura-bot
parent ff759bfbe1
commit 6a75ca1283
1 changed files with 137 additions and 75 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -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:
@ -134,8 +99,8 @@ added and named default.
idle_timeout: 180 idle_timeout: 180
max_connections: 50 max_connections: 50
retries: 1 retries: 1
tables: [] tables: []
functions: [] functions: []
``` ```
Apply the Metadata by running: Apply the Metadata by running:
@ -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