MyDb — a simple, fast, dependency-free PHP client for MySQL

MyDb is a small, production-hardened PHP client for MySQL. It speaks raw SQL at native mysqli/mysqlnd speed — no ORM, no query-language abstraction, no framework lock-in. You get a clean, fully typed API wrapped around opinionated defaults that make MySQL behave like a traditional SQL database: strict by default, explicit transactions, sanely bounded timeouts, and utf8mb4/UTC everywhere.

Think of it as a thin, well-tested layer between your PHP code and MySQL — nothing more, nothing less.

Simple to learn, fast to run, safe by default — the SQL client you stop thinking about. 🐬

• 🎯 Why MyDb? Pros and cons
• ✨ Highlights
• 📦 Installation
• 🏷️ Versioning / Releases
• 🚀 Quick start
• 🔌 Everything is injectable
• 🛡️ Safe defaults
• ⚡ Performance
• 🔧 Reliability
• ✅ Code quality
• 🧩 Compatibility
• 💡 Best use cases
• 🚫 Out of scope
• 💭 Why this library exists
• 🤝 Contributing
• 👤 Authors and license

If you want an ORM, a query-language abstraction, or a full framework, look at Doctrine or Eloquent. If you want a minimal, fast, predictable SQL client that gets out of your way, MyDb is for you.

• Raw SQL, first-class — select(), query(), command(), insert(), update(), delete(), replace() plus helper methods for common bulk work
• Prepared statements, opt-in — prepare() / execute() for parameterized execution with mysqli server-side binding; the raw fast path stays untouched
• Helper DML — array-based insertOne(), insertMany(), updateWhere(), deleteWhere(), replaceOne() with MydbExpression support for raw SQL fragments
• Friendly transactions — autocommit = 0, explicit commit() / rollback(), and an automatic commit on graceful shutdown so you never lose half a transaction
• Readonly connections — a first-class mode with READ COMMITTED isolation and read-only InnoDB optimizations
• Strict by default — TRADITIONAL SQL mode ("give an error instead of a warning"), strict MySQL error reporting, and PSR-3 logging of everything unusual
• Explicit timeouts — connect, read, server-side SELECT, and idle timeouts so one slow query cannot hang your process forever
• Signal aware — traps SIGTERM/SIGINT/SIGHUP, stops in-flight queries, and respects client disconnects under php-fpm
• Zero-friction integration — PSR-4 sql\ namespace, PSR-3 logging, constructor injection, no run-time or compile-time steps

composer require sshilko/php-sql-mydb

Requires ext-mysqli and ext-mysqlnd (bundled with the standard PHP distribution). Composer installs the latest stable release, currently the 2.x line.

What's new and improved in 3.x:

• Upgraded to PHP 8.3 — strict types, typed properties, constructor promotion, and union types throughout the codebase
• ext-pcntl is now optional: a bundled no-op polyfill keeps Windows and non-pcntl environments working (a hard requirement in 2.x)
• New MydbFactory for assembling connections with library defaults, including dedicated read-only options (createReadonlyOptions())
• Focused on MySQL 8.0 (MySQL 5.7 support deprecated)
• Psalm infers 100% of types with zero errors, and a taint-analysis pass was added

use sql\MydbCredentials;
use sql\MydbFactory;
use sql\MydbLogger;

$credentials = new MydbCredentials('127.0.0.1', 'root', 'secret', 'app', 3306);
$mydb        = (new MydbFactory())->create($credentials, new MydbLogger());

$mydb->beginTransaction();

$id = $mydb->insertOne(['name' => 'Ada Lovelace'], 'users');            // '9' — auto-increment id
$mydb->insertMany([['Grace Hopper'], ['Linus Torvalds']], ['name'], 'users');

$rows = $mydb->select('SELECT id, name FROM users ORDER BY id ASC');

$mydb->commitTransaction();

Read-only replicas get a dedicated factory helper:

$options = (new MydbFactory())->createReadonlyOptions();   // READ COMMITTED, autocommit on
$replica = (new MydbFactory())->create($credentials, new MydbLogger(), $options);

A complete runnable example lives in examples/example.php.

MyDb is assembled from small, interface-driven parts — and every single one can be swapped, extended, or mocked through MydbFactory::create(). Omit any dependency and the factory fills in production defaults, so flexibility costs nothing when you do not need it:

$mydb = (new MydbFactory())->create(
    credentials:  $credentials,       // MydbCredentialsInterface
    logger:       new MydbLogger(),   // Psr\Log\LoggerInterface
    options:      $myOptions,         // MydbOptionsInterface
    mysqli:       $myMysqli,          // MydbMysqliInterface
    environment:  $myEnvironment,     // MydbEnvironmentInterface
    queryBuilder: $myQueryBuilder,    // MydbQueryBuilderInterface
    listener:     $myListener,        // MydbListenerInterface
);

• Tracing and debugging with a listener — implement MydbListenerInterface (or extend MydbListener) and subscribe to lifecycle events: query begin/end and connection begin/end. Every event carries metadata — the SQL text, success flag, host, and database — and returning false stops dispatch. The built-in InternalListener logs connection events via your PSR-3 logger; query events are left for your own listener. A minimal SQL tracer:

use sql\MydbEvent\InternalQueryBegin;
use sql\MydbEventMetadataInterface;
use sql\MydbListener;

final class SqlTracer extends MydbListener
{
    protected function onEvent(MydbEventMetadataInterface $event): ?bool
    {
        if (InternalQueryBegin::class === $event->getEventName()) {
            var_dump($event->getEventMetadata()['sql'] ?? null);
        }

        return null; // keep dispatching
    }
}

$mydb = (new MydbFactory())->create($credentials, listener: new SqlTracer());

• Your own query builder — MydbQueryBuilderInterface is the single place where SQL for the helper methods is constructed (buildWhere, buildInsertMany, buildUpdateWhere, buildDeleteWhere, escaping). Bring your own implementation to customize quoting, add dialect behavior, or go further with MydbExpression.
• Environment dependencies are abstracted — MydbEnvironmentInterface wraps the global PHP surface the library touches: set_error_handler, error_reporting, ini_set, ignore_user_abort, mysqlnd network timeouts, and signal trapping. The library never reaches into globals directly, which makes it fully testable and predictable on any platform.
• Even mysqli itself is interfaced — MydbMysqliInterface is a complete facade over mysqli/mysqli_result: connecting, driver options, result reading, transactions, and warnings. Use your own implementation to run against an alternative transport or to test without a live MySQL server.

Every connection is set up to be strict, explicit, and deterministic:

• TRADITIONAL and strict SQL modes — MySQL returns an error instead of a warning
• autocommit = 0 with explicit commit() / rollback() on Mydb
• Commit is attempted on graceful shutdown (SIGTERM, SIGINT, SIGHUP), so in-flight transactions are not silently dropped
• utf8mb4 character set and UTC timezone on the session
• mysqli error reporting configured so silent data loss is not possible
• Connection retry for resilient reconnect

MyDb is tuned for high-throughput, low-latency workloads:

• MYSQLI_OPT_NET_READ_BUFFER_SIZE and MYSQLI_OPT_NET_CMD_BUFFER_SIZE increased
• Resultsets moved to PHP userspace memory with MYSQLI_STORE_RESULT_COPY_DATA
• fetch_all() from mysqlnd for fast, allocation-friendly result materialization
• Async command execution for parallel pipelines
• READ COMMITTED scan/read-only InnoDB optimizations on readonly connections
• No overhead from ORM mapping or query abstraction

• Connect timeout of 5 seconds, client-side read timeout of 90 seconds for any query, server-side SELECT timeout of 89 seconds, and a 7200-second idle timeout
• mysqlnd.net_read_timeout honoured on every query
• pcntl signal dispatch (SIGTERM, SIGINT, SIGHUP) cancels in-flight queries and shuts down cleanly; a no-op polyfill is bundled for Windows
• php-fpm client disconnect (ignore_user_abort) is respected
• Every failure path raises typed exceptions under sql\MydbException — no silent false

Code quality is not a checklist item here; it is the build. Every commit is verified by:

• Unit tests against a real MySQL 8.0 server — >=280 tests, >=870 assertions, with coverage badges generated on CI
• Psalm — 100% of types inferred, zero errors, plus a taint-analysis pass and an auto-fix (alter) pass for type annotations
• PHPStan at the highest level
• Phan with ext-ast, PHPMD, PHPCS (PSR-12), PHPCPD for duplication, and PDepend for architecture metrics
• PSR-12 formatting enforced by phpcs/phpcbf in pre-commit hooks and CI

The codebase is deliberately small: the complete library is ~26 source files, each with a single responsibility, typed properties, constructor promotion, and PSR-12 formatting. It is easy to read end-to-end.

• PHP >= 8.3
• MySQL 8.0 (mysqli + mysqlnd) and 5.7

• High-performance, low-latency, data-intensive applications
• Services that favor hand-written SQL over ORM magic
• Codebases that want a thin, auditable database layer without framework lock-in
• Projects that want parameterized execution for user-controlled values at high concurrency (prepare() / execute() are built in) and no extra dependencies
• Easy drop-in integration into existing applications

MyDb deliberately stays a component, not a framework. To keep focus and the codebase minimal, it does not provide:

• Input validation or an API facade
• Object-relational mapping (ORM)
• Active record
• Repository pattern
• Data import/export

Please reuse existing solutions that best fit your requirements.

• MySQL is fast, reliable, and scalable — and so is the PHP runtime
• Value developers' time; do not add complexity where it is not needed
• Measure application performance with real-world datasets and organic load
• Optimize for real bottlenecks and remember that there is no NoSQL silver bullet
• Do not optimize prematurely — CPU and memory are cheap
• Focus on architecture, learn from others, and improve over time

Please read the contributing document first. All quality gates run in Docker; see CONTRIBUTING for the supported workflow.

• Sergei Shilko contact@sshilko.com

Licensed under the MIT License. See also AUTHORS.