Getting Started

Install with composer require knobik/sql-agent; Laravel package discovery should register the service provider. Publish the package config using the tag documented in the README, then review config/sql-agent.php.
Look first at the table-permission configuration: allowed/restricted tables, connection selection, and any prompt/schema introspection settings. This is the main security boundary.
Configure a dedicated read-only database connection/user for the agent. Do not let the agent run as your application’s primary write-capable user.
First use case: an internal read-only “ask the database” tool over a small reporting schema. Start with an explicit allowlist of non-sensitive tables, restrict auth/audit/pivot tables, and test prompts that attempt joins, subqueries, and references to restricted tables.
Upgrade to 0.9.1 before exposing table restrictions to users. It fixes restricted tables leaking through references on permitted tables, so treat it as a security patch.

Implementation Patterns

Prefer explicit allowlists over blocklists. Define table access in config or a permission callback, scoped by tenant, role, or feature area.
Wrap agent calls in an application service rather than calling the package directly from controllers. This gives you one place for authorization, logging, result limits, and redaction.
Gate the feature itself with Laravel policies/Gates. The SQL agent’s table permissions are necessary but not sufficient; only authorized users should be able to invoke it.
Use separate agent configurations per domain: e.g. a sales reporting agent with sales tables only, and a support agent with support tables only. Narrow scopes reduce accidental cross-domain access.
For chat/dashboard integrations, persist the prompt, generated SQL, referenced tables, execution time, row count, and user ID. Redact sensitive values before writing to logs.
Add feature tests for permission boundaries: prompts that join permitted tables to restricted ones, reference restricted table names in subqueries, or ask for schema details. Include a regression test for the 0.9.1 fix.
When deploying, pin the package version, run composer update knobik/sql-agent, clear config cache, and re-run permission-boundary tests.

0.9.1 is a security-relevant release. If you use restricted tables, upgrade promptly and re-test joins, subqueries, relationship references, and schema introspection paths.
Do not rely on prompt instructions like “never query restricted tables.” Enforce restrictions in configuration and, ideally, at the database grant level.
Restricted tables can leak through more than result rows: generated SQL, foreign-key references, error messages, schema introspection, and model relationships. Verify all of these when testing.
After changing allowed/restricted tables, run php artisan config:clear locally and php artisan config:cache in production. Stale config can silently preserve old permissions.
Avoid wildcard permissions. Explicitly list tables and review new migrations for tables that should be restricted by default.
Debug with structured logs: prompt, generated SQL, tables referenced, execution time, and row count. Do not log raw result sets unless you have redaction.
Use a read replica and enforce row limits/timeouts where possible. Natural-language query tools can generate expensive queries.
Keep custom permission resolvers, prompt builders, and query execution wrappers in your application code rather than editing vendor files, so package upgrades remain safe.