## Overview

Spice.ai supports [federated SQL queries](https://github.com/spicehq/docs/blob/trunk/features/federated-sql-query.md) across a wide range of data sources. Data connectors let you query external data directly or replicate it into Spice for accelerated access.

For the full list of connectors and configuration options, see [Data Connectors](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/README.md).

## Supported Data Sources

### Category

| Connectors |
|---|
| **Relational databases** |
| [PostgreSQL](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/postgres.md), [MySQL](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/mysql.md), [MSSQL](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/mssql.md), [ClickHouse](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/clickhouse.md) |
| **Data warehouses** |
| [Snowflake](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/snowflake.md), [Databricks](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/databricks.md), [Dremio](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/dremio.md) |
| **Data lakes & formats** |
| [S3](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/s3.md), [Delta Lake](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/delta-lake.md), [ABFS](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/abfs.md) |
| **APIs & other** |
| [GraphQL](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/graphql.md), [GitHub](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/github.md), [SharePoint](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/sharepoint.md) |
| **Streaming** |
| [Debezium CDC](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/debezium.md) |
| **Embedded / local** |
| [DuckDB](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/duckdb.md), [SQLite](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/ftp.md) |

## Adding a Data Source

### 1. Store credentials as secrets

Data source credentials should be stored as [secrets](https://github.com/spicehq/docs/blob/trunk/portal/apps/secrets.md) in your app. In the Portal, go to your app → **Secrets** and create entries for connection strings, access keys, or tokens.

Secret values are write-only and cannot be retrieved after saving.

### 2. Configure the dataset in your Spicepod

Add a dataset entry to your app's `spicepod.yaml` referencing the connector and secrets:

```yaml
datasets:
  - from: postgres:my_schema.my_table
    name: my_table
    params:
      pg_host: my-database.example.com
      pg_port: "5432"
      pg_db: my_database
      pg_user: "${secrets:PG_USER}"
      pg_pass: "${secrets:PG_PASS}"
```

### 3. Deploy

Commit and deploy your app to make the dataset available for querying.

## Data Acceleration

For faster queries, enable [data acceleration](https://github.com/spicehq/docs/blob/trunk/features/data-acceleration/README.md) to cache datasets in a local engine:

```yaml
datasets:
  - from: postgres:my_schema.my_table
    name: my_table
    acceleration:
      engine: arrow  # or duckdb, sqlite, postgres
      refresh_interval: 10m
```

Available acceleration engines:

- [Arrow](https://github.com/spicehq/docs/blob/trunk/features/data-acceleration/in-memory-arrow-data-accelerator.md) — In-memory, fastest performance.
- [DuckDB](https://github.com/spicehq/docs/blob/trunk/features/data-acceleration/duckdb-data-accelerator.md) — Embedded analytical engine.
- [SQLite](https://github.com/spicehq/docs/blob/trunk/features/data-acceleration/sqlite-data-accelerator.md) — Lightweight, persistent.
- [PostgreSQL](https://github.com/spicehq/docs/blob/trunk/features/data-acceleration/postgresql-data-accelerator.md) — Full-featured relational engine.

## Common Issues

### Table not found

Spice normalizes unquoted SQL identifiers to **lowercase** (PostgreSQL-style). If your source uses mixed-case table or column names, double-quote them:

```sql
SELECT "ColumnName" FROM "MySchema"."MyTable"
```

### Object store file format errors

When connecting to object stores (S3, ABFS):

- **Folder paths** require an explicit `file_format` (e.g., `parquet`, `csv`).
- **Single file paths** auto-detect the format from the file extension.

### Schema changes break data refresh

Spice infers the schema at deployment time. If the source schema changes, refresh will fail. **Redeploy the app** to pick up the new schema.

### Connection failures

- Confirm the data source is network-accessible from Spice.ai Cloud (firewalls, IP allowlists).
- Verify secrets are correct and referenced with `${secrets:SECRET_NAME}` syntax.
- Check connector-specific docs for required parameters.