Db Mssql Laravel Package

Technical Evaluation

Package identity caveat (important): The release notes describe yiisoft/db-mssql 2.0.0 — the Microsoft SQL Server driver for the Yii3 database abstraction layer (yiisoft/db). It is not a Laravel package and has no ServiceProvider, facade, Eloquent, migration, or Illuminate\Database integration. The assessment below evaluates it as a PHP DB-layer dependency that could be consumed from a Laravel codebase only through a custom bridge, not as a drop-in Laravel component.

Architecture fit. Fit is poor for a standard Laravel application, because Laravel's DB stack (connectors, query builder, Eloquent, schema builder, migrations) is built around Illuminate\Database, and this package implements yiisoft/db interfaces instead. Adoption means running a second, parallel DB abstraction alongside Eloquent — effectively two data-access paths, two schema models, and two sets of conventions in one codebase. Fit is good only where the team either (a) is already on Yii3, or (b) has deliberately standardized on yiisoft/db as a framework-agnostic data layer and uses Laravel only for HTTP/container concerns. Note also that 2.0.0 is the companion release to yiisoft/db 2.0; the two must move in lockstep, and the package now advertises a virtual yiisoft/db-implementation provider (#372), which is a helpful Composer-level contract but also cements the coupling.

Integration feasibility. Technically feasible but a multi-sprint effort, not a Composer bump. 2.0.0 is a hard breaking release: removed ColumnInterface (#335), renamed ColumnSchemaInterface → ColumnInterface (#337), renamed insertWithReturningPks() → insertReturningPks() with return type changed to array|false (#366, #344), removed $withColumn from Quoter::getTableNameParts() (#306), moved getRawTableName() from SchemaInterface to QuoterInterface (#308), changed the QueryBuilder constructor (#333), removed Schema::getCacheKey()/getCacheTag() (#352), removed Connection::createBatchQueryResult() (#300), removed hasLimit()/hasOffset() usage (#348), switched to \InvalidArgumentException (#368), and now throws on unsigned column usage (#413). Any existing code touching schema introspection, quoting, cache keys, or insert-returning paths will break at compile or runtime. The new ColumnFactory / ColumnBuilder / ColumnDefinitionBuilder / SqlParser machinery (#277, #316, #320, #322, #293) is a genuine internal redesign, not a cosmetic refactor.

Technical risk.

• High — schema-qualified table names containing dots are no longer supported (#380 "Remove support dots in table names"). MSSQL shops routinely use dbo.Table, database.schema.table, or linked-server four-part names. This is a realistic production-breaking constraint, not a theoretical one.
• High — coordinated upgrade with yiisoft/db 2.0; mixing 1.x and 2.x of the pair is not viable.
• Medium — PHP floor raised to 8.1 and ceiling extended to 8.5 (#344, #317). Fine for modern stacks; verify CI matrices and any 8.0-era runtimes.
• Medium — behavior changes that fail silently-ish: caseSensitive LIKE option (#349), collation support (#386), JSON type (#342), enumeration column type (#415), trimmed dot in default-value normalization for PHP 8.5 warnings (#418). These change generated SQL and introspection output in ways regression tests must cover.
• Medium — upsertReturning() (#361/#362) and expression builders (ArrayMergeBuilder, GreatestBuilder, LeastBuilder, LengthBuilder, LongestBuilder, ShortestBuilder, #390/#396/#404) are attractive new capabilities that reduce hand-written SQL, but they are new code on a fresh major.
• Low/Positive — typed ColumnInterface classes per column type and Schema::loadResultColumn() (#353) should improve introspection and type-casting performance, which is the headline win.

Key questions.

1. Is our target application actually Laravel? If yes, why not Laravel's built-in sqlsrv connector, and what capability gap justifies a parallel yiisoft/db stack?
2. Do we use any dot-qualified table names (dbo., cross-database, linked servers)? If so, #380 alone may block adoption.
3. Which yiisoft/db version is pinned in the dependency graph, and can it be moved to 2.0 in the same window?
4. Do we depend on any removed/renamed API (ColumnSchemaInterface, insertWithReturningPks, getCacheKey, getCacheTag, createBatchQueryResult, Quoter::getTableNameParts with $withColumn)?
5. Do we rely on unsigned column definitions anywhere (they now throw)?
6. Which MSSQL Server versions and which PHP driver (pdo_sqlsrv vs sqlsrv, ODBC driver version) are in scope, and who owns that dependency?
7. Is there any near-term requirement for JSON columns, enum columns, collation-aware behavior, or insertReturningPks() — i.e., is 2.0 needed now, or is this opportunistic?

Integration Approach

Stack fit. Poor-to-conditional. In a Laravel codebase the honest recommendation is: default to Laravel's first-party sqlsrv driver (requires the Microsoft ODBC driver + pdo_sqlsrv/sqlsrv PHP extension) and do not introduce yiisoft/db-mssql unless there is a concrete requirement it uniquely satisfies. If it is genuinely required, treat it as an infrastructure-level dependency confined to a repository/gateway layer, and explicitly forbid Eloquent models from reaching into it (and vice versa) — no cross-layer joins, no shared transactions without a documented two-phase or single-connection strategy.

Migration path. There is no prior adoption, so treat 2.0.0 as greenfield, not upgrade — that removes the 1.x→2.0 breakage problem for us but means we inherit the 2.0 API as the baseline. If any codebase already uses yiisoft/db-mssql 1.x indirectly, pin ^1 and freeze until a full 1.x→2.0 migration is scoped; a partial migration is not realistic given the renames and constructor changes. Composer-wise, adopt yiisoft/db-mssql:^2.0 together with the matching yiisoft/db:^2.0 and treat them as a single versioned unit (use the yiisoft/db-implementation virtual package as the Composer-level assertion).

Compatibility. PHP 8.1–8.5 (matches current Laravel-supported PHP ranges, so runtime coexistence is fine). MSSQL Server version support should be verified empirically rather than assumed — particularly for JSON (#342), enum (#415), and collation introspection (#386), which are metadata-driven. Driver requirement is the real operational gate: ODBC Driver 17/18 for SQL Server plus the sqlsrv/pdo_sqlsrv extensions must be present in every environment, including CI and containers, where Microsoft's driver install is the most common source of "works locally, fails in build" incidents.

Sequencing.

1. Decision spike (1 week): confirm the capability gap versus Laravel's sqlsrv connector; confirm no dot-qualified table names are required. Kill or proceed.
2. Environment proof (1 week): ODBC + extension in Docker/CI; a smoke test that connects, introspects a table, and runs a parameterized query.
3. Gateway layer (1–2 sprints): thin interface + yiisoft/db-mssql implementation behind it; no framework types leak into domain code.
4. Feature validation (1 sprint): exercise the 2.0 headline features we actually need — typed column introspection/loadResultColumn(), upsertReturning(), JSON columns, collation — against representative schema.
5. Hardening (1 sprint): regression suite over every query path, error-handling for the \InvalidArgumentException surface, and a documented ban on unsigned and dotted table names.
6. Pilot in one bounded service, then expand.

Operational Impact

Maintenance. Moderate-to-high. The package is under active, high-velocity development (this single release spans roughly 90 issues/PRs across @Tigrov, @vjik, @rustamwin), and 2.0 restructured the schema/column/quoter internals substantially. Expect a steady 2.0.x bugfix stream and a smaller but real chance of 2.1 changes; budget recurring upgrade work proportional to how deeply the API is used. Keep the dependency behind our own interface so yiisoft/db churn does not reach application code. Also note the cache-key/tag removal (#352) means any caching of schema metadata is now our problem to implement.

Support. Weaker than the Laravel ecosystem: smaller contributor base, fewer Stack Overflow answers, no Laravel-oriented documentation, and error messages that reference Yii terminology. Internal expertise will need to be explicitly cultivated rather than assumed. For MSSQL specifically, Laravel-community knowledge is already thin, so this multiplies rather than adds to it. Assign an owner; do not let this become "the dependency nobody understands."

Scaling. Driver-level performance should be acceptable and is arguably improved by the type-cast ColumnInterface classes (#277, #384) and loadResultColumn() (#353), which target introspection and casting overhead. Two things to size explicitly: (a) Connection::createBatchQueryResult() was removed (#300) — verify large-result-set handling and memory behavior with our own batching, since the built-in batch path is gone; (b) connection pooling / persistent connections must be configured at the ODBC layer, not in PHP, and should be load-tested before we promise throughput numbers.

Failure modes to plan for.

• Runtime exceptions on schema patterns: dotted table names (#380) and unsigned columns (#413) now fail loudly. Mitigation: schema lint in CI that scans migrations/DDL for both patterns.
• Type contract regressions: insertReturningPks() now returns array|false (#344) after being renamed (#366). Any caller expecting a scalar PK will silently misbehave. Mitigation: static analysis (PHPStan/Psalm) with a strict level over the gateway layer.
• Nullability assumptions: nullable parameters were explicitly marked (#343). Code passing null into now-strict signatures will fail. Mitigation: enable strict types and run the analyzer before rollout.
• SQL divergence: caseSensitive LIKE (#349), collation support (#386), and default-value normalization (#418) change emitted SQL. Mitigation: golden-file tests on generated SQL for representative queries.
• Environment drift: missing/mismatched ODBC driver is the most likely cause of "works in dev, fails in prod." Mitigation: bake the driver into the base image and assert its version at boot.
• Upstream coupling: a future yiisoft/db 3.0 will require another coordinated major. Mitigation: treat the gateway layer as the upgrade seam and keep it small.

Ramp-up. Realistically 2–3 weeks before a competent PHP engineer is productive and 4–6 weeks before they are confident in the schema-introspection and quoting APIs, because the package's mental model (Yii3 DI, Quoter/Schema/Command separation, the new ColumnFactory/ColumnBuilder split) is unfamiliar to Laravel developers. Budget for one designated owner, a written internal "how we use this" note capturing the dotted-table-name and unsigned-column bans, and a paired walkthrough of the gateway layer. Given the framework mismatch, the strongest operational recommendation is to revisit the build-vs-adopt decision once the spike in step 1 completes — if Laravel's sqlsrv connector covers our MSSQL needs, this package's 2.0 feature set, however well executed, does not justify the parallel-stack cost.