[Feature Request] Read/Write connection splitting

[furan917]

I promise this is my last one for now, I don't want to drown you in requests but this functionality comes in massively useful for high volume stores I deal with and I think Marko is already perfectly set up for it (caveat, I'm skim reading docs/code).

The ConnectionInterface already has a natural read/write split, query() for reads, execute() for writes. A database-readwrite package could implement the interface with two underlying connections and route by method.

Transactions would pin to the write connection automatically. Sticky writes (to handle replication lag) would be a request-scoped flag on the split connection. No SQL parsing needed. A Preference binding in module.php could hndle all the wiring so nothing else in the framework needs to change.

I think this would fit cleanly with the existing driver pattern (database-mysql, database-pgsql). I done this for M2 and it was much more annoying to have fight it rather than it being natively built with it in mind before growing arms and legs.

[markshust]

Great suggestion — and you're right, the existing ConnectionInterface with its query()/execute() split makes this a natural fit. A ReadWriteConnection decorator that wraps two connections and routes by method is exactly the right approach, and it wouldn't require any core changes.

We're tagging this as post-1.0 — not because it lacks merit, but because the 1.0 release is focused on shipping the core framework primitives (DI, database, routing, authentication, etc.) in a stable state. Read/write splitting is a scaling optimization that becomes important at higher traffic levels, but a single-connection setup works correctly for all use cases at launch. We want to keep the 1.0 scope tight.

The good news is that because the interface already supports this pattern cleanly, adding it post-1.0 won't require any breaking changes or retrofitting. A database-readwrite package can implement ConnectionInterface, handle transaction pinning and sticky writes internally, and wire in via a Preference binding — exactly as you described.

We'd welcome a PR for this post-1.0. Your Magento 2 experience with this pattern would be valuable here.

[markshust]

Hey @furan917 — closed by #86! 🎉

Wanted to come back to you on this since we initially tagged it post-1.0. You were right that the existing ConnectionInterface made this a natural fit — once we sat down to scope it, the work turned out to be small enough that deferring would have been ceremony rather than caution:

• Two tiny additive primitives added to marko/database: a new ConnectionFactoryInterface (so the readwrite package can build underlying connections without depending on a specific driver) and a DatabaseConfig::fromArray() static factory.
• Zero changes to packages/core and zero existing API changes — pure decoration via the boot-callback override pattern.
• marko/database-pgsql and marko/database-mysql each got a one-class {Driver}ConnectionFactory + binding. Both fully backwards compatible.

The full feature list matches what you sketched: query() routes to a replica via a pluggable ReplicaSelectorInterface (random default, weighted option), writes and transactions pin to the primary, sticky-write flag persists for the request so you can read your own writes after committing, and a single-request fallback retries the next replica on PDOException. resetStickyState() is exposed for long-running processes (queue workers, RoadRunner, etc.).

Docs are at https://marko.build/docs/packages/database-readwrite/ — covers the config schema, sticky-write semantics, replica strategies, and the prepare() policy (always routes to write).

Thanks again for the suggestion and the M2 reference link — it was a good kick to look closer at the shape of the problem.