Persist Sql Query Laravel Package

Product Decisions This Supports

Build vs. buy for "query-as-data" features. Most of the value here lands in one product decision: do we treat a query as a code artifact (hand-written DB::select()) or as stored, editable data? jasny/persist-sql-query is built for the second model — a query object that can be built in PHP, rendered to SQL, re-parsed from SQL, and persisted (serialized) for later retrieval. That directly unlocks:

• Saved searches / saved views. A user composes filters, we store the query definition (not just the resulting rows), and later rehydrate, tweak, and re-run it. This is a recurring ask in admin panels, CRM/lead tooling, and reporting surfaces, and it's awkward to do well on top of Eloquent's array-based ->where() chains.
• User-defined report and dashboard builders. Non-engineers assemble a query; the app persists it, renders SQL for preview, and schedules it. The parse step matters because it lets us accept an existing SQL fragment (from a legacy report, an admin, or a migration) and fold it into our object model rather than special-casing strings everywhere.
• Query templates and "clone and modify" flows. Duplicate a saved query, swap a date range or a segment, re-save. Round-tripping is the enabling primitive.
• MySQL-specific write paths that Laravel's builder handles clumsily. INSERT ... ON DUPLICATE KEY UPDATE, INSERT ... SELECT, joined UPDATE/DELETE, and grouped/nested result hydration — bulk imports, sync jobs, and denormalized upserts. Worth a spike before we hand-roll these with raw SQL in five places.
• Auditability and governance. Because the query is an object we can render deterministically, we can log the exact SQL executed alongside the definition that produced it — useful for regulated data access and for debugging "why did this report change."

Roadmap fit. Treat this as infrastructure behind a feature bet, not a feature itself. If saved searches / configurable reporting is on the roadmap for the next two quarters, this package shortens the discovery-to-ship path. If it isn't, there is no standalone reason to adopt it.

Buy-side caveat to price in. Last release 2020-10-21, ~33 stars, single-maintainer. That is a maintenance cost we must budget explicitly: MIT license means we can fork and vendor it, and the surface area is a query builder — tractable to own — but someone must own it.

When to Consider This Package

Adopt only when most of the following hold:

• MySQL is the system of record and will stay so. This is MySQL-specific. Any Postgres or multi-dialect requirement — including a plausible future migration — is a hard stop. Laravel's grammars exist precisely for portability; this package trades that away deliberately.
• The product needs round-tripping, not just building. If we only need to generate SQL, Laravel's query builder (or a thin repository layer) is sufficient and already maintained. The parse-and-persist capability is the actual differentiator; without a use case for it, we're paying dependency risk for no unique value.
• Advanced MySQL syntax is on the critical path. Upserts with join semantics, multi-table updates, insert-from-select — and we've confirmed we'd otherwise be scattering raw SQL. Validate with a one-day spike against our real query shapes before committing.
• We accept it as our code. Fork-and-vendor or pin-and-patch is the realistic operating model. If the team can't absorb that, don't adopt.
• PHP version compatibility is verified. Confirm it runs on our current PHP runtime (post-2020 release against a modern PHP 8.x line) before it enters a design doc. This is a blocker check, not a footnote.

Look elsewhere — or build thin in-house — when:

• We need Eloquent relationships, model events, soft deletes, casting, or eager loading. This does not interoperate with Eloquent's hydration and grammar; it's a parallel data-access path. Introducing it means two ways to talk to the database, which is a real cognitive and correctness cost.
• Queries come from untrusted users. A parser is not a security boundary. If end users supply SQL directly, we need a constrained filter DSL of our own plus strict parameterization and allow-listing; the parse capability should not be mistaken for a validator.
• We need active upstream maintenance, prompt security response, or a large community for hiring and Stack Overflow support. This fails all three.
• A modern, maintained alternative fits. Doctrine DBAL, Laravel's own builder with scoped macros, or a dedicated reporting engine may cover the need with less ownership overhead — worth a half-day comparison before defaulting to this.

How to Pitch It (Stakeholders)

To executives — one line: This is a small, MIT-licensed MySQL query library that lets us store a query the way we store any other record, then load, modify, and re-run it later. It is the cheapest credible path to saved searches and self-serve reporting, which are repeatedly requested and currently expensive to build.

The business case: Today, configurable reporting is bespoke work per feature. Modeling a query as persisted data turns each new report into configuration rather than engineering. That's a leverage argument, not a technology argument — it changes the marginal cost of the next report.

To engineering — the honest version: It does two things our stack does not: it parses SQL back into an object, and it renders and persists that object. That enables round-trip editing and MySQL syntax we currently write by hand (upserts, joined updates, insert-from-select, grouped hydration). The cost is explicit: it is MySQL-only, it does not integrate with Eloquent, and it has had no release since October 2020. We would vendor and own it. The code is a query builder — contained, testable, and MIT-licensed — so ownership is bounded, but it is not free.

The ask: A one-week spike behind a single feature (saved search or upsert-heavy import) to validate PHP-version compatibility, real query shapes, and the parse round-trip on our data. Success criteria: round-trip fidelity on our top ten queries, no Eloquent interop surprises, and a written position on forking. Failure is cheap and informative; success gives us a reusable primitive and a concrete fork-or-follow decision rather than an open-ended dependency.

The risk we are naming, not hiding: single maintainer, stale release, narrow community. We mitigate with a fork, a pin, and an owner. If the spike shows we mostly need the builder and not the parser, we should stop and use Laravel's builder — the parser is the reason to be here.