1MYSQL_UPGRADE(1) MySQL Database System MYSQL_UPGRADE(1)
2
6 mysql_upgrade - check and upgrade MySQL tables
7
9 mysql_upgrade [options]
10
12 Note
13 As of MySQL 8.0.16, the MySQL server performs the upgrade tasks
14 previously handled by mysql_upgrade (for details, see
15 Section 2.11.3, “What the MySQL Upgrade Process Upgrades”).
16 Consequently, mysql_upgrade is unneeded and is deprecated as of
17 that version, and will be removed in a future MySQL version.
18 Because mysql_upgrade no longer performs upgrade tasks, it exits
19 with status 2 (EXIT_ALREADY_UPGRADED), except that it exits with
20 status 0 (EXIT_SUCCESS) if invoked with the --force option.
21 Each time you upgrade MySQL, you should execute mysql_upgrade, which
23 looks for incompatibilities with the upgraded MySQL server:
24 · It upgrades the system tables in the mysql schema so that you can
26 take advantage of new privileges or capabilities that might have
27 been added.
28 · It upgrades the Performance Schema, INFORMATION_SCHEMA, and sys
30 schema.
31 · It examines user schemas.
33 If mysql_upgrade finds that a table has a possible incompatibility, it
35 performs a table check and, if problems are found, attempts a table
36 repair. If the table cannot be repaired, see Section 2.11.13,
37 “Rebuilding or Repairing Tables or Indexes” for manual table repair
38 strategies.
39 mysql_upgrade communicates directly with the MySQL server, sending it
41 the SQL statements required to perform an upgrade.
42 Caution
44 You should always back up your current MySQL installation before
45 performing an upgrade. See Section 7.2, “Database Backup Methods”.
46 Some upgrade incompatibilities may require special handling before
48 upgrading your MySQL installation and running mysql_upgrade. See
49 Section 2.11, “Upgrading MySQL”, for instructions on determining
50 whether any such incompatibilities apply to your installation and
51 how to handle them.
52 Use mysql_upgrade like this:
54 1. Ensure that the server is running.
56 2. Invoke mysql_upgrade to upgrade the system tables in the mysql
58 schema and check and repair tables in other schemas:
59 shell> mysql_upgrade [options]
61 3. Stop the server and restart it so that any system table changes
63 take effect.
64 If you have multiple MySQL server instances to upgrade, invoke
66 mysql_upgrade with connection parameters appropriate for connecting to
67 each of the desired servers. For example, with servers running on the
68 local host on parts 3306 through 3308, upgrade each of them by
69 connecting to the appropriate port:
70 shell> mysql_upgrade --protocol=tcp -P 3306 [other_options]
72 shell> mysql_upgrade --protocol=tcp -P 3307 [other_options]
73 shell> mysql_upgrade --protocol=tcp -P 3308 [other_options]
74 For local host connections on Unix, the --protocol=tcp option forces a
76 connection using TCP/IP rather than the Unix socket file.
77 By default, mysql_upgrade runs as the MySQL root user. If the root
79 password is expired when you run mysql_upgrade, you will see a message
80 that your password is expired and that mysql_upgrade failed as a
81 result. To correct this, reset the root password to unexpire it and run
82 mysql_upgrade again. First, connect to the server as root:
83 shell> mysql -u root -p
85 Enter password: **** <- enter root password here
86 Reset the password using ALTER USER:
88 mysql> ALTER USER USER() IDENTIFIED BY 'root-password';
90 Then exit mysql and run mysql_upgrade again:
92 shell> mysql_upgrade [options]
94 Note
97 If you run the server with the disabled_storage_engines system
98 variable set to disable certain storage engines (for example,
99 MyISAM), mysql_upgrade might fail with an error like this:
100 mysql_upgrade: [ERROR] 3161: Storage engine MyISAM is disabled
102 (Table creation is disallowed).
103 To handle this, restart the server with disabled_storage_engines
105 disabled. Then you should be able to run mysql_upgrade
106 successfully. After that, restart the server with
107 disabled_storage_engines set to its original value.
108 Unless invoked with the --upgrade-system-tables option, mysql_upgrade
110 processes all tables in all user schemas as necessary. Table checking
111 might take a long time to complete. Each table is locked and therefore
112 unavailable to other sessions while it is being processed. Check and
113 repair operations can be time-consuming, particularly for large tables.
114 Table checking uses the FOR UPGRADE option of the CHECK TABLE
115 statement. For details about what this option entails, see
116 Section 13.7.3.2, “CHECK TABLE Syntax”.
117 mysql_upgrade marks all checked and repaired tables with the current
119 MySQL version number. This ensures that the next time you run
120 mysql_upgrade with the same version of the server, it can be determined
121 whether there is any need to check or repair a given table again.
122 mysql_upgrade saves the MySQL version number in a file named
124 mysql_upgrade_info in the data directory. This is used to quickly check
125 whether all tables have been checked for this release so that
126 table-checking can be skipped. To ignore this file and perform the
127 check regardless, use the --force option.
128 mysql_upgrade checks mysql.user system table rows and, for any row with
130 an empty plugin column, sets that column to 'mysql_native_password' if
131 the credentials use a hash format compatible with that plugin. Rows
132 with a pre-4.1 password hash must be upgraded manually.
133 mysql_upgrade does not upgrade the contents of the time zone tables or
135 help tables. For upgrade instructions, see Section 5.1.13, “MySQL
136 Server Time Zone Support”, and Section 5.1.14, “Server-Side Help
137 Support”.
138 Unless invoked with the --skip-sys-schema option, mysql_upgrade
140 installs the sys schema if it is not installed, and upgrades it to the
141 current version otherwise. An error occurs if a sys schema exists but
142 has no version view, on the assumption that its absence indicates a
143 user-created schema:
144 A sys schema exists with no sys.version view. If
146 you have a user created sys schema, this must be renamed for the
147 upgrade to succeed.
148 To upgrade in this case, remove or rename the existing sys schema
150 first.
151 mysql_upgrade checks for partitioned InnoDB tables that were created
153 using the generic partitioning handler and attempts to upgrade them to
154 InnoDB native partitioning. You can upgrade such tables individually in
155 the mysql client using the ALTER TABLE ... UPGRADE PARTITIONING SQL
156 statement.
157 mysql_upgrade supports the following options, which can be specified on
159 the command line or in the [mysql_upgrade] and [client] groups of an
160 option file. For information about option files used by MySQL programs,
161 see Section 4.2.7, “Using Option Files”.
162 · --help
164 Display a short help message and exit.
166 · --bind-address=ip_address
168 On a computer having multiple network interfaces, use this option
170 to select which interface to use for connecting to the MySQL
171 server.
172 · --character-sets-dir=dir_name
174 The directory where character sets are installed. See
176 Section 10.14, “Character Set Configuration”.
177 · --compress, -C
179 Compress all information sent between the client and the server if
181 both support compression.
182 · --debug[=debug_options], -# [debug_options]
184 Write a debugging log. A typical debug_options string is
186 d:t:o,file_name. The default is d:t:O,/tmp/mysql_upgrade.trace.
187 · --debug-check
189 Print some debugging information when the program exits.
191 · --debug-info, -T
193 Print debugging information and memory and CPU usage statistics
195 when the program exits.
196 · --default-auth=plugin
198 A hint about the client-side authentication plugin to use. See
200 Section 6.3.10, “Pluggable Authentication”.
201 · --default-character-set=charset_name
203 Use charset_name as the default character set. See Section 10.14,
205 “Character Set Configuration”.
206 · --defaults-extra-file=file_name
208 Read this option file after the global option file but (on Unix)
210 before the user option file. If the file does not exist or is
211 otherwise inaccessible, an error occurs. file_name is interpreted
212 relative to the current directory if given as a relative path name
213 rather than a full path name.
214 For additional information about this and other option-file
216 options, see Section 4.2.8, “Command-Line Options that Affect
217 Option-File Handling”.
218 · --defaults-file=file_name
220 Use only the given option file. If the file does not exist or is
222 otherwise inaccessible, an error occurs. file_name is interpreted
223 relative to the current directory if given as a relative path name
224 rather than a full path name.
225 For additional information about this and other option-file
227 options, see Section 4.2.8, “Command-Line Options that Affect
228 Option-File Handling”.
229 · --defaults-group-suffix=str
231 Read not only the usual option groups, but also groups with the
233 usual names and a suffix of str. For example, mysql_upgrade
234 normally reads the [client] and [mysql_upgrade] groups. If the
235 --defaults-group-suffix=_other option is given, mysql_upgrade also
236 reads the [client_other] and [mysql_upgrade_other] groups.
237 For additional information about this and other option-file
239 options, see Section 4.2.8, “Command-Line Options that Affect
240 Option-File Handling”.
241 · --force
243 Ignore the mysql_upgrade_info file and force execution even if
245 mysql_upgrade has already been executed for the current version of
246 MySQL.
247 · --get-server-public-key
249 Request from the server the public key required for RSA key
251 pair-based password exchange. This option applies to clients that
252 that authenticate with the caching_sha2_password authentication
253 plugin. For that plugin, the server does not send the public key
254 unless requested. This option is ignored for accounts that do not
255 authenticate with that plugin. It is also ignored if RSA-based
256 password exchange is not used, as is the case when the client
257 connects to the server using a secure connection.
258 If --server-public-key-path=file_name is given and specifies a
260 valid public key file, it takes precedence over
261 --get-server-public-key.
262 For information about the caching_sha2_password plugin, see
264 Section 6.5.1.3, “Caching SHA-2 Pluggable Authentication”.
265 · --host=host_name, -h host_name
267 Connect to the MySQL server on the given host.
269 · --login-path=name
271 Read options from the named login path in the .mylogin.cnf login
273 path file. A “login path” is an option group containing options
274 that specify which MySQL server to connect to and which account to
275 authenticate as. To create or modify a login path file, use the
276 mysql_config_editor utility. See mysql_config_editor(1).
277 For additional information about this and other option-file
279 options, see Section 4.2.8, “Command-Line Options that Affect
280 Option-File Handling”.
281 · --max-allowed-packet=value
283 The maximum size of the buffer for client/server communication. The
285 default value is 24MB. The minimum and maximum values are 4KB and
286 2GB.
287 · --net-buffer-length=value
289 The initial size of the buffer for client/server communication. The
291 default value is 1MB − 1KB. The minimum and maximum values are 4KB
292 and 16MB.
293 · --no-defaults
295 Do not read any option files. If program startup fails due to
297 reading unknown options from an option file, --no-defaults can be
298 used to prevent them from being read.
299 The exception is that the .mylogin.cnf file, if it exists, is read
301 in all cases. This permits passwords to be specified in a safer way
302 than on the command line even when --no-defaults is used.
303 (.mylogin.cnf is created by the mysql_config_editor utility. See
304 mysql_config_editor(1).)
305 For additional information about this and other option-file
307 options, see Section 4.2.8, “Command-Line Options that Affect
308 Option-File Handling”.
309 · --password[=password], -p[password]
311 The password to use when connecting to the server. If you use the
313 short option form (-p), you cannot have a space between the option
314 and the password. If you omit the password value following the
315 --password or -p option on the command line, mysql_upgrade prompts
316 for one.
317 Specifying a password on the command line should be considered
319 insecure. See Section 6.1.2.1, “End-User Guidelines for Password
320 Security”. You can use an option file to avoid giving the password
321 on the command line.
322 · --pipe, -W
324 On Windows, connect to the server using a named pipe. This option
326 applies only if the server supports named-pipe connections.
327 · --plugin-dir=dir_name
329 The directory in which to look for plugins. Specify this option if
331 the --default-auth option is used to specify an authentication
332 plugin but mysql_upgrade does not find it. See Section 6.3.10,
333 “Pluggable Authentication”.
334 · --port=port_num, -P port_num
336 The TCP/IP port number to use for the connection.
338 · --print-defaults
340 Print the program name and all options that it gets from option
342 files.
343 · --protocol={TCP|SOCKET|PIPE|MEMORY}
345 The connection protocol to use for connecting to the server. It is
347 useful when the other connection parameters normally would cause a
348 protocol to be used other than the one you want. For details on the
349 permissible values, see Section 4.2.2, “Connecting to the MySQL
350 Server”.
351 · --server-public-key-path=file_name
353 The path name to a file containing a client-side copy of the public
355 key required by the server for RSA key pair-based password
356 exchange. The file must be in PEM format. This option applies to
357 clients that authenticate with the sha256_password or
358 caching_sha2_password authentication plugin. This option is ignored
359 for accounts that do not authenticate with one of those plugins. It
360 is also ignored if RSA-based password exchange is not used, as is
361 the case when the client connects to the server using a secure
362 connection.
363 If --server-public-key-path=file_name is given and specifies a
365 valid public key file, it takes precedence over
366 --get-server-public-key.
367 For sha256_password, this option applies only if MySQL was built
369 using OpenSSL.
370 For information about the sha256_password and caching_sha2_password
372 plugins, see Section 6.5.1.2, “SHA-256 Pluggable Authentication”,
373 and Section 6.5.1.3, “Caching SHA-2 Pluggable Authentication”.
374 · --shared-memory-base-name=name
376 On Windows, the shared-memory name to use, for connections made
378 using shared memory to a local server. The default value is MYSQL.
379 The shared-memory name is case-sensitive.
380 The server must be started with the --shared-memory option to
382 enable shared-memory connections.
383 · --skip-sys-schema
385 By default, mysql_upgrade installs the sys schema if it is not
387 installed, and upgrades it to the current version otherwise. The
388 --skip-sys-schema option suppresses this behavior.
389 · --socket=path, -S path
391 For connections to localhost, the Unix socket file to use, or, on
393 Windows, the name of the named pipe to use.
394 · --ssl*
396 Options that begin with --ssl specify whether to connect to the
398 server using SSL and indicate where to find SSL keys and
399 certificates. See Section 6.4.2, “Command Options for Encrypted
400 Connections”.
401 · --ssl-fips-mode={OFF|ON|STRICT} Controls whether to enable FIPS
403 mode on the client side. The --ssl-fips-mode option differs from
404 other --ssl-xxx options in that it is not used to establish
405 encrypted connections, but rather to affect which cryptographic
406 operations are permitted. See Section 6.6, “FIPS Support”.
407 These --ssl-fips-mode values are permitted:
409 · OFF: Disable FIPS mode.
411 · ON: Enable FIPS mode.
413 · STRICT: Enable “strict” FIPS mode.
415 Note
418 If the OpenSSL FIPS Object Module is not available, the only
419 permitted value for --ssl-fips-mode is OFF. In this case,
420 setting --ssl-fips-mode to ON or STRICT causes the client to
421 produce a warning at startup and to operate in non-FIPS mode.
422 · --tls-ciphersuites=ciphersuite_list
424 For client programs, specifies which TLSv1.3 ciphersuites the
426 client permits for encrypted connections. The value is a list of
427 one or more colon-separated ciphersuite names. The ciphersuites
428 that can be named for this option depend on the SSL library used to
429 compile MySQL. For details, see Section 6.4.6, “Encrypted
430 Connection Protocols and Ciphers”.
431 This option was added in MySQL 8.0.16.
433 · --tls-version=protocol_list
435 The protocols the client permits for encrypted connections. The
437 value is a list of one or more comma-separated protocol names. The
438 protocols that can be named for this option depend on the SSL
439 library used to compile MySQL. For details, see Section 6.4.6,
440 “Encrypted Connection Protocols and Ciphers”.
441 · --upgrade-system-tables, -s
443 Upgrade only the system tables in the mysql schema, do not upgrade
445 user schemas.
446 · --user=user_name, -u user_name
448 The MySQL user name to use when connecting to the server. The
450 default user name is root.
451 · --verbose
453 Verbose mode. Print more information about what the program does.
455 · --version-check, -k
457 Check the version of the server to which mysql_upgrade is
459 connecting to verify that it is the same as the version for which
460 mysql_upgrade was built. If not, mysql_upgrade exits. This option
461 is enabled by default; to disable the check, use
462 --skip-version-check.
463 · --write-binlog
465 By default, binary logging by mysql_upgrade is disabled. Invoke the
467 program with --write-binlog if you want its actions to be written
468 to the binary log.
469 When the server is running with global transaction identifiers
471 (GTIDs) enabled (gtid_mode=ON), do not enable binary logging by
472 mysql_upgrade.
473
475 Copyright © 1997, 2019, Oracle and/or its affiliates. All rights
476 reserved.
477 This documentation is free software; you can redistribute it and/or
479 modify it only under the terms of the GNU General Public License as
480 published by the Free Software Foundation; version 2 of the License.
481 This documentation is distributed in the hope that it will be useful,
483 but WITHOUT ANY WARRANTY; without even the implied warranty of
484 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
485 General Public License for more details.
486 You should have received a copy of the GNU General Public License along
488 with the program; if not, write to the Free Software Foundation, Inc.,
489 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA or see
490 http://www.gnu.org/licenses/.
491
494 For more information, please refer to the MySQL Reference Manual, which
495 may already be installed locally and which is also available online at
496 http://dev.mysql.com/doc/.
497
499 Oracle Corporation (http://dev.mysql.com/).
500MySQL 8.0 02/20/2019 MYSQL_UPGRADE(1)