> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wittify.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 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 / {project} / 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 | **{n} tables** introspected. |
| Terms count | **{n} 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, **{n} rows** and **{n} 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
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.
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.
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.
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.
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 audit trail ships in a follow-up. Today, the tab carries the *coming soon* message. There is no temporary workaround for downloading history.
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.
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
Pair SQL with document retrieval.
Start a conversation that uses this source.
Force tool to SQL only, or pick Auto per turn.
Retrieval features and danger zone.