# Connect a database to a project

Show every statement your managed PostgreSQL database runs on the project's Queries tab, beside what your traces saw, with no change to your app.

Traces show only the statements of sampled requests, and nothing when your app sends no traces. A
connected database adds what it measured itself: every call of every statement, background jobs
and migrations included. Replace _project-id_ with the project's id and _ewdb-0123456789ab_ with
the database's id.

## Prerequisites

- A Deutsche Cloud PostgreSQL database of your organization with `pg_stat_statements` enabled (see
  [Find slow queries](/docs/rds/guide/find-slow-queries) in Postgres). A database outside
  Deutsche Cloud, and a Document Database cluster, can be seen through traces only.
- Permission for `errors:UpdateProject` on the project **and** `rds:DescribeDBQueryInsights` on
  the database, to connect it. Disconnecting and dismissing a suggestion need only
  `errors:UpdateProject`.
- In the console, also `errors:ListProjects` on the project to open it (without it the project is
  not found) and `errors:GetEvents` on it to read the **Queries** tab (without it the tab says "You
  can see this project but not its queries."). Without `errors:UpdateProject` the tab has no
  connect or disconnect controls, and it offers only databases you have
  `rds:DescribeDBQueryInsights` on.

Connecting grants nobody anything. Everyone who reads the tab needs `rds:DescribeDBQueryInsights`
on the database to see its statements; without it they see "A connected database is not shown."
and only that a database is connected (its name too, with `rds:DescribeDBInstances`).

## Connect the database

A project can have up to 10 databases. Connecting is free.

**Console**
1. Open the project, then the **Queries** tab.
2. Choose **Connect a database** (**Connect another** when one is connected already).
3. For **Database**, choose the database.
4. Choose **Connect**.

When an app connected to the project (see [Connect an app](connect-an-app.md)) uses a PostgreSQL
database through its `DATABASE_URL`, the tab suggests it instead: "_my-app_ uses _orders_. Show
what _orders_ measures here?". Choose **Connect …** to connect it, or **Not now** to stop
suggesting it for this project, for everyone. The suggestion is shown only to people who could
connect the database.

**CLI**
```sh
dcloud errors databases connect project-id ewdb-0123456789ab
dcloud errors databases list project-id
```

**API**
```http
PUT /errors/api/projects/project-id/databases/ewdb-0123456789ab
```

The answer is `201` with `dbInstanceId`, `identifier`, `projectId` and `connected: true`, or `200`
when the database was connected already. `GET /errors/api/projects/project-id/databases`
lists the connected databases and the suggested ones;
`POST /errors/api/projects/project-id/databases/ewdb-0123456789ab/dismiss` stops a
suggestion.

**Terraform**
```hcl
resource "dcloud_errors_database_link" "web" {
  project_id     = "project-id"
  db_instance_id = "ewdb-0123456789ab"
}
```

Changing either id replaces the link. Import one with
`terraform import dcloud_errors_database_link.web <project-id>/<db-instance-id>`.

## Result

The database is read once a minute, and the first minute only sets the starting point: until the
second, the tab says "Connected; the first statements arrive within two minutes". The database's
events say who connected it, and the audit log's entry for the project names the database.

The **Queries** tab then lists every statement the connected databases measured, joined with the
statements of the project's traces by their text without values. Each statement says where it was
seen:

| Label             | Seen by                                                                                                                                           |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Database + traces | the database (every call) and sampled traces                                                                                                      |
| Database only     | the database, never a sampled trace: background jobs, migrations, other apps, or requests that were not sampled                                   |
| Traces only       | traces only: a database that is not connected, or a statement outside the 50 that took the most time in a minute, which is all the database keeps |

**Calls**, **Total**, **Mean**, **Rows/call** and the **Trend** come from the database when it
measured the statement, else from the traces; the number of transactions and **N+1** come from the
traces. **Time share** is of all the time listed. A statement the traces saw opens its page
across your projects; one only the database saw opens it in the database's query insights.

When every app connected to the project has its own database role, the tab opens on **My apps**,
the statements of those roles; **Whole database** shows everything the database ran. When an app
uses the master user, the tab shows the whole database.

The tab shows the statement text without values and its numbers, never values, bind parameters
or plans. Through the API:

```http
GET /errors/api/projects/project-id/queries/all?range=7d&role=all
```

## Disconnect a database

Disconnecting changes nothing in the database or in its query insights.

**Console**
1. Open the project, then the **Queries** tab.
2. Beside the database under **Measured by**, choose **Disconnect** (×).

**CLI**
```sh
dcloud errors databases disconnect project-id ewdb-0123456789ab
```

**API**
```http
DELETE /errors/api/projects/project-id/databases/ewdb-0123456789ab
```

The answer is `200` with `connected: false`.

**Terraform**
Remove the `dcloud_errors_database_link` resource and apply.

## When connecting is refused

- `403` "Forbidden" without `errors:UpdateProject` on the project or `rds:DescribeDBQueryInsights`
  on the database. Either refusal is recorded in the audit log.
- `404` "Database not found" for a database that is not one of your organization's; `404` "Not
  found" for a project that does not exist, an id that is not a database id (a Document Database
  cluster's included), or, when disconnecting, a database that is not connected.
- `400` "A project can be connected to at most 10 databases; disconnect one first." when the
  project has 10 already.

## Related

- [Find slow database queries](find-slow-database-queries.md)
- [Find slow queries](/docs/rds/guide/find-slow-queries) in Postgres
- `errors.databases.connect` · `dcloud errors databases connect` · `dcloud_errors_database_link`
