Pg Builder Laravel Package

Product Decisions This Supports

• Build vs. buy for complex Postgres read paths. The package replaces hand-rolled SQL string concatenation for reporting, analytics, and admin dashboards with a structured, parameter-binding-aware builder. The decision it unblocks: do we invest engineering weeks in an internal query DSL, or adopt a small, permissively licensed library behind an adapter?
• Roadmap sequencing for Postgres-native features. Its value is concentrated in features teams routinely defer because Eloquent makes them awkward: recursive CTEs, window functions, LATERAL joins, RETURNING, ON CONFLICT upserts, array and JSONB operators, full-text search, and custom operators. If those are on the roadmap, this is a credible enabler; if the roadmap is CRUD and forms, it is not.
• Feature scoping. Because the builder is backed by a SQL parser, it can ingest an existing SQL string and let you modify it structurally rather than by regex or concatenation. That supports scoping decisions around: saved/shared queries that users can refine, query templates with injected filters, and "edit this report" style features.
• Query governance and multi-tenancy. Parse-and-rewrite is the interesting capability for a PM: injecting tenant or row-level filters into stored or user-authored SQL, canonicalizing queries for audit logs, or failing CI on disallowed constructs. This is a platform/compliance decision, not just an ORM preference.
• Architecture: read models vs. Eloquent. It argues for a repository/read-model layer where complex reads are expressed in this builder and writes/CRUD stay in Eloquent. That is a structural decision about where complexity is allowed to live.
• Vendor and dependency risk. 59 stars and zero dependents means this is an unproven bet. The PM decision is whether a small, forkable, BSD-2-Clause dependency is acceptable inside a wrapped interface with a documented exit path — typically yes for a contained read path, no as a foundational layer.

When to Consider This Package

Consider it when most of the following hold:

• You are Postgres-only, and staying that way. The API is explicitly Postgres-flavored; it is not a portability layer.
• Your hard problems are SQL-shaped. Analytics, reporting, hierarchical/recursive data, JSONB querying, bulk upsert, or window-function-heavy listings where Eloquent becomes raw DB::select with interpolated strings.
• You need to consume SQL you did not write — stored queries, user-saved filters, generated SQL — and rewrite it safely.
• Your team is fluent in SQL and comfortable reading a builder API. This is not an abstraction that hides SQL; it is an abstraction that structures it.
• You can wrap it. Adopt behind an internal interface so call sites do not import its types directly, and so a fork or replacement is a contained change.
• You accept maintenance risk. Verify release cadence, PHP version support, issue responsiveness, and test coverage in a short spike before committing. The license permits forking; budget the willingness, not necessarily the effort.

Look elsewhere when:

• You support MySQL/SQLite/SQL Server or plan to. Use Laravel's query builder and accept its limits.
• The feature set is plain CRUD. Eloquent and the standard builder are sufficient; the integration cost is pure overhead.
• You need batteries-included Laravel integration. There is no first-party Laravel provider, no Eloquent relationship bridging, and essentially no ecosystem to lean on.
• You need commercial support, an SLA, or a large hiring pool. Zero dependents and a small star count mean you are largely on your own.
• Your team treats SQL as an implementation detail to be avoided. The API will read as ceremony.
• Compliance or security review requires a maintained vendor. Even permissive licenses do not substitute for a support contract.

Suggested gate before adoption: a one-to-two week spike that (a) reimplements three of your ugliest existing queries, (b) proves parameter binding and injection safety on user-supplied filters, (c) confirms PHP/Laravel version compatibility, and (d) demonstrates the parse-and-rewrite path on a real stored query.

How to Pitch It (Stakeholders)

For executives. We have a recurring class of features — reporting, dashboards, admin tooling, complex filtering — where our current stack pushes engineers into hand-written SQL, which is slow to build, hard to review, and a standing injection risk. This package is a small, permissively licensed (BSD-2) library that lets us build those queries in structured, testable PHP while keeping full Postgres expressiveness. The cost is low and the blast radius is contained: we would wrap it behind our own interface, use it only for complex read paths, and keep Eloquent for everything else. The risk is maturity — it is a small project with no dependents — which is why the recommendation is a time-boxed spike and a contained pilot, not a codebase-wide standard. If it works, it removes a recurring source of engineering drag and de-risks the analytics roadmap; if it doesn't, we have spent two weeks and can fork or discard it.

For engineering. The pitch is not "replace Eloquent." It is: stop concatenating SQL strings for the 10% of queries that are genuinely complex. You get composable query objects, typed parameter binding, and a parser that lets you take an existing SQL string and modify it structurally — useful for tenant filtering, query auditing, linting in CI, and user-editable saved queries. The trade-offs are real: no Laravel integration to speak of, a Postgres-specific API, a small upstream with a single-maintainer risk profile, and a learning curve if you have not worked with a builder that mirrors SQL grammar rather than hiding it. Mitigations: adopt behind an internal adapter, pin versions, keep a fork branch warm, cover the adapter with characterization tests against raw SQL, and confine usage to read paths where a swap is cheap.