SQL Agent
The SQL tool gives agents the ability to query any SQLAlchemy-compatible database — PostgreSQL, MySQL, SQLite, and SQL Server. Agents can explore schemas, run queries, and surface data without needing to know the database structure in advance.
Tools
| Tool | Description |
|---|---|
sql_query | Execute a SQL query and return results as a table |
sql_list_tables | List all tables in the configured database |
sql_describe_table | Get the schema (columns, types, constraints) for a table |
Setting up database connections
Go to Settings → Databases and add a connection:
| Field | Description |
|---|---|
| Name | Friendly name for the connection |
| Type | postgres, mysql, sqlite, or mssql |
| Connection string | SQLAlchemy-compatible URL |
| Description | Optional notes about what's in this database |
Connection string formats
# PostgreSQL
postgresql://user:password@host:5432/dbname
# MySQL
mysql+pymysql://user:password@host:3306/dbname
# SQLite
sqlite:///path/to/database.db
# SQL Server
mssql+pyodbc://user:password@host/dbname?driver=ODBC+Driver+18+for+SQL+Server
Assigning databases to agents
In the agent editor, set db_configs to the list of DB config IDs the agent should have access to:
"db_configs": ["db-config-id-1", "db-config-id-2"]
The agent can query any of the assigned databases and automatically discovers which database has the data it needs by listing tables.
Write access
By default, only SELECT, SHOW, and DESCRIBE queries are allowed. To enable write operations (INSERT, UPDATE, DELETE), set allow_db_write: true in settings.
Enable allow_db_write only for agents that explicitly need to modify data. Consider creating a separate agent with a limited tool set for write operations.
Example agent prompts
What are the top 10 products by revenue in Q3 2024?
Show me all users who haven't logged in for more than 90 days.
Compare daily sign-ups this week vs last week and plot the trend.
Schema caching
After you add a database, Synapse can cache its schema (table names, columns, types) to speed up queries. Click Refresh Schema in the database settings to update the cache. The cached schema is injected into the agent's context so it knows the structure before running any queries.
Default SQL connection
For the built-in coding agent, set DATABASE_URL in the environment:
DATABASE_URL=postgres://user:password@localhost:5432/mydb
This is separate from the per-agent DB configs in settings — it provides a default connection for the coding agent's general use.