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

• Version: 0.9
• Date: 2026-02-26
• 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, with up to 8× performance improvement in some scenarios, dependent on network latency.
• Prepared statement metadata caching – reducing overhead for repeatedly executed prepared statements.
• Extended metadata and finer-grained type information – allowing more accurate data handling and improved type awareness in PHP.
• Progress indication for long-running operations – improving transparency and enabling better application-level monitoring and user feedback.
• MariaDB authentication plugins – including parsec, the authentication plugin which will become 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.

The full protocol description for MariaDB capabilities can be found in the official documentation: MariaDB Client/Server Protocol.

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.

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 or sent as multiple parameter sets.

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
  • ROW: ignore entire row

• 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 INSERT:

<?php
$stmt = $mysqli->prepare("INSERT INTO t1 (col1, col2) VALUES (?, ?)");
$rows = [ [1, 'a'], [2, 'b'], [3, 'c'], ];
$stmt->executemany($rows);
?>

Example UPDATE with indicator variable:

<?php
use Mysql\Indicator;
 
$stmt = $mysqli->prepare("UPDATE table t1 SET col2=? WHERE col1=?");
$rows = [
  ['b', 1],
  [Indicator::Default, 3]
];
$stmt->executemany($rows);
?>

Additional advantages of bulk execution include:

• Alternative to LOAD DATA LOCAL INFILE: Bulk execution can be used as a programmatic alternative for loading large datasets. Performance is often comparable to LOAD DATA LOCAL INFILE, while avoiding the security restrictions that frequently disable local_infile in many environments. This makes bulk execution usable in hosted or restricted deployments where LOAD DATA LOCAL INFILE cannot be enabled.
• Support for indicator variables even for single-row execution: Although designed for multiple parameter sets, the protocol can also be used for single-row execution. This enables the use of indicator variables such as DEFAULT, NULL, or IGNORE, which are not supported by existing helper functions like mysqli_stmt_execute(). As a result, applications can explicitly request default column values without modifying the SQL statement.

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.

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.