SQL Connections

A SQL connection runs a query against a PostgreSQL or MSSQL database and returns the results to your widgets.

Setting up a SQL connection

1. Go to Data Connections and click New Connection.
2. Select SQL as the connection type.
3. Choose a data source config — the database server to query.
4. Write your SQL query in the query editor.
5. Give the connection a name.
6. Click Save.

Writing queries

SQL connections support SELECT and WITH (CTE) statements. Other statement types (INSERT, UPDATE, DELETE) are not allowed — connections are read-only.

Example:

SELECT order_id, status, quantity, created_at
FROM production_orders
WHERE status = 'In Progress'
ORDER BY created_at DESC
LIMIT 100

Column labels

By default, the column names in your query results match the column names in your database. You can assign custom labels to make them more readable in widget code.

For example, if your query returns prod_ord_id, you could label it Order ID. Widgets would then access it as row["Order ID"].

Supported databases

Database	Driver	Status
PostgreSQL	postgres	Fully supported
Microsoft SQL Server	tedious (MSSQL)	Fully supported
MySQL	—	Not yet supported

Previewing results

After saving, you can preview the query results from the connection detail page. This runs the query and shows a sample of the returned rows, which helps verify that your query works before using it in a widget.

Notes

• Queries have a 30-second timeout. Long-running queries will fail.
• SQL connections don't support caching. Every getData() call executes the query fresh.
• The query runs on the Crow's Nest worker (server-side), not in your browser. Make sure the database server is accessible from the internet.
• If you get connection errors, ask your admin to test the data source config and verify that the database allows external connections.