> ## Documentation Index
> Fetch the complete documentation index at: https://ahvn.top/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Connection

> Connect an existing SQL database into a HeavenBase workspace and browse schema as db-* entities.

<Note>
  This workshop is a docs transcript of `demos/enterprise/01_connect_and_ingest.py`. It uses the committed seed database at `demos/data/warehouse.db`.
</Note>

You will enable the optional `database` extension, ingest an existing SQLite warehouse into browsable `db-*` rows, and discover tables through normal HeavenBase queries and card search.

<br />

## 1. Prerequisites

From a HeavenBase source checkout with SQL extras synced:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
rtk bash scripts/sync-env.bash -- --extra sql
rtk uv run python demos/data/seed_warehouse.py   # only if warehouse.db is missing
```

<br />

## 2. Enable the Database Extension

The `database` extension registers six schema entities: `db-database`, `db-table`, `db-column`, `db-enum`, `db-snippet`, and `db-predicate`. Enable it explicitly when ingesting from Python:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import heavenbase as hb
import heavenbase.ext as hb_ext

ws = hb.HeavenBase("ent-01-warehouse", backends={"main": {"type": "inmem"}})
ws.enable_extension("database")
```

<br />

## 3. Ingest an Existing Database

`hb.ext.ingest_database` accepts a workspace SQL backend name, DSN, local SQLite path, or `hb.Database` instance. It uses SQLAlchemy `inspect()` and redacts credentials in stored rows:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from heavenbase.utils.files import pj, get_file_dir

DEMOS = get_file_dir("demos", abs=True)
WAREHOUSE_DB = pj(DEMOS, "data", "warehouse.db", abs=True)

result = hb_ext.ingest_database(ws, WAREHOUSE_DB, name="warehouse")
database_id = result["database"][0]

db_row = ws.get(database_id, entity="db-database")
print(db_row["name"], db_row["dialect"])
print(db_row["dsn_summary"])  # credentials redacted
```

Run the full script:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
rtk uv run python demos/enterprise/01_connect_and_ingest.py
```

<br />

## 4. Browse Schema Rows

Query ingested tables and columns like any other entity:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
tables = (
    ws.query("db-table")
    .where({"database_id": database_id})
    .select("table_name", "row_estimate")
    .execute()
)
print(tables.to_str())

customers = next(row for row in tables.rows() if row["table_name"] == "customers")
columns = (
    ws.query("db-column")
    .where({"table_id": customers["object_id"]})
    .select("column_name", "dtype")
    .execute()
)
print(columns.to_str())
```

Discover tables with text search:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
discovered = ws.query("db-table").where({"table_name": {"$match": "customer"}}).execute()
print([row["table_name"] for row in discovered.rows()])
```

<br />

## Summary

* The `database` extension introspects external SQL databases into first-class HeavenBase entities.
* Ingestion redacts credentials; re-run ingest after manifest import when live connection metadata is needed.
* Schema rows are queryable and searchable before you register SQL snippets or expose MCP tools.

<br />

## Further Exploration

<Tip>
  **Related resources:**

  * [Data analysis workshop](/quickstart/data-analysis-workshop) — Snippets, predicates, and agent analysis
  * [Database integration](/integrations/databases) — Backend families and connection patterns
  * [Enterprise demo track](https://github.com/Magolor/HeavenBase/tree/master/demos/enterprise) — Full runnable scripts
</Tip>

<br />