# Configuration

Sources, catalogs, environment overrides, and cache settings.

HTML: https://igloodb.github.io/docs/configuration/
Source: https://github.com/igloodb/igloodb/blob/b5a210d54a2e78a9a8c9497e2476061aad771d36/igloo.example.toml (connector preview b5a210d (unreleased))

## Configuration loading

Igloo reads ./igloo.toml when present. Set IGLOO_CONFIG to use another file. Environment variables override file values. Source configuration and explicitly supplied paths are validated at startup; there are no silent localhost defaults. The connector preview makes legacy parquet_path and cdc_path optional for server and agent commands.

The environment is read directly. A .env file is not automatically loaded by the engine; export its variables using your shell or a dotenv tool.

## Multiple PostgreSQL sources

Declare one [[sources]] entry per PostgreSQL database. Each source becomes a DataFusion catalog. Use environment variables for connection strings so credentials stay out of the file. Source names use lowercase letters, digits, and underscores, starting with a letter.

```toml
listen_addr = "127.0.0.1:5442"

[[sources]]
name = "orders_db"
schemas = ["public", "billing"]
tables = ["orders", "customers"]

[[sources]]
name = "crm"
schemas = ["public"]
```

> Set IGLOO_SOURCE_ORDERS_DB_URI and IGLOO_SOURCE_CRM_URI before startup. The optional tables allowlist filters by table name. Omit it to discover all base tables in the selected schemas.

## Environment reference

The single-source shorthand uses postgres_uri and optional postgres_schemas in TOML, or DATABASE_URL / IGLOO_POSTGRES_URI in the environment. Do not combine the single-source and [[sources]] forms in the config file.

| Variable | Purpose | Default / requirement |
| --- | --- | --- |
| IGLOO_CONFIG | TOML config file path | ./igloo.toml if present |
| IGLOO_PARQUET_PATH | Legacy Parquet directory | Optional; fixed-schema iceberg table |
| IGLOO_CDC_PATH | JSON event directory | Optional; file-based cache invalidation |
| DATABASE_URL | Primary PostgreSQL URI | Wins over IGLOO_POSTGRES_URI |
| IGLOO_POSTGRES_URI | Single-source PostgreSQL URI | Required in single-source mode |
| IGLOO_POSTGRES_SCHEMAS | Comma-separated schema list | public |
| IGLOO_SOURCE_<NAME>_URI | Named source connection string | Required if URI omitted in TOML |
| IGLOO_SOURCE_<NAME>_SCHEMAS | Named source schema override | public |
| IGLOO_LISTEN_ADDR | PostgreSQL wire bind address | Required for serve |
| IGLOO_CACHE_MAX_ENTRIES | Positive cache entry limit | 1024 |
| IGLOO_CACHE_TTL_SECONDS | Positive cache TTL | 300 |
| IGLOO_CDC_POLL_SECONDS | Positive polling interval | 10 |
| IGLOO_CRYPTO_PARQUET_PATH | OHLCV demo directory | ./crypto_ohlcv_data |
| RUST_LOG | env_logger log level | info |

## Catalog names and aliases

The canonical identifier is <source>.<schema>.<table>, such as orders_db.billing.invoices. These names are always unambiguous and appear in SHOW TABLES.

Short aliases are allocated in configured source order: table, then schema__table, then source__schema__table. The first configured source keeps an available bare name; a later table is never silently substituted. Use canonical identifiers in shared queries.