Database onboarding and schema introspection

SchemaRouter can treat databases as typed capability sources without exposing connection objects, credentials, or arbitrary query strings to the model.

The database layer follows the same boundary as provider-first onboarding:

caller-owned connection / engine
        ↓
trusted schema introspection
        ↓
ToolSpec / EndpointSpec / FieldSpec
        ↓
principal-aware retrieval
        ↓
bounded read-only invoker
        ↓
database-native authorization

SchemaRouter does not become a database proxy or IAM system. The host application owns authentication, secrets, connection pools, and native database roles.

SQLite reference path

SQLite is the dependency-free reference implementation.

import sqlite3

from schemarouter import SchemaRouter

connection = sqlite3.connect("/srv/app/company.db")

router = SchemaRouter()
keys = router.add_sqlite_database(
    connection,
    database_name="company",
    tables={"employee_directory", "orders"},
)

SchemaRouter inspects the selected tables/views and compiles:

• one typed tool per table/view;
• fields from table columns;
• primary-key exact-match parameters when a primary key exists;
• bounded limit / offset;
• projected read-only select operations.

There is no model-visible sql, where, or raw-query parameter.

The live sqlite3.Connection stays only inside the trusted invoker.

SQLAlchemy engines

Install the optional database integration:

pip install "schemarouter[database]"

Then pass a caller-owned SQLAlchemy Engine:

from sqlalchemy import create_engine

from schemarouter import SchemaRouter

engine = create_engine(DATABASE_URL)

router = SchemaRouter()
keys = router.add_sqlalchemy_database(
    engine,
    database_name="erp",
    schemas=["public"],
    tables={"orders", "customers"},
)

SQLAlchemy performs dialect-specific reflection and parameter binding. The Engine URL, password, driver state, pool, and live connections are never copied into ToolSpec metadata.

The generic SQLAlchemy path is intended to cover relational and warehouse systems for which a working SQLAlchemy dialect/driver exists, including PostgreSQL, MySQL/MariaDB, Microsoft SQL Server, Oracle, SQLite, and common warehouse dialects. This is a dialect capability statement, not a claim that every vendor has completed live acceptance testing.

Authorization

Database tools compose with PrincipalContext and AuthorizationPolicy.

For example, an employee may see only a directory view while a manager can retrieve the underlying employee table and an executive can additionally see board financial tables.

AuthorizationRule(
    effect="allow",
    operation="company.employee_directory.*",
    roles_any=("employee", "manager", "executive"),
)

AuthorizationRule(
    effect="allow",
    operation="company.employees.*",
    roles_any=("manager", "executive"),
)

AuthorizationRule(
    effect="allow",
    operation="company.board_financials.*",
    roles_any=("executive",),
)

Unauthorized relations are removed before model-visible retrieval and are checked again before execution.

Database-native roles, grants, RLS, and ACLs remain authoritative. SchemaRouter policy may narrow what is visible or callable, but it must never broaden the database account's native rights.

Current query boundary

The first database execution surface is deliberately narrow:

• read-only;
• explicit output-field projection;
• exact-match filters on introspected primary-key columns;
• bounded limit/offset;
• parameterized execution;
• no arbitrary SQL generated by the model;
• no DDL/DML execution.

This keeps schema discovery separate from query authority.

Current database-family coverage

Different database families keep their native execution model instead of being forced into SQL.

Family	Current core path
SQLite	stdlib introspection + bounded SELECT
RDB / warehouse	caller-owned SQLAlchemy Engine with dialect reflection
Vector	provider-neutral contract plus Qdrant, Milvus, Pinecone, Weaviate, Chroma, PostgreSQL/pgvector adapters
Property graph / RDF	provider-neutral contract plus Neo4j, Neptune, ArangoDB, FalkorDB, SPARQL adapters
Document / search / key-value / time-series	provider-neutral contract plus MongoDB, Elasticsearch/OpenSearch, DynamoDB, Cosmos DB, Couchbase, ClickHouse, InfluxDB adapters
Cross-family authorization	shared capability, field, row/tenant, collection/source, relationship and hop scopes

See enterprise data onboarding for the cross-family model and the vector, graph, and record-store guides for vendor-specific behavior.

Support means the adapter and bounded contract exist in core. Live external acceptance still varies by vendor/version/deployment and is reported separately from that architectural support.

Vendor-specific credentials and client objects stay behind adapters/plugins rather than becoming part of SchemaRouter's model-visible graph.