Database Laravel Package

Product Decisions This Supports

• Build vs. buy (buy = adopt): do not build a query builder. If a workstream needs safe, parameterized SQL with typed row objects, this package removes weeks of custom plumbing. The decision to make is not "build vs. buy" but "adopt a second data-access layer vs. extend the one we already have."
• Framework-boundary decision (the big one). This is a Nette-ecosystem, framework-agnostic library — not a Laravel package. There is no service provider, no facades, no Eloquent bridge. So the real product decision is: do we have a bounded module where a PDO-like layer with automatic FK-driven joins is materially better than Eloquent/Query Builder, and are we willing to run two DB abstractions, two transaction stacks, and two connection configs inside one Laravel app? Default answer should be no; the exception is concrete (see below).
• Roadmap scoping for reporting/read paths. The FK-graph Selection/ActiveRow model is well suited to reporting, exports, admin grids, and data-migration scripts where you want joins inferred from foreign keys instead of hand-written relation definitions. If a roadmap item is "internal reporting/dashboards," this is a credible accelerator; if it's "core domain modeling," it is the wrong tool.
• Multi-vendor database strategy. One API across MySQL, PostgreSQL, SQLite, MS SQL Server and Oracle is a genuine differentiator versus Laravel's driver coverage (Oracle especially). If a customer/enterprise requirement includes MSSQL or Oracle, this becomes a top-three option instead of a footnote.
• Reliability policy decisions unlocked by v3.2.9's typed exceptions. DeadlockException, LockTimeoutException, CheckConstraintViolationException, ConnectionLostException let us define per-failure-mode retry and idempotency policy instead of a catch-all QueryException handler. That's a concrete error-budget/SLO decision, not a nice-to-have.
• Schema-introspection product bets. The reflection layer (Table/Column/Index/ForeignKey metadata, unified FK shape across drivers) can feed schema docs, data dictionaries, or low-code admin scaffolding as a derived artifact rather than a hand-maintained one.
• Version-pinning decision. v4.0 is an RC with breaking changes (removed getPdo()/getDsn(), removed IRow/IRowContainer, Connection+Explorer merged, changed type-conversion defaults). Product call: adopt and pin 3.2.x for stability, treat v4 as a re-evaluation gate, and budget a migration spike if we commit.
• Dependency-risk acceptance. 539 stars and an ambiguous license signal (NOASSERTION) are procurement/legal decisions, not engineering ones — resolve before adoption, not after.

When to Consider This Package

Consider it when most of these hold:

• The workstream is a bounded, read-heavy or script-like surface — reporting, exports, imports, admin grids, ETL, internal tooling — not the core transactional domain.
• You need one API across multiple engines, particularly Oracle or MSSQL, where the framework's native support is thin or absent.
• You want raw SQL with automatic parameter binding, not a full ORM; the team is comfortable with SQL and prefers explicitness over magic.
• You want typed rows and reflection metadata without adopting a heavier ORM and its conventions.
• Your team is already in the Nette ecosystem (then it's the obvious default and most of the friction disappears).
• You can own the integration yourself: config wiring, transaction-lifecycle rules alongside the framework's, and internal docs for the "low-level core vs. Explorer" split and its lazy-execution/N+1 sharp edges.

Look elsewhere when any of these hold:

• You're in a Laravel app and Eloquent or the Query Builder already covers the need. Two data layers mean two transaction managers, two connection pools/configs, inconsistent lastInsertId/date-conversion semantics in one request, and a class of bugs that is expensive to reason about. The cost almost always exceeds the ergonomic win for CRUD.
• You need migrations/schema versioning. This package introspects schema; it does not manage it.
• You need ORM features: relations with eager loading, model events, soft deletes, attribute casting, serialization, policies.
• You need connection pooling or long-lived workers (Swoole/RoadRunner/Octane) — pooling is not part of the package's job.
• You need modern engine-specific features as first-class citizens (Postgres JSONB/arrays, CTEs as API, window functions) — you'll drop to raw SQL anyway, at which point the framework's builder is equally capable.
• Ecosystem support is a hard requirement. Low star count and negligible declared dependents mean you will be largely self-supporting; verify Packagist install/download numbers before deciding, and assume no third-party answers on forums.
• License cannot be cleared. NOASSERTION must be resolved by legal before any code lands; if it can't be, stop here.

How to Pitch It (Stakeholders)

To executives (30 seconds): This is a small, free, mature PHP database library — the cost isn't license fees, it's integration and ownership. Its value is narrow and real: safe SQL with automatic parameter binding, typed results, and one API across five database engines including MSSQL and Oracle. Its risk is also real: it's not built for our framework, its community is small, its license needs clearing, and adopting it means running a second data-access layer. Recommendation: approve a short, timeboxed spike on a bounded, read-only workstream (e.g., internal reporting) with a clear exit criterion — not a framework-wide adoption. Expected cost: days, not weeks. Expected downside if abandoned: near zero.

To engineering:

• What it gives you: parameterized query builder, Selection/ActiveRow with FK-inferred joins, nested transaction() with guards against manual commit/rollback inside it, driver abstraction, and — since 3.2.9 — specific exception types for deadlocks, lock timeouts, check-constraint violations, and lost connections, which is exactly what retry logic needs.
• What it costs you: no framework integration (write and own the wiring), a second transaction lifecycle to reconcile with the existing one, per-driver quirks the changelog shows are still being fixed, and a documented internal sharp edge around lazy execution and N+1 in the Explorer layer. Budget for internal documentation; upstream prose won't match our idioms.
• What we deliberately will not do: replace the existing ORM. This is additive, contained, and reversible.
• Version posture: pin 3.2.x. v4 is pre-release with breaking API changes (removed getPdo()/getDsn()/IRow, merged Connection+Explorer, changed boolean/datetime conversion defaults) — attractive for new drivers beyond PDO, but not a foundation to build on today.
• Exit criteria for the spike: measurable win over the existing builder on a real query set, transaction behavior provably consistent with the rest of the app, license cleared, and no second connection config shipped to production. If any of those fail, we walk away at a known, small cost.