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.

Last updated 19 November 2026View as Markdown

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 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.

  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) 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.

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=all

Disconnect a database

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

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

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.
Did this page help you?