Databases

PostgreSQL

Connect a PostgreSQL database or read replica to TraceX with a read-only user. Includes the SQL to create the user, the connection fields and how queries are checked.

Connect a PostgreSQL database, ideally a read replica, with a read-only user. Works with self-hosted PostgreSQL and managed services such as Amazon RDS and Aurora, Google Cloud SQL, Azure Database for PostgreSQL, Supabase and Neon.

Why connect PostgreSQL

Most production issues are about specific records: an order that didn’t ship, a payment stuck in pending_capture, a customer who can’t sign in. With the database connected, TraceX looks those records up instead of guessing. It checks their state, the rows around them and how many others are affected, and uses that as evidence.

Before you start

Create a dedicated read-only user. Adjust the database and schema names:

CREATE ROLE tracex_readonly LOGIN PASSWORD '<strong password>';
GRANT CONNECT ON DATABASE production TO tracex_readonly;
GRANT USAGE ON SCHEMA public TO tracex_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO tracex_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO tracex_readonly;

The last line makes tables created later readable too. Repeat the USAGE and SELECT lines for each extra schema. Leave out tables TraceX shouldn’t see, such as ones holding secrets.

TraceX connects from the internet. If your database only accepts known addresses or sits in a private network, contact TraceX support about network access before you connect.

Connect

In the dashboard, open Integrations → PostgreSQL and fill in:

Field	Value
Host	`db.acme.com`
Port	`5432` (optional)
Database	`production`
Username	`tracex_readonly`
Password	the user’s password

TraceX tests the connection, reads the schema, and is ready for investigations. The password is stored encrypted and never shown again.

How TraceX queries it

Every query TraceX writes is checked before it runs:

it must be a single read-only statement: no writes, no schema changes, no locks, no file or remote functions;
it runs in a read-only transaction with row and time limits, so a query can’t slow your database down;
results are summarized for the investigation, and secrets in them are masked before an AI model sees them.

TraceX also reads the schema (tables or collections, columns or fields) when you connect, so it writes queries against names that really exist. Add notes about what a table is for in the company profile: they help it pick the right table first time.

Example

Order 48213 has been stuck in pending_capture since this morning.

TraceX runs SELECT … FROM orders WHERE id = 48213, then reads the matching rows in payments and payment_attempts, counts how many other orders entered pending_capture after 09:00, and uses the result to separate “one bad order” from “the capture job stopped”.

Troubleshooting

Problem	What to check
Connection times out	The database must be reachable from the internet. If it only accepts known addresses or sits in a private network, contact support about network access before connecting.
Authentication failed	Re-check the username and password or key, and that the user is allowed to sign in from outside your network.
Connected, but tables are missing	The user needs read access to those tables or schemas. Grant it, then reconnect so TraceX re-reads the schema.
Answers use the wrong table	Add a note about what each table is for in the company profile.

Remove access

Disconnect PostgreSQL in Integrations, and drop the user: DROP ROLE tracex_readonly; (after revoking its grants).