PHPackages                             dbmind/laravel-sql - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. dbmind/laravel-sql

ActiveLibrary[Database & ORM](/categories/database)

dbmind/laravel-sql
==================

DBMind 1.0 — the SQL-only edition: a local Ollama model writes guarded, read-only SQL (with JOINs) against your approved tables and answers from the real rows. No Qdrant, no embeddings.

v1.0.0(1mo ago)00MITPHPPHP ^8.3

Since Jun 10Pushed 1mo agoCompare

[ Source](https://github.com/mo-alzainy/dbmind)[ Packagist](https://packagist.org/packages/dbmind/laravel-sql)[ RSS](/packages/dbmind-laravel-sql/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (7)Versions (2)Used By (0)

 [![DBMind 1.0 — your database speaks SQL, now you don't have to](art/banner.svg)](art/banner.svg)

 [![PHP 8.3+](https://camo.githubusercontent.com/652bc58942f389fc0befe411ebb0ce450d1a070c1cd54fb4a1f554c3e5bc690a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e332532422d3763366366663f7374796c653d666c61742d737175617265266c6f676f3d706870266c6f676f436f6c6f723d7768697465)](https://www.php.net/releases/8.3/) [![Laravel 11, 12, 13](https://camo.githubusercontent.com/1f045034e70d15def3d95835ac5b606dd8e8e6c90904a78454d75283ccd9ad02/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d3131253230c2b72532303132253230c2b725323031332d6666346438643f7374796c653d666c61742d737175617265266c6f676f3d6c61726176656c266c6f676f436f6c6f723d7768697465)](https://laravel.com) [![Tested with Pest](https://camo.githubusercontent.com/bc74ff7f82782964637c1418d9c35217c0a43d0df43628ecf01f0baa35676c5d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f74657374732d506573742d3334653364303f7374796c653d666c61742d737175617265)](#-testing) [![MIT license](https://camo.githubusercontent.com/87d23ec8f394993bab6ee6f7bd2872a68156f84ce1df1643cc9ddc161f796743/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d6537623735623f7374796c653d666c61742d737175617265)](https://camo.githubusercontent.com/87d23ec8f394993bab6ee6f7bd2872a68156f84ce1df1643cc9ddc161f796743/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d6537623735623f7374796c653d666c61742d737175617265)

 **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](#-quickstart) · [How it works](#-how-it-works) · [Cloud vs local](#two-ways-to-run-it) · [Commands](#-commands) · [Usage](#-programmatic-use) · [Security](#-security) · [Architecture](#-architecture)

---

Why the SQL-only edition?
-------------------------

[](#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
------------

[](#-quickstart)

```
composer require dbmind/laravel-sql
```

**Cloud mode** needs nothing but an API key from your DBMind dashboard. **Local mode** needs [Ollama](https://ollama.com) 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
```

 [![A dbmind1:install session followed by a guarded text-to-SQL answer](art/terminal.svg)](art/terminal.svg)

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
--------------

[](#-how-it-works)

 [![The DBMind 1.0 pipeline: write the SQL, guard and execute, answer from real rows](art/pipeline.svg)](art/pipeline.svg)

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
------------------

[](#two-ways-to-run-it)

`cloud` (recommended)`local`Setuppaste the API key from your DBMind dashboardrun Ollama + pull a modelWho reasonsfrontier models via the hosted DBMind gateway (`/v1/sql/*`, OpenRouter-backed)your own Ollama serverWhat leaves the serverquestion + schema metadata + the query's result rows (capped + sanitised, **private text values AES-256-GCM-encrypted**)nothingWho touches your DB**only your server** — SQL is guarded and executed locally in both modessameBilling / quotasmetered per token on your DBMind planfreeIn **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`](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`
------------------------------------

[](#how-it-differs-from-dbmindlaravel)

`dbmind/laravel``dbmind/laravel-sql` (this)Namespace`DBMind\``DBMind1\`Config / commands`dbmind`, `dbmind:*``dbmind1`, `dbmind1:*`Answeringvector RAG + plan engine + raw SQL**raw SQL only**Joins across tables✗ (plan engine)✓ (follows real foreign keys)Clarifying questions✗✓ (interactive)Qdrant / embeddingsrequired**none**Table approvalper-table wizard**exclusion list** ("don't answer from X")Both packages use different namespaces, config keys, and command prefixes, so they can be installed side by side.

🛠 Commands
----------

[](#-commands)

CommandPurpose`dbmind1:install`Interactive setup: provider + table exclusions + auto-config`dbmind1:doctor`Health check: DB read access + the AI gateway`dbmind1:discover`Read-only listing of connections, tables, columns`dbmind1:sync [--dry-run]`After migrations: auto-approve new tables, refresh metadata`dbmind1:test "question"`Ask from the CLI### `dbmind1:test` flags

[](#dbmind1test-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
------------------

[](#-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
----------

[](#-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
----------------

[](#️-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
--------------

[](#-architecture)

 [![Clean architecture: dependencies point inward, the framework lives only at the edge](art/architecture.svg)](art/architecture.svg)

```
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
---------

[](#-testing)

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

📄 License
---------

[](#-license)

MIT — see [LICENSE](LICENSE).

###  Health Score

38

—

LowBetter than 83% of packages

Maintenance91

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity48

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

46d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/198031590?v=4)[mo-alzainy](/maintainers/mo-alzainy)[@mo-alzainy](https://github.com/mo-alzainy)

---

Top Contributors

[![mo-alzainy](https://avatars.githubusercontent.com/u/198031590?v=4)](https://github.com/mo-alzainy "mo-alzainy (5 commits)")

---

Tags

laravelaisqlllmollamatext-to-sqlnl2sql

###  Code Quality

TestsPest

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/dbmind-laravel-sql/health.svg)

```
[![Health](https://phpackages.com/badges/dbmind-laravel-sql/health.svg)](https://phpackages.com/packages/dbmind-laravel-sql)
```

###  Alternatives

[laravel/ai

The official AI SDK for Laravel.

1.0k3.2M247](/packages/laravel-ai)[spatie/laravel-health

Monitor the health of a Laravel application

87912.0M177](/packages/spatie-laravel-health)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9762.4M133](/packages/roots-acorn)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

255.2k](/packages/aedart-athenaeum)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)