> 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.