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_statementsenabled (see Find slow queries in Postgres). A database outside Deutsche Cloud, and a Document Database cluster, can be seen through traces only. - Permission for
errors:UpdateProjecton the project andrds:DescribeDBQueryInsightson the database, to connect it. Disconnecting and dismissing a suggestion need onlyerrors:UpdateProject. - In the console, also
errors:ListProjectson the project to open it (without it the project is not found) anderrors:GetEventson it to read the Queries tab (without it the tab says "You can see this project but not its queries."). Withouterrors:UpdateProjectthe tab has no connect or disconnect controls, and it offers only databases you haverds:DescribeDBQueryInsightson.
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.
- Open the project, then the Queries tab.
- Choose Connect a database (Connect another when one is connected already).
- For Database, choose the database.
- Choose Connect.
When an app connected to the project (see Connect an app) 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.
dcloud errors databases connect project-id ewdb-0123456789ab
dcloud errors databases list project-idPUT /errors/api/projects/project-id/databases/ewdb-0123456789abThe 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.
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:
GET /errors/api/projects/project-id/queries/all?range=7d&role=allDisconnect a database
Disconnecting changes nothing in the database or in its query insights.
- Open the project, then the Queries tab.
- Beside the database under Measured by, choose Disconnect (×).
dcloud errors databases disconnect project-id ewdb-0123456789abDELETE /errors/api/projects/project-id/databases/ewdb-0123456789abThe answer is 200 with connected: false.
Remove the dcloud_errors_database_link resource and apply.
When connecting is refused
403"Forbidden" withouterrors:UpdateProjecton the project orrds:DescribeDBQueryInsightson 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.