SQL Sources

Read-only database connections your assistant can query.

SQL Sources is the page that connects your project to live databases. Once a source is connected, the assistant can introspect the schema, write SQL against your tables, and render the result inline (as a table or a chart). All access is read-only, the assistant cannot modify your data.

Page anatomy

Region	What you see
Topbar breadcrumb	Chat with Your Documents / / SQL Sources.
Page header	Title with a + New connection button on the end edge.
List body	A grid of source cards.
Empty state	A dashed-border card with a Connect a SQL source button when the project has none.

SQL source cards

Each card summarises a connected database.

Element	What it shows
Card title	The source name.
Tables count	tables introspected.
Terms count	terms in the semantic glossary.
Last refreshed	A relative timestamp like 3h ago last refreshed or never refreshed.
Status chip	live in green, or stale in amber when the schema has not been refreshed in a while.
Click	Opens the source detail page.

Empty state

Element	What it says
Title	No SQL sources yet.
Body	Connect a read-only database to let your agent answer questions from live data.
Button	Connect a SQL source. Brand-gradient pill.

Connecting a new source

The new-connection dialog has a name field, a dialect dropdown, and a connection string input.

Field	Notes
Name required	Plain-text input. Placeholder e.g. hr_prod. The dialog blocks save until the field has at least one non-whitespace character.
Dialect	Dropdown with PostgreSQL, MySQL, SQL Server, BigQuery, Snowflake.
Connection string required	Password-style input. Placeholder postgresql://user:password@host:5432/dbname. Direction is left-to-right even in Arabic mode.
Connection note	A small one-line caption Read-only access only. The agent validates every query before running it.
Connect button	Brand-gradient submit. The label flips to Connecting… with a spinner during the request.
Cancel button	Closes the dialog.

For safety, the dialog rejects private IP ranges, cloud metadata endpoints, and localhost before submitting.

Your connection details are stored encrypted and are never saved in your browser.

SQL source detail page

The detail page has four tabs: Schema, Semantic terms, Query history, and Connection.

Schema tab

The default tab. Shows what the assistant sees when it generates SQL.

Element	Notes
Filter tables search	Filters the table list by name.
Each table card	The table name, PK badge for the primary key, FK badge for foreign keys, rows and columns counts, and a small expand caret.
Expanded table	A list of columns with the column name, the type, and any constraints.
Refresh schema button	Re-introspects the database. The toast confirms Schema refreshed.

When the schema is empty, the empty state reads No tables introspected yet. Refresh the schema.

Semantic terms tab

Teaches the assistant Arabic ↔ English vocabulary for your schema.

Element	What it shows
Subtitle	Teach the agent Arabic ↔ English vocabulary for your schema.
Add term button	Opens the term editor.
Each term card	Arabic term, English term, SQL expression, type chip.
Empty state	No terms yet. Add your first term so the agent can map natural questions to SQL.

Each term has the following fields:

Field	Notes
Arabic term	At least one of Arabic or English is required.
English term	At least one of Arabic or English is required.
SQL expression required	The expression the assistant injects when it spots this term, for example COUNT(*) or employees.department_id.
Type	Dropdown: Metric, Dimension, Filter, Table alias.

Save with Save term. Delete with Delete term, which confirms The agent will stop mapping this vocabulary to the SQL expression.

Semantic terms are how a user asking How many موظفين? gets the assistant to write SELECT COUNT(*) FROM employees. Build the glossary up front, every chat in this project benefits.

Query history tab

Reads Query history is coming soon. Every SQL the agent runs against this source will be audited here.

The tab is intentionally empty today, the audit trail ships in a follow-up.

Connection tab

Field	Notes
Dialect	Read-only. The dialect picked when the source was created.
Connection string	Read-only and masked. Only an admin can rotate it (delete and reconnect).
Connected	The creation date.
Schema last refreshed	Timestamp of the last refresh.
Delete this source button	Opens a destructive confirmation.

Delete this source

Element	What it says
Title	Delete this SQL source?
Body	This removes the connection and every semantic term. Chat sessions referencing this source will silently drop it on the next turn. This cannot be undone.
Cancel button	Closes the dialog.
Delete button	Styled with the destructive (red) background and white text.

After confirmation, the source disappears from the list. Chats that referenced it stop writing SQL against it on the next turn.

How a chat turn uses a SQL source

When you ask the assistant a data question that maps to SQL, the answer carries a SQL · {source name} tag and renders both the generated SQL (collapsible block) and the result (table or chart). Every SQL is validated server-side before running, with destructive operations rejected.

Common questions

My connection string failed validation.

The most common causes are private IPs (10.x, 172.16-31.x, 192.168.x), localhost (127.0.0.1 or localhost), or cloud-metadata endpoints (169.254.169.254). These are blocked to protect against server-side request forgery. Use a public hostname or a VPN gateway your account can reach.

The Schema tab is empty after I connected.

Click Refresh schema at the top of the tab. The first introspection can take a moment for very large databases. After it lands, every table appears as a card.

The assistant returned a wrong column name.

Add a semantic term that maps the natural-language phrase to the right column. For example, an Arabic term العمر with SQL expression employees.age and type Dimension stops the assistant from inventing a column.

My database changed (column added or renamed).

Click Refresh schema in the Schema tab. The assistant picks up the new shape on the next turn. Old SQL the assistant cached is rebuilt from the fresh schema.

Can the assistant modify my data?

No. Every query is read-only. Server-side validation rejects INSERT, UPDATE, DELETE, DROP, CREATE, and any other destructive operation. Sensitive columns can also be deny-listed.

The Query history tab is empty.

The audit trail ships in a follow-up. Today, the tab carries the coming soon message. There is no temporary workaround for downloading history.

Can I connect the same database with different credentials per project?

Yes. Each project owns its own SQL sources. Connect the database in each project with the credentials that project should use, the credentials are encrypted independently per source.

My connection went stale.

The status chip flips to stale when the schema has not been refreshed for a long time. Click into the source, then Refresh schema to flip it back to live.

Where to go next

Knowledge Bases

Pair SQL with document retrieval.

Chats

Start a conversation that uses this source.

Chat Canvas

Force tool to SQL only, or pick Auto per turn.

Project Settings

Retrieval features and danger zone.