> ## Documentation Index
> Fetch the complete documentation index at: https://docs.incident.io/llms.txt
> Use this file to discover all available pages before exploring further.
# PostgreSQL
> Query your PostgreSQL database during an investigation to confirm what the data actually shows.
PostgreSQL is a relational database. Connect one and investigations can run read-only SQL against it, checking the rows directly when that's the fastest way to confirm a hypothesis, like whether a record is in the state the symptoms suggest or when a value last changed.
PostgreSQL connects directly, with its own host and credentials. See [How telemetry
works](/investigations/connect/telemetry/how-it-works) for how investigations query your stack, and the [telemetry
overview](/investigations/connect/telemetry/overview) for how data sources fit together.
## What we support
Investigations query PostgreSQL with read-only SQL. They write the query, run it for the window that matters, and read back the results, joining across tables, filtering and aggregating, and reading from tables, views, and materialized views.
### Exploring your schema
Investigations don't need you to describe your database. They learn its shape on their own: the tables you have, their columns and types, primary and foreign keys, and how tables relate. From there they explore progressively, starting with an overview of the database, then pulling fuller detail on the specific tables a question turns out to need, rather than loading everything up front. That keeps queries accurate against large schemas and grounded in tables that actually exist.
How investigations learn and use this structure is covered in [How telemetry works](/investigations/connect/telemetry/how-it-works#learning-your-stack).
Investigations only ever read from your database; they never write. Connect with a **read-only** database user so that
guarantee is enforced on your side, not just trusted.
## Security
Investigations query your database to read from it, never to change it, and that guarantee is enforced in several independent layers rather than left to trust.
**Every connection is read-only, and stays that way.** Connections open in read-only transaction mode and re-assert it before each query, so a session can't be flipped into a writable state mid-flight. We recommend connecting a read-only database user too, so the guarantee holds on your side as well.
**Every query is parsed and checked before it runs.** Each query is parsed with PostgreSQL's own parser and must be a single `SELECT`. Anything that writes or changes structure, bundles multiple statements into one request, or reaches a write path another way is rejected. The functions a query may call are allowlisted to safe, read-only ones, so anything unrecognized is blocked rather than allowed by default.
**Sensitive system tables are off limits.** Queries can't read PostgreSQL's internal tables for credentials, roles, other sessions' activity, or server configuration, regardless of what the connected user could otherwise see.
**Queries can't overload your database.** Every query runs under a timeout and returns a capped number of rows, so a broad or expensive query stays bounded rather than running away. We hold only a small number of connections to your database, keep none open idle, and recycle them regularly, and we give up quickly on a database we can't reach.
For more on how we handle your data during AI processing, see our [Trust Center](https://trust.incident.io/).
## Connecting PostgreSQL
Connect PostgreSQL directly with its connection details.
**What you'll need:**
* The **host** and **port** of your database (port defaults to 5432).
* The **database name** to connect to.
* A **username** and **password**.
* The **SSL mode** to use, and any **client certificate**, **client key**, or **CA certificate** your database requires. Mutual TLS is supported for environments that need it.
1. From the [Investigations settings](https://app.incident.io/~/investigations), add a telemetry data source and choose **PostgreSQL**.
2. Enter the connection details and credentials, then test the connection.
3. Once connected, the database is enabled for investigations. You can disable it at any time.
## Best practice
* Connect a **read-only** user. Investigations only ever read, and a read-only user makes that enforceable on your side.
* Point it at a **replica** rather than your primary, so investigation queries never compete with production traffic.
* Grant access to the tables investigations should see and no more. They explore only what the user can read.
## Related
How providers, capabilities, and data sources fit together.
How investigations explore your schema and query your data.