python-sdk/docs/tools/database.md

Database Tools

The database tools (hanzo-tools-database) provide SQL and graph database operations for project-embedded databases.

Overview

Each project can have an embedded SQLite database with tables for metadata, files, and symbols. The database tools also support graph database operations for tracking code relationships.

SQL Tools

sql_query - Execute SQL Queries

Execute raw SQL on the project database:

# Read query (default safe mode)
sql_query(query="SELECT * FROM files LIMIT 10")

# Query with specific project
sql_query(query="SELECT name, type FROM symbols WHERE type='function'", project_path="/project")

# Write query (requires read_only=False)
sql_query(
    query="INSERT INTO metadata (key, value) VALUES ('version', '1.0')",
    read_only=False
)

Parameters

Parameter	Type	Default	Description
query	str	required	SQL query to execute
project_path	str	cwd	Project path
read_only	bool	True	Block write operations

Database Schema

Default tables in project databases:

-- Key-value metadata
CREATE TABLE metadata (
    key TEXT PRIMARY KEY,
    value TEXT
);

-- File information
CREATE TABLE files (
    path TEXT PRIMARY KEY,
    content TEXT,
    modified_at TEXT
);

-- Code symbols
CREATE TABLE symbols (
    id INTEGER PRIMARY KEY,
    name TEXT,
    type TEXT,  -- function, class, variable
    file_path TEXT,
    line_number INTEGER
);

sql_search - Full-Text Search

Search database content with text matching:

sql_search(pattern="error", table="files")
sql_search(pattern="TODO", column="content")

sql_stats - Database Statistics

Get database statistics and schema info:

sql_stats()
sql_stats(project_path="/project")

Graph Tools

The graph database stores relationships between code entities (files, functions, classes).

graph_add - Add Nodes/Edges

Add nodes and edges to the graph:

# Add a node
graph_add(node_id="main.py", node_type="file")

# Add an edge
graph_add(
    source="main.py",
    target="utils.py",
    relationship="imports"
)

# Add with properties
graph_add(
    node_id="MyClass",
    node_type="class",
    properties={"methods": 5, "lines": 120}
)

graph_remove - Remove from Graph

Remove nodes or edges:

graph_remove(node_id="deprecated_file.py")
graph_remove(source="a.py", target="b.py", relationship="imports")

graph_query - Query Graph Database

Execute graph traversal queries:

# Find neighbors
graph_query(query="neighbors", node_id="main.py")

# Find path between nodes
graph_query(query="path", node_id="main.py", target_id="utils.py")

# Get subgraph
graph_query(query="subgraph", node_id="MyClass", depth=3)

# Find ancestors (nodes pointing TO this node)
graph_query(query="ancestors", node_id="error_handler", relationship="calls")

# Find descendants (nodes this node points TO)
graph_query(query="descendants", node_id="BaseClass", relationship="inherits")

# Find all connected nodes
graph_query(query="connected", node_id="main.py", direction="both")

Query Types

Query	Description	Required Params
neighbors	Direct neighbors	node_id
path	Shortest path	node_id, target_id
subgraph	Subgraph around node	node_id
connected	All connected nodes	node_id
ancestors	Incoming edges	node_id
descendants	Outgoing edges	node_id

Parameters

Parameter	Type	Default	Description
query	str	required	Query type
node_id	str	-	Starting node
target_id	str	-	Target node (for path)
depth	int	2	Max traversal depth
relationship	str	-	Filter by edge type
node_type	str	-	Filter by node type
direction	str	both	both, incoming, outgoing

graph_search - Search Graph

Search for nodes by properties:

graph_search(pattern="Service", node_type="class")
graph_search(pattern="test_*", relationship="depends_on")

graph_stats - Graph Statistics

Get graph statistics:

graph_stats()
# Returns: nodes count, edges count, relationship types, node types

Relationship Types

Common relationship types in code graphs:

Relationship	Description
imports	File imports another file
calls	Function calls another function
inherits	Class inherits from another
implements	Class implements interface
depends_on	General dependency
contains	File contains symbol

Installation

pip install hanzo-tools-database

Best Practices

1. Use Read-Only Mode

# Default: safe read-only queries
sql_query(query="SELECT * FROM files")

# Only disable when necessary
sql_query(query="UPDATE ...", read_only=False)

2. Filter Graph Queries

# Avoid unbounded traversals
graph_query(query="subgraph", node_id="main.py", depth=2)

# Filter by relationship type
graph_query(query="neighbors", node_id="func", relationship="calls")

3. Index Before Querying

Ensure the project is indexed before running database queries:

# Index project first
index(path="/project")

# Then query
sql_query(query="SELECT * FROM symbols WHERE type='function'")