Database connectors

Plans and permissions:

• Add-on: AI agents, billed separately
• Add database connectors and SQL query tools: Admin role, or a custom role with Tools and connectors set to Can edit tools and connectors settings
• Use a query in a workflow: Admin, Manager, or Team Lead role, or a custom role with Workflows set to Can create, edit, and delete workflows
• To turn on database connectors for your company, contact our team.

Use database connectors to let your workflows look up data in your data warehouse, such as a customer’s tier, an order’s status, or a shipment’s expected arrival, while the AI agent handles a case. You connect a database once, save the SQL queries the AI agent can run, and then use those queries in workflow steps.

To add one, go to Configure > Tools and connectors and select Add connector > Database connector.

How database connectors work

• A database connector holds the connection details. SQL query tools hold the queries, and one connector can have many of them.
• A saved query must be a single SELECT statement (or one that starts with WITH) that lists the columns it returns. Queries that change data, and queries that use *, can’t be saved.
• Placeholders such as {{order_id:int}} let a query take values from the workflow. Assembled passes them to the database as parameters, not as text added to the SQL.
• Each query returns at most 1–10 rows (Max rows, 1 by default) and stops after 1–60 seconds (Timeout, 10 seconds by default).
• Workflows run queries in a Database query step, or from a Guide step.

Data connector types

Assembled has three kinds of data connectors, each with its own workflow step.

Add a database connector

Use a dedicated service account for Assembled rather than someone’s personal login. It’s easier to control its access, rotate its credentials, and audit what it does.

1. Go to Configure > Tools and connectors.
2. Select Add connector, then Database connector.
3. Enter a Name, such as Analytics database, and optionally a Description of the data it holds.
4. Choose the Connector type: Snowflake, Databricks, or Redshift.
5. Enter the Host, Port, and Database, and the Schema if you use one. Depending on the type, also enter the Warehouse (Snowflake), the Catalog (Databricks), or the SSL mode (Redshift).
6. Under Authentication, choose the Authentication type and enter the credentials.
7. Select Create connector.

The connector appears on the Tools and connectors page. Next, test the connection.

Database connector options

To change credentials later, select Change credentials in the connector’s settings. Saved credentials are hidden.

Note: If your database only accepts known IP addresses, Snowflake connectors can use static egress IPs. See MCP connectors.

Test the connection

1. On Configure > Tools and connectors, select the connector.
2. Open the connector actions menu and select Test connection.

The test checks that Assembled can reach the host, sign in, and open a connection. It doesn’t check that a particular query works. If it fails, the most common causes are:

• The host or port is wrong.
• The username, password, token, or OAuth credentials are wrong.
• For Snowflake, the warehouse is wrong. For Databricks, the catalog is wrong.
• For Redshift, the SSL mode doesn’t match the server.
• A firewall or network allowlist blocks Assembled.
• The account Assembled uses doesn’t have access to connect.

Create a SQL query tool

A SQL query tool is a saved query that workflows can run.

1. On Configure > Tools and connectors, select the database connector.
2. Select Create SQL query.
3. Enter a Name that identifies the query in workflows, such as Get order status.
4. Enter a Description that says what the query returns and when the AI agent should use it.
5. Under Query setup, check the Database connector, and enter the SQL query. You can’t change the connector after you create the tool.
6. Under Configurations, set Max rows and Timeout.
7. Optionally, turn on Save output to smart field and choose the Output smart field, so later steps can use the result. Assembled saves the first column of the result to the smart field.
8. Select Preview query to check it (see below), then select Create tool.

To make a query reusable, add placeholders for the values it needs, written as {{name}} or {{name:type}}. The type is string (the default), int, float, or bool. For example:

SELECT order_status, shipment_eta
FROM support.order_lookup
WHERE order_id = {{order_id:int}}

Saving the result to a smart field helps when a later step needs it. For example, look up the customer’s tier, save it to a smart field, and branch on the tier later in the workflow.

Preview a query

Important: Preview query runs your SQL against the live database, including text you haven’t saved yet. Give Assembled’s account read-only access, so a preview can’t change data.

1. In the query’s settings, select Preview query.
2. If the query has placeholders, enter a test value for each.
3. Run the preview.

You see Query ran successfully with the Rows returned, Columns returned, and Execution time, and the rows themselves, or Query errored with the error. Check that the query uses the right values, returns the columns and rows you expect, finishes within the timeout, and returns data in a shape the workflow can use.

If it fails, check:

• The placeholder names and types.
• The table and column names, and the schema and catalog.
• That Assembled’s account can read those tables or views.
• The Max rows and Timeout settings.

Use a query in a workflow

1. In the workflow builder, select + after a step, select Add step, and choose Database query.
2. Optionally, enter a Step name, then choose the Database query.
3. Under Tool inputs, set each placeholder from a Smart field or a Fixed value.
4. Optionally, change the Request timeout.
5. To handle each result differently, turn on Branch based on tool result. The step then has three branches: Rows returned, No rows returned, and Error.
6. Under Output mapping, map each Response field to a Stored variable for later steps.
7. Select Update step.

If you don’t see Database query in the list of steps, contact our team to turn it on.

Use a query in a Guide step

1. Open the workflow and select the Guide step.
2. In Response instructions, type @ and choose the SQL query tool.
3. Around it, write when to run the query, which values to use, and what to do with the result.
4. Select Save step.

Important: The AI agent runs a query only when it’s inserted from the @ menu. A query name typed as plain text isn’t reliable.