# Publish database context for agents

Source: https://www.hotdata.dev/use-cases/agent-context
Site index: https://www.hotdata.dev/llms.txt

Agents need structure, but dumping full schemas into every prompt doesn't scale. Database context stores things like your data model once; queries pick it up automatically. List what's there, push when the join graph changes, cross-check against live tables, and keep throwaway exploration in local files instead of promoting half-baked ideas to shared docs.

## How it works

### Step 1: See what already exists

**Claude**

```
What shared docs are stored for this database? If there’s a data model, show the whole thing.
```

**CLI**

```bash
hotdata databases context list

hotdata databases context show DATAMODEL
```

**Python SDK**

```python
import hotdata

ctx = hotdata.DatabaseContextApi(api_client)
ctx.list_database_contexts("<database_id>")
ctx.get_database_context("<database_id>", "DATAMODEL")
```

### Step 2: Edit locally, push when the join graph changes

**Claude**

```
Pull the data model down so I can edit it on disk, then publish my edits back to the database.
```

**CLI**

```bash
hotdata databases context pull DATAMODEL   # optional: creates ./DATAMODEL.md
# edit ./DATAMODEL.md (entities, keys, naming)
hotdata databases context push DATAMODEL
```

**Python SDK**

```python
import hotdata

ctx = hotdata.DatabaseContextApi(api_client)
body = open("DATAMODEL.md", encoding="utf-8").read()
ctx.upsert_database_context(
    "<database_id>",
    hotdata.UpsertDatabaseContextRequest(name="DATAMODEL", content=body),
)
```

### Step 3: Pair with live schema

**`hotdata databases tables`** is ground truth for columns. Context explains relationships and intent (`context:DATAMODEL`). Context names follow the same rules as SQL identifiers.

**Claude**

```
I want to compare our written data model to what’s live in the catalog. Show a slice of current tables and then show the DATAMODEL context so I can see definitions next to real columns.
```

**CLI**

```bash
hotdata databases tables list --limit 30

hotdata databases context show DATAMODEL
```

**Python SDK**

```python
import hotdata

api = hotdata.InformationSchemaApi(api_client)
api.information_schema(limit=30)
ctx = hotdata.DatabaseContextApi(api_client)
ctx.get_database_context("<database_id>", "DATAMODEL")
```

### Step 4: Keep scratch local, publish what's stable

Keep throwaway exploration in **local files** on disk. When something should guide the whole team, not just today's thread, publish it into **DATAMODEL** (or another stem) with `context push`. See [Database context](/docs/api-reference/database-context).

**Claude**

```
Keep my quick exploration note in a local file, then publish my updated DATAMODEL from disk so scratch stays local and the team gets the stable definitions.
```

**CLI**

```bash
# Scratch stays on disk — not pushed to the database
printf '%s\n' '## Exploration' '- Hypothesis: orders join to customers on customer_id' > NOTES.md

hotdata databases context push DATAMODEL
```

**Python SDK**

```python
import hotdata

# Scratch stays on disk — not published to the database
with open("NOTES.md", "w", encoding="utf-8") as f:
    f.write("## Exploration\n- Hypothesis: orders join to customers on customer_id\n")

ctx = hotdata.DatabaseContextApi(api_client)
body = open("DATAMODEL.md", encoding="utf-8").read()
ctx.upsert_database_context(
    "<database_id>",
    hotdata.UpsertDatabaseContextRequest(name="DATAMODEL", content=body),
)
```

## Who uses this

- Teams shipping agents against one shared semantic description.
- Engineers maintaining join docs next to what catalog discovery turns up.
- Anyone keeping glossary or policy text beside technical mappings.