Getting Started

Treat hyperf/database v3.2.5 as a patch-level release. The only supplied release note is the changelog compare link (v3.2.3...v3.2.5), so there are no documented breaking changes or new features to assess from the note alone. Review that diff before upgrading.
First look at composer.json constraints, then config/autoload/databases.php in a Hyperf application. Check connection names, pool settings, driver options, and environment mappings.
A Laravel developer will recognize much of the query builder and Eloquent-style model API, but this is Hyperf’s database layer, not a full Laravel application. Expect Hyperf wiring, coroutine context, and connection-pool behavior rather than Laravel service-provider/facade assumptions.
First practical use case: add a small read-only query through the connection/query builder inside a service, enable SQL logging locally, and confirm it works under a coroutine request before migrating larger repository code.

Implementation Patterns

Keep database access behind repositories or service classes. Use the query builder for reporting/list endpoints and models for domain writes where Eloquent-style behavior is useful.
Use named connections deliberately: default, read/write splits, and test connections. Keep credentials and pool sizes in environment-specific config rather than hard-coding them in services.
For coroutine workers, scope transactions and connection usage to the request/job/coroutine. Do not store a connection object on a singleton or reuse it across unrelated coroutines.
Use chunking/cursor-style reads for large datasets and pagination for API responses. Avoid loading full tables into memory just because the query builder makes it easy.
Wrap multi-step writes in transaction APIs, and keep transaction bodies short. Long-running transactions are especially costly when a connection pool is involved.
Integration tip: use SQL logging/listeners in local and staging to inspect connection name, bindings, and generated SQL. This is the fastest way to catch grammar or configuration drift after a patch upgrade.
Upgrade pattern: pin ^3.2.5, run the existing test suite, then inspect the changelog diff for query grammar, connection handling, model hydration, or schema-builder changes before deploying.

The v3.2.5 note is only a changelog link. Do not assume “patch” means “no behavior change”; review the actual diff for SQL grammar, pooling, or model-layer fixes.
Laravel parity is not guaranteed. Avoid relying on Laravel-only helpers, facades, service providers, or application bootstrapping assumptions unless the Hyperf package explicitly supports them.
Coroutine safety is the main operational risk. Never keep a connection or open transaction across coroutine boundaries, and be careful with static caches that hold connection objects.
Pool exhaustion often appears as timeouts under load, not as an obvious database error. Check pool max connections, wait timeouts, and long transactions first.
Debugging tip: log the connection name with the SQL and bindings. Many “wrong database” bugs are actually the wrong named connection or stale config cache.
Config quirk: after changing config/autoload/databases.php or related env values, rebuild/clear any Hyperf config cache used by the deployment.
Extension points to prefer: connection resolvers/factories, query macros, model events, and SQL listeners where supported. Keep customizations in application service providers or dedicated integration classes rather than forking package internals.