Legacy SQL tool loop

New projects should start with RLM over local SQLite. RLM can inspect a schema, query and re-query data, calculate intermediate results, and make semantic subcalls in one adaptive loop.

The SQL tool loop is an older SDK-side helper for applications that need a narrowly controlled text-to-SQL flow. It asks a model to inspect a schema, generate one or more queries, validates each query through /sql/validate, and executes approved SQL through handlers supplied by the application.

When to keep using it

Use the legacy loop when:

The application already integrates its handlers.
The desired flow is schema inspection followed by a small number of SQL queries.
Returning the exact executed SQL and rows is more important than open-ended analysis.

Prefer RLM when the task needs iterative exploration, joins across several investigations, Python calculations, semantic classification, or synthesis across many query results.

Safety model

The helper exposes four application-defined operations:

Operation	Purpose
`list_tables`	List tables visible to the model
`describe_table`	Return allowed columns and types
`sample_rows`	Return a bounded sample when enabled
`execute_sql`	Execute a query after validation

The application remains responsible for database credentials and execution. /sql/validate checks a query against an inline policy or SQL profile, but database permissions remain the final security boundary.

Production integrations should:

Use a read-only database user.
Allowlist tables and columns.
Cap rows, bytes, attempts, and execution time.
Treat model-generated SQL as untrusted input.
Log validated and executed SQL.

Migration to RLM

For SQLite, replace the handler loop with:

mrl rlm "What are the top customers by order value, and what explains the ranking?" \
  --db ./app.db \
  --sql-profile "$MODELRELAY_SQL_PROFILE_ID"

For a hosted or non-SQLite database, keep credentials in your boundary and expose a controlled adapter. See RLM data sources and Security and Data Boundaries.