reference/pdo_mysql/reference.xml
ed851c6bbc75edca2706ea43f224278dd0538a6f
ed851c6bbc75edca2706ea43f224278dd0538a6f
...
...
@@ -12,13 +12,33 @@
12
12
<para>
13
13
PDO_MYSQL is a driver that implements the <link linkend="intro.pdo">PHP
14
14
Data Objects (PDO) interface</link>
15
-
to enable access from PHP to MySQL 3.x, 4.x and 5.x databases.
15
+
to enable access from PHP to MySQL databases.
16
16
</para>
17
17
<para>
18
-
PDO_MYSQL will take advantage of native prepared statement support
19
-
present in MySQL 4.1 and higher. If you're using an older version of the
20
-
mysql client libraries, PDO will emulate them for you.
18
+
PDO_MYSQL uses emulated prepares by default.
21
19
</para>
20
+
21
+
<para>
22
+
<emphasis role="bold">MySQL 8</emphasis>
23
+
</para>
24
+
25
+
<para>
26
+
When running a PHP version before 7.1.16, or PHP 7.2 before 7.2.4, set
27
+
MySQL 8 Server's default password plugin to <emphasis>mysql_native_password</emphasis>
28
+
or else you will see errors similar to
29
+
<emphasis>The server requested authentication method unknown to the client [caching_sha2_password]</emphasis>
30
+
even when <emphasis>caching_sha2_password</emphasis> is not used.
31
+
</para>
32
+
<para>
33
+
This is because MySQL 8 defaults to caching_sha2_password, a plugin that is
34
+
not recognized by the older PHP (mysqlnd) releases. Instead, change it by
35
+
setting <literal>default_authentication_plugin=mysql_native_password</literal>
36
+
in <filename>my.cnf</filename>. The <emphasis>caching_sha2_password</emphasis>
37
+
plugin is fully supported as of PHP 7.4.4. For older releases, the
38
+
<link linkend="book.mysql-xdevapi">mysql_xdevapi</link> extension does
39
+
support it.
40
+
</para>
41
+
22
42
<warning>
23
43
<para>
24
44
Beware: Some MySQL table types (storage engines) do not support transactions. When
...
...
@@ -28,6 +48,13 @@
28
48
commit any pending transactions.
29
49
</para>
30
50
</warning>
51
+
<note>
52
+
<para>
53
+
The MySQL driver does not properly support <constant>PDO::PARAM_INPUT_OUTPUT</constant>
54
+
via <methodname>PDOStatement::bindParam</methodname>; while such parameters can be used,
55
+
they are not updated (i.e. the actual output is ignored).
56
+
</para>
57
+
</note>
31
58
</section>
32
59
&reference.pdo-mysql.configure;
33
60
&reference.pdo-mysql.constants;
...
...
@@ -93,73 +120,12 @@
93
120
The character set. See the <link linkend="mysqlinfo.concepts.charset">character set</link>
94
121
concepts documentation for more information.
95
122
</para>
96
-
<para>
97
-
Prior to PHP 5.3.6, this element was silently ignored. The same
98
-
behaviour can be partly replicated with the
99
-
<constant>PDO::MYSQL_ATTR_INIT_COMMAND</constant> driver option, as
100
-
the following example shows.
101
-
</para>
102
-
<warning>
103
-
<simpara>
104
-
The method in the below example can only be used with character sets
105
-
that share the same lower 7 bit representation as ASCII, such as
106
-
ISO-8859-1 and UTF-8. Users using character sets that have different
107
-
representations (such as UTF-16 or Big5) <emphasis>must</emphasis>
108
-
use the <literal>charset</literal> option provided in PHP 5.3.6
109
-
and later versions.
110
-
</simpara>
111
-
</warning>
112
-
<para>
113
-
<example>
114
-
<title>
115
-
Setting the connection character set to UTF-8 prior to PHP 5.3.6
116
-
</title>
117
-
<programlisting role="php">
118
-
<![CDATA[
119
-
<?php
120
-
$dsn = 'mysql:host=localhost;dbname=testdb';
121
-
$username = 'username';
122
-
$password = 'password';
123
-
$options = array(
124
-
PDO::MYSQL_ATTR_INIT_COMMAND => 'SET NAMES utf8',
125
-
);
126
-
127
-
$dbh = new PDO($dsn, $username, $password, $options);
128
-
?>
129
-
]]>
130
-
</programlisting>
131
-
</example>
132
-
</para>
133
123
</listitem>
134
124
</varlistentry>
135
125
</variablelist>
136
126
</para>
137
127
</refsect1>
138
128
139
-
<refsect1 role="changelog">
140
-
&reftitle.changelog;
141
-
<para>
142
-
<informaltable>
143
-
<tgroup cols="2">
144
-
<thead>
145
-
<row>
146
-
<entry>&Version;</entry>
147
-
<entry>&Description;</entry>
148
-
</row>
149
-
</thead>
150
-
<tbody>
151
-
<row>
152
-
<entry>5.3.6</entry>
153
-
<entry>
154
-
Prior to version 5.3.6, <literal>charset</literal> was ignored.
155
-
</entry>
156
-
</row>
157
-
</tbody>
158
-
</tgroup>
159
-
</informaltable>
160
-
</para>
161
-
</refsect1>
162
-
163
129
<refsect1 role="examples">
164
130
&reftitle.examples;
165
131
<para>
...
...
@@ -191,9 +157,9 @@ mysql:unix_socket=/tmp/mysql.sock;dbname=testdb
191
157
<title>Unix only:</title>
192
158
<para>
193
159
When the host name is set to <literal>"localhost"</literal>, then the connection to the
194
-
server is made thru a domain socket. If PDO_MYSQL is compiled against libmysqlclient then the
160
+
server is made through a domain socket. If PDO_MYSQL is compiled against libmysqlclient then the
195
161
location of the socket file is at libmysqlclient's compiled in location. If PDO_MYSQL is compiled
196
-
against mysqlnd a default socket can be set thru the <link linkend="ini.pdo-mysql.default-socket">
162
+
against mysqlnd a default socket can be set through the <link linkend="ini.pdo-mysql.default-socket">
197
163
pdo_mysql.default_socket</link> setting.
198
164
</para>
199
165
</note>
200
166