Guide Database Navigator

An agent that helps teams navigate and understand complex database schemas, providing interactive exploration of table relationships, column definitions, data flows, and documentation to accelerate database comprehension and reduce time-to-productivity.

When to Use This Agent

Choose Database Navigator when:

• Onboarding to a new project with an unfamiliar database schema
• Exploring table relationships and foreign key chains
• Understanding data flows through complex multi-table operations
• Creating documentation for existing database structures
• Investigating where specific data lives across a large schema

Consider alternatives when:

• Designing new database schemas from scratch (use a database architect agent)
• Optimizing query performance (use a DBA agent)
• Migrating between databases (use a migration specialist agent)

Quick Start

Copy
# .claude/agents/guide-database-navigator.yml
name: Database Navigator
model: claude-sonnet-4-20250514
tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
prompt: |
  You are a database navigation expert. Help users understand
  complex database schemas by exploring table relationships,
  tracing data flows, and creating clear documentation. Make
  large schemas approachable through interactive exploration.

Example invocation:

Copy
claude --agent guide-database-navigator "Map out the order
  processing data flow in our database - from when a customer
  places an order through fulfillment and invoicing. Show all
  tables involved and their relationships."

Core Concepts

Schema Exploration Workflow

1. Schema Overview → table count, key entities, naming conventions
2. Entity Mapping → primary entities and their relationships
3. Data Flow Tracing → follow data through table chains
4. Documentation → ERD, data dictionary, flow diagrams

Relationship Mapping

Relationship	Indicator	Example
Direct FK	Foreign key constraint	orders.customer_id → customers.id
Implicit FK	Naming convention, no constraint	log.user_id (no FK defined)
Junction table	Table with two FKs, no own data	order_items(order_id, product_id)
Polymorphic	Type + ID columns	comments(commentable_type, commentable_id)
Self-referential	FK to same table	employees.manager_id → employees.id
Hierarchical	Parent-child in same table	categories.parent_id → categories.id

Data Flow Diagram Format

Customer places order:
  customers → orders → order_items → products
                  ↓         ↓
              payments   inventory_movements
                  ↓
              invoices → invoice_lines
                  ↓
              shipping → tracking_events

Configuration

Parameter	Description	Default
schema_source	Schema information source	Migration files
diagram_format	Entity diagram style	ASCII
include_columns	Show column details in maps	true
trace_depth	Relationship tracing depth	3 levels
documentation_format	Output format for docs	Markdown
include_indexes	Show index information	true
show_data_types	Display column types	true

Best Practices

1. Start with the core business entities, not every table. Large databases can have hundreds of tables, but only 10-15 represent the core business domain. Identify the primary entities (customers, orders, products) first, then explore supporting tables outward. This approach builds understanding incrementally rather than overwhelming with the complete schema.

2. Trace data flows through real business scenarios. Instead of reading table definitions in isolation, follow the data through a concrete scenario: "What happens when a customer places an order?" This reveals which tables participate in business processes, what order they're accessed, and how they relate. Scenario-based exploration creates practical understanding that table-by-table reading doesn't.

3. Document naming conventions and patterns early. Most databases follow conventions: created_at for timestamps, _id suffix for foreign keys, is_ prefix for booleans. Identifying these patterns lets you navigate unfamiliar tables by inference. Note inconsistencies too—a table that breaks conventions often has historical reasons worth understanding.

4. Create a visual entity relationship diagram for the core schema. A diagram showing the 15-20 most important tables with their relationships gives anyone a mental model of the database in minutes. Include cardinality (one-to-many, many-to-many) and mark junction tables. Update the diagram when schema changes affect core entities.

5. Identify and document orphaned or legacy tables. Every mature database has tables that are no longer used, tables from abandoned features, and tables whose purpose nobody remembers. Flagging these prevents developers from building on deprecated structures and helps during cleanup initiatives. Check application code for table references before labeling anything as orphaned.

Common Issues

Schema has implicit relationships without foreign key constraints. Many production databases rely on naming conventions (matching _id columns) rather than enforced foreign keys. Identify these implicit relationships by matching column names across tables and checking application code for JOIN queries. Document them explicitly since they won't appear in automated ERD tools that rely on constraint metadata.

Data flow is complex with multiple paths between the same tables. When orders connect to customers through both a direct foreign key and through an invoices table, the schema has redundant paths that can lead to confusion. Map all paths and document which one is authoritative. Check whether the paths stay synchronized or can diverge, and note the implications for queries and reports.

Table purposes are unclear due to poor naming. Tables named data_store, temp_records, or misc_values provide no context about their purpose. Investigate by examining the columns, checking what application code reads and writes to the table, and looking at the git history for when it was created and why. Document the purpose once discovered so future developers don't repeat the investigation.