Options and Variables Deprecated in MySQL 8.

• innodb_undo_tablespaces: Number of tablespace files that rollback segments are divided between.
Deprecated in MySQL 8.0.4.

• keyring_encrypted_file_data: keyring_encrypted_file plugin data file. Deprecated in MySQL

8.0.34.

• keyring_encrypted_file_password: keyring_encrypted_file plugin password. Deprecated in

MySQL 8.0.34.

• keyring_file_data: keyring_file plugin data file. Deprecated in MySQL 8.0.34.

• keyring_oci_ca_certificate: CA certificate file for peer authentication. Deprecated in MySQL

8.0.31.

• keyring_oci_compartment: OCI compartment OCID. Deprecated in MySQL 8.0.31.

• keyring_oci_encryption_endpoint: OCI encryption server endpoint. Deprecated in MySQL

8.0.31.

• keyring_oci_key_file: OCI RSA private key file. Deprecated in MySQL 8.0.31.

• keyring_oci_key_fingerprint: OCI RSA private key file fingerprint. Deprecated in MySQL 8.0.31.

• keyring_oci_management_endpoint: OCI management server endpoint. Deprecated in MySQL

8.0.31.

• keyring_oci_master_key: OCI master key OCID. Deprecated in MySQL 8.0.31.

• keyring_oci_secrets_endpoint: OCI secrets server endpoint. Deprecated in MySQL 8.0.31.

• keyring_oci_tenancy: OCI tenancy OCID. Deprecated in MySQL 8.0.31.

• keyring_oci_user: OCI user OCID. Deprecated in MySQL 8.0.31.

• keyring_oci_vaults_endpoint: OCI vaults server endpoint. Deprecated in MySQL 8.0.31.

• keyring_oci_virtual_vault: OCI vault OCID. Deprecated in MySQL 8.0.31.

• log_bin_trust_function_creators: If equal to 0 (default), then when --log-bin is used, stored

function creation is allowed only to users having SUPER privilege and only if function created does not
break binary logging. Deprecated in MySQL 8.0.34.

• log_bin_use_v1_row_events: Whether server is using version 1 binary log row events. Deprecated
in MySQL 8.0.18.

• log_slave_updates: Whether replica should log updates performed by its replication SQL thread to
its own binary log. Deprecated in MySQL 8.0.26.

• log_slow_slave_statements: Cause slow statements as executed by replica to be written to slow

query log. Deprecated in MySQL 8.0.26.

• log_statements_unsafe_for_binlog: Disables error 1592 warnings being written to error log.

Deprecated in MySQL 8.0.34.

• log_syslog: Whether to write error log to syslog. Deprecated in MySQL 8.0.2.

• master-info-file: Location and name of file that remembers source and where I/O replication thread
is in source's binary log. Deprecated in MySQL 8.0.18.

89
 Options and Variables Deprecated in MySQL 8.0

• master_info_repository: Whether to write connection metadata repository, containing source

information and replication I/O thread location in source's binary log, to file or table. Deprecated in
MySQL 8.0.23.

• master_verify_checksum: Cause source to examine checksums when reading from binary log.
Deprecated in MySQL 8.0.26.

• max_length_for_sort_data: Max number of bytes in sorted records. Deprecated in MySQL 8.0.20.

• myisam_repair_threads: Number of threads to use when repairing MyISAM tables. 1 disables

parallel repair. Deprecated in MySQL 8.0.29.

• new: Use very new, possibly 'unsafe' functions. Deprecated in MySQL 8.0.35.

• no-dd-upgrade: Prevent automatic upgrade of data dictionary tables at startup. Deprecated in MySQL
8.0.16.

• old: Cause server to revert to certain behaviors present in older versions. Deprecated in MySQL 8.0.35.

• old-style-user-limits: Enable old-style user limits (before 5.0.3, user resources were counted per
each user+host vs. per account). Deprecated in MySQL 8.0.30.

• performance_schema_show_processlist: Select SHOW PROCESSLIST implementation.

Deprecated in MySQL 8.0.35.

• pseudo_slave_mode: For internal server use. Deprecated in MySQL 8.0.26.

• query_prealloc_size: Persistent buffer for query parsing and execution. Deprecated in MySQL
8.0.29.

• relay_log_info_file: File name for applier metadata repository in which replica records information
about relay logs. Deprecated in MySQL 8.0.18.

• relay_log_info_repository: Whether to write location of replication SQL thread in relay logs to file
or table. Deprecated in MySQL 8.0.23.

• replica_parallel_type: Tells replica to use timestamp information (LOGICAL_CLOCK) or

database partitioning (DATABASE) to parallelize transactions. Deprecated in MySQL 8.0.29.

• rpl_stop_slave_timeout: Number of seconds that STOP REPLICA or STOP SLAVE waits before
timing out. Deprecated in MySQL 8.0.26.

• safe-user-create: Do not allow new user creation by user who has no write privileges to mysql.user
table; this option is deprecated and ignored. Deprecated in MySQL 8.0.11.

• show-slave-auth-info: Show user name and password in SHOW REPLICAS and SHOW SLAVE
HOSTS on this source. Deprecated in MySQL 8.0.26.

• skip-character-set-client-handshake: Ignore client side character set value sent during

handshake. Deprecated in MySQL 8.0.35.

• skip-host-cache: Do not cache host names. Deprecated in MySQL 8.0.30.

• skip-new: Do not use new, possibly wrong routines. Deprecated in MySQL 8.0.35.

• skip-slave-start: If set, replication is not autostarted when replica server starts. Deprecated in
MySQL 8.0.26.

• slave-skip-errors: Tells replication thread to continue replication when query returns error from
provided list. Deprecated in MySQL 8.0.26.

90
 Options and Variables Deprecated in MySQL 8.0

• slave_checkpoint_group: Maximum number of transactions processed by multithreaded replica

before checkpoint operation is called to update progress status. Not supported by NDB Cluster.
Deprecated in MySQL 8.0.26.

• slave_checkpoint_period: Update progress status of multithreaded replica and flush relay log info
to disk after this number of milliseconds. Not supported by NDB Cluster. Deprecated in MySQL 8.0.26.

• slave_compressed_protocol: Use compression of source/replica protocol. Deprecated in MySQL

8.0.18.

• slave_load_tmpdir: Location where replica should put its temporary files when replicating LOAD
DATA statements. Deprecated in MySQL 8.0.26.

• slave_max_allowed_packet: Maximum size, in bytes, of packet that can be sent from replication
source server to replica; overrides max_allowed_packet. Deprecated in MySQL 8.0.26.

• slave_net_timeout: Number of seconds to wait for more data from source/replica connection before
aborting read. Deprecated in MySQL 8.0.26.

• slave_parallel_type: Tells replica to use timestamp information (LOGICAL_CLOCK) or database

partioning (DATABASE) to parallelize transactions. Deprecated in MySQL 8.0.26.

• slave_parallel_workers: Number of applier threads for executing replication transactions in

parallel; 0 or 1 disables replica multithreading. NDB Cluster: see documentation. Deprecated in MySQL
8.0.26.

• slave_pending_jobs_size_max: Maximum size of replica worker queues holding events not yet
applied. Deprecated in MySQL 8.0.26.

• slave_preserve_commit_order: Ensures that all commits by replica workers happen in same order
as on source to maintain consistency when using parallel applier threads. Deprecated in MySQL 8.0.26.

• slave_rows_search_algorithms: Determines search algorithms used for replica update batching.

Any 2 or 3 from this list: INDEX_SEARCH, TABLE_SCAN, HASH_SCAN. Deprecated in MySQL 8.0.18.

• slave_sql_verify_checksum: Cause replica to examine checksums when reading from relay log.
Deprecated in MySQL 8.0.26.

• slave_transaction_retries: Number of times replication SQL thread retries transaction in case it

failed with deadlock or elapsed lock wait timeout, before giving up and stopping. Deprecated in MySQL
8.0.26.

• slave_type_conversions: Controls type conversion mode on replica. Value is list of zero or

more elements from this list: ALL_LOSSY, ALL_NON_LOSSY. Set to empty string to disallow type
conversions between source and replica. Deprecated in MySQL 8.0.26.

• sql_slave_skip_counter: Number of events from source that replica should skip. Not compatible
with GTID replication. Deprecated in MySQL 8.0.26.

• ssl: Enable connection encryption. Deprecated in MySQL 8.0.26.

• ssl_fips_mode: Whether to enable FIPS mode on server side. Deprecated in MySQL 8.0.34.

• symbolic-links: Permit symbolic links for MyISAM tables. Deprecated in MySQL 8.0.2.

• sync_master_info: Synchronize source information after every #th event. Deprecated in MySQL
8.0.26.

91
 Options and Variables Removed in MySQL 8.0

• sync_relay_log_info: Synchronize relay.info file to disk after every #th event. Deprecated in MySQL
8.0.34.

• temptable_use_mmap: Defines whether TempTable storage engine allocates memory-mapped files

when the temptable_max_ram threshold is reached. Deprecated in MySQL 8.0.26.

• transaction_prealloc_size: Persistent buffer for transactions to be stored in binary log.

Deprecated in MySQL 8.0.29.

• transaction_write_set_extraction: Defines algorithm used to hash writes extracted during

transaction. Deprecated in MySQL 8.0.26.

Options and Variables Removed in MySQL 8.0

The following system variables, status variables, and options have been removed in MySQL 8.0.

• Com_alter_db_upgrade: Count of ALTER DATABASE ... UPGRADE DATA DIRECTORY NAME

statements. Removed in MySQL 8.0.0.

• Innodb_available_undo_logs: Total number of InnoDB rollback segments; different from

innodb_rollback_segments, which displays number of active rollback segments. Removed in MySQL
8.0.2.

• Qcache_free_blocks: Number of free memory blocks in query cache. Removed in MySQL 8.0.3.

• Qcache_free_memory: Amount of free memory for query cache. Removed in MySQL 8.0.3.

• Qcache_hits: Number of query cache hits. Removed in MySQL 8.0.3.

• Qcache_inserts: Number of query cache inserts. Removed in MySQL 8.0.3.

• Qcache_lowmem_prunes: Number of queries which were deleted from query cache due to lack of free
memory in cache. Removed in MySQL 8.0.3.

• Qcache_not_cached: Number of noncached queries (not cacheable, or not cached due to

query_cache_type setting). Removed in MySQL 8.0.3.

• Qcache_queries_in_cache: Number of queries registered in query cache. Removed in MySQL 8.0.3.

• Qcache_total_blocks: Total number of blocks in query cache. Removed in MySQL 8.0.3.

• Slave_heartbeat_period: Replica's replication heartbeat interval, in seconds. Removed in MySQL

8.0.1.

• Slave_last_heartbeat: Shows when latest heartbeat signal was received, in TIMESTAMP format.
Removed in MySQL 8.0.1.

• Slave_received_heartbeats: Number of heartbeats received by replica since previous reset.

Removed in MySQL 8.0.1.

• Slave_retried_transactions: Total number of times since startup that replication SQL thread has
retried transactions. Removed in MySQL 8.0.1.

• Slave_running: State of this server as replica (replication I/O thread status). Removed in MySQL
8.0.1.

• bootstrap: Used by mysql installation scripts. Removed in MySQL 8.0.0.

• date_format: DATE format (unused). Removed in MySQL 8.0.3.

92
 Options and Variables Removed in MySQL 8.0

• datetime_format: DATETIME/TIMESTAMP format (unused). Removed in MySQL 8.0.3.

• des-key-file: Load keys for des_encrypt() and des_encrypt from given file. Removed in MySQL
8.0.3.

• group_replication_allow_local_disjoint_gtids_join: Allow current server to join group

even if it has transactions not present in group. Removed in MySQL 8.0.4.

• have_crypt: Availability of crypt() system call. Removed in MySQL 8.0.3.

• ignore-db-dir: Treat directory as nondatabase directory. Removed in MySQL 8.0.0.

• ignore_builtin_innodb: Ignore built-in InnoDB. Removed in MySQL 8.0.3.

• ignore_db_dirs: Directories treated as nondatabase directories. Removed in MySQL 8.0.0.

• innodb_checksums: Enable InnoDB checksums validation. Removed in MySQL 8.0.0.

• innodb_disable_resize_buffer_pool_debug: Disables resizing of InnoDB buffer pool. Removed

in MySQL 8.0.0.

• innodb_file_format: Format for new InnoDB tables. Removed in MySQL 8.0.0.

• innodb_file_format_check: Whether InnoDB performs file format compatibility checking. Removed

in MySQL 8.0.0.

• innodb_file_format_max: File format tag in shared tablespace. Removed in MySQL 8.0.0.

• innodb_large_prefix: Enables longer keys for column prefix indexes. Removed in MySQL 8.0.0.

• innodb_locks_unsafe_for_binlog: Force InnoDB not to use next-key locking. Instead use only
row-level locking. Removed in MySQL 8.0.0.

• innodb_scan_directories: Defines directories to scan for tablespace files during InnoDB recovery.
Removed in MySQL 8.0.4.

• innodb_stats_sample_pages: Number of index pages to sample for index distribution statistics.

Removed in MySQL 8.0.0.

• innodb_support_xa: Enable InnoDB support for XA two-phase commit. Removed in MySQL 8.0.0.

• innodb_undo_logs: Number of undo logs (rollback segments) used by InnoDB; alias for
innodb_rollback_segments. Removed in MySQL 8.0.2.

• internal_tmp_disk_storage_engine: Storage engine for internal temporary tables. Removed in

MySQL 8.0.16.

• log-warnings: Write some noncritical warnings to log file. Removed in MySQL 8.0.3.

• log_builtin_as_identified_by_password: Whether to log CREATE/ALTER USER, GRANT in

backward-compatible fashion. Removed in MySQL 8.0.11.

• log_error_filter_rules: Filter rules for error logging. Removed in MySQL 8.0.4.

• log_syslog: Whether to write error log to syslog. Removed in MySQL 8.0.13.

• log_syslog_facility: Facility for syslog messages. Removed in MySQL 8.0.13.

• log_syslog_include_pid: Whether to include server PID in syslog messages. Removed in MySQL

8.0.13.

93
 How to Report Bugs or Problems

• log_syslog_tag: Tag for server identifier in syslog messages. Removed in MySQL 8.0.13.

• max_tmp_tables: Unused. Removed in MySQL 8.0.3.

• metadata_locks_cache_size: Size of metadata locks cache. Removed in MySQL 8.0.13.

• metadata_locks_hash_instances: Number of metadata lock hashes. Removed in MySQL 8.0.13.

• multi_range_count: Maximum number of ranges to send to table handler at once during range
selects. Removed in MySQL 8.0.3.

• myisam_repair_threads: Number of threads to use when repairing MyISAM tables. 1 disables

parallel repair. Removed in MySQL 8.0.30.

• old_passwords: Selects password hashing method for PASSWORD(). Removed in MySQL 8.0.11.

• partition: Enable (or disable) partitioning support. Removed in MySQL 8.0.0.

• query_cache_limit: Do not cache results that are bigger than this. Removed in MySQL 8.0.3.

• query_cache_min_res_unit: Minimal size of unit in which space for results is allocated (last unit is
trimmed after writing all result data). Removed in MySQL 8.0.3.

• query_cache_size: Memory allocated to store results from old queries. Removed in MySQL 8.0.3.

• query_cache_type: Query cache type. Removed in MySQL 8.0.3.

• query_cache_wlock_invalidate: Invalidate queries in query cache on LOCK for write. Removed in

MySQL 8.0.3.

• secure_auth: Disallow authentication for accounts that have old (pre-4.1) passwords. Removed in
MySQL 8.0.3.

• show_compatibility_56: Compatibility for SHOW STATUS/VARIABLES. Removed in MySQL 8.0.1.

• skip-partition: Do not enable user-defined partitioning. Removed in MySQL 8.0.0.

• sync_frm: Sync .frm to disk on create. Enabled by default. Removed in MySQL 8.0.0.

• temp-pool: Using this option causes most temporary files created to use small set of names, rather
than unique name for each new file. Removed in MySQL 8.0.1.

• time_format: TIME format (unused). Removed in MySQL 8.0.3.

• tx_isolation: Default transaction isolation level. Removed in MySQL 8.0.3.

• tx_read_only: Default transaction access mode. Removed in MySQL 8.0.3.

1.5 How to Report Bugs or Problems

Before posting a bug report about a problem, please try to verify that it is a bug and that it has not been
reported already:

• Start by searching the MySQL online manual at https://dev.mysql.com/doc/. We try to keep the manual
up to date by updating it frequently with solutions to newly found problems. In addition, the release
notes accompanying the manual can be particularly useful since it is quite possible that a newer version
contains a solution to your problem. The release notes are available at the location just given for the
manual.

94
 How to Report Bugs or Problems

• If you get a parse error for an SQL statement, please check your syntax closely. If you cannot find
something wrong with it, it is extremely likely that your current version of MySQL Server doesn't support
the syntax you are using. If you are using the current version and the manual doesn't cover the syntax
that you are using, MySQL Server doesn't support your statement.

If the manual covers the syntax you are using, but you have an older version of MySQL Server, you
should check the MySQL change history to see when the syntax was implemented. In this case, you
have the option of upgrading to a newer version of MySQL Server.

• For solutions to some common problems, see Section B.3, “Problems and Common Errors”.

• Search the bugs database at http://bugs.mysql.com/ to see whether the bug has been reported and
fixed.

• You can also use http://www.mysql.com/search/ to search all the Web pages (including the manual) that
are located at the MySQL website.

If you cannot find an answer in the manual, the bugs database, or the mailing list archives, check with your
local MySQL expert. If you still cannot find an answer to your question, please use the following guidelines
for reporting the bug.

The normal way to report bugs is to visit http://bugs.mysql.com/, which is the address for our bugs
database. This database is public and can be browsed and searched by anyone. If you log in to the
system, you can enter new reports.

Bugs posted in the bugs database at http://bugs.mysql.com/ that are corrected for a given release are
noted in the release notes.

If you find a security bug in MySQL Server, please let us know immediately by sending an email message
to <[email protected]>. Exception: Support customers should report all problems, including
security bugs, to Oracle Support at http://support.oracle.com/.

To discuss problems with other users, you can use the MySQL Community Slack.

Writing a good bug report takes patience, but doing it right the first time saves time both for us and for
yourself. A good bug report, containing a full test case for the bug, makes it very likely that we will fix the
bug in the next release. This section helps you write your report correctly so that you do not waste your
time doing things that may not help us much or at all. Please read this section carefully and make sure that
all the information described here is included in your report.

Preferably, you should test the problem using the latest production or development version of MySQL
Server before posting. Anyone should be able to repeat the bug by just using mysql test <
script_file on your test case or by running the shell or Perl script that you include in the bug report.
Any bug that we are able to repeat has a high chance of being fixed in the next MySQL release.

It is most helpful when a good description of the problem is included in the bug report. That is, give a good
example of everything you did that led to the problem and describe, in exact detail, the problem itself.
The best reports are those that include a full example showing how to reproduce the bug or problem. See
Section 7.9, “Debugging MySQL”.

Remember that it is possible for us to respond to a report containing too much information, but not to one
containing too little. People often omit facts because they think they know the cause of a problem and
assume that some details do not matter. A good principle to follow is that if you are in doubt about stating
something, state it. It is faster and less troublesome to write a couple more lines in your report than to wait
longer for the answer if we must ask you to provide information that was missing from the initial report.

The most common errors made in bug reports are (a) not including the version number of the MySQL
distribution that you use, and (b) not fully describing the platform on which the MySQL server is installed

95
 How to Report Bugs or Problems

(including the platform type and version number). These are highly relevant pieces of information, and in
99 cases out of 100, the bug report is useless without them. Very often we get questions like, “Why doesn't
this work for me?” Then we find that the feature requested wasn't implemented in that MySQL version,
or that a bug described in a report has been fixed in newer MySQL versions. Errors often are platform-
dependent. In such cases, it is next to impossible for us to fix anything without knowing the operating
system and the version number of the platform.

If you compiled MySQL from source, remember also to provide information about your compiler if it is
related to the problem. Often people find bugs in compilers and think the problem is MySQL-related.
Most compilers are under development all the time and become better version by version. To determine
whether your problem depends on your compiler, we need to know what compiler you used. Note that
every compiling problem should be regarded as a bug and reported accordingly.

If a program produces an error message, it is very important to include the message in your report. If we try
to search for something from the archives, it is better that the error message reported exactly matches the
one that the program produces. (Even the lettercase should be observed.) It is best to copy and paste the
entire error message into your report. You should never try to reproduce the message from memory.

If you have a problem with Connector/ODBC (MyODBC), please try to generate a trace file and send it with
your report. See How to Report Connector/ODBC Problems or Bugs.

If your report includes long query output lines from test cases that you run with the mysql command-
line tool, you can make the output more readable by using the --vertical option or the \G statement
terminator. The EXPLAIN SELECT example later in this section demonstrates the use of \G.

Please include the following information in your report:

• The version number of the MySQL distribution you are using (for example, MySQL 5.7.10). You can find
out which version you are running by executing mysqladmin version. The mysqladmin program can
be found in the bin directory under your MySQL installation directory.

• The manufacturer and model of the machine on which you experience the problem.

• The operating system name and version. If you work with Windows, you can usually get the name and
version number by double-clicking your My Computer icon and pulling down the “Help/About Windows”
menu. For most Unix-like operating systems, you can get this information by executing the command
uname -a.

• Sometimes the amount of memory (real and virtual) is relevant. If in doubt, include these values.

• The contents of the docs/INFO_BIN file from your MySQL installation. This file contains information
about how MySQL was configured and compiled.

• If you are using a source distribution of the MySQL software, include the name and version number of
the compiler that you used. If you have a binary distribution, include the distribution name.

• If the problem occurs during compilation, include the exact error messages and also a few lines of
context around the offending code in the file where the error occurs.

• If mysqld died, you should also report the statement that caused mysqld to unexpectedly exit. You can
usually get this information by running mysqld with query logging enabled, and then looking in the log
after mysqld exits. See Section 7.9, “Debugging MySQL”.

• If a database table is related to the problem, include the output from the SHOW CREATE TABLE
db_name.tbl_name statement in the bug report. This is a very easy way to get the definition of
any table in a database. The information helps us create a situation matching the one that you have
experienced.

96
 How to Report Bugs or Problems

• The SQL mode in effect when the problem occurred can be significant, so please report the value of
the sql_mode system variable. For stored procedure, stored function, and trigger objects, the relevant
sql_mode value is the one in effect when the object was created. For a stored procedure or function,
the SHOW CREATE PROCEDURE or SHOW CREATE FUNCTION statement shows the relevant SQL mode,
or you can query INFORMATION_SCHEMA for the information:
SELECT ROUTINE_SCHEMA, ROUTINE_NAME, SQL_MODE
FROM INFORMATION_SCHEMA.ROUTINES;

For triggers, you can use this statement:

SELECT EVENT_OBJECT_SCHEMA, EVENT_OBJECT_TABLE, TRIGGER_NAME, SQL_MODE
FROM INFORMATION_SCHEMA.TRIGGERS;

• For performance-related bugs or problems with SELECT statements, you should always include the
output of EXPLAIN SELECT ..., and at least the number of rows that the SELECT statement produces.
You should also include the output from SHOW CREATE TABLE tbl_name for each table that is
involved. The more information you provide about your situation, the more likely it is that someone can
help you.

The following is an example of a very good bug report. The statements are run using the mysql
command-line tool. Note the use of the \G statement terminator for statements that would otherwise
provide very long output lines that are difficult to read.
mysql> SHOW VARIABLES;
mysql> SHOW COLUMNS FROM ...\G
<output from SHOW COLUMNS>
mysql> EXPLAIN SELECT ...\G
<output from EXPLAIN>
mysql> FLUSH STATUS;
mysql> SELECT ...;
<A short version of the output from SELECT,
including the time taken to run the query>
mysql> SHOW STATUS;
<output from SHOW STATUS>

• If a bug or problem occurs while running mysqld, try to provide an input script that reproduces the
anomaly. This script should include any necessary source files. The more closely the script can
reproduce your situation, the better. If you can make a reproducible test case, you should upload it to be
attached to the bug report.

If you cannot provide a script, you should at least include the output from mysqladmin variables
extended-status processlist in your report to provide some information on how your system is
performing.

• If you cannot produce a test case with only a few rows, or if the test table is too big to be included in the
bug report (more than 10 rows), you should dump your tables using mysqldump and create a README
file that describes your problem. Create a compressed archive of your files using tar and gzip or zip.
After you initiate a bug report for our bugs database at http://bugs.mysql.com/, click the Files tab in the
bug report for instructions on uploading the archive to the bugs database.

• If you believe that the MySQL server produces a strange result from a statement, include not only the
result, but also your opinion of what the result should be, and an explanation describing the basis for
your opinion.

• When you provide an example of the problem, it is better to use the table names, variable names, and
so forth that exist in your actual situation than to come up with new names. The problem could be related
to the name of a table or variable. These cases are rare, perhaps, but it is better to be safe than sorry.
After all, it should be easier for you to provide an example that uses your actual situation, and it is by all

97
 How to Report Bugs or Problems

means better for us. If you have data that you do not want to be visible to others in the bug report, you
can upload it using the Files tab as previously described. If the information is really top secret and you do
not want to show it even to us, go ahead and provide an example using other names, but please regard
this as the last choice.

• Include all the options given to the relevant programs, if possible. For example, indicate the options that
you use when you start the mysqld server, as well as the options that you use to run any MySQL client
programs. The options to programs such as mysqld and mysql, and to the configure script, are often
key to resolving problems and are very relevant. It is never a bad idea to include them. If your problem
involves a program written in a language such as Perl or PHP, please include the language processor's
version number, as well as the version for any modules that the program uses. For example, if you have
a Perl script that uses the DBI and DBD::mysql modules, include the version numbers for Perl, DBI,
and DBD::mysql.

• If your question is related to the privilege system, please include the output of mysqladmin reload,
and all the error messages you get when trying to connect. When you test your privileges, you should
execute mysqladmin reload version and try to connect with the program that gives you trouble.

• If you have a patch for a bug, do include it. But do not assume that the patch is all we need, or that we
can use it, if you do not provide some necessary information such as test cases showing the bug that
your patch fixes. We might find problems with your patch or we might not understand it at all. If so, we
cannot use it.

If we cannot verify the exact purpose of the patch, we will not use it. Test cases help us here. Show that
the patch handles all the situations that may occur. If we find a borderline case (even a rare one) where
the patch will not work, it may be useless.

• Guesses about what the bug is, why it occurs, or what it depends on are usually wrong. Even the
MySQL team cannot guess such things without first using a debugger to determine the real cause of a
bug.

• Indicate in your bug report that you have checked the reference manual and mail archive so that others
know you have tried to solve the problem yourself.

• If your data appears corrupt or you get errors when you access a particular table, first check your tables
with CHECK TABLE. If that statement reports any errors:

• The InnoDB crash recovery mechanism handles cleanup when the server is restarted after being
killed, so in typical operation there is no need to “repair” tables. If you encounter an error with
InnoDB tables, restart the server and see whether the problem persists, or whether the error
affected only cached data in memory. If data is corrupted on disk, consider restarting with the
innodb_force_recovery option enabled so that you can dump the affected tables.

• For non-transactional tables, try to repair them with REPAIR TABLE or with myisamchk. See
Chapter 7, MySQL Server Administration.

If you are running Windows, please verify the value of lower_case_table_names using the SHOW
VARIABLES LIKE 'lower_case_table_names' statement. This variable affects how the server
handles lettercase of database and table names. Its effect for a given value should be as described in
Section 11.2.3, “Identifier Case Sensitivity”.

• If you often get corrupted tables, you should try to find out when and why this happens. In this case,
the error log in the MySQL data directory may contain some information about what happened. (This
is the file with the .err suffix in the name.) See Section 7.4.2, “The Error Log”. Please include any
relevant information from this file in your bug report. Normally mysqld should never corrupt a table if
nothing killed it in the middle of an update. If you can find the cause of mysqld dying, it is much easier

98
 MySQL Standards Compliance

for us to provide you with a fix for the problem. See Section B.3.1, “How to Determine What Is Causing a
Problem”.

• If possible, download and install the most recent version of MySQL Server and check whether it solves
your problem. All versions of the MySQL software are thoroughly tested and should work without
problems. We believe in making everything as backward-compatible as possible, and you should be able
to switch MySQL versions without difficulty. See Section 2.1.2, “Which MySQL Version and Distribution
to Install”.

1.6 MySQL Standards Compliance

This section describes how MySQL relates to the ANSI/ISO SQL standards. MySQL Server has many
extensions to the SQL standard, and here you can find out what they are and how to use them. You can
also find information about functionality missing from MySQL Server, and how to work around some of the
differences.

The SQL standard has been evolving since 1986 and several versions exist. In this manual, “SQL-92”
refers to the standard released in 1992. “SQL:1999”, “SQL:2003”, “SQL:2008”, and “SQL:2011” refer to the
versions of the standard released in the corresponding years, with the last being the most recent version.
We use the phrase “the SQL standard” or “standard SQL” to mean the current version of the SQL Standard
at any time.

One of our main goals with the product is to continue to work toward compliance with the SQL standard,
but without sacrificing speed or reliability. We are not afraid to add extensions to SQL or support for non-
SQL features if this greatly increases the usability of MySQL Server for a large segment of our user base.
The HANDLER interface is an example of this strategy. See Section 15.2.5, “HANDLER Statement”.

We continue to support transactional and nontransactional databases to satisfy both mission-critical 24/7
usage and heavy Web or logging usage.

MySQL Server was originally designed to work with medium-sized databases (10-100 million rows,
or about 100MB per table) on small computer systems. Today MySQL Server handles terabyte-sized
databases.

We are not targeting real-time support, although MySQL replication capabilities offer significant
functionality.

MySQL supports ODBC levels 0 to 3.51.

MySQL supports high-availability database clustering using the NDBCLUSTER storage engine. See
Chapter 25, MySQL NDB Cluster 8.0.

We implement XML functionality which supports most of the W3C XPath standard. See Section 14.11,
“XML Functions”.

MySQL supports a native JSON data type as defined by RFC 7159, and based on the ECMAScript
standard (ECMA-262). See Section 13.5, “The JSON Data Type”. MySQL also implements a subset of the
SQL/JSON functions specified by a pre-publication draft of the SQL:2016 standard; see Section 14.17,
“JSON Functions”, for more information.

Selecting SQL Modes

The MySQL server can operate in different SQL modes, and can apply these modes differently for different
clients, depending on the value of the sql_mode system variable. DBAs can set the global SQL mode to

99
 Running MySQL in ANSI Mode

match site server operating requirements, and each application can set its session SQL mode to its own
requirements.

Modes affect the SQL syntax MySQL supports and the data validation checks it performs. This makes it
easier to use MySQL in different environments and to use MySQL together with other database servers.

For more information on setting the SQL mode, see Section 7.1.11, “Server SQL Modes”.

Running MySQL in ANSI Mode

To run MySQL Server in ANSI mode, start mysqld with the --ansi option. Running the server in ANSI
mode is the same as starting it with the following options:
--transaction-isolation=SERIALIZABLE --sql-mode=ANSI

To achieve the same effect at runtime, execute these two statements:

SET GLOBAL TRANSACTION ISOLATION LEVEL SERIALIZABLE;
SET GLOBAL sql_mode = 'ANSI';

You can see that setting the sql_mode system variable to 'ANSI' enables all SQL mode options that are
relevant for ANSI mode as follows:
mysql> SET GLOBAL sql_mode='ANSI';
mysql> SELECT @@GLOBAL.sql_mode;
-> 'REAL_AS_FLOAT,PIPES_AS_CONCAT,ANSI_QUOTES,IGNORE_SPACE,ANSI'

Running the server in ANSI mode with --ansi is not quite the same as setting the SQL mode to 'ANSI'
because the --ansi option also sets the transaction isolation level.

See Section 7.1.7, “Server Command Options”.

1.6.1 MySQL Extensions to Standard SQL

MySQL Server supports some extensions that you are not likely to find in other SQL DBMSs. Be warned
that if you use them, your code is most likely not portable to other SQL servers. In some cases, you can
write code that includes MySQL extensions, but is still portable, by using comments of the following form:
/*! MySQL-specific code */

In this case, MySQL Server parses and executes the code within the comment as it would any other SQL
statement, but other SQL servers should ignore the extensions. For example, MySQL Server recognizes
the STRAIGHT_JOIN keyword in the following statement, but other servers should not:
SELECT /*! STRAIGHT_JOIN */ col1 FROM table1,table2 WHERE ...

If you add a version number after the ! character, the syntax within the comment is executed only if the
MySQL version is greater than or equal to the specified version number. The KEY_BLOCK_SIZE clause in
the following comment is executed only by servers from MySQL 5.1.10 or higher:
CREATE TABLE t1(a INT, KEY (a)) /*!50110 KEY_BLOCK_SIZE=1024 */;

The following descriptions list MySQL extensions, organized by category.

• Organization of data on disk

MySQL Server maps each database to a directory under the MySQL data directory, and maps tables
within a database to file names in the database directory. Consequently, database and table names are

100
 MySQL Extensions to Standard SQL

case-sensitive in MySQL Server on operating systems that have case-sensitive file names (such as most
Unix systems). See Section 11.2.3, “Identifier Case Sensitivity”.

• General language syntax

• By default, strings can be enclosed by " as well as '. If the ANSI_QUOTES SQL mode is enabled,
strings can be enclosed only by ' and the server interprets strings enclosed by " as identifiers.

• \ is the escape character in strings.

• In SQL statements, you can access tables from different databases with the db_name.tbl_name
syntax. Some SQL servers provide the same functionality but call this User space. MySQL
Server doesn't support tablespaces such as used in statements like this: CREATE TABLE
ralph.my_table ... IN my_tablespace.

• SQL statement syntax

• The ANALYZE TABLE, CHECK TABLE, OPTIMIZE TABLE, and REPAIR TABLE statements.

• The CREATE DATABASE, DROP DATABASE, and ALTER DATABASE statements. See Section 15.1.12,
“CREATE DATABASE Statement”, Section 15.1.24, “DROP DATABASE Statement”, and
Section 15.1.2, “ALTER DATABASE Statement”.

• The DO statement.

• EXPLAIN SELECT to obtain a description of how tables are processed by the query optimizer.

• The FLUSH and RESET statements.

• The SET statement. See Section 15.7.6.1, “SET Syntax for Variable Assignment”.

• The SHOW statement. See Section 15.7.7, “SHOW Statements”. The information produced by many of
the MySQL-specific SHOW statements can be obtained in more standard fashion by using SELECT to
query INFORMATION_SCHEMA. See Chapter 28, INFORMATION_SCHEMA Tables.

• Use of LOAD DATA. In many cases, this syntax is compatible with Oracle LOAD DATA. See
Section 15.2.9, “LOAD DATA Statement”.

• Use of RENAME TABLE. See Section 15.1.36, “RENAME TABLE Statement”.

• Use of REPLACE instead of DELETE plus INSERT. See Section 15.2.12, “REPLACE Statement”.

• Use of CHANGE col_name, DROP col_name, or DROP INDEX, IGNORE or RENAME in ALTER TABLE
statements. Use of multiple ADD, ALTER, DROP, or CHANGE clauses in an ALTER TABLE statement.
See Section 15.1.9, “ALTER TABLE Statement”.

• Use of index names, indexes on a prefix of a column, and use of INDEX or KEY in CREATE TABLE
statements. See Section 15.1.20, “CREATE TABLE Statement”.
• Use of TEMPORARY or IF NOT EXISTS with CREATE TABLE.

• Use of IF EXISTS with DROP TABLE and DROP DATABASE.

• The capability of dropping multiple tables with a single DROP TABLE statement.

• The ORDER BY and LIMIT clauses of the UPDATE and DELETE statements.

• INSERT INTO tbl_name SET col_name = ... syntax.

101
 MySQL Extensions to Standard SQL

• The DELAYED clause of the INSERT and REPLACE statements.

• The LOW_PRIORITY clause of the INSERT, REPLACE, DELETE, and UPDATE statements.

• Use of INTO OUTFILE or INTO DUMPFILE in SELECT statements. See Section 15.2.13, “SELECT
Statement”.

• Options such as STRAIGHT_JOIN or SQL_SMALL_RESULT in SELECT statements.

• You don't need to name all selected columns in the GROUP BY clause. This gives better performance
for some very specific, but quite normal queries. See Section 14.19, “Aggregate Functions”.

• You can specify ASC and DESC with GROUP BY, not just with ORDER BY.

• The ability to set variables in a statement with the := assignment operator. See Section 11.4, “User-
Defined Variables”.

• Data types

• The MEDIUMINT, SET, and ENUM data types, and the various BLOB and TEXT data types.

• The AUTO_INCREMENT, BINARY, NULL, UNSIGNED, and ZEROFILL data type attributes.

• Functions and operators

• To make it easier for users who migrate from other SQL environments, MySQL Server supports
aliases for many functions. For example, all string functions support both standard SQL syntax and
ODBC syntax.

• MySQL Server understands the || and && operators to mean logical OR and AND, as in the
C programming language. In MySQL Server, || and OR are synonyms, as are && and AND.
Because of this nice syntax, MySQL Server doesn't support the standard SQL || operator for string
concatenation; use CONCAT() instead. Because CONCAT() takes any number of arguments, it is easy
to convert use of the || operator to MySQL Server.

• Use of COUNT(DISTINCT value_list) where value_list has more than one element.

• String comparisons are case-insensitive by default, with sort ordering determined by the collation
of the current character set, which is utf8mb4 by default. To perform case-sensitive comparisons
instead, you should declare your columns with the BINARY attribute or use the BINARY cast, which
causes comparisons to be done using the underlying character code values rather than a lexical
ordering.

• The % operator is a synonym for MOD(). That is, N % M is equivalent to MOD(N,M). % is supported
for C programmers and for compatibility with PostgreSQL.

• The =, <>, <=, <, >=, >, <<, >>, <=>, AND, OR, or LIKE operators may be used in expressions in the
output column list (to the left of the FROM) in SELECT statements. For example:
mysql> SELECT col1=1 AND col2=2 FROM my_table;

• The LAST_INSERT_ID() function returns the most recent AUTO_INCREMENT value. See
Section 14.15, “Information Functions”.

• LIKE is permitted on numeric values.

• The REGEXP and NOT REGEXP extended regular expression operators.

102
 MySQL Differences from Standard SQL

• CONCAT() or CHAR() with one argument or more than two arguments. (In MySQL Server, these
functions can take a variable number of arguments.)

• The BIT_COUNT(), CASE, ELT(), FROM_DAYS(), FORMAT(), IF(), MD5(), PERIOD_ADD(),

PERIOD_DIFF(), TO_DAYS(), and WEEKDAY() functions.

• Use of TRIM() to trim substrings. Standard SQL supports removal of single characters only.

• The GROUP BY functions STD(), BIT_OR(), BIT_AND(), BIT_XOR(), and GROUP_CONCAT(). See
Section 14.19, “Aggregate Functions”.

1.6.2 MySQL Differences from Standard SQL

We try to make MySQL Server follow the ANSI SQL standard and the ODBC SQL standard, but MySQL
Server performs operations differently in some cases:

• There are several differences between the MySQL and standard SQL privilege systems. For example, in
MySQL, privileges for a table are not automatically revoked when you delete a table. You must explicitly
issue a REVOKE statement to revoke privileges for a table. For more information, see Section 15.7.1.8,
“REVOKE Statement”.

• The CAST() function does not support cast to REAL or BIGINT. See Section 14.10, “Cast Functions and
Operators”.

1.6.2.1 SELECT INTO TABLE Differences

MySQL Server doesn't support the SELECT ... INTO TABLE Sybase SQL extension. Instead, MySQL
Server supports the INSERT INTO ... SELECT standard SQL syntax, which is basically the same thing.
See Section 15.2.7.1, “INSERT ... SELECT Statement”. For example:
INSERT INTO tbl_temp2 (fld_id)
SELECT tbl_temp1.fld_order_id
FROM tbl_temp1 WHERE tbl_temp1.fld_order_id > 100;

Alternatively, you can use SELECT ... INTO OUTFILE or CREATE TABLE ... SELECT.

You can use SELECT ... INTO with user-defined variables. The same syntax can also be used inside
stored routines using cursors and local variables. See Section 15.2.13.1, “SELECT ... INTO Statement”.

1.6.2.2 UPDATE Differences

If you access a column from the table to be updated in an expression, UPDATE uses the current value of
the column. The second assignment in the following statement sets col2 to the current (updated) col1
value, not the original col1 value. The result is that col1 and col2 have the same value. This behavior
differs from standard SQL.
UPDATE t1 SET col1 = col1 + 1, col2 = col1;

1.6.2.3 FOREIGN KEY Constraint Differences

The MySQL implementation of foreign key constraints differs from the SQL standard in the following key
respects:

• If there are several rows in the parent table with the same referenced key value, InnoDB performs a
foreign key check as if the other parent rows with the same key value do not exist. For example, if you

103
 MySQL Differences from Standard SQL

define a RESTRICT type constraint, and there is a child row with several parent rows, InnoDB does not
permit the deletion of any of the parent rows.

• If ON UPDATE CASCADE or ON UPDATE SET NULL recurses to update the same table it has previously
updated during the same cascade, it acts like RESTRICT. This means that you cannot use self-
referential ON UPDATE CASCADE or ON UPDATE SET NULL operations. This is to prevent infinite
loops resulting from cascaded updates. A self-referential ON DELETE SET NULL, on the other hand, is
possible, as is a self-referential ON DELETE CASCADE. Cascading operations may not be nested more
than 15 levels deep.

• In an SQL statement that inserts, deletes, or updates many rows, foreign key constraints (like unique
constraints) are checked row-by-row. When performing foreign key checks, InnoDB sets shared row-
level locks on child or parent records that it must examine. MySQL checks foreign key constraints
immediately; the check is not deferred to transaction commit. According to the SQL standard, the
default behavior should be deferred checking. That is, constraints are only checked after the entire SQL
statement has been processed. This means that it is not possible to delete a row that refers to itself
using a foreign key.

• No storage engine, including InnoDB, recognizes or enforces the MATCH clause used in referential-
integrity constraint definitions. Use of an explicit MATCH clause does not have the specified effect, and it
causes ON DELETE and ON UPDATE clauses to be ignored. Specifying the MATCH should be avoided.

The MATCH clause in the SQL standard controls how NULL values in a composite (multiple-column)
foreign key are handled when comparing to a primary key in the referenced table. MySQL essentially
implements the semantics defined by MATCH SIMPLE, which permits a foreign key to be all or partially
NULL. In that case, a (child table) row containing such a foreign key can be inserted even though it does
not match any row in the referenced (parent) table. (It is possible to implement other semantics using
triggers.)

• MySQL requires that the referenced columns be indexed for performance reasons. However, MySQL
does not enforce a requirement that the referenced columns be UNIQUE or be declared NOT NULL.

A FOREIGN KEY constraint that references a non-UNIQUE key is not standard SQL but rather an
InnoDB extension. The NDB storage engine, on the other hand, requires an explicit unique key (or
primary key) on any column referenced as a foreign key.

The handling of foreign key references to nonunique keys or keys that contain NULL values is not well
defined for operations such as UPDATE or DELETE CASCADE. You are advised to use foreign keys that
reference only UNIQUE (including PRIMARY) and NOT NULL keys.

• For storage engines that do not support foreign keys (such as MyISAM), MySQL Server parses and
ignores foreign key specifications.

• MySQL parses but ignores “inline REFERENCES specifications” (as defined in the SQL standard) where
the references are defined as part of the column specification. MySQL accepts REFERENCES clauses
only when specified as part of a separate FOREIGN KEY specification.

Defining a column to use a REFERENCES tbl_name(col_name) clause has no actual effect and
serves only as a memo or comment to you that the column which you are currently defining is intended
to refer to a column in another table. It is important to realize when using this syntax that:

• MySQL does not perform any sort of check to make sure that col_name actually exists in tbl_name
(or even that tbl_name itself exists).

• MySQL does not perform any sort of action on tbl_name such as deleting rows in response to
actions taken on rows in the table which you are defining; in other words, this syntax induces no ON

104
 MySQL Differences from Standard SQL

DELETE or ON UPDATE behavior whatsoever. (Although you can write an ON DELETE or ON UPDATE
clause as part of the REFERENCES clause, it is also ignored.)

• This syntax creates a column; it does not create any sort of index or key.

You can use a column so created as a join column, as shown here:

CREATE TABLE person (

id SMALLINT UNSIGNED NOT NULL AUTO_INCREMENT,
name CHAR(60) NOT NULL,
PRIMARY KEY (id)
);

CREATE TABLE shirt (

id SMALLINT UNSIGNED NOT NULL AUTO_INCREMENT,
style ENUM('t-shirt', 'polo', 'dress') NOT NULL,
color ENUM('red', 'blue', 'orange', 'white', 'black') NOT NULL,
owner SMALLINT UNSIGNED NOT NULL REFERENCES person(id),
PRIMARY KEY (id)
);

INSERT INTO person VALUES (NULL, 'Antonio Paz');

SELECT @last := LAST_INSERT_ID();

INSERT INTO shirt VALUES

(NULL, 'polo', 'blue', @last),
(NULL, 'dress', 'white', @last),
(NULL, 't-shirt', 'blue', @last);

INSERT INTO person VALUES (NULL, 'Lilliana Angelovska');

SELECT @last := LAST_INSERT_ID();

INSERT INTO shirt VALUES

(NULL, 'dress', 'orange', @last),
(NULL, 'polo', 'red', @last),
(NULL, 'dress', 'blue', @last),
(NULL, 't-shirt', 'white', @last);

SELECT * FROM person;

+----+---------------------+
| id | name |
+----+---------------------+
| 1 | Antonio Paz |
| 2 | Lilliana Angelovska |
+----+---------------------+

SELECT * FROM shirt;

+----+---------+--------+-------+
| id | style | color | owner |
+----+---------+--------+-------+
| 1 | polo | blue | 1 |
| 2 | dress | white | 1 |
| 3 | t-shirt | blue | 1 |
| 4 | dress | orange | 2 |
| 5 | polo | red | 2 |
| 6 | dress | blue | 2 |
| 7 | t-shirt | white | 2 |
+----+---------+--------+-------+

SELECT s.* FROM person p INNER JOIN shirt s

ON s.owner = p.id
WHERE p.name LIKE 'Lilliana%'
AND s.color <> 'white';

105
 How MySQL Deals with Constraints

+----+-------+--------+-------+
| id | style | color | owner |
+----+-------+--------+-------+
| 4 | dress | orange | 2 |
| 5 | polo | red | 2 |
| 6 | dress | blue | 2 |
+----+-------+--------+-------+

When used in this fashion, the REFERENCES clause is not displayed in the output of SHOW CREATE
TABLE or DESCRIBE:
SHOW CREATE TABLE shirt\G
*************************** 1. row ***************************
Table: shirt
Create Table: CREATE TABLE `shirt` (
`id` smallint(5) unsigned NOT NULL auto_increment,
`style` enum('t-shirt','polo','dress') NOT NULL,
`color` enum('red','blue','orange','white','black') NOT NULL,
`owner` smallint(5) unsigned NOT NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci

For information about foreign key constraints, see Section 15.1.20.5, “FOREIGN KEY Constraints”.

1.6.2.4 '--' as the Start of a Comment

Standard SQL uses the C syntax /* this is a comment */ for comments, and MySQL Server
supports this syntax as well. MySQL also support extensions to this syntax that enable MySQL-specific
SQL to be embedded in the comment; see Section 11.7, “Comments”.

MySQL Server also uses # as the start comment character. This is nonstandard.

Standard SQL also uses “--” as a start-comment sequence. MySQL Server supports a variant of the --
comment style; the -- start-comment sequence is accepted as such, but must be followed by a whitespace
character such as a space or newline. The space is intended to prevent problems with generated SQL
queries that use constructs such as the following, which updates the balance to reflect a charge:
UPDATE account SET balance=balance-charge
WHERE account_id=user_id

Consider what happens when charge has a negative value such as -1, which might be the case when an
amount is credited to the account. In this case, the generated statement looks like this:
UPDATE account SET balance=balance--1
WHERE account_id=5752;

balance--1 is valid standard SQL, but -- is interpreted as the start of a comment, and part of the
expression is discarded. The result is a statement that has a completely different meaning than intended:
UPDATE account SET balance=balance
WHERE account_id=5752;

This statement produces no change in value at all. To keep this from happening, MySQL requires a
whitespace character following the -- for it to be recognized as a start-comment sequence in MySQL
Server, so that an expression such as balance--1 is always safe to use.

1.6.3 How MySQL Deals with Constraints

MySQL enables you to work both with transactional tables that permit rollback and with nontransactional
tables that do not. Because of this, constraint handling is a bit different in MySQL than in other DBMSs. We

106
 How MySQL Deals with Constraints

must handle the case when you have inserted or updated a lot of rows in a nontransactional table for which
changes cannot be rolled back when an error occurs.

The basic philosophy is that MySQL Server tries to produce an error for anything that it can detect while
parsing a statement to be executed, and tries to recover from any errors that occur while executing the
statement. We do this in most cases, but not yet for all.

The options MySQL has when an error occurs are to stop the statement in the middle or to recover as well
as possible from the problem and continue. By default, the server follows the latter course. This means, for
example, that the server may coerce invalid values to the closest valid values.

Several SQL mode options are available to provide greater control over handling of bad data values
and whether to continue statement execution or abort when errors occur. Using these options, you can
configure MySQL Server to act in a more traditional fashion that is like other DBMSs that reject improper
input. The SQL mode can be set globally at server startup to affect all clients. Individual clients can
set the SQL mode at runtime, which enables each client to select the behavior most appropriate for its
requirements. See Section 7.1.11, “Server SQL Modes”.

The following sections describe how MySQL Server handles different types of constraints.

1.6.3.1 PRIMARY KEY and UNIQUE Index Constraints

Normally, errors occur for data-change statements (such as INSERT or UPDATE) that would violate
primary-key, unique-key, or foreign-key constraints. If you are using a transactional storage engine such
as InnoDB, MySQL automatically rolls back the statement. If you are using a nontransactional storage
engine, MySQL stops processing the statement at the row for which the error occurred and leaves any
remaining rows unprocessed.

MySQL supports an IGNORE keyword for INSERT, UPDATE, and so forth. If you use it, MySQL ignores
primary-key or unique-key violations and continues processing with the next row. See the section for the
statement that you are using (Section 15.2.7, “INSERT Statement”, Section 15.2.17, “UPDATE Statement”,
and so forth).

You can get information about the number of rows actually inserted or updated with the mysql_info() C
API function. You can also use the SHOW WARNINGS statement. See mysql_info(), and Section 15.7.7.42,
“SHOW WARNINGS Statement”.

InnoDB and NDB tables support foreign keys. See Section 1.6.3.2, “FOREIGN KEY Constraints”.

1.6.3.2 FOREIGN KEY Constraints

Foreign keys let you cross-reference related data across tables, and foreign key constraints help keep this
spread-out data consistent.

MySQL supports ON UPDATE and ON DELETE foreign key references in CREATE TABLE and ALTER
TABLE statements. The available referential actions are RESTRICT, CASCADE, SET NULL, and NO
ACTION (the default).

SET DEFAULT is also supported by the MySQL Server but is currently rejected as invalid by InnoDB.
Since MySQL does not support deferred constraint checking, NO ACTION is treated as RESTRICT. For the
exact syntax supported by MySQL for foreign keys, see Section 15.1.20.5, “FOREIGN KEY Constraints”.

MATCH FULL, MATCH PARTIAL, and MATCH SIMPLE are allowed, but their use should be avoided,
as they cause the MySQL Server to ignore any ON DELETE or ON UPDATE clause used in the same
statement. MATCH options do not have any other effect in MySQL, which in effect enforces MATCH SIMPLE
semantics full-time.

107
 How MySQL Deals with Constraints

MySQL requires that foreign key columns be indexed; if you create a table with a foreign key constraint but
no index on a given column, an index is created.

You can obtain information about foreign keys from the Information Schema KEY_COLUMN_USAGE table.
An example of a query against this table is shown here:
mysql> SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, CONSTRAINT_NAME
> FROM INFORMATION_SCHEMA.KEY_COLUMN_USAGE
> WHERE REFERENCED_TABLE_SCHEMA IS NOT NULL;
+--------------+---------------+-------------+-----------------+
| TABLE_SCHEMA | TABLE_NAME | COLUMN_NAME | CONSTRAINT_NAME |
+--------------+---------------+-------------+-----------------+
| fk1 | myuser | myuser_id | f |
| fk1 | product_order | customer_id | f2 |
| fk1 | product_order | product_id | f1 |
+--------------+---------------+-------------+-----------------+
3 rows in set (0.01 sec)

Information about foreign keys on InnoDB tables can also be found in the INNODB_FOREIGN and
INNODB_FOREIGN_COLS tables, in the INFORMATION_SCHEMA database.

InnoDB and NDB tables support foreign keys.

1.6.3.3 Enforced Constraints on Invalid Data

By default, MySQL 8.0 rejects invalid or improper data values and aborts the statement in which they
occur. It is possible to alter this behavior to be more forgiving of invalid values, such that the server
coerces them to valid ones for data entry, by disabling strict SQL mode (see Section 7.1.11, “Server SQL
Modes”), but this is not recommended.

Older versions of MySQL employed the forgiving behavior by default; for a description of this behavior, see
Constraints on Invalid Data.

1.6.3.4 ENUM and SET Constraints

ENUM and SET columns provide an efficient way to define columns that can contain only a given set of
values. See Section 13.3.5, “The ENUM Type”, and Section 13.3.6, “The SET Type”.

Unless strict mode is disabled (not recommended, but see Section 7.1.11, “Server SQL Modes”), the
definition of a ENUM or SET column acts as a constraint on values entered into the column. An error occurs
for values that do not satisfy these conditions:

• An ENUM value must be one of those listed in the column definition, or the internal numeric equivalent
thereof. The value cannot be the error value (that is, 0 or the empty string). For a column defined as
ENUM('a','b','c'), values such as '', 'd', or 'ax' are invalid and are rejected.

• A SET value must be the empty string or a value consisting only of the values listed in the column
definition separated by commas. For a column defined as SET('a','b','c'), values such as 'd' or
'a,b,c,d' are invalid and are rejected.

Errors for invalid values can be suppressed in strict mode if you use INSERT IGNORE or UPDATE
IGNORE. In this case, a warning is generated rather than an error. For ENUM, the value is inserted as the
error member (0). For SET, the value is inserted as given except that any invalid substrings are deleted.
For example, 'a,x,b,y' results in a value of 'a,b'.

108
Chapter 2 Installing MySQL

Table of Contents
2.1 General Installation Guidance .................................................................................................... 111
2.1.1 Supported Platforms ....................................................................................................... 112
2.1.2 Which MySQL Version and Distribution to Install ............................................................. 112
2.1.3 How to Get MySQL ........................................................................................................ 113
2.1.4 Verifying Package Integrity Using MD5 Checksums or GnuPG ......................................... 113
2.1.5 Installation Layouts ........................................................................................................ 130
2.1.6 Compiler-Specific Build Characteristics ........................................................................... 130
2.2 Installing MySQL on Unix/Linux Using Generic Binaries .............................................................. 130
2.3 Installing MySQL on Microsoft Windows .................................................................................... 134
2.3.1 MySQL Installation Layout on Microsoft Windows ............................................................ 136
2.3.2 Choosing an Installation Package ................................................................................... 137
2.3.3 MySQL Installer for Windows ......................................................................................... 138
2.3.4 Installing MySQL on Microsoft Windows Using a noinstall ZIP Archive ......................... 170
2.3.5 Troubleshooting a Microsoft Windows MySQL Server Installation ...................................... 178
2.3.6 Windows Postinstallation Procedures .............................................................................. 179
2.3.7 Windows Platform Restrictions ........................................................................................ 181
2.4 Installing MySQL on macOS ..................................................................................................... 183
2.4.1 General Notes on Installing MySQL on macOS ............................................................... 183
2.4.2 Installing MySQL on macOS Using Native Packages ....................................................... 184
2.4.3 Installing and Using the MySQL Launch Daemon ............................................................ 191
2.4.4 Installing and Using the MySQL Preference Pane ............................................................ 194
2.5 Installing MySQL on Linux ........................................................................................................ 199
2.5.1 Installing MySQL on Linux Using the MySQL Yum Repository .......................................... 200
2.5.2 Installing MySQL on Linux Using the MySQL APT Repository .......................................... 205
2.5.3 Installing MySQL on Linux Using the MySQL SLES Repository ........................................ 205
2.5.4 Installing MySQL on Linux Using RPM Packages from Oracle .......................................... 205
2.5.5 Installing MySQL on Linux Using Debian Packages from Oracle ....................................... 210
2.5.6 Deploying MySQL on Linux with Docker Containers ......................................................... 212
2.5.7 Installing MySQL on Linux from the Native Software Repositories ..................................... 225
2.5.8 Installing MySQL on Linux with Juju ............................................................................... 227
2.5.9 Managing MySQL Server with systemd ........................................................................... 227
2.6 Installing MySQL Using Unbreakable Linux Network (ULN) ......................................................... 232
2.7 Installing MySQL on Solaris ...................................................................................................... 233
2.7.1 Installing MySQL on Solaris Using a Solaris PKG ............................................................ 234
2.8 Installing MySQL from Source ................................................................................................... 235
2.8.1 Source Installation Methods ............................................................................................ 235
2.8.2 Source Installation Prerequisites ..................................................................................... 236
2.8.3 MySQL Layout for Source Installation ............................................................................. 238
2.8.4 Installing MySQL Using a Standard Source Distribution ................................................... 238
2.8.5 Installing MySQL Using a Development Source Tree ....................................................... 242
2.8.6 Configuring SSL Library Support ..................................................................................... 244
2.8.7 MySQL Source-Configuration Options ............................................................................. 245
2.8.8 Dealing with Problems Compiling MySQL ....................................................................... 278
2.8.9 MySQL Configuration and Third-Party Tools .................................................................... 280
2.8.10 Generating MySQL Doxygen Documentation Content .................................................... 280
2.9 Postinstallation Setup and Testing ............................................................................................. 281
2.9.1 Initializing the Data Directory .......................................................................................... 282

109
 2.9.2 Starting the Server ......................................................................................................... 287
2.9.3 Testing the Server ......................................................................................................... 290
2.9.4 Securing the Initial MySQL Account ................................................................................ 292
2.9.5 Starting and Stopping MySQL Automatically .................................................................... 294
2.10 Perl Installation Notes ............................................................................................................. 295
2.10.1 Installing Perl on Unix .................................................................................................. 295
2.10.2 Installing ActiveState Perl on Windows .......................................................................... 296
2.10.3 Problems Using the Perl DBI/DBD Interface .................................................................. 297

This chapter describes how to obtain and install MySQL. A summary of the procedure follows and later
sections provide the details. If you plan to upgrade an existing version of MySQL to a newer version rather
than install MySQL for the first time, see Chapter 3, Upgrading MySQL, for information about upgrade
procedures and about issues that you should consider before upgrading.

If you are interested in migrating to MySQL from another database system, see Section A.8, “MySQL 8.0
FAQ: Migration”, which contains answers to some common questions concerning migration issues.

Installation of MySQL generally follows the steps outlined here:

1. Determine whether MySQL runs and is supported on your platform.

Please note that not all platforms are equally suitable for running MySQL, and that not all platforms
on which MySQL is known to run are officially supported by Oracle Corporation. For information about
those platforms that are officially supported, see https://www.mysql.com/support/supportedplatforms/
database.html on the MySQL website.

2. Choose which distribution to install.

Several versions of MySQL are available, and most are available in several distribution formats. You
can choose from pre-packaged distributions containing binary (precompiled) programs or source code.
When in doubt, use a binary distribution. Oracle also provides access to the MySQL source code for
those who want to see recent developments and test new code. To determine which version and type
of distribution you should use, see Section 2.1.2, “Which MySQL Version and Distribution to Install”.

3. Choose which track to install.

MySQL offers a bugfix track (such as MySQL 8.0), and an innovation track (today it's MySQL 8.3) and
each track addresses different use cases. Both tracks are considered production-ready and include bug
fixes, while innovation releases also include new features and potential for modified behavior.

A bugfix track upgrade includes point releases, such as MySQL 8.0.x upgrading to 8.0.y, while
innovation track releases typically only have minor releases, such as MySQL 8.3.0 upgrading to 9.0.0.
However, an innovation track does have the occasional point release.

4. Download the distribution that you want to install.

For instructions, see Section 2.1.3, “How to Get MySQL”. To verify the integrity of the distribution, use
the instructions in Section 2.1.4, “Verifying Package Integrity Using MD5 Checksums or GnuPG”.

5. Install the distribution.

To install MySQL from a binary distribution, use the instructions in Section 2.2, “Installing MySQL on
Unix/Linux Using Generic Binaries”. Alternatively, use the Secure Deployment Guide, which provides
procedures for deploying a generic binary distribution of MySQL Enterprise Edition Server with features
for managing the security of your MySQL installation.

110
 General Installation Guidance

To install MySQL from a source distribution or from the current development source tree, use the
instructions in Section 2.8, “Installing MySQL from Source”.

6. Perform any necessary postinstallation setup.

After installing MySQL, see Section 2.9, “Postinstallation Setup and Testing” for information about
making sure the MySQL server is working properly. Also refer to the information provided in
Section 2.9.4, “Securing the Initial MySQL Account”. This section describes how to secure the initial
MySQL root user account, which has no password until you assign one. The section applies whether
you install MySQL using a binary or source distribution.

7. If you want to run the MySQL benchmark scripts, Perl support for MySQL must be available. See
Section 2.10, “Perl Installation Notes”.

Instructions for installing MySQL on different platforms and environments is available on a platform by
platform basis:

• Unix, Linux

For instructions on installing MySQL on most Linux and Unix platforms using a generic binary (for
example, a .tar.gz package), see Section 2.2, “Installing MySQL on Unix/Linux Using Generic
Binaries”.

For information on building MySQL entirely from the source code distributions or the source code
repositories, see Section 2.8, “Installing MySQL from Source”

For specific platform help on installation, configuration, and building from source see the corresponding
platform section:

• Linux, including notes on distribution specific methods, see Section 2.5, “Installing MySQL on Linux”.

• IBM AIX, see Section 2.7, “Installing MySQL on Solaris”.

• Microsoft Windows

For instructions on installing MySQL on Microsoft Windows, using either the MySQL Installer or Zipped
binary, see Section 2.3, “Installing MySQL on Microsoft Windows”.

For details and instructions on building MySQL from source code using Microsoft Visual Studio, see
Section 2.8, “Installing MySQL from Source”.

• macOS

For installation on macOS, including using both the binary package and native PKG formats, see
Section 2.4, “Installing MySQL on macOS”.

For information on making use of an macOS Launch Daemon to automatically start and stop MySQL,
see Section 2.4.3, “Installing and Using the MySQL Launch Daemon”.

For information on the MySQL Preference Pane, see Section 2.4.4, “Installing and Using the MySQL
Preference Pane”.

2.1 General Installation Guidance

The immediately following sections contain the information necessary to choose, download, and verify your
distribution. The instructions in later sections of the chapter describe how to install the distribution that you

111
 Supported Platforms

choose. For binary distributions, see the instructions at Section 2.2, “Installing MySQL on Unix/Linux Using
Generic Binaries” or the corresponding section for your platform if available. To build MySQL from source,
use the instructions in Section 2.8, “Installing MySQL from Source”.

2.1.1 Supported Platforms

MySQL platform support evolves over time; please refer to https://www.mysql.com/support/
supportedplatforms/database.html for the latest updates.

2.1.2 Which MySQL Version and Distribution to Install

When preparing to install MySQL, decide which version and distribution format (binary or source) to use.

First, decide whether to install from a bugfix series like MySQL 8.0, or use an innovation release like
MySQL 8.3. Both tracks include bug fixes while an innovation release includes the newest features. Both
bugfix and innovation releases are meant for production use.

The naming scheme in MySQL 8.0 uses release names that consist of three numbers and an optional
suffix (for example, mysql-8.0.34). The numbers within the release name are interpreted as follows:

• The first number (8) is the major version number.

• The second number (0) is the minor version number. Taken together, the major and minor numbers
constitute the release series number. The series number describes the stable feature set.

• The third number (34) is the version number within the release series. This is incremented for each new
bugfix release; for an innovation release, it will likely always be 0. For a bugfix series such as MySQL
8.0, the most recent version within the series is the best choice.

After choosing which MySQL version to install, decide which distribution format to install for your operating
system. For most use cases, a binary distribution is the right choice. Binary distributions are available
in native format for many platforms, such as RPM packages for Linux or DMG packages for macOS.
Distributions are also available in more generic formats such as Zip archives or compressed tar files. On
Windows, you can use the MySQL Installer to install a binary distribution.

Under some circumstances, it may be preferable to install MySQL from a source distribution:

• You want to install MySQL at some explicit location. The standard binary distributions are ready to run at
any installation location, but you might require even more flexibility to place MySQL components where
you want.

• You want to configure mysqld with features that might not be included in the standard binary
distributions. Here is a list of the most common extra options used to ensure feature availability:

• -DWITH_LIBWRAP=1 for TCP wrappers support.

• -DWITH_ZLIB={system|bundled} for features that depend on compression

• -DWITH_DEBUG=1 for debugging support

For additional information, see Section 2.8.7, “MySQL Source-Configuration Options”.

• You want to configure mysqld without some features that are included in the standard binary
distributions.

• You want to read or modify the C and C++ code that makes up MySQL. For this purpose, obtain a
source distribution.

112
 How to Get MySQL

• Source distributions contain more tests and examples than binary distributions.

2.1.3 How to Get MySQL

Check our downloads page at https://dev.mysql.com/downloads/ for information about the current version
of MySQL and for downloading instructions.

For RPM-based Linux platforms that use Yum as their package management system, MySQL can be
installed using the MySQL Yum Repository. See Section 2.5.1, “Installing MySQL on Linux Using the
MySQL Yum Repository” for details.

For Debian-based Linux platforms, MySQL can be installed using the MySQL APT Repository. See
Section 2.5.2, “Installing MySQL on Linux Using the MySQL APT Repository” for details.

For SUSE Linux Enterprise Server (SLES) platforms, MySQL can be installed using the MySQL SLES
Repository. See Section 2.5.3, “Installing MySQL on Linux Using the MySQL SLES Repository” for details.

To obtain the latest development source, see Section 2.8.5, “Installing MySQL Using a Development
Source Tree”.

2.1.4 Verifying Package Integrity Using MD5 Checksums or GnuPG

After downloading the MySQL package that suits your needs and before attempting to install it, make sure
that it is intact and has not been tampered with. There are three means of integrity checking:

• MD5 checksums

• Cryptographic signatures using GnuPG, the GNU Privacy Guard

• For RPM packages, the built-in RPM integrity verification mechanism

The following sections describe how to use these methods.

If you notice that the MD5 checksum or GPG signatures do not match, first try to download the respective
package one more time, perhaps from another mirror site.

2.1.4.1 Verifying the MD5 Checksum

After you have downloaded a MySQL package, you should make sure that its MD5 checksum matches
the one provided on the MySQL download pages. Each package has an individual checksum that you can
verify against the package that you downloaded. The correct MD5 checksum is listed on the downloads
page for each MySQL product; you should compare it against the MD5 checksum of the file (product) that
you download.

Each operating system and setup offers its own version of tools for checking the MD5 checksum. Typically
the command is named md5sum, or it may be named md5, and some operating systems do not ship it at
all. On Linux, it is part of the GNU Text Utilities package, which is available for a wide range of platforms.
You can also download the source code from http://www.gnu.org/software/textutils/. If you have OpenSSL
installed, you can use the command openssl md5 package_name instead. A Windows implementation
of the md5 command line utility is available from http://www.fourmilab.ch/md5/. winMd5Sum is a graphical
MD5 checking tool that can be obtained from http://www.nullriver.com/index/products/winmd5sum. Our
Microsoft Windows examples assume the name md5.exe.

Linux and Microsoft Windows examples:

113
 Verifying Package Integrity Using MD5 Checksums or GnuPG

$> md5sum mysql-standard-8.0.36-linux-i686.tar.gz

aaab65abbec64d5e907dcd41b8699945 mysql-standard-8.0.36-linux-i686.tar.gz

$> md5.exe mysql-installer-community-8.0.36.msi

aaab65abbec64d5e907dcd41b8699945 mysql-installer-community-8.0.36.msi

You should verify that the resulting checksum (the string of hexadecimal digits) matches the one displayed
on the download page immediately below the respective package.

Note

Make sure to verify the checksum of the archive file (for example, the .zip,
.tar.gz, or .msi file) and not of the files that are contained inside of the archive.
In other words, verify the file before extracting its contents.

2.1.4.2 Signature Checking Using GnuPG

Another method of verifying the integrity and authenticity of a package is to use cryptographic signatures.
This is more reliable than using MD5 checksums, but requires more work.

We sign MySQL downloadable packages with GnuPG (GNU Privacy Guard). GnuPG is an Open Source
alternative to the well-known Pretty Good Privacy (PGP) by Phil Zimmermann. Most Linux distributions ship
with GnuPG installed by default. Otherwise, see http://www.gnupg.org/ for more information about GnuPG
and how to obtain and install it.

To verify the signature for a specific package, you first need to obtain a copy of our public GPG build
key, which you can download from http://pgp.mit.edu/. The key that you want to obtain is named mysql-
[email protected]. The keyID for MySQL 8.0.28 to 8.0.35 packages is 3A79BD29. After obtaining
this key, you should compare it with the key shown following, before using it verify MySQL packages.
Alternatively, you can copy and paste the key directly from the text below.

Important

The 3A79BD29 key expires on 2023-12-14. A new replacement key (A8D3785C)

will sign upcoming MySQL 8.0.36 and higher packages. Both keys are installed by
the MySQL repository setup packages released with MySQL 8.0.35, and both keys
are also available at https://repo.mysql.com/.

Note

The following public GPG build key is for MySQL 8.0.28 to 8.0.35 packages. For the
public GPG build key for earlier MySQL release packages (keyID 5072E1F5), see
Section 2.1.4.5, “GPG Public Build Key for Archived Packages”.

-----BEGIN PGP PUBLIC KEY BLOCK-----

Version: SKS 1.1.6
Comment: Hostname: pgp.mit.edu

mQINBGG4urcBEACrbsRa7tSSyxSfFkB+KXSbNM9rxYqoB78u107skReefq4/+Y72TpDvlDZL
mdv/lK0IpLa3bnvsM9IE1trNLrfi+JES62kaQ6hePPgn2RqxyIirt2seSi3Z3n3jlEg+mSdh
AvW+b+hFnqxo+TY0U+RBwDi4oO0YzHefkYPSmNPdlxRPQBMv4GPTNfxERx6XvVSPcL1+jQ4R
2cQFBryNhidBFIkoCOszjWhm+WnbURsLheBp757lqEyrpCufz77zlq2gEi+wtPHItfqsx3rz
xSRqatztMGYZpNUHNBJkr13npZtGW+kdN/xu980QLZxN+bZ88pNoOuzD6dKcpMJ0LkdUmTx5
z9ewiFiFbUDzZ7PECOm2g3veJrwr79CXDLE1+39Hr8rDM2kDhSr9tAlPTnHVDcaYIGgSNIBc
YfLmt91133klHQHBIdWCNVtWJjq5YcLQJ9TxG9GQzgABPrm6NDd1t9j7w1L7uwBvMB1wgpir
RTPVfnUSCd+025PEF+wTcBhfnzLtFj5xD7mNsmDmeHkF/sDfNOfAzTE1v2wq0ndYU60xbL6/
yl/Nipyr7WiQjCG0m3WfkjjVDTfs7/DXUqHFDOu4WMF9v+oqwpJXmAeGhQTWZC/QhWtrjrNJ
AgwKpp263gDSdW70ekhRzsok1HJwX1SfxHJYCMFs2aH6ppzNsQARAQABtDZNeVNRTCBSZWxl
YXNlIEVuZ2luZWVyaW5nIDxteXNxbC1idWlsZEBvc3Mub3JhY2xlLmNvbT6JAlQEEwEIAD4W

114
 Verifying Package Integrity Using MD5 Checksums or GnuPG

IQSFm+jXxYb1OEMLGcJGe5QtOnm9KQUCYbi6twIbAwUJA8JnAAULCQgHAgYVCgkICwIEFgID
AQIeAQIXgAAKCRBGe5QtOnm9KUewD/992sS31WLGoUQ6NoL7qOB4CErkqXtMzpJAKKg2jtBG
G3rKE1/0VAg1D8AwEK4LcCO407wohnH0hNiUbeDck5x20pgS5SplQpuXX1K9vPzHeL/WNTb9
8S3H2Mzj4o9obED6Ey52tTupttMF8pC9TJ93LxbJlCHIKKwCA1cXud3GycRN72eqSqZfJGds
aeWLmFmHf6oee27d8XLoNjbyAxna/4jdWoTqmp8oT3bgv/TBco23NzqUSVPi+7ljS1hHvcJu
oJYqaztGrAEf/lWIGdfl/kLEh8IYx8OBNUojh9mzCDlwbs83CBqoUdlzLNDdwmzu34Aw7xK1
4RAVinGFCpo/7EWoX6weyB/zqevUIIE89UABTeFoGih/hx2jdQV/NQNthWTW0jH0hmPnajBV
AJPYwAuO82rx2pnZCxDATMn0elOkTue3PCmzHBF/GT6c65aQC4aojj0+Veh787QllQ9FrWbw
nTz+4fNzU/MBZtyLZ4JnsiWUs9eJ2V1g/A+RiIKu357Qgy1ytLqlgYiWfzHFlYjdtbPYKjDa
ScnvtY8VO2Rktm7XiV4zKFKiaWp+vuVYpR0/7Adgnlj5Jt9lQQGOr+Z2VYx8SvBcC+by3XAt
YkRHtX5u4MLlVS3gcoWfDiWwCpvqdK21EsXjQJxRr3dbSn0HaVj4FJZX0QQ7WZm6WLkCDQRh
uLq3ARAA6RYjqfC0YcLGKvHhoBnsX29vy9Wn1y2JYpEnPUIB8X0VOyz5/ALv4Hqtl4THkH+m
mMuhtndoq2BkCCk508jWBvKS1S+Bd2esB45BDDmIhuX3ozu9Xza4i1FsPnLkQ0uMZJv30ls2
pXFmskhYyzmo6aOmH2536LdtPSlXtywfNV1HEr69V/AHbrEzfoQkJ/qvPzELBOjfjwtDPDeP
iVgW9LhktzVzn/BjO7XlJxw4PGcxJG6VApsXmM3t2fPN9eIHDUq8ocbHdJ4en8/bJDXZd9eb
QoILUuCg46hE3p6nTXfnPwSRnIRnsgCzeAz4rxDR4/Gv1Xpzv5wqpL21XQi3nvZKlcv7J1IR
VdphK66De9GpVQVTqC102gqJUErdjGmxmyCA1OOORqEPfKTrXz5YUGsWwpH+4xCuNQP0qmre
Rw3ghrH8potIr0iOVXFic5vJfBTgtcuEB6E6ulAN+3jqBGTaBML0jxgj3Z5VC5HKVbpg2DbB
/wMrLwFHNAbzV5hj2Os5Zmva0ySP1YHB26pAW8dwB38GBaQvfZq3ezM4cRAo/iJ/GsVE98dZ
EBO+Ml+0KYj+ZG+vyxzo20sweun7ZKT+9qZM90f6cQ3zqX6IfXZHHmQJBNv73mcZWNhDQOHs
4wBoq+FGQWNqLU9xaZxdXw80r1viDAwOy13EUtcVbTkAEQEAAYkCPAQYAQgAJhYhBIWb6NfF
hvU4QwsZwkZ7lC06eb0pBQJhuLq3AhsMBQkDwmcAAAoJEEZ7lC06eb0pSi8P/iy+dNnxrtiE
Nn9vkkA7AmZ8RsvPXYVeDCDSsL7UfhbS77r2L1qTa2aB3gAZUDIOXln51lSxMeeLtOequLME
V2Xi5km70rdtnja5SmWfc9fyExunXnsOhg6UG872At5CGEZU0c2Nt/hlGtOR3xbt3O/Uwl+d
ErQPA4BUbW5K1T7OC6oPvtlKfF4bGZFloHgt2yE9YSNWZsTPe6XJSapemHZLPOxJLnhs3VBi
rWE31QS0bRl5AzlO/fg7ia65vQGMOCOTLpgChTbcZHtozeFqva4IeEgE4xN+6r8WtgSYeGGD
RmeMEVjPM9dzQObf+SvGd58u2z9f2agPK1H32c69RLoA0mHRe7Wkv4izeJUc5tumUY0e8Ojd
enZZjT3hjLh6tM+mrp2oWnQIoed4LxUw1dhMOj0rYXv6laLGJ1FsW5eSke7ohBLcfBBTKnMC
BohROHy2E63Wggfsdn3UYzfqZ8cfbXetkXuLS/OM3MXbiNjg+ElYzjgWrkayu7yLakZx+mx6
sHPIJYm2hzkniMG29d5mGl7ZT9emP9b+CfqGUxoXJkjs0gnDl44bwGJ0dmIBu3ajVAaHODXy
Y/zdDMGjskfEYbNXCAY2FRZSE58tgTvPKD++Kd2KGplMU2EIFT7JYfKhHAB5DGMkx92HUMid
sTSKHe+QnnnoFmu4gnmDU31i
=Xqbo
-----END PGP PUBLIC KEY BLOCK-----

To import the build key into your personal public GPG keyring, use gpg --import. For example, if you
have saved the key in a file named mysql_pubkey.asc, the import command looks like this:
$> gpg --import mysql_pubkey.asc
gpg: key 3A79BD29: public key "MySQL Release Engineering
<[email protected]>" imported
gpg: Total number processed: 1
gpg: imported: 1

You can also download the key from the public keyserver using the public key id, 3A79BD29:
$> gpg --recv-keys 3A79BD29
gpg: requesting key 3A79BD29 from hkp server keys.gnupg.net
gpg: key 3A79BD29: "MySQL Release Engineering <[email protected]>"
1 new user ID
gpg: key 3A79BD29: "MySQL Release Engineering <[email protected]>"
53 new signatures
gpg: no ultimately trusted keys found
gpg: Total number processed: 1
gpg: new user IDs: 1
gpg: new signatures: 53

If you want to import the key into your RPM configuration to validate RPM install packages, you should be
able to import the key directly:
$> rpm --import mysql_pubkey.asc

If you experience problems or require RPM specific information, see Section 2.1.4.4, “Signature Checking
Using RPM”.

115
 Verifying Package Integrity Using MD5 Checksums or GnuPG

After you have downloaded and imported the public build key, download your desired MySQL package
and the corresponding signature, which also is available from the download page. The signature file has
the same name as the distribution file with an .asc extension, as shown by the examples in the following
table.

Table 2.1 MySQL Package and Signature Files for Source files

File Type File Name

Distribution file mysql-standard-8.0.36-linux-
i686.tar.gz
Signature file mysql-standard-8.0.36-linux-
i686.tar.gz.asc

Make sure that both files are stored in the same directory and then run the following command to verify the
signature for the distribution file:
$> gpg --verify package_name.asc

If the downloaded package is valid, you should see a Good signature message similar to this:
$> gpg --verify mysql-standard-8.0.36-linux-i686.tar.gz.asc
gpg: Signature made Tue 01 Feb 2011 02:38:30 AM CST using DSA key ID 3A79BD29
gpg: Good signature from "MySQL Release Engineering <[email protected]>"

The Good signature message indicates that the file signature is valid, when compared to the signature
listed on our site. But you might also see warnings, like so:
$> gpg --verify mysql-standard-8.0.36-linux-i686.tar.gz.asc
gpg: Signature made Wed 23 Jan 2013 02:25:45 AM PST using DSA key ID 3A79BD29
gpg: checking the trustdb
gpg: no ultimately trusted keys found
gpg: Good signature from "MySQL Release Engineering <[email protected]>"
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: A4A9 4068 76FC BD3C 4567 70C8 8C71 8D3B 5072 E1F5

That is normal, as they depend on your setup and configuration. Here are explanations for these warnings:

• gpg: no ultimately trusted keys found: This means that the specific key is not "ultimately trusted" by you
or your web of trust, which is okay for the purposes of verifying file signatures.

• WARNING: This key is not certified with a trusted signature! There is no indication that the signature
belongs to the owner.: This refers to your level of trust in your belief that you possess our real public key.
This is a personal decision. Ideally, a MySQL developer would hand you the key in person, but more
commonly, you downloaded it. Was the download tampered with? Probably not, but this decision is up to
you. Setting up a web of trust is one method for trusting them.

See the GPG documentation for more information on how to work with public keys.

2.1.4.3 Signature Checking Using Gpg4win for Windows

The Section 2.1.4.2, “Signature Checking Using GnuPG” section describes how to verify MySQL
downloads using GPG. That guide also applies to Microsoft Windows, but another option is to use a GUI
tool like Gpg4win. You may use a different tool but our examples are based on Gpg4win, and utilize its
bundled Kleopatra GUI.

Download and install Gpg4win, and then load Kleopatra. The dialog should look similar to:

116
 Verifying Package Integrity Using MD5 Checksums or GnuPG

Figure 2.1 Kleopatra: Initial Screen

Next, add the MySQL Release Engineering certificate. Do this by clicking File, Lookup Certificates on
Server. Type "Mysql Release Engineering" into the search box and press Search.

Figure 2.2 Kleopatra: Lookup Certificates on Server Wizard: Finding a Certificate

Select the "MySQL Release Engineering" certificate. The Fingerprint and Key-ID must be "3A79BD29" for
MySQL 8.0.28 and higher or "5072E1F5" for MySQL 8.0.27 and earlier, or choose Details... to confirm the
certificate is valid. Now, import it by clicking Import. When the import dialog is displayed, choose Okay,
and this certificate should now be listed under the Imported Certificates tab.

Next, configure the trust level for our certificate. Select our certificate, then from the main menu select
Certificates, Change Owner Trust.... We suggest choosing I believe checks are very accurate for our
certificate, as otherwise you might not be able to verify our signature. Select I believe checks are very
accurate to enable "full trust" and then press OK.

117
 Verifying Package Integrity Using MD5 Checksums or GnuPG

Figure 2.3 Kleopatra: Change Trust level for MySQL Release Engineering

Next, verify the downloaded MySQL package file. This requires files for both the packaged file, and the
signature. The signature file must have the same name as the packaged file but with an appended .asc
extension, as shown by the example in the following table. The signature is linked to on the downloads
page for each MySQL product. You must create the .asc file with this signature.

Table 2.2 MySQL Package and Signature Files for MySQL Installer for Microsoft Windows

File Type File Name

Distribution file mysql-installer-community-8.0.36.msi
Signature file mysql-installer-
community-8.0.36.msi.asc

Make sure that both files are stored in the same directory and then run the following command to verify the
signature for the distribution file. Either drag and drop the signature (.asc) file into Kleopatra, or load the
dialog from File, Decrypt/Verify Files..., and then choose either the .msi or .asc file.

118