database

Multi-driver async SQL database module with support for SQLite, PostgreSQL, MySQL, SQL Server, and Oracle. Provides named connection management, query execution, full schema introspection, security policies, business annotations, read replica routing, and transaction control.

Property	Value
Module ID	database
Version	1.0.0
Type	database
Platforms	All
Async Drivers	aiosqlite, asyncpg, aiomysql, aioodbc, oracledb
Declared Permissions	database:read, database:write, database:admin

---

Actions (28)

Connection Management

Action	Description	Key Parameters
connect	Open named database connection	connection_id, driver, database, host, port, username, password_env, policy, role, group, persist, options
disconnect	Close connection (or all with *)	connection_id
list_connections	List active connections with metadata	—
ping	Check connection liveness with auto-reconnect	connection_id, reconnect

Query Execution

Action	Description	Key Parameters
execute_query	Raw SQL (DDL, DML)	connection_id, query, parameters
fetch_results	SELECT with safety LIMIT injection	connection_id, query, parameters, limit
explain_query	Show query execution plan (EXPLAIN)	connection_id, query, params, analyze
fetch_paginated	Cursor-based pagination for large results	connection_id, query, params, page_size, cursor
query_history	Recent query history with timing and errors	connection_id, limit, errors_only

Security:

• @requires_permission(Permission.DATABASE_WRITE) for execute_query
• @audit_trail("detailed") for execute_query
• All queries use parameterized binding — SQL injection is prevented by design

Schema Introspection

Action	Description	Key Parameters
list_tables	List all tables with columns and indexes	connection_id
get_table_schema	Detailed column types, nullability, PKs	connection_id, table
table_stats	Row count and size stats	connection_id, table
sample	Fetch sample rows for data shape	connection_id, table, limit
introspect	Full schema dump (all tables)	connection_id
describe	Full table context: schema + stats + samples + annotations	connection_id, table
schema_diff	Compare schema against saved baseline	connection_id, save_snapshot

Business Context

Action	Description	Key Parameters
annotate	Add/update annotations on tables or columns	connection_id, table, description, columns
get_annotations	Retrieve annotations	connection_id, table, column

Security & Audit

Action	Description	Key Parameters
set_policy	Update connection security policy	connection_id, policy
get_audit_log	Retrieve audit log entries	connection_id, limit

Transaction Control

Action	Description	Key Parameters
begin_transaction	Start transaction	connection_id
commit_transaction	Commit	connection_id
rollback_transaction	Rollback	connection_id

Watcher Integration

Action	Description	Key Parameters
list_items	List watchable items (tables/views)	connection_id
checksum	Compute content hashes for change detection	connection_id, item_ids
extract_for_index	Extract schema for index module	connection_id

---

Read Replica Routing

Connections with the same group and different role values form a replica set:

- action: connect
  params:
    connection_id: main_db
    role: primary
    group: main
    # ...

- action: connect
  params:
    connection_id: main_replica
    role: replica
    group: main
    # ...

Read queries on the group are automatically distributed across replicas via round-robin.

---

Security Policies

Per-connection policies control what queries are allowed:

Preset	Description
readonly	Only SELECT queries allowed
safe_write	SELECT + INSERT/UPDATE, no DDL
unrestricted	All queries allowed

Fine-grained control with set_policy:

- action: set_policy
  params:
    connection_id: main_db
    policy:
      preset: safe_write
      allowed_tables: [users, orders]
      blocked_tables: [credentials]
      blocked_keywords: [DROP, TRUNCATE, ALTER]
      max_rows: 10000

---

App YAML Configuration

The database module is fully configurable via the Digitorn app YAML system. See docs/app-config.yaml for a complete reference with all options.

Use digitorn app schema database to view the full YAML schema in the terminal.

---

Implementation Notes

• Named connection IDs allow multiple concurrent database connections
• SQLAlchemy async engine with connection pooling (pool_size, max_overflow, pool_recycle)
• SQLite: WAL mode enabled, foreign key enforcement on
• Persistent connections survive daemon restarts when persist: true
• Parameterized queries only — string interpolation is never used
• Audit log tracks all queries with timestamps, durations, and blocked status
• Annotations persist across restarts and enrich LLM context