EKOSdocs
Docs / Guides Build

Indexing a Database

Recover tables, columns, keys and transformations from SQL files, dbt projects and ClickHouse.

EKOS recovers database knowledge from checked-in SQL and metadata rather than a live connection. (Live PostgreSQL and SQL Server connectors are planned, not shipped.)

SQL files

  1. Put the DDL where [observe] paths covers it.
  2. Set the dialect. This is load-bearing — a wrong or missing dialect makes the whole-file parse fail and the entire schema silently disappears, leaving only a SQL001 warning:
[recover.sql]
default-dialect = "generic"

[[recover.sql.dialect-rules]]
path-glob = "db/legacy/**/*.sql"
dialect = "mysql"

[[recover.sql.dialect-rules]]
path-glob = "db/warehouse/**/*.sql"
dialect = "snowflake"

Supported dialects: PostgreSQL, MySQL, SQL Server (T-SQL), Snowflake, Databricks, ClickHouse.

  1. Compile as usual and check that tables exist:
ekos ekl "FIND Object WHERE kind = 'Table' LIMIT 20"

Zero tables for a repo that has a schema means: check the dialect, then read the recover diagnostics in .ekos/diagnostics/ for SQL001.

Also recovered

Source Recovered
SELECT, VIEW, stored procedures Transformation IR (source → filter → join → aggregate → sink)
COMMENT ON … (PostgreSQL) author-written descriptions, ranked above LLM text
dbt projects one Table per models/**/*.sql and per declared source — from the project's own files, never manifest.json
ClickHouse schema metadata over HTTP; optional live NL-to-SQL tool (gated, off by default)
Pentaho .ktr/.kjb Transformation IR, exportable to dbt with ekos dbt

Explain a legacy pipeline

Through MCP, ekos_transformation_explain walks a pipeline step by step with evidence per step; ekos_transformation_diff compares an old pipeline with a new one to check a migration preserved the logic. Unmapped steps are reported, never guessed.