PHP RFC: Add MariaDB-specific features to mysqlnd and mysqli

• Version: 1.0
• Date: 2026-03-30
• Author: Georg Richter, georg@php.net
• Status: Draft

The PHP MySQL ecosystem is currently centered around mysqlnd, mysqli, and PDO_MySQL, which together provide a unified and efficient interface for interacting with MySQL-compatible database servers. MariaDB originated as a fork of MySQL and continues to share a large portion of its protocol, behavior, and feature set. Because of this substantial overlap, maintaining a completely separate PHP extension for MariaDB would introduce unnecessary duplication, fragmentation, and long-term maintenance cost.

At the same time, MySQL and MariaDB have diverged over the years. MariaDB has introduced a number of server-side features that are not available in MySQL, many of which provide significant performance and observability improvements. Currently, these MariaDB-specific capabilities are either inaccessible or only partially usable from PHP, despite being available through the same wire protocol and client library functions.

This RFC proposes to extend mysqlnd and mysqli to optionally expose MariaDB-specific functionality when connected to a MariaDB server, without affecting behavior when used with MySQL. The goal is not to fork or specialize the extensions, but to enhance them in a way that preserves compatibility while allowing PHP applications to benefit from MariaDB’s additional capabilities.

The MariaDB features targeted by this proposal include:

• Bulk operations – Enabling significantly faster INSERT, UPDATE, REPLACE, and DELETE statements. Benchmarks show improvements of 6x to 32x in remote network scenarios (e.g., Raspberry Pi via Ethernet) and a 2x to 3x improvement even on unix_socket connections, heavily dependent on network latency and hardware processing power.
• Prepared statement metadata caching – Reducing overhead for repeatedly executed prepared statements by eliminating redundant metadata exchanges between the client and server.
• Extended metadata and finer-grained type information – Allowing more accurate data handling and improved type awareness within PHP's data types.
• Progress indication for long-running operations – Improving transparency and enabling better application-level monitoring and user feedback for heavy maintenance tasks.
• MariaDB authentication plugins – Including parsec, the authentication plugin which will become the default in upcoming MariaDB releases. Full support ensures reliable connectivity, avoids fallback workarounds, and allows PHP to remain compatible with current and future MariaDB server versions.

Exposing these features through existing PHP database extensions allows developers to take advantage of MariaDB’s strengths while continuing to rely on familiar MySQL-oriented APIs. This approach aligns with PHP’s long-standing emphasis on pragmatism, performance, and backward compatibility, while preparing the extensions to handle protocol divergence and feature evolution in MariaDB.

Notes:

• The concepts apply to mysqlnd internally and are exposed through mysqli. PDO_MySQL is currently out of scope for visible API changes in this RFC.

A fundamental requirement for exposing MariaDB-specific features in PHP extensions is reliably detecting whether the connected server is MariaDB or MySQL. This cannot be done solely by checking the server_version string. While standard MySQL and MariaDB installations report the server type and version in server_version, many derived products—including cloud offerings, packaged distributions, and proxies may report different names, modified version numbers, or other inconsistencies. Therefore, relying on server_version alone is unreliable for feature detection.

A robust approach is to determine server type through capability flags exchanged between the client and server during the connection handshake. These flags indicate which features the server supports and which extensions the client can enable.

One key difference between MySQL and MariaDB is the handling of the long password capability:

MySQL servers always indicate the CLIENT_LONG_PASSWORD capability.

MariaDB historically used the same capability name, but later versions renamed it to CLIENT_MYSQL and removed it entirely.

By examining these flags, the client can detect MariaDB servers accurately and safely. Once a MariaDB server is recognized, the client can both read and advertise MariaDB-specific capabilities, enabling access to enhanced features.

To fully support modern MariaDB features, PHP extensions must handle 64-bit capability flags. These flags extend the feature set beyond what can fit in traditional 32-bit integers. For legacy 32-bit clients and to maintain backward compatibility, it is necessary to expose these capabilities in both server_capabilities and ext_server_capabilities. This dual exposure ensures that extensions can access all advertised features safely, regardless of the client architecture.

MySQL has also introduced a forward-looking mechanism for capability expansion via the CLIENT_CAPABILITY_EXTENSION flag. This flag reserves space for extending the traditional 32-bit capability field to 64 bits. As both MySQL and MariaDB move toward extended capability sets, it becomes important to clearly separate vendor-specific extensions.

To avoid ambiguity and potential conflicts between MySQL and MariaDB capability flags in the extended range, PHP should introduce distinct namespaces for these flags. For example, MariaDB-specific extended capabilities could be exposed using a prefix such as MYSQLI_MARIADB_*, ensuring that they remain clearly distinguishable from MySQL-defined flags and any future extensions

This capability-based detection allows PHP extensions to:

• Enable MariaDB-specific features such as bulk operations, extended metadata, progress reporting, and mariadb_stmt_execute_direct.
• Support MariaDB authentication plugins like parsec.
• Maintain full backward compatibility with MySQL servers.

Example:

<?php
 
$link = new mysqli('127.0.0.1', 'my_user', 'my_password', 'test');
 
/* Check if we are connected to MariaDB or MySQL */
 
if ($link->server_capabilities & MYSQLI_CLIENT_MYSQL) {
	printf("Connected to MySQL server\n");
} else {
	printf("Connected to Mariadb server\n");
 
	printf("Bulk operations are ");
	if ($link->extended_server_capabilities & MYSQLI_MARIADB_CLIENT_STMT_BULK_OPERATIONS) {
		printf("supported\n");
	} else {
		printf("not supported\n");
	}
}
 
$link->close();
?>

MariaDB provides mechanisms to improve the performance of repeated or multi-row statements through bulk execution. The most common scenario is INSERT statements. In many cases, a standard single-row INSERT or REPLACE can be rewritten using the multi-value syntax:

 INSERT INTO table (col1, col2) VALUES (?, ?), (?, ?), ..., (?, ?) 

This approach can significantly reduce network round-trips and server parsing overhead. However, it has some limitations:

• Not all INSERT or REPLACE statements can be safely rewritten using multi-value syntax (e.g., INSERT ... SELECT or statements with complex ON DUPLICATE KEY UPDATE clauses).
• DELETE and UPDATE statements cannot generally use multi-value or IN(...) optimizations when additional conditions exist. Even when IN(...) could work, it only applies to simple statements with a single column in the WHERE clause. For complex queries, each statement must be executed individually.

The MySQL protocol already anticipated support for bulk operations when prepared statements were introduced in MySQL 4.1. Prepared statement headers include a 4-byte iteration count, intended to allow repeated execution of a statement. This field, however, was never used by MySQL.

MariaDB addressed this limitation in version 10.2 by introducing a new command, COM_STMT_BULK_EXECUTE, which implements an enhanced protocol for executing bulk operations. This protocol provides several advantages:

• Efficient execution of multiple statement iterations in a single network round-trip.
• Support for indicator variables, allowing the client to specify NULL or default values for individual parameters within the bulk operation. Supported indicators:
  • NULL: use null value
  • IGNORE: ignore this column
  • DEFAULT: use column’s default value

• Reduced server parsing and binding overhead, which can result in up to 7× performance improvement for suitable statements (depending on network latency).

From a PHP perspective, exposing bulk execution through mysqli or PDO would allow applications to take advantage of these performance gains without requiring changes to existing SQL logic, other than optionally preparing statements for bulk execution.

Example:

<?php
 
use Mysqlnd\Indicator;
 
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = new mysqli('127.0.0.1', 'my_user', 'my_pass', 'test');
 
$link->query("DROP TABLE IF EXISTS t1");
$link->query("CREATE TABLE t1 (id INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, name VARCHAR(50), score double default 20)");
 
$rows = [
	["Jennifer", 20.34],
	["Marcus", 21.9],
	["Rasmus", 22.1],
	["Derick", 20.9],
	["Zak", 20.91]
];
 
$stmt = $link->prepare("INSERT INTO t1 (name, score) VALUES (?, ?) RETURNING id");
 
$stmt->executemany($rows);
$result= $stmt->get_result();
 
printf("%d rows inserted with the following id's:\n", $result->num_rows);
 
if ($rows = $result->fetch_all()) {
	printf("%s ", implode(", ", array_column($rows, 0)));
}
printf("\n");
$stmt->close();
 
$rows = [
	[20.39, 1],
	[24.02, 2],
	[Indicator::Default, 3]
];
 
$stmt= $link->prepare("UPDATE t1 SET score=? WHERE id=?");
$stmt->executemany($rows);
 
printf("%d rows updated\n", $stmt->affected_rows);
 
$link->query("DROP TABLE t1");
 
$link->close();
?>

In many production environments, the LOAD DATA LOCAL INFILE command is disabled (local_infile=0) to mitigate security risks, such as unauthorized local file reads by a compromised client. While this secures the server, it often leaves developers with the slow alternative of executing thousands of individual INSERT statements.

executemany() provides a high-performance, secure alternative that operates over the standard Prepared Statement protocol. By accepting an iterable, it allows for “Streaming” data directly into the database.

Key Advantages:

• Security Compliance: Unlike LOAD DATA, executemany() does not require the FILE privilege or enabling local_infile. It operates within the existing security sandbox of the database connection.
• Memory Efficiency: By using a PHP Generator, only one row of data resides in PHP's memory at a time. This allows for the processing of files with a constant, minimal memory footprint.
• Format Versatility: While LOAD DATA is generally limited to flat text files (CSV/TSV), executemany() can stream data from any source. This includes:
  • XML/JSON: Parsing large documents via XMLReader or a JSON machine.
  • Remote APIs: Fetching and inserting records from a REST or SOAP endpoint in chunks.
  • Binary Streams: Processing custom data formats or encrypted streams.
• Programmable Filtering: Because the data is processed in a PHP loop before being “yielded” to the driver, developers can perform complex validation, data cleaning, or conditional skipping natively in PHP.

The following snippet demonstrates how a Generator acts as a programmable filter, replacing the need for row-level “Ignore” indicators:

<?php
function csv_streamer(string $path): Generator {
    if (!$handle = fopen($path, 'r')) return;
 
    /* Skip first row */
    fgetcsv($handle, 0, ",", "\"", "\\");
 
    while (($row = fgetcsv($handle, 0, ",", "\"", "\\")) !== false) {
        /* Only yield 'ACTIVE' rows to the database */
        if (isset($row[2]) && $row[2] === 'ACTIVE') {
            /* Yielding data to executemany() without loading the whole file */
            yield [(int)$row[0], $row[1]];
        }
    }
    fclose($handle);
}
 
$stmt = $mysqli->prepare("INSERT INTO users (id, name) VALUES (?, ?)");
 
/* The driver 'drains' the generator, maintaining O(1) memory usage in PHP */
$stmt->executemany(csv_streamer('large_data_export.csv'));
?>

When a prepared statement is created, the server normally returns statement metadata describing result columns. This metadata includes:

• Qualified identifiers like table and column naes
• Column types
• Length, precision, and scale
• Nullability and flags

For applications that repeatedly execute identical SQL statements—common in request-based execution models—this metadata is typically transmitted and parsed repeatedly, even though it does not change.

MariaDB supports prepared statement metadata caching, allowing the client to indicate that it is capable of caching metadata locally. Once this capability is negotiated:

• The server sends full metadata only on the first prepare of a given statement.
• For subsequent execution of the same statement, the server does not resend metadata, unless these have changed.
• The client reuses the previously cached metadata without additional parsing or allocation.

This optimization reduces:

• Network traffic, by avoiding retransmission of identical metadata.
• Client-side processing, by reusing already parsed metadata structures.

Importantly, this does not change the logical protocol flow of prepared statements. Instead, it optimizes the existing flow by eliminating redundant metadata transfer when both client and server support caching. This improves performance transparently, without requiring changes to application code or SQL syntax.

Long-running SQL statements such as large ALTER TABLE, CREATE INDEX or complex UPDATE operations can take a significant amount of time to complete. Traditionally, clients have no insight into the progress of such operations and can only wait for completion or timeout.

MariaDB provides server-side progress reporting, allowing the server to send progress information to the client while a statement is executing. This information includes:

• Current progress value
• Maximum progress value
• Stage or operation context

Progress information is sent asynchronously during statement execution and does not alter the semantics of the SQL statement itself.

Key characteristics:

• Progress messages are sent out-of-band while a statement is running.
• They do not interrupt or terminate the executing statement.
• Clients may ignore progress messages without affecting correctness.
• Progress reporting is optional and enabled only when both client and server support it.

From a PHP perspective, exposing this feature allows applications to:

• Provide feedback to users for long-running operations
• Implement progress bars or logging for batch jobs
• Detect stalled operations earlier
• Improve observability without polling or additional queries

Example pseudo-code:

<?php
function callback_progress($current, $max) { 
  printf("Progress: %d / %d\n", $current, $max);
}
 
$mysqli->options(MYSQLI_OPT_PROGRESS_CALLBACK, 'callback_progress');
$mysqli->query("ALTER TABLE big_table ADD INDEX idx_col (col)");
?>

MariaDB supports server-side authentication plugins that extend or replace the default MySQL authentication mechanisms. The most notable example is the parsec plugin, which became the default in recent MariaDB versions.

Currently, mysqlnd provides only limited support for MariaDB-specific authentication plugins. As a result, connections to MariaDB servers using these plugins can fail, or require fallback to less secure authentication methods, unless external mysqlnd authentication plugins are installed (for example, mysqlnd_parsec or mysqlnd_ed25519 from Packagist).

This feature is invisible to application code:

• No changes to mysqli (or PDO) methods are required.
• Existing connection logic remains the same.
• Full support ensures reliable connectivity to MariaDB servers using modern authentication plugins.

By supporting MariaDB authentication plugins at the protocol level, PHP extensions can safely and efficiently connect to current and future MariaDB servers without requiring separate extensions or application changes.

MariaDB extends standard MySQL metadata with additional type information to provide more precise data handling. This extended metadata allows clients to differentiate types that MySQL treats identically, improving type awareness, validation, and performance in PHP applications.

Key MariaDB extensions include:

* ext_type — indicates the server-side extended type for a column or parameter. * ext_format — indicates the data format used for transmission, which may differ from the standard MySQL format. This is particularly relevant for binary or structured types such as geometry or network types.

Together, ext_type and ext_format allow clients to:

• Correctly interpret complex or structured data types without guessing.
• Avoid unnecessary conversions or misinterpretation of binary formats.

From a PHP perspective, exposing this extended metadata through mysqli allows applications to:

• Handle MariaDB-specific types correctly and efficiently.
• Implement precise type mapping for geometric, UUID, or network types.
• Improve compatibility with MariaDB features while maintaining MySQL backward compatibility.

PDO_MySQL currently does not support array binding or bulk execution semantics required to expose MariaDB-specific bulk operations in a clean and consistent way.

This RFC focuses on enhancing mysqlnd and mysqli first. Future RFCs may extend PDO_MySQL once the underlying mysqlnd capabilities are available and an appropriate PDO API design is agreed upon.

A proof-of-concept implementation is available at: php-src 8.6-mariadb POC

The implementation modifies:

mysqlnd

• to support COM_STMT_BULK_EXECUTE
• to detect MariaDB server
• to cache metadata (prepared statements)
• to support extended field types

mysqli

• to expose executemany()
• Indicator handling in parameter binding
• Protocol-level result processing for bulk operations
• Metadata caching
• Support for extended metadata

The patch is intended for PHP 8.6 and requires MariaDB Server ≥ 10.2 for full functionality.

Fallback behavior for MySQL Server remains unchanged and continues to use repeated COM_STMT_EXECUTE.

It is impossible to say that executemany() is “n-times” faster than a sequential execute() loop as a universal rule. The performance delta is highly dependent on two primary factors: hardware processing power and network latency.

For this reason, two distinct scenarios were chosen for this analysis:

• Localhost: A very fast connection via unix_socket, representing minimal overhead.
• Raspberry Pi 4: A resource-constrained client connected via Ethernet, representing a real-world remote hardware scenario.

---

The measurements reveal how these two variables determine the “efficiency gap.”

The most dramatic performance gains are observed in the remote Ethernet environment. While executemany() performance remains relatively stable across both environments, the sequential loop suffers a massive penalty over the network.

• Remote Update: 5,723 rows/sec
• Localhost Update: 70,286 rows/sec

In a loop, the application is IO-bound, waiting for the network acknowledgement of each individual row before sending the next. executemany() mitigates this by wrapping multiple operations into fewer network packets, effectively amortizing the Round-Trip Time (RTT) cost.

On the Raspberry Pi 4, the CPU overhead of preparing and sending individual command packets is significantly higher than on a standard desktop.

• Since the Pi's processor is slower, the relative cost of the PHP loop and repeated mysqlnd calls is higher.
• The iterative approach requires the client to context-switch between application logic and the network stack for every single row.
• Even on localhost, where network latency is near-zero, executemany() is still 2x to 3x faster, proving that reducing driver-level overhead and transaction commit frequency provides a significant performance floor regardless of the connection.

For remote clients or resource-constrained hardware like the Raspberry Pi, executemany() is mandatory for high-performance applications, offering up to a 32x speedup. The data suggests that as network latency increases or hardware power decreases, the necessity of batching becomes exponentially more critical.

Measurements taken using Raspberry Pi 4 (Client) via Ethernet to 192.168.10.1 (Server) and local loopback (127.0.0.1).

This section evaluates the throughput efficiency of batch operations (executemany()) compared to iterative single-row operations (execute() in a loop). The data confirms that batching is a critical optimization, especially when network latency or hardware constraints are present.

Measurements taken using Raspberry Pi 4 (Client) via Ethernet to 192.168.10.1 (Server) and local loopback (127.0.0.1).

MariaDB-specific features can be categorized based on whether they require changes to the PHP API or are handled entirely internally by mysqlnd or the PHP extensions.

These features require new methods, functions, or options in PHP to expose MariaDB-specific functionality to developers:

Impact: Applications can call these new methods directly to leverage MariaDB-specific performance or monitoring features. Backward compatibility with MySQL is maintained because these methods can be no-ops when connected to a MySQL server.

These features are internal optimizations that improve performance or protocol behavior without requiring changes to application code:

Performance Improvements: Existing PHP functions that prepare and execute statements, such as mysql_execute_query() (introduced in PHP 8.2), could be updated to use execute_direct when connected to a MariaDB server. This would allow one-time statements to bypass the extra round-trip and metadata fetch, providing immediate performance gains.

Backward Compatibility: All invisible features are fully backward-compatible with MySQL. Visible features are MariaDB-specific but can be safely ignored or no-oped when connected to a MySQL server.

None

• MariaDB Client/Server Protocol
• MariaDB Protocol Differences with MySQL

If there are major changes to the initial proposal, please include a short summary with a date or a link to the mailing list announcement here, as not everyone has access to the wikis' version history.