README

Ask your database questions in plain language — it answers with one guarded, read-only SELECT.
The SQL-only edition: no Qdrant, no embeddings, no indexing. The AI writes the query, SqlGuard vets it, and the answer is grounded in your real rows.

Quickstart · How it works · Cloud vs local · Commands · Usage · Security · Architecture

Why the SQL-only edition?

Install the package, paste an API key, and ask your database questions in plain language. For every question an AI model writes a single read-only SELECT (it may JOIN your approved tables), the query is validated by SqlGuard, run on a read-only connection with a statement timeout, and the real result rows are handed back to the model to phrase a grounded answer.

There is no Qdrant, no embeddings, no vector retrieval — and no per-table configuration: during install you only choose which tables the AI must NOT answer from. Everything else is approved and auto-configured from the schema (column types, foreign keys, indexes).

It also adds a clarifying-question loop: when a question is genuinely ambiguous the model asks short questions, the CLI collects the answers, and it re-asks with them in context.

⚡ Quickstart

composer require dbmind/laravel-sql

Cloud mode needs nothing but an API key from your DBMind dashboard. Local mode needs Ollama with a SQL-capable chat model:

ollama pull qwen2.5-coder:7b

Then run the wizard:

php artisan dbmind1:install      # 1) cloud API key or local Ollama  2) exclude tables  → done
php artisan dbmind1:doctor       # health: DB read access + the AI gateway
php artisan dbmind1:discover     # read-only: list connections, tables, columns
php artisan dbmind1:sync         # after migrations: auto-approve new tables, refresh metadata
php artisan dbmind1:test "which users spent the most? top 3 spenders" --show-sql

Note

The install wizard asks "Which tables should the AI NOT answer from?" — framework tables (migrations, jobs, sessions, …) are pre-selected. Every other table is approved and auto-configured: primary key, readable/filterable/numeric columns, foreign-key join paths and indexed columns are inferred from the schema. Fine-tune by editing storage/app/dbmind1/catalog.json anytime.

🧭 How it works

1. Write the SQL — the model sees a sanitised schema (approved tables, real foreign keys, indexed columns) and writes exactly one SELECT, JOINing along the foreign keys it was given.
2. Guard & execute — SqlGuard rejects anything that isn't a single read-only SELECT on approved tables with no denied columns and an enforced LIMIT. The query runs on a read-only connection under a database-side statement timeout; failures feed a bounded repair loop.
3. Answer from real rows — the result rows (capped and sanitised) go back to the model, which phrases a grounded answer. --show-sql prints the exact query so every answer is auditable.

Two ways to run it

In both modes every generated query passes the local SqlGuard and runs on your local read-only connection. The cloud never connects to your database.

In cloud mode, value encryption is on by default: names, emails, phone numbers and other text values are sealed into opaque [[DBM1:…]] tokens before the rows leave your server. The model copies the tokens verbatim into its answer and the package decrypts them locally — the key never leaves your server. Numbers stay readable so rankings and totals work. Full walkthrough: docs/cloud-request-simulation.md.

On top of that, dbmind1:install lets you mark whole tables or single columns as always-encrypted — for data that is too sensitive even for the default rules (salaries, ledgers, medical records). Values from those selections are sent as tokens numbers and dates included. The choice is stored per source in the catalog (encrypt_all / encrypt) and is hand-editable anytime.

How it differs from dbmind/laravel

Both packages use different namespaces, config keys, and command prefixes, so they can be installed side by side.

🛠 Commands

dbmind1:test flags

• --show-sql — print the SQL that was executed
• --think — prefix an Approach: line stating the metric/assumptions
• --no-clarify — never pause for clarification; answer with best assumptions
• --rounds=N — max clarifying rounds (default 3)

💻 Programmatic use

use DBMind1\Laravel\Facades\DBMind1;
use DBMind1\Domain\DTO\AskRequest;

$response = DBMind1::ask(new AskRequest('top 3 customers by spend', allowClarify: false));

if ($response->isClarification()) {
    // $response->clarifyingQuestions() — collect answers, then:
    // DBMind1::ask($request->withClarification($q, $a));
}

$response->answer;            // the grounded answer
$response->metadata['sql'];   // the read-only SELECT that ran

🛡 Security

• Read-only. SqlGuard allows exactly one SELECT — no DML/DDL, no stacked statements, no comments — and always enforces a LIMIT. It runs through the connection's read PDO; for defence in depth point DBMIND1_SQL_CONNECTION at a user with only SELECT grants.
• Approved tables only. Every FROM/JOIN target must be an approved source.
• Denied columns blocked, three ways. password, token, secret, api_key, … are stripped from the schema the model sees, rejected by SqlGuard if they appear in a query, and stripped from result rows before they reach the model. SELECT * is rejected outright so unlisted columns can never leak through a star-select.
• Statement timeout. Every generated query runs under a database-side timeout (DBMIND1_SQL_TIMEOUT_MS, default 5 s) — a heavy query is killed by the server and the error feeds the model's repair loop.
• Fast by construction. The model is given the real foreign keys and indexed columns and instructed to join/filter along them only.

Important

This edition is not tenant-scoped (raw SQL can't be safely tenant-filtered). For multi-tenant isolation use the full dbmind/laravel plan engine.

⚙️ Configuration

Publish with php artisan vendor:publish --tag=dbmind1-config. Key env vars:

DBMIND1_PROVIDER=cloud             # cloud | local

# cloud
DBMIND1_API_URL=https://dbmind.online
DBMIND1_API_KEY=sk_live_…          # from your DBMind dashboard
DBMIND1_PROJECT_ID=project_…
DBMIND1_ENCRYPT_VALUES=true        # encrypt text values in result rows (default on)
DBMIND1_CRYPT_KEY=                 # optional explicit key (base64:…); else derived from APP_KEY
DBMIND1_ENCRYPT_DATES=false        # also encrypt date values

# local
DBMIND1_OLLAMA_URL=http://localhost:11434
DBMIND1_CHAT_MODEL=qwen2.5-coder:7b

# both
DBMIND1_SQL_CONNECTION=            # optional read-only connection name
DBMIND1_SQL_MAX_ROWS=200
DBMIND1_SQL_MAX_ATTEMPTS=3         # query-repair retries
DBMIND1_SQL_TIMEOUT_MS=5000        # DB-side statement timeout
DBMIND1_CLARIFY=true
DBMIND1_THINK=false

🏛 Architecture

src/
  Domain/          Contracts, DTOs, Exceptions          (pure PHP, no framework)
  Application/     Use cases: Asking, Catalog (auto-config), Discovery
  Infrastructure/  Adapters: Ollama gateway, Cloud SQL gateway, read-only executor, HTTP
  Security/        SqlGuard, ColumnDenyList, SourcePolicy
  Support/         SchemaSerializer, Prompts, TokenEstimator
  Laravel/         ServiceProvider, Facade, Console     (the only Laravel-coupled layer)

Application depends only on Domain contracts; Infrastructure implements those contracts; Laravel/DBMind1ServiceProvider is the composition root that wires them together. Data crosses boundaries as final readonly DTOs — never arrays or Eloquent models.

🧪 Testing

composer test    # Pest unit tests (framework-free: SqlGuard, AskService, auto-config, cloud gateway)
composer lint    # Laravel Pint

📄 License

MIT — see LICENSE.