Build with AI agents

One engine, two agent interfaces#

Igloo gives developers and agents a SQL interface across native PostgreSQL, compatible ADBC drivers and named local Parquet snapshots. Use native stdio MCP in compatible coding agents, or JSON commands through a shell/subprocess tool. No LLM provider or API key is required. The Database connectors guide distinguishes tested integrations from unverified driver candidates and planned routes.

The agent workflow is discover → explain → query. Both interfaces use the same read-only SQL policy, structured errors, exact numeric encodings, and result budgets. A persistent MCP process retains its engine and source metadata. Native PostgreSQL shares connections; ADBC opens a connection per scan. Each CLI invocation initializes its own engine.

1. Try without database setup#

Clone the agent preview and build with Rust 1.88+ and a native linker. The first build compiles DataFusion. The --demo flag uses an in-memory sample_events table with four deterministic rows, including a NULL event. It does not access PostgreSQL, load configuration, or create files.

git clone --branch codex/agent-native-access https://github.com/igloodb/igloodb.git
cd igloodb
git checkout --detach b5a210d54a2e78a9a8c9497e2476061aad771d36
cargo build --locked
./target/debug/igloo schema --demo
./target/debug/igloo query --demo --sql 'SELECT event, count(*) AS total FROM sample_events GROUP BY event'

2. Connect an MCP client#

For clients using mcpServers configuration, merge the following entry into their MCP configuration. Use an absolute binary path because client working directories differ. Build first so each connection starts the binary directly. Stdout carries only protocol messages; logs use stderr.

{
  "mcpServers": {
    "igloo": {
      "command": "/absolute/path/to/igloodb/target/debug/igloo",
      "args": ["mcp", "--demo"]
    }
  }
}

Codex configuration#

Add this entry to the MCP section of your Codex TOML configuration. Then ask the agent to inspect Igloo's capabilities and schema, explain an event-count query, and run it with a small row budget.

[mcp_servers.igloo]
command = "/absolute/path/to/igloodb/target/debug/igloo"
args = ["mcp", "--demo"]

Five focused tools#

Discover the schema before generating SQL. Prefer named source catalogs and copy qualified_name verbatim. Default-catalog entries may be aliases. Follow next_cursor using after until it is null.

Use a shell agent or application#

The query, explain and schema commands accept --json to read one object from stdin. Stdout is one JSON result; successful requests exit 0 and errors exit 2. Unknown fields are rejected. Pass JSON using subprocess input and an argument array, so SQL never becomes shell code.

import json, subprocess

run = subprocess.run(
    ["/absolute/path/to/igloo", "query", "--demo", "--json"],
    input=json.dumps({"sql": "SELECT * FROM sample_events", "max_rows": 2}),
    text=True, capture_output=True, check=False,
)
result = json.loads(run.stdout)
if run.returncode:
    raise RuntimeError(result["error"])
print(result["rows"], result["truncated"])

Connect existing sources#

Create an Igloo TOML configuration with the source family you need. Set IGLOO_CONFIG to its absolute path and supply connection strings through IGLOO_SOURCE_<NAME>_URI in the client process environment. Remove --demo to use configured data. Keep credentials out of prompts and committed configuration. Native PostgreSQL is shown below; the Database connectors guide covers ADBC and named Parquet.

Use a SELECT-only PostgreSQL role and a source-side statement_timeout. The native source connection uses NoTls; use an appropriately secured development connection. Native PostgreSQL needs no ADBC driver. Generic adbc_sources require a trusted installed driver. Named parquet_sources infer other schemas; only the optional legacy iceberg table retains user_id: Int64 and data: Utf8. Real Iceberg/CDC integration remains planned. Agent mode needs no listen address.

[[sources]]
name = "app"
schemas = ["public"]
tables = ["customers", "orders"]
# Supply IGLOO_SOURCE_APP_URI in the process environment.

Budgets and result semantics#

Queries default to 100 rows and 10 seconds, with hard maxima of 1000 rows, 30 seconds and a 1 MiB JSON data envelope. MCP protocol wrappers can make transport messages larger. The engine limits the plan before collecting results and fetches one extra row to determine truncated. These limits do not bound upstream scans, memory or startup time, and a local timeout does not guarantee cancellation in PostgreSQL.

Rows are JSON objects with unique column names and explicit NULLs. Top-level Int64, UInt64 and Decimal columns are exact decimal strings; column metadata describes types and encodings. Empty results still include columns. Cast nested large numeric values to text when exact precision is essential.

Agent queries bypass the result cache. Independent sources do not share a consistent snapshot. Check truncated before drawing conclusions; use stable ordering and keyset predicates for additional results. Errors include a code, message and hint.

Documentation agents can read directly#

The site publishes /llms.txt, /llms-full.txt, /docs/agents.md and /skills/igloo-query/SKILL.md. These are plain-text discovery and usage context, not access controls. The full text documentation is generated from the same content as the HTML guides during the build.

The repository's docs/MARKET_ANALYSIS.md records the competitive research, product choices and evaluation priorities. Igloo focuses on structured data access; it does not implement vector search, persistent agent memory, tenant isolation, or a hosted MCP service.