Documentation Home
MySQL 5.7 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 39.5Mb
PDF (A4) - 39.5Mb
PDF (RPM) - 38.7Mb
HTML Download (TGZ) - 11.0Mb
HTML Download (Zip) - 11.0Mb
HTML Download (RPM) - 9.7Mb
Man Pages (TGZ) - 217.1Kb
Man Pages (Zip) - 326.8Kb
Info (Gzip) - 3.6Mb
Info (Zip) - 3.6Mb
Excerpts from this Manual

MySQL 5.7 Reference Manual  /  ...  /  Global Transaction ID Options and Variables

16.1.6.5 Global Transaction ID Options and Variables

The MySQL Server options and system variables described in this section are used to monitor and control Global Transaction Identifiers (GTIDs).

For additional information, see Section 16.1.3, “Replication with Global Transaction Identifiers”.

Startup Options Used with GTID Replication

The following server startup options are used with GTID-based replication:

  • --enforce-gtid-consistency

    Property Value
    Command-Line Format --enforce-gtid-consistency[=value]
    System Variable enforce_gtid_consistency
    Scope Global
    Dynamic (>= 5.7.6) Yes
    Dynamic (<= 5.7.5) No
    Type (>= 5.7.6) Enumeration
    Type (<= 5.7.5) Boolean
    Default Value OFF
    Valid Values

    OFF

    ON

    WARN

    When enabled, the server enforces GTID consistency by allowing execution of only statements that can be safely logged using a GTID. You must set this option to ON before enabling GTID based replication.

    The values that --enforce-gtid-consistency can be configured to are:

    • OFF: all transactions are allowed to violate GTID consistency.

    • ON: no transaction is allowed to violate GTID consistency.

    • WARN: all transactions are allowed to violate GTID consistency, but a warning is generated in this case. WARN was added in MySQL 5.7.6.

    Setting --enforce-gtid-consistency without a value is an alias for --enforce-gtid-consistency=ON. This impacts on the behavior of the variable, see enforce_gtid_consistency.

    Only statements that can be logged using GTID safe statements can be logged when enforce-gtid-consistency is set to ON, so the operations listed here cannot be used with this option:

    • CREATE TABLE ... SELECT statements

    • CREATE TEMPORARY TABLE or DROP TEMPORARY TABLE statements inside transactions

    • Transactions or statements that update both transactional and nontransactional tables. There is an exception that nontransactional DML is allowed in the same transaction or in the same statement as transactional DML, if all nontransactional tables are temporary.

    --enforce-gtid-consistency only takes effect if binary logging takes place for a statement. If binary logging is disabled on the server, or if statements are not written to the binary log because they are removed by a filter, GTID consistency is not checked or enforced for the statements that are not logged.

    For more information, see Section 16.1.3.6, “Restrictions on Replication with GTIDs”.

  • --executed-gtids-compression-period

    Property Value
    Command-Line Format --executed-gtids-compression-period=#
    Introduced 5.7.5
    Removed 5.7.6
    Type Integer
    Default Value 1000
    Minimum Value 0
    Maximum Value 4294967295

    Renamed to --gtid-executed-compression-period .

  • --gtid-mode

    Property Value
    Command-Line Format --gtid-mode=MODE
    System Variable gtid_mode
    Scope Global
    Dynamic (>= 5.7.6) Yes
    Dynamic (<= 5.7.5) No
    Type Enumeration
    Default Value OFF
    Valid Values (>= 5.7.6)

    OFF

    OFF_PERMISSIVE

    ON_PERMISSIVE

    ON

    Valid Values (<= 5.7.5)

    OFF

    UPGRADE_STEP_1

    UPGRADE_STEP_2

    ON

    This option specifies whether global transaction identifiers (GTIDs) are used to identify transactions. Setting this option to --gtid-mode=ON requires that enforce-gtid-consistency be set to ON. Prior to MySQL 5.7.6 the gtid_mode variable which this option controls could only be set at server startup. In MySQL 5.7.6 and later the gtid_mode variable is dynamic and enables GTID based replication to be configured online. Before using this feature, see Section 16.1.5, “Changing Replication Modes on Online Servers”.

    Prior to MySQL 5.7.5, starting the server with --gtid-mode=ON required that the server also be started with the --log-bin, --log-slave-updates, options. In versions of MySQL 5.7.5 and later this is not a requirement. See mysql.gtid_executed Table.

  • --gtid-executed-compression-period

    Property Value
    Command-Line Format --gtid-executed-compression-period=#
    Introduced 5.7.6
    Type Integer
    Default Value 1000
    Minimum Value 0
    Maximum Value 4294967295

    Compress the mysql.gtid_executed table each time this many transactions have taken place. A setting of 0 means that this table is not compressed. No compression of the table occurs when binary logging is enabled, therefore the option has no effect unless log_bin is OFF.

    See mysql.gtid_executed Table Compression, for more information.

    In MySQL version 5.7.5, this variable was added as executed_gtids_compression_period and in MySQL version 5.7.6 it was renamed to gtid_executed_compression_period.

System Variables Used with GTID Replication

The following system variables are used with GTID-based replication:

  • binlog_gtid_simple_recovery

    Property Value
    Command-Line Format --binlog-gtid-simple-recovery[={OFF|ON}]
    Introduced 5.7.6
    System Variable binlog_gtid_simple_recovery
    Scope Global
    Dynamic No
    Type Boolean
    Default Value (>= 5.7.7) ON
    Default Value (<= 5.7.6) OFF

    This variable controls how binary log files are iterated during the search for GTIDs when MySQL starts or restarts.

    When binlog_gtid_simple_recovery=TRUE, which is the default from MySQL 5.7.7, the values of gtid_executed and gtid_purged are computed at startup based on the values of Previous_gtids_log_event in the most recent and oldest binary log files. For a description of the computation, see The gtid_purged System Variable. This setting accesses only two binary log files during server restart. If all binary logs on the server were generated using MySQL 5.7.8 or later and you are using MySQL 5.7.8 or later, binlog_gtid_simple_recovery=TRUE can always safely be used.

    With binlog_gtid_simple_recovery=TRUE, gtid_executed and gtid_purged might be initialized incorrectly in the following two situations:

    • The newest binary log was generated by MySQL 5.7.5 or earlier, and gtid_mode was ON for some binary logs but OFF for the newest binary log.

    • A SET @@GLOBAL.gtid_purged statement was issued on MySQL 5.7.7 or earlier, and the binary log that was active at the time of the SET @@GLOBAL.gtid_purged statement has not yet been purged.

    If an incorrect GTID set is computed in either situation, it will remain incorrect even if the server is later restarted with binlog_gtid_simple_recovery=FALSE. If either of these situations apply on the server, set binlog_gtid_simple_recovery=FALSE before starting or restarting the server. To check for the second situation, if you are using MySQL 5.7.7 or earlier, after issuing a SET @@GLOBAL.gtid_purged statement note down the current binary log file name, which can be checked using SHOW MASTER STATUS. If the server is restarted before this file has been purged, then you should set binlog_gtid_simple_recovery=FALSE.

    When binlog_gtid_simple_recovery=FALSE is set, the method of computing gtid_executed and gtid_purged as described in The gtid_purged System Variable is changed to iterate the binary log files as follows:

    • Instead of using the value of Previous_gtids_log_event and GTID log events from the newest binary log file, the computation for gtid_executed iterates from the newest binary log file, and uses the value of Previous_gtids_log_event and any GTID log events from the first binary log file where it finds a Previous_gtids_log_event value. If the server's most recent binary log files do not have GTID log events, for example if gtid_mode=ON was used but the server was later changed to gtid_mode=OFF, this process can take a long time.

    • Instead of using the value of Previous_gtids_log_event from the oldest binary log file, the computation for gtid_purged iterates from the oldest binary log file, and uses the value of Previous_gtids_log_event from the first binary log file where it finds either a nonempty Previous_gtids_log_event value, or at least one GTID log event (indicating that the use of GTIDs starts at that point). If the server's older binary log files do not have GTID log events, for example if gtid_mode=ON was only set recently on the server, this process can take a long time.

    In MySQL version 5.7.5, this variable was added as simplified_binlog_gtid_recovery and in MySQL version 5.7.6 it was renamed to binlog_gtid_simple_recovery.

  • enforce_gtid_consistency

    Property Value
    Command-Line Format --enforce-gtid-consistency[=value]
    System Variable enforce_gtid_consistency
    Scope Global
    Dynamic (>= 5.7.6) Yes
    Dynamic (<= 5.7.5) No
    Type (>= 5.7.6) Enumeration
    Type (<= 5.7.5) Boolean
    Default Value OFF
    Valid Values

    OFF

    ON

    WARN

    Depending on the value of this variable, the server enforces GTID consistency by allowing execution of only statements that can be safely logged using a GTID. You must set this variable to ON before enabling GTID based replication.

    The values that enforce_gtid_consistency can be configured to are:

    • OFF: all transactions are allowed to violate GTID consistency.

    • ON: no transaction is allowed to violate GTID consistency.

    • WARN: all transactions are allowed to violate GTID consistency, but a warning is generated in this case. WARN was added in MySQL 5.7.6.

    enforce_gtid_consistency only takes effect if binary logging takes place for a statement. If binary logging is disabled on the server, or if statements are not written to the binary log because they are removed by a filter, GTID consistency is not checked or enforced for the statements that are not logged.

    For more information on statements that can be logged using GTID based replication, see --enforce-gtid-consistency.

    Prior to MySQL 5.7.6, the boolean enforce_gtid_consistency defaulted to OFF. To maintain compatibility with previous releases, in MySQL 5.7.6 the enumeration defaults to OFF, and setting --enforce-gtid-consistency without a value is interpreted as setting the value to ON. The variable also has multiple textual aliases for the values: 0=OFF=FALSE, 1=ON=TRUE,2=WARN. This differs from other enumeration types but maintains compatibility with the boolean type used in previous versions. These changes impact on what is returned by the variable. Using SELECT @@ENFORCE_GTID_CONSISTENCY, SHOW VARIABLES LIKE 'ENFORCE_GTID_CONSISTENCY', and SELECT * FROM INFORMATION_SCHEMA.VARIABLES WHERE 'VARIABLE_NAME' = 'ENFORCE_GTID_CONSISTENCY', all return the textual form, not the numeric form. This is an incompatible change, since @@ENFORCE_GTID_CONSISTENCY returns the numeric form for booleans but returns the textual form for SHOW and the Information Schema.

  • executed_gtids_compression_period

    Property Value
    Introduced 5.7.5
    Removed 5.7.6
    System Variable (>= 5.7.5) executed_gtids_compression_period
    Scope (>= 5.7.5) Global
    Dynamic (>= 5.7.5) Yes
    Type Integer
    Default Value 1000
    Minimum Value 0
    Maximum Value 4294967295

    Renamed to gtid_executed_compression_period.

  • gtid_executed

    Property Value
    System Variable (>= 5.7.7) gtid_executed
    System Variable gtid_executed
    Scope (>= 5.7.7) Global
    Scope Global, Session
    Dynamic (>= 5.7.7) No
    Dynamic No
    Type String

    When used with global scope, this variable contains a representation of the set of all transactions executed on the server and GTIDs that have been set by a SET gtid_purged statement. This is the same as the value of the Executed_Gtid_Set column in the output of SHOW MASTER STATUS and SHOW SLAVE STATUS. The value of this variable is a GTID set, see GTID Sets for more information.

    When the server starts, @@GLOBAL.gtid_executed is initialized. See binlog_gtid_simple_recovery for more information on how binary logs are iterated to populate gtid_executed. GTIDs are then added to the set as transactions are executed, or if any SET gtid_purged statement is executed.

    The set of transactions that can be found in the binary logs at any given time is equal to GTID_SUBTRACT(@@GLOBAL.gtid_executed, @@GLOBAL.gtid_purged); that is, to all transactions in the binary log that have not yet been purged.

    Issuing RESET MASTER causes the global value (but not the session value) of this variable to be reset to an empty string. GTIDs are not otherwise removed from this set other than when the set is cleared due to RESET MASTER.

    Prior to MySQL 5.7.7, this variable could also be used with session scope, where it contained a representation of the set of transactions that are written to the cache in the current session. The session scope was deprecated in MySQL 5.7.7.

  • gtid_executed_compression_period

    Property Value
    Introduced 5.7.6
    System Variable (>= 5.7.6) gtid_executed_compression_period
    Scope (>= 5.7.6) Global
    Dynamic (>= 5.7.6) Yes
    Type Integer
    Default Value 1000
    Minimum Value 0
    Maximum Value 4294967295

    Compress the mysql.gtid_executed table each time this many transactions have been processed. A setting of 0 means that this table is not compressed. Since no compression of the table occurs when using the binary log, setting the value of the variable has no effect unless binary logging is disabled.

    See mysql.gtid_executed Table Compression, for more information.

    In MySQL version 5.7.5, this variable was added as executed_gtids_compression_period and in MySQL version 5.7.6 it was renamed to gtid_executed_compression_period.

  • gtid_mode

    Property Value
    System Variable gtid_mode
    Scope Global
    Dynamic (>= 5.7.6) Yes
    Dynamic (<= 5.7.5) No
    Type Enumeration
    Default Value OFF
    Valid Values (>= 5.7.6)

    OFF

    OFF_PERMISSIVE

    ON_PERMISSIVE

    ON

    Valid Values (<= 5.7.5)

    OFF

    UPGRADE_STEP_1

    UPGRADE_STEP_2

    ON

    Controls whether GTID based logging is enabled and what type of transactions the logs can contain. Prior to MySQL 5.7.6 this variable was read-only and was set using the --gtid-mode option only. MySQL 5.7.6 enables this variable to be set dynamically. You must have privileges sufficient to set global system variables. See Section 5.1.8.1, “System Variable Privileges”. enforce_gtid_consistency must be true before you can set gtid_mode=ON. Before modifying this variable, see Section 16.1.5, “Changing Replication Modes on Online Servers”.

    Transactions logged in MySQL 5.7.6 and later can be either anonymous or use GTIDs. Anonymous transactions rely on binary log file and position to identify specific transactions. GTID transactions have a unique identifier that is used to refer to transactions. The OFF_PERMISSIVE and ON_PERMISSIVE modes added in MySQL 5.7.6 permit a mix of these transaction types in the topology. The different modes are now:

    • OFF: Both new and replicated transactions must be anonymous.

    • OFF_PERMISSIVE: New transactions are anonymous. Replicated transactions can be either anonymous or GTID transactions.

    • ON_PERMISSIVE: New transactions are GTID transactions. Replicated transactions can be either anonymous or GTID transactions.

    • ON: Both new and replicated transactions must be GTID transactions.

    Changes from one value to another can only be one step at a time. For example, if gtid_mode is currently set to OFF_PERMISSIVE, it is possible to change to OFF or ON_PERMISSIVE but not to ON.

    In MySQL 5.7.6 and later, the values of gtid_purged and gtid_executed are persistent regardless of the value of gtid_mode. Therefore even after changing the value of gtid_mode, these variables contain the correct values. In MySQL 5.7.5 and earlier, the values of gtid_purged and gtid_executed are not persistent while gtid_mode=OFF. Therefore, after changing gtid_mode to OFF, once all binary logs containing GTIDs are purged, the values of these variables are lost.

  • gtid_next

    Property Value
    System Variable gtid_next
    Scope Session
    Dynamic Yes
    Type Enumeration
    Default Value AUTOMATIC
    Valid Values

    AUTOMATIC

    ANONYMOUS

    UUID:NUMBER

    This variable is used to specify whether and how the next GTID is obtained.

    Setting the session value of this system variable is a restricted operation. The session user must have privileges sufficient to set restricted session variables. See Section 5.1.8.1, “System Variable Privileges”.

    gtid_next can take any of the following values:

    • AUTOMATIC: Use the next automatically-generated global transaction ID.

    • ANONYMOUS: Transactions do not have global identifiers, and are identified by file and position only.

    • A global transaction ID in UUID:NUMBER format.

    Exactly which of the above options are valid depends on the setting of gtid_mode, see Section 16.1.5.1, “Replication Mode Concepts” for more information. Setting this variable has no effect if gtid_mode is OFF.

    After this variable has been set to UUID:NUMBER, and a transaction has been committed or rolled back, an explicit SET GTID_NEXT statement must again be issued before any other statement.

    In MySQL 5.7.5 and later, DROP TABLE or DROP TEMPORARY TABLE fails with an explicit error when used on a combination of nontemporary tables with temporary tables, or of temporary tables using transactional storage engines with temporary tables using nontransactional storage engines. Prior to MySQL 5.7.5, when GTIDs were enabled but gtid_next was not AUTOMATIC, DROP TABLE did not work correctly when used with either of these combinations of tables. (Bug #17620053)

    In MySQL 5.7.1, you cannot execute any of the statements CHANGE MASTER TO, START SLAVE, STOP SLAVE, REPAIR TABLE, OPTIMIZE TABLE, ANALYZE TABLE, CHECK TABLE, CREATE SERVER, ALTER SERVER, DROP SERVER, CACHE INDEX, LOAD INDEX INTO CACHE, FLUSH, or RESET when gtid_next is set to any value other than AUTOMATIC; in such cases, the statement fails with an error. Such statements are not disallowed in MySQL 5.7.2 and later. (Bug #16062608, Bug #16715809, Bug #69045) (Bug #16062608)

  • gtid_owned

    Property Value
    System Variable gtid_owned
    Scope Global, Session
    Dynamic No
    Type String

    This read-only variable is primarily for internal use. Its contents depend on its scope.

    • When used with global scope, gtid_owned holds a list of all the GTIDs that are currently in use on the server, with the IDs of the threads that own them. This variable is mainly useful for a multi-threaded replication slave to check whether a transaction is already being applied on another thread. An applier thread takes ownership of a transaction's GTID all the time it is processing the transaction, so @@global.gtid_owned shows the GTID and owner for the duration of processing. When a transaction has been committed (or rolled back), the applier thread releases ownership of the GTID.

    • When used with session scope, gtid_owned holds a single GTID that is currently in use by and owned by this session. This variable is mainly useful for testing and debugging the use of GTIDs when the client has explicitly assigned a GTID for the transaction by setting gtid_next. In this case, @@session.gtid_owned displays the GTID all the time the client is processing the transaction, until the transaction has been committed (or rolled back). When the client has finished processing the transaction, the variable is cleared. If gtid_next=AUTOMATIC is used for the session, gtid_owned is only populated briefly during the execution of the commit statement for the transaction, so it cannot be observed from the session concerned, although it will be listed if @@global.gtid_owned is read at the right point. If you have a requirement to track the GTIDs that are handled by a client in a session, you can enable the session state tracker controlled by the session_track_gtids system variable.

  • gtid_purged

    Property Value
    System Variable gtid_purged
    Scope Global
    Dynamic Yes
    Type String

    The global value of the gtid_purged system variable (@@GLOBAL.gtid_purged) is a GTID set consisting of the GTIDs of all the transactions that have been committed on the server, but do not exist in any binary log file on the server. gtid_purged is a subset of gtid_executed. The following categories of GTIDs are in gtid_purged:

    • GTIDs of replicated transactions that were committed with binary logging disabled on the slave.

    • GTIDs of transactions that were written to a binary log file that has now been purged.

    • GTIDs that were added explicitly to the set by the statement SET @@GLOBAL.gtid_purged.

    When the server starts or restarts, the global value of gtid_purged is initialized to a set of GTIDs. For information on how this GTID set is computed, see The gtid_purged System Variable. If binary logs from MySQL 5.7.7 or older are present on the server, you might need to set binlog_gtid_simple_recovery=FALSE in the server's configuration file to produce the correct computation. See the description for binlog_gtid_simple_recovery for details of the situations in which this setting is needed.

    Issuing RESET MASTER causes the value of gtid_purged to be reset to an empty string.

    You can set the value of gtid_purged in order to record on the server that the transactions in a certain GTID set have been applied, although they do not exist in any binary log on the server. An example use case for this action is when you are restoring a backup of one or more databases on a server, but you do not have the relevant binary logs containing the transactions on the server.

    In MySQL 5.7, it is possible to update the value of gtid_purged only when gtid_executed is the empty string, and therefore gtid_purged is the empty string. This is the case either when replication has not been started previously, or when replication did not previously use GTIDs. Prior to MySQL 5.7.6, gtid_purged was also settable only when gtid_mode=ON. In MySQL 5.7.6 and later, gtid_purged is settable regardless of the value of gtid_mode.

    To replace the value of gtid_purged with your specified GTID set, use the following statement:

    SET @@GLOBAL.gtid_purged = 'gtid_set'
    Note

    If you are using MySQL 5.7.7 or earlier, after issuing a SET @@GLOBAL.gtid_purged statement, you might need to set binlog_gtid_simple_recovery=FALSE in the server's configuration file before restarting the server, otherwise gtid_purged can be computed incorrectly. See the description for binlog_gtid_simple_recovery for details of the situations in which this setting is needed. If all binary logs on the server were generated using MySQL 5.7.8 or later and you are using MySQL 5.7.8 or later, binlog_gtid_simple_recovery=TRUE (which is the default setting from MySQL 5.7.7) can always safely be used.

  • simplified_binlog_gtid_recovery

    Property Value
    Command-Line Format --simplified-binlog-gtid-recovery[={OFF|ON}]
    Introduced 5.7.5
    Deprecated Yes (removed in 5.7.6)
    System Variable simplified_binlog_gtid_recovery
    Scope Global
    Dynamic No
    Type Boolean
    Default Value OFF

    Renamed to binlog_gtid_simple_recovery.