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 |
|---|---|
run_sql_query | Execute a SQL query and return results as a table |
list_tables | List all tables in the configured database |
get_table_schema | Get the schema (columns, types, constraints) for a table |
Setting up database connections
Go to Settings → Databases (self-hosted, Settings → DB configs) 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+ServerAssigning 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), turn on Database write access under Settings → General (the allow_db_write setting). On Cloud, tick Allow writes on the database itself.
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, SynapseOrch can cache its schema (table names, columns, types) to speed up queries. Self-hosted, click Refresh schema on the database's row 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
The built-in coding agent uses the PostgreSQL connection you configure under Settings → General → Code repository indexing (stored as the sql_connection_string setting). Set it once from the UI — SynapseOrch validates the connection and enables pgvector for you. This is separate from the per-agent DB configs in settings; it provides a default connection for the coding agent's general use.
Python Sandbox
The sandbox tool executes Python code in an isolated Docker container with resource limits. It's the safest way to give agents the ability to run code without exposing your host system.
Browser
The browser tools let an agent work in a real browser inside Synapse: open pages, read them, click, and fill in forms, while you watch and take over. Each chat and run gets its own browser.