Skip to content

Postgres Setup Beta ​

If your team runs its own Postgres database -- a billing system, an internal reporting store, a homegrown tool -- connect it to Junto and ask questions about it in plain language. The agent finds the right tables, checks their columns, writes a SQL query, and reports the answer along with the table, filter, and time range it used.

The connection is read-only. The agent can list tables, describe them, run SELECT queries, and explain how a query would run. It can never insert, update, or delete data, or change the database's structure.

Postgres is an Internal integration: it connects a database your MSP runs, not a customer's. It appears under Internal on the Integrations page, next to Sentry and Linear. Junto supports one Postgres connection per organization, and there's no company mapping: the agent sees whatever the database user can read.

Prerequisites ​

  • A Junto Admin or Owner account
  • A Postgres database reachable from the internet at a public host name or IP address, with TLS (SSL) enabled
  • A database user that can connect from Junto and read the tables you want the agent to use. A user limited to SELECT is strongly recommended.

Step 1: Create a Read-Only Database User ​

Junto runs every query in a read-only transaction, but the database user is the real safeguard. Create a dedicated user that can only read the tables the agent needs. For example, to grant read access to every table in the public schema:

sql
CREATE ROLE junto_reader WITH LOGIN PASSWORD 'choose-a-strong-password';
GRANT CONNECT ON DATABASE your_database TO junto_reader;
GRANT USAGE ON SCHEMA public TO junto_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO junto_reader;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO junto_reader;

ALTER DEFAULT PRIVILEGES covers only tables later created by the role that runs it, so run the snippet as the role that owns your tables. Grant SELECT on fewer tables, or on views, to narrow what the agent can see. Then make sure the server accepts the connection:

  • Your firewall or cloud security group allows inbound connections to the database port.
  • The server's pg_hba.conf allows the user to connect over SSL.

Step 2: Configure in Junto ​

  1. Go to Settings > Integrations, and under Internal, open Postgres.

  2. Click Add configuration.

  3. Complete the form:

    FieldWhat to enter
    HostThe server's public host name, like db.example.com, or its public IP address. Enter the host only, with no scheme, port, or path.
    PortUsually 5432
    DatabaseThe name of the database the agent will read
    UsernameThe database user from Step 1
    PasswordThat user's password. It is encrypted when stored.
    Verify the server certificateTurn on when the server has a certificate from a public certificate authority. Leave off for a self-signed certificate. The connection is encrypted either way.
    ActiveLeave on. Turn it off later to pause agent access without deleting the connection.
  4. Click Create configuration. Junto connects to the database before saving, so a wrong host, password, or database name is rejected with an error in the dialog. On success a Configuration created notice names the database.

  5. Click Test connection to confirm the connection at any time. A successful test reports Connected to the database name database.

The connection shows the database name, the user and host:port it connects as, the PostgreSQL server version, and an Active or Inactive status. Add configuration is unavailable once a connection exists.

Database User Warnings ​

When Junto connects, it checks what the database user is allowed to do and warns you if the user can do more than read:

  • This database user is a superuser -- Connect with a user that can only read the tables the agent needs.
  • This database user can change data -- Junto only runs read-only queries, but a user limited to SELECT is safer.

The warning doesn't block saving. To clear it, switch to a read-only user, or revoke the extra privileges and click Test connection again.

What the Agent Can Do ​

CapabilityWhat Junto can doRisk level
List tablesList every table and view the database user can read, with its schema, type, estimated row count, and comment. Filter by schema or by part of a table nameLow
Describe tableRead one table's columns (name, type, nullable, default, and comment), its primary, foreign, and unique keys, its indexes, and its estimated row countLow
Run queryRun one SELECT statement and read the results a page at a timeLow
Explain queryShow how the database would run a SELECT -- the planner's estimated cost and rows per step -- without running itLow

All Postgres tools are read-only. Read-only tools do not require approval: each ships with Approval set to Automatic and is visible to all staff. Admins can change either setting per tool under Tool Policies.

How the Agent Queries ​

  • Schema first: The agent lists tables and describes the ones it needs before writing a query, rather than guessing table or column names.
  • The database does the math: The agent counts, sums, groups, and filters in SQL instead of reading every row.
  • One statement, read-only: Each query is a single SELECT (a WITH ... SELECT or VALUES also works). INSERT, UPDATE, DELETE, schema changes, and a second statement are refused. Each query runs in its own read-only transaction that is never committed.
  • Time limit: A query that runs longer than 15 seconds is cancelled. The agent can then explain the query to find a slow step and narrow it with a filter on an indexed column or a smaller date range.
  • Paging: Results come back up to 500 rows at a time; ask for more to continue. Long values are shortened to about 2,000 characters, and binary values show only their size. Paging re-runs the query, so the agent adds an ORDER BY to keep pages consistent. Paging stops after 50,000 rows; aggregate in SQL instead.
  • Row contents are data: Text stored in the database is treated as data, never as instructions to the agent.

Where the Tools Are Available ​

Postgres tools are available in Explore and through your connected MCP client. They aren't used in ticket chat, during automatic ticket triage, or in runbooks.

Example requests:

  • "What tables are in our Postgres database?"
  • "How many invoices were issued last month, grouped by status?"
  • "Which customers in the billing database have an overdue balance over $1,000?"
  • "Describe the contracts table and tell me how it joins to customers."
  • "This query timed out -- explain it and suggest a faster version."

Managing the Connection ​

  • Update the connection: Click Edit, change any field, and click Update configuration. Leave Password blank to keep the stored password. Junto re-checks the connection before saving a new host, port, database, user, password, or TLS setting.
  • Pause the integration: Click Edit, turn off Active, and save. The connection stays saved and the agent loses access until you turn it back on.
  • Disconnect: Click Disconnect and confirm. This removes Junto's saved connection details and password. Nothing changes in your database.

Troubleshooting ​

  • "The database host must be reachable at a public address" -- Junto connects only to public addresses. A private, internal, or VPN-only address, or a host name that resolves to one, is refused. Expose the database at a public address with TLS, or use a managed database's public endpoint.
  • "Enter the database host name only" -- Remove any postgres:// prefix, port, or path from Host, and put the port in Port.
  • "Could not connect to the database" -- Check the host and port, that your firewall allows inbound connections, and that the server has SSL enabled. If the server uses a self-signed certificate, turn off Verify the server certificate.
  • "The database rejected the username or password" -- Check the credentials, then update the configuration.
  • "The database refused this user" -- The server's pg_hba.conf doesn't allow this user to connect from Junto over SSL. Add a matching host or hostssl entry for the user and database, then reload the server.
  • "That database does not exist on the server" -- Check the spelling of Database. Database names are case-sensitive.
  • "The database has no free connections" -- The server reached its connection limit. Try again shortly, or raise the limit.
  • A query timed out -- Ask the agent to explain the query, then narrow it with a WHERE clause on an indexed column or a smaller date range.
  • "The database role is not allowed to do that" -- The database user can't read that table. Grant it SELECT in the database if the agent should use it.
  • A table is missing from the list -- Only tables and views the database user can read are listed. Grant SELECT on the table and ask again.
  • The agent doesn't use Postgres in ticket chat -- Postgres tools are only available in Explore chat and connected MCP clients.