From c0c6ee30a79fca3474f98fc653875e2fb532a751 Mon Sep 17 00:00:00 2001 From: Ulf Wendel Date: Wed, 21 Sep 2011 15:11:40 +0000 Subject: [PATCH] Adding Change History, adding test instructions for upcoming 1.1.0-beta, replacing 5.3.99 references with 5.4.0 references. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@317106 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/mysqlnd_ms/book.xml | 40 ++++--- reference/mysqlnd_ms/changes.xml | 169 ++++++++++++++++++++++++++++ reference/mysqlnd_ms/concepts.xml | 4 +- reference/mysqlnd_ms/quickstart.xml | 6 +- reference/mysqlnd_ms/setup.xml | 78 ++++++++++++- 5 files changed, 277 insertions(+), 20 deletions(-) create mode 100644 reference/mysqlnd_ms/changes.xml diff --git a/reference/mysqlnd_ms/book.xml b/reference/mysqlnd_ms/book.xml index 68a8805fa4..7453af1662 100755 --- a/reference/mysqlnd_ms/book.xml +++ b/reference/mysqlnd_ms/book.xml @@ -25,16 +25,17 @@ MySQL Client Library (AKA libmysql/libmysqlclient). Using mysqlnd has several advantages: no extra downloads because it comes with PHP, PHP license, lower memory consumption in certain cases, - new functionality such as asynchronous queries. + new functionality such as asynchronous queries. As of PHP 5.4.0, mysqlnd is + the compile time default library used by all PHP MySQL extensions + (mysqli, + mysql, + PDO_MYSQL). Mysqlnd plugins such as the replication and load balancing plugin operate mostly transparent from an user perspective. The replication and load balancing plugin supports all PHP applications - and all PHP MySQL extensions ( - mysqli, - mysql, - PDO_MYSQL). + and all PHP MySQL extensions. It does not change existing APIs. Therefore, it can easily be used with existing PHP applications. @@ -69,6 +70,18 @@ very little, if any, application changes required, dependent on the usage scenario required + + + lazy connections: connections to master and slave servers are not + opened before a SQL statement is run + + + + + optional, automatic use of master after first write in a web request to + lower the possible impact of replication lag + + @@ -148,14 +161,14 @@ will be based on the beginning of the statement string. - The plugin does not support native prepared statements. Please - note that PDO_MySQL is using a + Prior to version 1.1 beta the plugin did not support native prepared statements. + Please note that PDO_MySQL is using a client-side prepared statement emulation by default. Client-side emulated - prepared statements are fully supported by the replication and load balancing - plugin because the emulation is not using native prepared statements. - If you are using PHP based database abstraction, please consult the - vendor manual to learn if a client-side prepared statement emulation is - used. + prepared statements are fully supported by any version of + the replication and load balancing plugin because the emulation is not + using native prepared statements. If you are using PHP based database + abstraction, please consult the vendor manual to learn if a client-side + prepared statement emulation is used. @@ -185,7 +198,8 @@ &reference.mysqlnd-ms.concepts; &reference.mysqlnd-ms.setup; &reference.mysqlnd-ms.constants; - &reference.mysqlnd-ms.reference; + &reference.mysqlnd-ms.reference; + &reference.mysqlnd-ms.changes; diff --git a/reference/mysqlnd_ms/changes.xml b/reference/mysqlnd_ms/changes.xml new file mode 100644 index 0000000000..17968f6d1b --- /dev/null +++ b/reference/mysqlnd_ms/changes.xml @@ -0,0 +1,169 @@ + + + + + Change History + + The Change History lists major changes users need to be aware if upgrading + from one version to another. It is a high level summary of selected changes + that may impact applications or might even break backwards compatibility. + Please, consult the CHANGES file contained in the source + distribution for a more complete list of changes. If you are eager to learn + about all changes, even smaller ones that do not make it into the + CHANGES file, you may want to monitor PECL commit messages. + To do you, you could, for example, subsribe to the PECL commit message mailing + list. + + +
+ PECL/mysqlnd_ms 1.1 series + + 1.1.0-beta + + + + Release date: no released yet, planned for 09/2011 + + + + + Motto/theme: Cover replication basics with production quality + + + + + + The 1.1 and 1.0 series expose a similar, although not identical, feature + set to the user, as can be guessed from the release motto/theme. Interally, + the 1.1 series has been refactored significantly to prepare for future + feature additions. A new configuration file format has been introduced + and, limitations have been lifted. Code quality and quality assurance + have been improved. + + + Freature changes + + + + Introduction of (chainable) filter concept + + + + + New powerful JSON based configuration syntax. + + + + + Lazy connections improved: security relevant, state changing commands covered + + + + + Support for (native) prepared statements + + + + + + Bug fixes + + + + Fixed PECL #22724 - Server switching (mysqlnd_ms_query_is_select() case sensitive) + + + + + Fixed PECL #22784 - Using mysql_connect and mysql_select_db won't work + + + + +
+ +
+ PECL/mysqlnd_ms 1.0 series + + 1.0.1-alpha + + + + Release date: 04/2011 + + + + + Motto/theme: bug fix release + + + + + + 1.0.0-alpha + + + + Release date: 04/2011 + + + + + Motto/theme: Cover replication basics to test user feeedback + + + + + + First release of practical use. Features basic automatic read-write splitting, + SQL hints to overrule automatic redirection, load balancing of + slave requests, lazy connections and, optional, automatic use of the master + after the first write. + + + The public feature set is close to that of the 1.1 release. + + + 1.0.0-pre-alpha + + + + Release date: 09/2010 + + + + + Motto/theme: Proof of concept + + + + + + Initial check-in. At this stage the plugin is hardly of + any practical use but a demo of the + mysqlnd plugin API. + +
+ + + + diff --git a/reference/mysqlnd_ms/concepts.xml b/reference/mysqlnd_ms/concepts.xml index f49e48a5b9..80efd9ce41 100755 --- a/reference/mysqlnd_ms/concepts.xml +++ b/reference/mysqlnd_ms/concepts.xml @@ -181,7 +181,7 @@ The latest version of the mysqlnd library, as found in - PHP 5.3.99, allows the plugin to subclass the library C API call + PHP 5.4.0, allows the plugin to subclass the library C API call trx_autocommit() to detect the status of the autocommit mode. The PHP MySQL extensions either issue a query such as SET AUTOCOMMIT=0|1 @@ -194,7 +194,7 @@ The experimental pluging configuration option trx_stickiness=master can be used to make the plugin - transaction aware if using PHP 5.3.99. In this mode the plugin stops load + transaction aware if using PHP 5.4.0 or newer. In this mode the plugin stops load balancing if autocommit gets disabled and directs all statements to the master until autocommit gets enabled. diff --git a/reference/mysqlnd_ms/quickstart.xml b/reference/mysqlnd_ms/quickstart.xml index 8a3eed1793..da1d2f472a 100755 --- a/reference/mysqlnd_ms/quickstart.xml +++ b/reference/mysqlnd_ms/quickstart.xml @@ -582,14 +582,14 @@ $mysqli->close(); - Starting with PHP 5.3.99 the mysqlnd library allows the + Starting with PHP 5.4.0 the mysqlnd library allows the plugin to monitor the status of the autocommit mode, if the mode is set by API calls instead of using SQL statements such as SET AUTOCOMMIT=0. This makes it possible for the plugin to become transaction aware. - If using PHP 5.3.99, API calls to set the autocommit mode + If using PHP 5.4.0 or newer, API calls to set the autocommit mode and setting the experimental plugin configuration option trx_stickiness=master the plugin can automatically disable load balancing and connection switches @@ -663,7 +663,7 @@ $mysqli->close(); The plugin configuration option trx_stickiness=master - is an experimental feature. It requires PHP 5.3.99. + is an experimental feature. It requires PHP 5.4.0 or newer. diff --git a/reference/mysqlnd_ms/setup.xml b/reference/mysqlnd_ms/setup.xml index 704cd8c6a7..8bc81b1e1a 100755 --- a/reference/mysqlnd_ms/setup.xml +++ b/reference/mysqlnd_ms/setup.xml @@ -315,7 +315,7 @@ slave[] = mysql_slave_2 Experimental feature. - The setting requires 5.3.99 or newer. If used with PHP older than 5.3.99, + The setting requires 5.4.0 or newer. If used with PHP older than 5.4.0, the plugin will emit a warning like (mysqlnd_ms) trx_stickiness strategy is not supported before PHP 5.3.99. @@ -328,7 +328,7 @@ slave[] = mysql_slave_2 avoid connection switches during a transaction. - As of PHP 5.3.99 the mysqlnd library allows the plugin to monitor + As of PHP 5.4.ß the mysqlnd library allows the plugin to monitor the autocommit mode set by calls to the libraries trx_autocommit() function. If setting trx_stickiness=master and @@ -355,6 +355,80 @@ slave[] = mysql_slave_2 +
+ Testing + + + The section applies to the development tree (1.1.0-beta) but not the + 1.0 series. + + + + The PECL/mysqlnd_ms test suite is in the tests/ + directory of the source distribution. The test suite consists of standard + phpt tests, which are described on the PHP Quality Assurance Teams website. + + + Before running the tests, edit tests/config.inc to + configure the MySQL servers to be used for testing. You will need at least + one MySQL server to run the tests. However, configuring two distinct MySQL + servers is better. If two distinct servers are configured, the tests can use + one of them as a logical master and the other one as a logical slave. Those + two servers do not need to be part of a MySQL replication cluster. Tests + are written in a way that they can be successfully executed without having + to setup a MySQL replication cluster. If two servers are configured they + must allow login to a test database using the same username and password on + both servers. + + + The most basic configuration is as follows. + + + + + + MYSQL_TEST_HOST, MYSQL_TEST_PORT and + MYSQL_TEST_SOCKET define the hostname, + TCP/IP port and Unix domain socket of the default database server. + MYSQL_TEST_USER and MYSQL_TEST_PASSWD + contain the user and password needed to connect to the database/schema + configured with MYSQL_TEST_DB. If using two distinct + servers, a logical master and a logical slave server, both of them must + have the same database user configured to give access to the test database. + + + Some tests require availability of two distinct MySQL test servers. Those + tests will be skipped, if only one server is configured. To configure a logical + slave server that runs on a different host and/or listens to a different port + or socket than the default server, set MYSQL_TEST_SLAVE_HOST. + Using host, host:port or host:/path/to/socket + syntax for MYSQL_TEST_SLAVE_HOST you can set an alternate + host, host and port or host and socket for the logical slave host. + The same syntax can be used to set MYSQL_TEST_MASTER_HOST. + + + + +
+