Mysql Laravel Package

Getting Started

Start by installing the package via Composer: composer require react/mysql. The core entry point is React\Mysql\MysqlClient, instantiated with a DSN-style connection URI (e.g., 'user:pass@localhost/db'). Your first use case will likely be executing simple SELECT queries — see the Quickstart example in the README. Use query() for small result sets (buffers full result in memory), and queryStream() for large datasets (streams row-by-row). Both return promises or streams compatible with ReactPHP’s async model.

Implementation Patterns

• Connection reuse & batching: Instantiate MysqlClient once per service/service class; the client queues queries while establishing the connection and reuses idle connections (default idle timeout = 1ms). Group related operations using then() chains or Promise::all() for concurrent reads, but be mindful that the MySQL protocol is sequential — queries still execute in order per connection.
• Parameter binding: Always use parameterized queries ($mysql->query('SELECT * FROM users WHERE id = ?', [$id])) to avoid injection and improve safety.
• Streaming large results: Use queryStream() with event handlers (on('data', ...)) or pipe to writable streams (e.g., format + log pipeline). Ensure the destination stream processes data quickly to avoid server-side timeouts.
• Transaction support: Manually wrap BEGIN, DML statements, and COMMIT/ROLLBACK using promises (sequencing is critical — never interleave transactions across queries on the same client instance).
• Error handling: Attach rejection handlers to every promise; implement retry logic for transient errors (e.g., Connection refused) but be cautious with transaction-aware operations.

Gotchas and Tips

• Idle connection churn: Default idle timeout (1ms) causes connection churn. For long-lived CLI apps or workers, increase ?idle=30.0 to reduce handshake overhead — but avoid keeping idle connections open across forked processes.
• Connection state & transactions: Transactions implicitly span queries — closing or reconnecting mid-transaction (e.g., due to idle timeout) leaves you in undefined state. Explicitly commit()/rollback() and avoid concurrent commands during transaction blocks.
• UTF-8 & charset: Default charset is utf8mb4, but legacy DBs may require explicit ?charset=utf8 — mismatch can cause silent truncation or errors with 4-byte emojis.
• DNS & TLS quirks: Use a custom React\Socket\Connector for proxy, bindto, or DNS overrides. TLS handshake failures often mask as connection timeouts — validate certs carefully in dev.
• Debugging: Enable MYSQL_DEBUG environment variable (per ReactPHP convention) to inspect raw protocol traffic. Add middleware to log slow queries (wrap query() with timing).
• Version vigilance: The package is in active 0.7 development. Prefer the 0.6.x branch for stable production use unless you plan to contribute or tolerate breaking changes. Check changelog for migration notes between minor versions.