Db Mysql Laravel Package

Getting Started

• Install the driver, which pulls in the base package: composer require yiisoft/db-mysql. You need ext-pdo, ext-pdo_mysql, a PSR-16 cache and a PSR-3 logger — all constructor dependencies, not optional at the API level.
• Read yiisoft/db's README first. The db-mysql repo is mostly the driver; the docs, query builder guide and changelog live in the parent package, so start there.
• Minimal bootstrap (verify against the installed version — the Connection signature changed across 1.x):

use Psr\Log\NullLogger;
use Yiisoft\Cache\ArrayCache;
use Yiisoft\Db\Cache\SchemaCache;
use Yiisoft\Db\Mysql\Connection;
use Yiisoft\Db\Mysql\Driver;

$driver = new Driver(
    dsn: 'mysql:host=127.0.0.1;port=3306;dbname=app;charset=utf8mb4',
    username: 'app',
    password: 'secret',
);
$db = new Connection($driver, new SchemaCache(new ArrayCache()), new NullLogger());

$rows = $db->createCommand('SELECT * FROM users WHERE id = :id', ['id' => 1])->queryAll();

• First realistic use case: a CLI script, queue worker, or small PSR-15 service that needs typed, cached schema access against an existing MySQL/MariaDB database without dragging in a full ORM. From Laravel, treat it as a drop-in for a second, low-level connection rather than a replacement for illuminate/database.

Implementation Patterns

• Layer accordingly. Connection owns the PDO driver, schema cache and transactions; Command is raw SQL with named/positional bindings; QueryBuilder ($db->createQuery()->select(...)) is the fluent path; Schema/ColumnSchemaBuilder handles introspection and DDL. Pick one layer per concern rather than mixing.
• Transactions. Wrap units of work in $db->transaction(fn () => ...) or explicit beginTransaction/commit/rollBack. Nested calls become savepoints. Keep DDL out (see Gotchas).
• Schema introspection as codegen input. $db->getSchema()->getTableNames(), getTableSchemas(), getViewNames(), index and foreign-key metadata are all exposed. This is the fastest win for a Laravel dev: generate Eloquent migrations or typed DTOs from an existing database.
• Migrations come from the sibling yiisoft/db-migration package. ColumnSchemaBuilder gives you tinyint(1), json, enum, set, currentTimestamp() and friends. Laravel's Schema facade will not read these files, and vice versa — pick one migration owner per database.
• Laravel wiring. Register the Connection as a singleton in a service provider, read DSN/user/pass from config('database.connections.mysql'), use a real PSR-16 cache in production and ArrayCache in tests. Do not share the PDO handle with Eloquent; two pools is simpler than reconciling transaction semantics.
• Long-lived processes. Open the connection lazily on first query and keep it as a singleton per worker; drop it with $db->close() at the end of a job batch to avoid stale session state.
• Read/write splits aren't automated. Instantiate two Connection objects and route explicitly.
• Bulk work. Reuse one connection, chunk writes into explicit transactions, and bypass the query builder with Command for very large INSERT ... VALUES batches — the builder's per-row overhead adds up.

Gotchas and Tips

• It is not a Laravel package. No service provider, no facade, no DB:: helper, no Eloquent, no Model. Everything (cache, logger, container binding) is hand-wired.
• Documentation drift is real. The db-mysql README is thin and the parent guide often lags the 1.x source. If a snippet fails, read Connection, Driver and Schema in vendor/ before assuming your config is wrong. Pin a version.
• The schema cache is mandatory, not optional. Passing ArrayCache in production means every request re-queries information_schema; pass Redis/file cache in real deployments. Conversely, clear the cache after migrations or Laravel will keep a stale schema.
• The logger is mandatory too. Use NullLogger by default and swap in a real logger behind a flag; a PSR-3 decorator around Command is the least invasive way to debug.
• MySQL vs MariaDB is not cosmetic. JSON semantics, generated columns, INSERT ... RETURNING (MariaDB only), default collations and information_schema shape all differ. The Schema class branches on server version — test both if you support both.
• DSN and PDO options matter. Always set charset=utf8mb4; set PDO::ATTR_EMULATE_PREPARES => false if you want real prepared statements. Pass PDO attributes through the Driver constructor, not the DSN.
• Introspection quirks. tinyint(1) vs boolean, enum/set surfacing as strings, and zero-date handling will surprise codegen. Normalise in your generator, not in Schema.
• Quoting is backtick-based. Plain strings in select()/where() get quoted as identifiers; wrap raw SQL fragments in Expression or they will break.
• DDL inside transactions silently commits (MySQL implicit commit) — same footgun as Laravel. Keep CREATE/ALTER outside transactional blocks.
• Persistent PDO connections leak state across PHP-FPM requests (temp tables, session variables, user-defined vars). Avoid PDO::ATTR_PERSISTENT unless you audit for it.
• Extension points are subclassing: a Driver subclass for PDO attributes and reconnect logic, a Schema subclass for type-mapping overrides, and custom column builders for vendor-specific types. Check the source for exact hook names — they aren't documented.
• Ecosystem risk. Low star count and a small community mean fewer Stack Overflow answers and slower fixes; budget for reading source and writing your own wrappers around anything nontrivial.