Skip to main content

SQL connectors: PostgreSQL and MySQL

For Studio users with a PostgreSQL or MySQL database and a database user whose grants match what agents may read. The form is the same for both; only Database Type differs.

Before you start: make the database reachable over TLS from the deployment on the port you will enter. A database on your own network must be in one of the deployment's internal service ranges, which an administrator sets under Network on its Overview in Organisations (Data connectors); a public one must accept the deployment's egress address (shown as Deployment egress IP on the Snowflake form). Studio connects with sslmode=require to PostgreSQL and with TLS by default to MySQL; with verify-ca or verify-full it also trusts the certificate authorities an administrator added to the deployment.

Steps​

  1. Open Data Connectors, click Create Connector, choose SQL Database and fill Connector Name, Description and Connector Guide (write what the database holds; step 5 expands it).
  2. In Connection Configuration ("Where the database lives. Credentials are entered below and stored in AWS Secrets Manager."):
    • Database Type: PostgreSQL or MySQL.
    • Host (placeholder localhost) and Port (placeholder 5432, PostgreSQL's port; type your MySQL port). Neither is marked required, but the test needs both.
    • Database Name: required.
    • Schema (Optional) (placeholder public): for PostgreSQL, Studio's own queries use it as the search path; leave it blank for MySQL.
  3. Enter Username and Password.
  1. Click Test Connection. Studio connects with a 10-second timeout and runs SELECT 1; a tick reads "Connection successful". Nothing is saved.
  2. Click Explore Schema & Enrich Guide. Studio reads tables, columns, relationships and a five-row sample per table and streams a proposed guide. Edit it, then click Accept & Use This Guide (or Discard to keep your text). The result line reads "Schema exploration and guide enrichment completed successfully!".
  1. Click Create Connector (v1). It is enabled when name, description and guide are filled, a database type and database name are set, username and password are entered and, once a test has passed, you have accepted an explored guide.
  2. Open the agent, choose Configure, and add the connector (Agents: configure and activate).

What you should see​

The list shows the connector as SQL "(v1)", Active. The detail page's Configuration shows database type, host, port, database and schema; Credentials shows the username and a masked password with a View toggle.

In chat​

Ask the agent a question about the data. The agent runs read-only queries through its connector query tool, which executes each statement on Studio's connector service and returns only the rows (200 by default, at most 1,000); the guide tells it which tables and columns to use. When a step needs more than that, its code in the execution environment can connect itself with SQLAlchemy and the PostgreSQL or MySQL driver, but only to a port the environment may use: 443 always, and on a private deployment the ports an administrator approved for the internal service ranges (Execution environments). Credentials are read from the run's environment and are never printed or shown to you.

Notes​

  • Read-only at run time. Queries through the connector accept one statement per request, and only DESC, DESCRIBE, EXPLAIN, SELECT, SHOW and WITH (a WITH may not contain data-modifying or DDL keywords). Anything else is refused: "Statement type 'INSERT' is not allowed. Only read-only statements are permitted: DESC, DESCRIBE, EXPLAIN, SELECT, SHOW, WITH." There is no write mode. When a process must write, have the agent write its proposals as run files and load them with your own process (the loader pattern).
  • Timeouts and caps: 10 seconds to connect (test and exploration); 60 seconds per statement on Studio's own queries (a PostgreSQL statement timeout set server-side; a MySQL read and write timeout); 1,000 rows returned; 5 sample rows per table.
  • Two things connect to the database: Studio's connector service (Test Connection, exploration and the agent's query tool), and agent code in the execution environment. The connector service reaches any port; the execution environment reaches 443 and, on a private deployment, the approved ports to the internal service ranges. So a test can pass while agent code cannot connect on 5432 or 3306: ask an administrator to approve the port, or let the agent use its query tool.
  • "Connection failed: ...": the driver's error follows the colon; check host, port, firewall, TLS and credentials. "Missing required connection parameters: host, port, or database_name": fill Host and Port.
  • Create Connector (v1) disabled after a passing test: run Explore Schema & Enrich Guide and accept a guide.