> For the complete documentation index, see [llms.txt](https://docs.smaq.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.smaq.io/documentation/connections/sql-databases.md).

# SQL databases

SMAQ supports six SQL flavors via direct connection strings:

| Database                | Notes                                                          |
| ----------------------- | -------------------------------------------------------------- |
| **PostgreSQL**          | Most common — self-hosted, RDS, GCP Cloud SQL, Supabase, Azure |
| **MySQL**               | Self-hosted, RDS, GCP Cloud SQL, PlanetScale                   |
| **BigQuery**            | GCP serverless warehouse — uses a service-account JSON key     |
| **ClickHouse**          | High-performance analytical DB — self-hosted or Cloud          |
| **Microsoft Azure SQL** | Managed SQL Server on Azure                                    |
| **MongoDB**             | Document store — supported via the MongoDB connector           |

Specific hosted-database guides:

* [AWS RDS](/documentation/connections/sql-databases/aws-rds.md) (Postgres/MySQL on AWS)
* [GCP Cloud SQL](/documentation/connections/sql-databases/gcp-cloud-sql.md) (Postgres/MySQL on GCP)
* [Microsoft Azure SQL](/documentation/connections/sql-databases/microsoft-azure-sql.md)

### What you'll need

* **Hostname / endpoint**
* **Port** (5432 for Postgres, 3306 for MySQL, 1433 for Azure SQL, etc.)
* **Database name**
* **Username + password** (read-only DB user recommended)
* **SSL settings** — required for most hosted databases
* For BigQuery: a service-account JSON key with BigQuery Data Viewer + Job User roles

### IP allowlist

SMAQ's outbound traffic comes from a fixed set of IPs. You'll need to allow these in your database's firewall / security group. Get the current list from **<info@smaq.io>** when setting up.

### Steps to connect

1. **Data Source → Add data source**.
2. Pick the right SQL type from the list.
3. Fill in the connection fields:
   * Hostname, port, database, username, password
   * SSL mode (almost always **Require**)
   * Optional: a custom schema name (defaults to `public` for Postgres)
4. Click **Test connection**.
5. Name and click **Connect**.

> **\[Screen video needed]** Postgres connection setup including SSL toggle and Test connection step. \~75 seconds.

> **\[Screenshot needed]** Successful "Test connection" result showing the tables that were discovered.

### How SQL connections differ from API connections

* **Filters** — the visual filter UI doesn't work for SQL sources. Instead, use **parameters** inside your SQL: `${start_date}`, `${end_date}`, `${campaign_id}`, etc. SMAQ substitutes values at fetch time.
* **No global datablocks** — global datablocks are tied to specific ad platforms. SQL connections only support project-built datablocks.
* **You write the SQL.** SMAQ's datablock builder for SQL sources is essentially a SQL editor with parameter binding.

See [Limitations and tips](/documentation/features/dashboard/mastering-dashboard-filters/limitations-and-tips.md) for the filter-system caveats.

### Security

* **Use a read-only DB user.** SMAQ never issues writes, but defense-in-depth matters.
* **Connection strings are encrypted at rest.** SMAQ stores credentials encrypted with AES-256, decrypted only at query time.
* **VPC peering** is available for enterprise customers — contact <info@smaq.io>.

### Troubleshooting

* **"Connection refused" / timeout** — check the IP allowlist and that the DB is publicly accessible (or that VPC peering is in place).
* **"SSL handshake failed"** — try toggling SSL mode between Require, Verify-CA, and Disable. Most hosted DBs require Require.
* **"Permission denied for table"** — your DB user needs SELECT on the schemas and tables you want to query.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.smaq.io/documentation/connections/sql-databases.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.