lakesh
A DuckDB SQL shell for your data lake catalogs
Iceberg REST and DuckLake in one shell, with an MCP server for LLM agents.
Kevin Keller ยท kevinkeller.org
Why it matters
Catalog work is full of small frictions
- Re-pasting ATTACH statements and OAuth tokens every session
- Getting S3 credential plumbing right for cloud and MinIO
- Switching between dev, staging and prod catalogs
- Individually thin conveniences; together, meaningfully faster daily work
The division of labour
DuckDB does the heavy lifting, lakesh adds the ergonomics
- DuckDB: Parquet reads, predicate pushdown, joins across namespaces
- lakesh: named profiles, automatic OAuth2 token fetch and reuse
- lakesh: pre-configured S3 credentials, psql-style meta-commands
- lakesh: autocomplete scoped to the attached catalog
Multi-catalog workflows
Switching catalogs is one flag
lakesh -p prod
Works against any Iceberg REST catalog: Polaris, Nessie, Lakekeeper, managed REST, or any DuckLake catalog. Secrets can come from environment variables, so production profiles keep credentials out of config files.
Two profile types
Read through REST, write through DuckLake
| Iceberg REST | DuckLake direct | |
|---|---|---|
| Connects via | Iceberg REST Catalog API | Postgres + S3 |
| Auth | OAuth2, handled per session | Postgres DSN |
| Writes | Not over REST | INSERT, UPDATE, DELETE |
LLM agents over your lake
Give your AI assistant catalog access, read-only by default
lakesh mcp exposes profiles, namespaces, tables, schemas and queries to any MCP client. Writes need LAKESH_MCP_WRITE=1.
The MCP tools
Five tools, no custom tooling to build
list_profiles: discover configured catalogslist_namespaces: list schemaslist_tables: list tables, optionally scopeddescribe_table: columns, types, nullabilityquery: rejects anything not starting withSELECT,SHOW,DESCRIBE,WITHorEXPLAIN
Scripted pipelines
Clean output for the next tool in the pipe
lakesh execruns one-shot queries- Output as table, JSON or CSV
- No REPL noise, so
jqworks as expected lakesh doctorruns a connectivity smoke test
Takeaway
One shell for every catalog, and safe SQL access for your AI agents.
Open source: github.com/KellerKev/lakesh