igloo.

Explore the documentation

QuickstartRun your first Arrow-native SQL queries with Igloo.Build with AI agentsConnect a coding agent through native MCP or a read-only JSON CLI.Database connectorsBroad database coverage through native adapters, compatible ADBC drivers, and open data formats.Connect PostgreSQLConfigure live sources and query them through the PostgreSQL wire protocol.ConfigurationSources, catalogs, environment overrides, and cache settings.ArchitectureFollow a query through the single-process Rust engine.Caching & freshnessWhat the result cache does, and how it becomes fresh again.SQL & clientsFederation, local files, catalog discovery, and prepared queries.Project roadmapWhat is implemented, what is evolving, and where to contribute.ContributingHelp build the engine or improve this website.
Use Tab to navigate esc to close
Get started
Igloo/Documentation/Configuration
Browse documentation

Build with Igloo

Configuration

Sources, catalogs, environment overrides, and cache settings.

Read as Markdown

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.

igloo.toml
listen_addr = "127.0.0.1:5442"

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

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

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.

Environment reference reference
VariablePurposeDefault / requirement
IGLOO_CONFIGTOML config file path./igloo.toml if present
IGLOO_PARQUET_PATHLegacy Parquet directoryOptional; fixed-schema iceberg table
IGLOO_CDC_PATHJSON event directoryOptional; file-based cache invalidation
DATABASE_URLPrimary PostgreSQL URIWins over IGLOO_POSTGRES_URI
IGLOO_POSTGRES_URISingle-source PostgreSQL URIRequired in single-source mode
IGLOO_POSTGRES_SCHEMASComma-separated schema listpublic
IGLOO_SOURCE_<NAME>_URINamed source connection stringRequired if URI omitted in TOML
IGLOO_SOURCE_<NAME>_SCHEMASNamed source schema overridepublic
IGLOO_LISTEN_ADDRPostgreSQL wire bind addressRequired for serve
IGLOO_CACHE_MAX_ENTRIESPositive cache entry limit1024
IGLOO_CACHE_TTL_SECONDSPositive cache TTL300
IGLOO_CDC_POLL_SECONDSPositive polling interval10
IGLOO_CRYPTO_PARQUET_PATHOHLCV demo directory./crypto_ohlcv_data
RUST_LOGenv_logger log levelinfo

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.

Grounded in the engine source at connector preview b5a210d (unreleased) . The quickstart pins this experimental source revision; it is not a tagged release.

Suggest an improvement