SQL Connector

The SQL connector provides live access to relational databases with 8 tools for schema inspection, querying, and statistical analysis. It supports PostgreSQL and MySQL.

Authentication

Provide a standard database connection string:

PostgreSQL

{
  "name": "Production Postgres",
  "source_type": "sql",
  "config": {
    "connection_string": "postgresql://agentcy:password@db.example.com:5432/myapp",
    "database_type": "postgresql",
    "schema": "public",
    "read_only": true
  }
}

MySQL

{
  "name": "Analytics MySQL",
  "source_type": "sql",
  "config": {
    "connection_string": "mysql://agentcy:password@db.example.com:3306/analytics",
    "database_type": "mysql",
    "read_only": true
  }
}

WARNING

Always use a read-only database user for the SQL connector. The read_only flag adds a safety layer, but a least-privilege database user is the primary line of defense.

Creating a Read-Only User

PostgreSQL:

CREATE USER agentcy WITH PASSWORD 'secure-password';
GRANT CONNECT ON DATABASE myapp TO agentcy;
GRANT USAGE ON SCHEMA public TO agentcy;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO agentcy;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO agentcy;

MySQL:

CREATE USER 'agentcy'@'%' IDENTIFIED BY 'secure-password';
GRANT SELECT ON analytics.* TO 'agentcy'@'%';
FLUSH PRIVILEGES;

Live Tools (8)

Tool	Description	Arguments
sql_list_tables	List all tables in the database or schema	schema?
sql_describe_table	Get column names, types, nullability, defaults, and constraints	table, schema?
sql_query	Execute a read-only SQL query and return results	query, limit?
sql_list_indexes	List indexes on a table with columns and uniqueness	table, schema?
sql_list_constraints	List constraints including foreign keys and their references	table?, schema?
sql_table_stats	Get row counts, table size, and column statistics	table, schema?
sql_list_views	List views with their definitions	schema?
sql_explain_query	Get the execution plan for a query	query

TIP

The sql_query tool enforces a read_only transaction mode. INSERT, UPDATE, DELETE, and DDL statements are rejected even if the database user has write permissions.

Example: Agent Using SQL Tools

User: "What's the schema of the users table and how many rows does it have?"

Agent: Let me check the users table.
→ Calls sql_describe_table(table: "users")
→ Calls sql_table_stats(table: "users")
→ Reports:
  "The users table has 12 columns:
   - id (uuid, PK)
   - email (varchar, unique, not null)
   - name (varchar)
   - created_at (timestamptz, not null)
   - ...
   Total rows: 45,231. Table size: 18 MB."

ETL Ingestion

Nodes Created

Node Label	Properties	Source
Database	name, type (postgresql/mysql), host, port	Connection
Table	name, schema, row_count, size_bytes, column_count	Information schema
Column	name, data_type, nullable, default_value, is_primary_key	Information schema
Index	name, table_name, columns, is_unique, type	Information schema
ForeignKey	name, from_table, from_columns, to_table, to_columns	Information schema
View	name, schema, definition	Information schema

Relationships Created

Relationship	From	To
CONTAINS	Database	Table, View
HAS_COLUMN	Table	Column
HAS_INDEX	Table	Index
REFERENCES	Table	Table (via ForeignKey)
FOREIGN_KEY	Column	Column
DERIVED_FROM	View	Table

Graph Queries

-- Find all tables referencing the users table
MATCH (t:Table)-[:REFERENCES]->(users:Table {name: "users"})
RETURN t.name, t.row_count

-- Find tables without indexes (potential performance issues)
MATCH (t:Table)
WHERE NOT (t)-[:HAS_INDEX]->()
AND t.row_count > 1000
RETURN t.name, t.row_count
ORDER BY t.row_count DESC

-- Map the full schema graph
MATCH (t:Table)-[:HAS_COLUMN]->(c:Column)
WHERE t.schema = "public"
RETURN t.name, collect({name: c.name, type: c.data_type}) AS columns

Configuration Reference

Field	Type	Default	Description
connection_string	string	required	Database connection URL
database_type	string	auto-detected	postgresql or mysql
schema	string	public (PG)	Schema to scope ingestion and tools to
read_only	bool	true	Enforce read-only queries
max_query_rows	int	1000	Maximum rows returned by sql_query
query_timeout_secs	int	30	Query execution timeout
ssl_mode	string	prefer	SSL mode: disable, prefer, require, verify-ca, verify-full
ssl_ca_cert	string	--	CA certificate for SSL connections
sync_views	bool	true	Include views in ingestion
sync_indexes	bool	true	Include indexes in ingestion
exclude_tables	string[]	[]	Tables to exclude from ingestion

Connection String Formats

# PostgreSQL
postgresql://user:password@host:5432/database
postgresql://user:password@host:5432/database?sslmode=require

# MySQL
mysql://user:password@host:3306/database
mysql://user:password@host:3306/database?ssl-mode=REQUIRED

Troubleshooting

Error	Cause	Fix
Connection refused	Database is unreachable	Verify host, port, and network/firewall rules
Authentication failed	Invalid credentials	Check username and password
Database does not exist	Wrong database name in connection string	Verify the database name
Permission denied for table	User lacks SELECT on one or more tables	Grant SELECT permissions
SSL connection required	Server requires SSL but client didn't use it	Add ?sslmode=require to connection string
Query timeout	Query exceeded the configured timeout	Increase query_timeout_secs or optimize the query