SQL Database
On this page
Purpose
SQL Database runs a SQL query against a SQLAlchemy-compatible database and returns the result as a DataFrame.
When to use it
- Read rows from a database table.
- Join data for a downstream DataFrame step.
- Test a limited query against a development database.
Required setup
Provide a valid Database URL. Normal mode also needs a SQL query, while Agent Core supplies the query in Tool Mode. The component is Builder-only. Use a dedicated least-privilege database account, and do not put production credentials or sensitive query results in screenshots.
How to use it
Tool Mode
- Add SQL Database, enter the Database URL, and enable Tool Mode.
- Connect the tool output to Agent Core. The Agent can supply the SQL query, so use a read-only account with access only to the required data.
- Test the tool with the smallest useful result set.
Normal mode
- Enter the Database URL, such as a redacted
sqlite:///example.dbvalue for local testing. - Enter or connect SQL Query.
- Connect Result Table to a DataFrame-aware component.
- Test the query with the smallest useful result set.
Configuration
| Setting | What it controls | Recommended starting point |
|---|---|---|
| Database URL | Connects to the target database. | Use a dedicated read-only account where possible. |
| SQL Query | Defines the query to execute. | Start with a bounded SELECT query. |
| Include Columns | Does not affect Result Table or Agent tool output. | Leave unchanged. |
| Add Error | Does not change the component output or error behavior. | Leave disabled. |
Expected result
Tool Mode gives Agent Core a SQL query tool. Normal mode returns successful query results as a DataFrame. Connection and query failures return to the flow. The component runs the supplied SQL, so Arkus does not make an unsafe query safe.
Reference details
The Database URL is stored as plain text. Use a dedicated least-privilege account, avoid production credentials where possible, and rotate any exposed credential.