Scans a PostgreSQL database and returns its structure.

Accepts connection params as a keyword list:

EctoDBScanner.scan(
  hostname: "localhost",
  username: "postgres",
  password: "postgres",
  database: "my_db",
  port: 5432
)

Scans are safe to run concurrently: each call starts its own anonymous repo instance, so multiple databases (or the same database) can be scanned at the same time from a single node.

Options

• :analyze (boolean, default true) — Runs ANALYZE against the target database before scanning so planner statistics (notably pg_class.reltuples, used for row counts and enum detection sampling) are fresh. On large databases this may take a while; set to false if stats are already current or the connecting role lacks permission.

• :detect_enums (boolean, default true) — Runs the cardinality-based heuristic that samples string columns to detect enum-like sets of values. Set to false to skip detection on databases where even TABLESAMPLE-bounded sampling is too slow; PostgreSQL ENUM-typed columns are still detected via catalog lookup.

• :enum_detection_timeout (integer, default 60_000) — Per-column sampling timeout in milliseconds for heuristic enum detection. A column that exceeds it is silently dropped from the results, the rest of the scan continues.

• :enum_detection_max_concurrency (integer) — Number of columns to sample concurrently. Defaults to pool_size - 1 (minimum 1) so the connection pool is not saturated by the scan itself.

• :schemas (list of strings) — When present, only these schemas are scanned. Filtering happens at the query level, so tables, columns, constraints, sizes, indexes, sequences, and enum detection sampling all skip everything outside the listed schemas.

• :exclude_schemas (list of strings) — Schemas to skip, in addition to the always-excluded system schemas (information_schema, pg_catalog, pg_toast). Applied at the query level like :schemas.

All other options are passed through to the underlying repo connection.

Returns {:ok, %EctoDBScanner.Result.Database{}} or {:error, reason}.