4.3.9.2 NDB Cluster System Variables

This section provides detailed information about MySQL server system variables that are specific to NDB Cluster and the NDB storage engine. For system variables not specific to NDB Cluster, see Server System Variables. For general information on using system variables, see Using System Variables.

  • ndb_autoincrement_prefetch_sz

    Command-Line Format --ndb-autoincrement-prefetch-sz=#
    System Variable ndb_autoincrement_prefetch_sz
    Scope Global, Session
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value (≥ 8.0.19-ndb-8.0.19) 512
    Default Value (≤ 8.0.18-ndb-8.0.18) 1
    Minimum Value 1
    Maximum Value 65536

    Determines the probability of gaps in an autoincremented column. Set it to 1 to minimize this. Setting it to a high value for optimization makes inserts faster, but decreases the likelihood of consecutive autoincrement numbers being used in a batch of inserts.

    This variable affects only the number of AUTO_INCREMENT IDs that are fetched between statements; within a given statement, at least 32 IDs are obtained at a time.

    Important

    This variable does not affect inserts performed using INSERT ... SELECT.

  • ndb_clear_apply_status

    Command-Line Format --ndb-clear-apply-status[={OFF|ON}]
    System Variable ndb_clear_apply_status
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value ON

    By the default, executing RESET SLAVE causes an NDB Cluster replica to purge all rows from its ndb_apply_status table. You can disable this by setting ndb_clear_apply_status=OFF.

  • ndb_conflict_role

    Command-Line Format --ndb-conflict-role=value
    Introduced 8.0.23-ndb-8.0.23
    System Variable ndb_conflict_role
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Enumeration
    Default Value NONE
    Valid Values

    NONE

    PRIMARY

    SECONDARY

    PASS

    Determines the role of this SQL node (and NDB Cluster) in a circular (“active-active”) replication setup. ndb_slave_conflict_role can take any one of the values PRIMARY, SECONDARY, PASS, or NULL (the default). The replica SQL thread must be stopped before you can change ndb_slave_conflict_role. In addition, it is not possible to change directly between PASS and either of PRIMARY or SECONDARY directly; in such cases, you must ensure that the SQL thread is stopped, then execute SET @@GLOBAL.ndb_slave_conflict_role = 'NONE' first.

    This variable replaces ndb_slave_conflict_role, which is deprecated as of NDB 8.0.23.

    For more information, see Section 7.12, “NDB Cluster Replication Conflict Resolution”.

  • ndb_data_node_neighbour

    Command-Line Format --ndb-data-node-neighbour=#
    System Variable ndb_data_node_neighbour
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 0
    Minimum Value 0
    Maximum Value 255

    Sets the ID of a “nearest” data node—that is, a preferred nonlocal data node is chosen to execute the transaction, rather than one running on the same host as the SQL or API node. This used to ensure that when a fully replicated table is accessed, we access it on this data node, to ensure that the local copy of the table is always used whenever possible. This can also be used for providing hints for transactions.

    This can improve data access times in the case of a node that is physically closer than and thus has higher network throughput than others on the same host.

    See Setting NDB Comment Options, for further information.

    Note

    An equivalent method set_data_node_neighbour() is provided for use in NDB API applications.

  • ndb_dbg_check_shares

    Command-Line Format --ndb-dbg-check-shares=#
    Introduced 8.0.13-ndb-8.0.13
    System Variable ndb_dbg_check_shares
    Scope Global, Session
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 0
    Minimum Value 0
    Maximum Value 1

    When set to 1, check that no shares are lingering. Available in debug builds only.

  • ndb_default_column_format

    Command-Line Format --ndb-default-column-format={FIXED|DYNAMIC}
    System Variable ndb_default_column_format
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Enumeration
    Default Value FIXED
    Valid Values

    FIXED

    DYNAMIC

    Sets the default COLUMN_FORMAT and ROW_FORMAT for new tables (see CREATE TABLE Statement). The default is FIXED.

  • ndb_deferred_constraints

    Command-Line Format --ndb-deferred-constraints=#
    System Variable ndb_deferred_constraints
    Scope Global, Session
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 0
    Minimum Value 0
    Maximum Value 1

    Controls whether or not constraint checks are deferred, where these are supported. 0 is the default.

    This variable is not normally needed for operation of NDB Cluster or NDB Cluster Replication, and is intended primarily for use in testing.

  • ndb_distribution

    Command-Line Format --ndb-distribution={KEYHASH|LINHASH}
    System Variable ndb_distribution
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Enumeration
    Default Value KEYHASH
    Valid Values

    LINHASH

    KEYHASH

    Controls the default distribution method for NDB tables. Can be set to either of KEYHASH (key hashing) or LINHASH (linear hashing). KEYHASH is the default.

  • ndb_eventbuffer_free_percent

    Command-Line Format --ndb-eventbuffer-free-percent=#
    System Variable ndb_eventbuffer_free_percent
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 20
    Minimum Value 1
    Maximum Value 99

    Sets the percentage of the maximum memory allocated to the event buffer (ndb_eventbuffer_max_alloc) that should be available in event buffer after reaching the maximum, before starting to buffer again.

  • ndb_eventbuffer_max_alloc

    Command-Line Format --ndb-eventbuffer-max-alloc=#
    System Variable ndb_eventbuffer_max_alloc
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 0
    Minimum Value 0
    Maximum Value (≥ 8.0.26-ndb-8.0.26) 9223372036854775807
    Maximum Value 9223372036854775807
    Maximum Value 9223372036854775807
    Maximum Value (≤ 8.0.25-ndb-8.0.25) 4294967295

    Sets the maximum amount memory (in bytes) that can be allocated for buffering events by the NDB API. 0 means that no limit is imposed, and is the default.

  • ndb_extra_logging

    Command-Line Format ndb_extra_logging=#
    System Variable ndb_extra_logging
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 1
    Minimum Value 0
    Maximum Value 1

    This variable enables recording in the MySQL error log of information specific to the NDB storage engine.

    When this variable is set to 0, the only information specific to NDB that is written to the MySQL error log relates to transaction handling. If it set to a value greater than 0 but less than 10, NDB table schema and connection events are also logged, as well as whether or not conflict resolution is in use, and other NDB errors and information. If the value is set to 10 or more, information about NDB internals, such as the progress of data distribution among cluster nodes, is also written to the MySQL error log. The default is 1.

  • ndb_force_send

    Command-Line Format --ndb-force-send[={OFF|ON}]
    System Variable ndb_force_send
    Scope Global, Session
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value ON

    Forces sending of buffers to NDB immediately, without waiting for other threads. Defaults to ON.

  • ndb_fully_replicated

    Command-Line Format --ndb-fully-replicated[={OFF|ON}]
    System Variable ndb_fully_replicated
    Scope Global, Session
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value OFF

    Determines whether new NDB tables are fully replicated. This setting can be overridden for an individual table using COMMENT="NDB_TABLE=FULLY_REPLICATED=..." in a CREATE TABLE or ALTER TABLE statement; see Setting NDB Comment Options, for syntax and other information.

  • ndb_index_stat_enable

    Command-Line Format --ndb-index-stat-enable[={OFF|ON}]
    System Variable ndb_index_stat_enable
    Scope Global, Session
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value ON

    Use NDB index statistics in query optimization. The default is ON.

    Prior to NDB 8.0.27, starting the server with --ndb-index-stat-enable set to OFF prevented the creation of the index statistics tables. In NDB 8.0.27 and later, these tables are always created when the server starts, regardless of this option's value.

  • ndb_index_stat_option

    Command-Line Format --ndb-index-stat-option=value
    System Variable ndb_index_stat_option
    Scope Global, Session
    Dynamic Yes
    SET_VAR Hint Applies No
    Type String
    Default Value loop_checkon=1000ms,loop_idle=1000ms,loop_busy=100ms, update_batch=1,read_batch=4,idle_batch=32,check_batch=32, check_delay=1m,delete_batch=8,clean_delay=0,error_batch=4, error_delay=1m,evict_batch=8,evict_delay=1m,cache_limit=32M, cache_lowpct=90

    This variable is used for providing tuning options for NDB index statistics generation. The list consist of comma-separated name-value pairs of option names and values, and this list must not contain any space characters.

    Options not used when setting ndb_index_stat_option are not changed from their default values. For example, you can set ndb_index_stat_option = 'loop_idle=1000ms,cache_limit=32M'.

    Time values can be optionally suffixed with h (hours), m (minutes), or s (seconds). Millisecond values can optionally be specified using ms; millisecond values cannot be specified using h, m, or s.) Integer values can be suffixed with K, M, or G.

    The names of the options that can be set using this variable are shown in the table that follows. The table also provides brief descriptions of the options, their default values, and (where applicable) their minimum and maximum values.

    Table 4.13 ndb_index_stat_option options and values

    Name Description Default/Units Minimum/Maximum
    loop_enable 1000 ms 0/4G
    loop_idle Time to sleep when idle 1000 ms 0/4G
    loop_busy Time to sleep when more work is waiting 100 ms 0/4G
    update_batch 1 0/4G
    read_batch 4 1/4G
    idle_batch 32 1/4G
    check_batch 8 1/4G
    check_delay How often to check for new statistics 10 m 1/4G
    delete_batch 8 0/4G
    clean_delay 1 m 0/4G
    error_batch 4 1/4G
    error_delay 1 m 1/4G
    evict_batch 8 1/4G
    evict_delay Clean LRU cache, from read time 1 m 0/4G
    cache_limit Maximum amount of memory in bytes used for cached index statistics by this mysqld; clean up the cache when this is exceeded. 32 M 0/4G
    cache_lowpct 90 0/100
    zero_total Setting this to 1 resets all accumulating counters in ndb_index_stat_status to 0. This option value is also reset to 0 when this is done. 0 0/1

  • ndb_join_pushdown

    System Variable ndb_join_pushdown
    Scope Global, Session
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value ON

    This variable controls whether joins on NDB tables are pushed down to the NDB kernel (data nodes). Previously, a join was handled using multiple accesses of NDB by the SQL node; however, when ndb_join_pushdown is enabled, a pushable join is sent in its entirety to the data nodes, where it can be distributed among the data nodes and executed in parallel on multiple copies of the data, with a single, merged result being returned to mysqld. This can reduce greatly the number of round trips between an SQL node and the data nodes required to handle such a join.

    By default, ndb_join_pushdown is enabled.

    Conditions for NDB pushdown joins.  In order for a join to be pushable, it must meet the following conditions:

    1. Only columns can be compared, and all columns to be joined must use exactly the same data type. This means that (for example) a join on an INT column and a BIGINT column also cannot be pushed down.

      Previously, expressions such as t1.a = t2.a + constant could not be pushed down. This restriction is lifted in NDB 8.0. The result of any operations on any column to be compared must yield the same type as the column itself.

      Expressions comparing columns from the same table can also be pushed down. The columns (or the result of any operations on those columns) must be of exactly the same type, including the same signedness, length, character set and collation, precision, and scale, where these are applicable.

    2. Queries referencing BLOB or TEXT columns are not supported.

    3. Explicit locking is not supported; however, the NDB storage engine's characteristic implicit row-based locking is enforced.

      This means that a join using FOR UPDATE cannot be pushed down.

    4. In order for a join to be pushed down, child tables in the join must be accessed using one of the ref, eq_ref, or  const access methods, or some combination of these methods.

      Outer joined child tables can only be pushed using eq_ref.

      If the root of the pushed join is an eq_ref or const, only child tables joined by eq_ref can be appended. (A table joined by ref is likely to become the root of another pushed join.)

      If the query optimizer decides on Using join cache for a candidate child table, that table cannot be pushed as a child. However, it may be the root of another set of pushed tables.

    5. Joins referencing tables explicitly partitioned by [LINEAR] HASH, LIST, or RANGE currently cannot be pushed down.

    You can see whether a given join can be pushed down by checking it with EXPLAIN; when the join can be pushed down, you can see references to the pushed join in the Extra column of the output, as shown in this example: 

    mysql> EXPLAIN
    ->     SELECT e.first_name, e.last_name, t.title, d.dept_name
    ->         FROM employees e
    ->         JOIN dept_emp de ON e.emp_no=de.emp_no
    ->         JOIN departments d ON d.dept_no=de.dept_no
    ->         JOIN titles t ON e.emp_no=t.emp_no\G
*************************** 1. row ***************************
           id: 1
  select_type: SIMPLE
        table: d
         type: ALL
possible_keys: PRIMARY
          key: NULL
      key_len: NULL
          ref: NULL
         rows: 9
        Extra: Parent of 4 pushed join@1
*************************** 2. row ***************************
           id: 1
  select_type: SIMPLE
        table: de
         type: ref
possible_keys: PRIMARY,emp_no,dept_no
          key: dept_no
      key_len: 4
          ref: employees.d.dept_no
         rows: 5305
        Extra: Child of 'd' in pushed join@1
*************************** 3. row ***************************
           id: 1
  select_type: SIMPLE
        table: e
         type: eq_ref
possible_keys: PRIMARY
          key: PRIMARY
      key_len: 4
          ref: employees.de.emp_no
         rows: 1
        Extra: Child of 'de' in pushed join@1
*************************** 4. row ***************************
           id: 1
  select_type: SIMPLE
        table: t
         type: ref
possible_keys: PRIMARY,emp_no
          key: emp_no
      key_len: 4
          ref: employees.de.emp_no
         rows: 19
        Extra: Child of 'e' in pushed join@1
4 rows in set (0.00 sec)
    Note

    If inner joined child tables are joined by ref, and the result is ordered or grouped by a sorted index, this index cannot provide sorted rows, which forces writing to a sorted tempfile.

    Two additional sources of information about pushed join performance are available:

    1. The status variables Ndb_pushed_queries_defined, Ndb_pushed_queries_dropped, Ndb_pushed_queries_executed, and Ndb_pushed_reads.

    2. The counters in the ndbinfo.counters table that belong to the DBSPJ kernel block.

  • ndb_log_apply_status

    Command-Line Format --ndb-log-apply-status[={OFF|ON}]
    System Variable ndb_log_apply_status
    Scope Global
    Dynamic No
    SET_VAR Hint Applies No
    Type Boolean
    Default Value OFF

    A read-only variable which shows whether the server was started with the --ndb-log-apply-status option.

  • ndb_log_bin

    Command-Line Format --ndb-log-bin[={OFF|ON}]
    System Variable ndb_log_bin
    Scope Global, Session
    Dynamic No
    SET_VAR Hint Applies No
    Type Boolean
    Default Value (≥ 8.0.16-ndb-8.0.16) OFF
    Default Value (≤ 8.0.15-ndb-8.0.15) ON

    Causes updates to NDB tables to be written to the binary log. The setting for this variable has no effect if binary logging is not already enabled on the server using log_bin. In NDB 8.0, ndb_log_bin defaults to 0 (FALSE).

  • ndb_log_binlog_index

    Command-Line Format --ndb-log-binlog-index[={OFF|ON}]
    System Variable ndb_log_binlog_index
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value ON

    Causes a mapping of epochs to positions in the binary log to be inserted into the ndb_binlog_index table. Setting this variable has no effect if binary logging is not already enabled for the server using log_bin. (In addition, ndb_log_bin must not be disabled.) ndb_log_binlog_index defaults to 1 (ON); normally, there is never any need to change this value in a production environment.

  • ndb_log_cache_size

    Command-Line Format --ndb-log-cache-size=#
    Introduced 8.0.40-ndb_8.0.40
    System Variable ndb_log_cache_size
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 64M
    Minimum Value 4096
    Maximum Value 18446744073709551615

    Set the size of the transaction cache used for writing the NDB binary log.

  • ndb_log_empty_epochs

    Command-Line Format --ndb-log-empty-epochs[={OFF|ON}]
    System Variable ndb_log_empty_epochs
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value OFF

    When this variable is set to 0, epoch transactions with no changes are not written to the binary log, although a row is still written even for an empty epoch in ndb_binlog_index.

  • ndb_log_empty_update

    Command-Line Format --ndb-log-empty-update[={OFF|ON}]
    System Variable ndb_log_empty_update
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value OFF

    When this variable is set to ON (1), update transactions with no changes are written to the binary log, even when log_replica_updates or log_slave_updates is enabled.

  • ndb_log_exclusive_reads

    Command-Line Format --ndb-log-exclusive-reads[={OFF|ON}]
    System Variable ndb_log_exclusive_reads
    Scope Global, Session
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value 0

    This variable determines whether primary key reads are logged with exclusive locks, which allows for NDB Cluster Replication conflict detection and resolution based on read conflicts. To enable these locks, set the value of ndb_log_exclusive_reads to 1. 0, which disables such locking, is the default.

    For more information, see Read conflict detection and resolution.

  • ndb_log_orig

    Command-Line Format --ndb-log-orig[={OFF|ON}]
    System Variable ndb_log_orig
    Scope Global
    Dynamic No
    SET_VAR Hint Applies No
    Type Boolean
    Default Value OFF

    Shows whether the originating server ID and epoch are logged in the ndb_binlog_index table. Set using the --ndb-log-orig server option.

  • ndb_log_transaction_id

    System Variable ndb_log_transaction_id
    Scope Global
    Dynamic No
    SET_VAR Hint Applies No
    Type Boolean
    Default Value OFF

    This read-only, Boolean system variable shows whether a replica mysqld writes NDB transaction IDs in the binary log (required to use “active-active” NDB Cluster Replication with NDB$EPOCH_TRANS() conflict detection). To change the setting, use the --ndb-log-transaction-id option.

    ndb_log_transaction_id is not supported in mainline MySQL Server 8.0.

    For more information, see Section 7.12, “NDB Cluster Replication Conflict Resolution”.

  • ndb_log_transaction_compression

    Command-Line Format --ndb-log-transaction-compression
    Introduced 8.0.31-ndb-8.0.31
    System Variable ndb_log_transaction_compression
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value OFF

    Whether a replica mysqld writes compressed transactions in the binary log; present only if mysqld was compiled with support for NDB.

    You should note that starting the MySQL server with --binlog-transaction-compression forces this variable to be enabled (ON), and that this overrides any setting for --ndb-log-transaction-compression made on the command line or in a my.cnf file, as shown here: 

    $> mysqld_safe --ndbcluster --ndb-connectstring=127.0.0.1 \
  --binlog-transaction-compression=ON --ndb-log-transaction-compression=OFF &
[1] 27667
$> 2022-07-07T12:29:20.459937Z mysqld_safe Logging to '/usr/local/mysql/data/myhost.err'.
2022-07-07T12:29:20.509873Z mysqld_safe Starting mysqld daemon with databases from /usr/local/mysql/data

$> mysql -e 'SHOW VARIABLES LIKE "%transaction_compression%"'
+--------------------------------------------+-------+
| Variable_name                              | Value |
+--------------------------------------------+-------+
| binlog_transaction_compression             | ON    |
| binlog_transaction_compression_level_zstd  | 3     |
| ndb_log_transaction_compression            | ON    |
| ndb_log_transaction_compression_level_zstd | 3     |
+--------------------------------------------+-------+

    To disable binary log transaction compression for NDB tables only, set the ndb_log_transaction_compression system variable to OFF in a mysql or other client session after starting mysqld.

    Setting the binlog_transaction_compression variable after startup has no effect on the value of ndb_log_transaction_compression.

    For more information on binary log transaction compression, such as which events are or are not compressed and as well as behavior changes to be aware of when this feature is used, see Binary Log Transaction Compression.

  • ndb_log_transaction_compression_level_zstd

    Command-Line Format --ndb-log-transaction-compression-level-zstd=#
    Introduced 8.0.31-ndb-8.0.31
    System Variable ndb_log_transaction_compression_level_zstd
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 3
    Minimum Value 1
    Maximum Value 22

    The ZSTD compression level used for writing compressed transactions to the replica's binary log if enabled by ndb_log_transaction_compression. Not supported if mysqld was not compiled with support for the NDB storage engine.

    See Binary Log Transaction Compression, for more information.

  • ndb_metadata_check

    Command-Line Format --ndb-metadata-check[={OFF|ON}]
    Introduced 8.0.16-ndb-8.0.16
    System Variable ndb_metadata_check
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value ON

    NDB uses a background thread to check for metadata changes each ndb_metadata_check_interval seconds as compared with the MySQL data dictionary. This metadata change detection thread can be disabled by setting ndb_metadata_check to OFF. The thread is enabled by default.

  • ndb_metadata_check_interval

    Command-Line Format --ndb-metadata-check-interval=#
    Introduced 8.0.16-ndb-8.0.16
    System Variable ndb_metadata_check_interval
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 60
    Minimum Value 0
    Maximum Value 31536000
    Unit seconds

    NDB runs a metadata change detection thread in the background to determine when the NDB dictionary has changed with respect to the MySQL data dictionary. By default,the interval between such checks is 60 seconds; this can be adjusted by setting the value of ndb_metadata_check_interval. To enable or disable the thread, use ndb_metadata_check.

  • ndb_metadata_sync

    Introduced 8.0.19-ndb-8.0.19
    System Variable ndb_metadata_sync
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value false

    Setting this variable causes the change monitor thread to override any values set for ndb_metadata_check or ndb_metadata_check_interval, and to enter a period of continuous change detection. When the thread ascertains that there are no more changes to be detected, it stalls until the binary logging thread has finished synchronization of all detected objects. ndb_metadata_sync is then set to false, and the change monitor thread reverts to the behavior determined by the settings for ndb_metadata_check and ndb_metadata_check_interval.

    In NDB 8.0.22 and later, setting this variable to true causes the list of excluded objects to be cleared, and setting it to false clears the list of objects to be retried.

  • ndb_optimized_node_selection

    Command-Line Format --ndb-optimized-node-selection=#
    System Variable ndb_optimized_node_selection
    Scope Global
    Dynamic No
    SET_VAR Hint Applies No
    Type Integer
    Default Value 3
    Minimum Value 0
    Maximum Value 3

    There are two forms of optimized node selection, described here:

    1. The SQL node uses promixity to determine the transaction coordinator; that is, the “closest” data node to the SQL node is chosen as the transaction coordinator. For this purpose, a data node having a shared memory connection with the SQL node is considered to be “closest” to the SQL node; the next closest (in order of decreasing proximity) are: TCP connection to localhost, followed by TCP connection from a host other than localhost.

    2. The SQL thread uses distribution awareness to select the data node. That is, the data node housing the cluster partition accessed by the first statement of a given transaction is used as the transaction coordinator for the entire transaction. (This is effective only if the first statement of the transaction accesses no more than one cluster partition.)

    This option takes one of the integer values 0, 1, 2, or 3. 3 is the default. These values affect node selection as follows:

    • 0: Node selection is not optimized. Each data node is employed as the transaction coordinator 8 times before the SQL thread proceeds to the next data node.

    • 1: Proximity to the SQL node is used to determine the transaction coordinator.

    • 2: Distribution awareness is used to select the transaction coordinator. However, if the first statement of the transaction accesses more than one cluster partition, the SQL node reverts to the round-robin behavior seen when this option is set to 0.

    • 3: If distribution awareness can be employed to determine the transaction coordinator, then it is used; otherwise proximity is used to select the transaction coordinator. (This is the default behavior.)

    Proximity is determined as follows:

    1. Start with the value set for the Group parameter (default 55).

    2. For an API node sharing the same host with other API nodes, decrement the value by 1. Assuming the default value for Group, the effective value for data nodes on same host as the API node is 54, and for remote data nodes 55.

    3. Setting ndb_data_node_neighbour further decreases the effective Group value by 50, causing this node to be regarded as the nearest node. This is needed only when all data nodes are on hosts other than that hosts the API node and it is desirable to dedicate one of them to the API node. In normal cases, the default adjustment described previously is sufficient.

    Frequent changes in ndb_data_node_neighbour are not advisable, since this changes the state of the cluster connection and thus may disrupt the selection algorithm for new transactions from each thread until it stablilizes.

  • ndb_read_backup

    Command-Line Format --ndb-read-backup[={OFF|ON}]
    System Variable ndb_read_backup
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value (≥ 8.0.19-ndb-8.0.19) ON
    Default Value (≤ 8.0.18-ndb-8.0.18) OFF

    Enable read from any fragment replica for any NDB table subsequently created; doing so greatly improves the table read performance at a relatively small cost to writes.

    If the SQL node and the data node use the same host name or IP address, this fact is detected automatically, so that the preference is to send reads to the same host. If these nodes are on the same host but use different IP addresses, you can tell the SQL node to use the correct data node by setting the value of ndb_data_node_neighbour on the SQL node to the node ID of the data node.

    To enable or disable read from any fragment replica for an individual table, you can set the NDB_TABLE option READ_BACKUP for the table accordingly, in a CREATE TABLE or ALTER TABLE statement; see Setting NDB Comment Options, for more information.

  • ndb_recv_thread_activation_threshold

    Command-Line Format --ndb-recv-thread-activation-threshold=#
    System Variable ndb_recv_thread_activation_threshold
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 8
    Minimum Value 0 (MIN_ACTIVATION_THRESHOLD)
    Maximum Value 16 (MAX_ACTIVATION_THRESHOLD)

    When this number of concurrently active threads is reached, the receive thread takes over polling of the cluster connection.

    This variable is global in scope. It can also be set at startup.

  • ndb_recv_thread_cpu_mask

    Command-Line Format --ndb-recv-thread-cpu-mask=mask
    System Variable ndb_recv_thread_cpu_mask
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Bitmap
    Default Value [empty]

    CPU mask for locking receiver threads to specific CPUs. This is specified as a hexadecimal bitmask. For example, 0x33 means that one CPU is used per receiver thread. An empty string is the default; setting ndb_recv_thread_cpu_mask to this value removes any receiver thread locks previously set.

    This variable is global in scope. It can also be set at startup.

  • ndb_report_thresh_binlog_epoch_slip

    Command-Line Format --ndb-report-thresh-binlog-epoch-slip=#
    System Variable ndb_report_thresh_binlog_epoch_slip
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 10
    Minimum Value 0
    Maximum Value 256

    This represents the threshold for the number of epochs completely buffered in the event buffer, but not yet consumed by the binlog injector thread. When this degree of slippage (lag) is exceeded, an event buffer status message is reported, with BUFFERED_EPOCHS_OVER_THRESHOLD supplied as the reason (see Section 6.2.3, “Event Buffer Reporting in the Cluster Log”). Slip is increased when an epoch is received from data nodes and buffered completely in the event buffer; it is decreased when an epoch is consumed by the binlog injector thread, it is reduced. Empty epochs are buffered and queued, and so included in this calculation only when this is enabled using the Ndb::setEventBufferQueueEmptyEpoch() method from the NDB API.

  • ndb_report_thresh_binlog_mem_usage

    Command-Line Format --ndb-report-thresh-binlog-mem-usage=#
    System Variable ndb_report_thresh_binlog_mem_usage
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 10
    Minimum Value 0
    Maximum Value 10

    This is a threshold on the percentage of free memory remaining before reporting binary log status. For example, a value of 10 (the default) means that if the amount of available memory for receiving binary log data from the data nodes falls below 10%, a status message is sent to the cluster log.

  • ndb_row_checksum

    System Variable ndb_row_checksum
    Scope Global, Session
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 1
    Minimum Value 0
    Maximum Value 1

    Traditionally, NDB has created tables with row checksums, which checks for hardware issues at the expense of performance. Setting ndb_row_checksum to 0 means that row checksums are not used for new or altered tables, which has a significant impact on performance for all types of queries. This variable is set to 1 by default, to provide backward-compatible behavior.

  • ndb_schema_dist_lock_wait_timeout

    Command-Line Format --ndb-schema-dist-lock-wait-timeout=value
    Introduced 8.0.18-ndb-8.0.18
    System Variable ndb_schema_dist_lock_wait_timeout
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 30
    Minimum Value 0
    Maximum Value 1200
    Unit seconds

    Number of seconds to wait during schema distribution for the metadata lock taken on each SQL node in order to change its local data dictionary to reflect the DDL statement change. After this time has elapsed, a warning is returned to the effect that a given SQL node's data dictionary was not updated with the change. This avoids having the binary logging thread wait an excessive length of time while handling schema operations.

  • ndb_schema_dist_timeout

    Command-Line Format --ndb-schema-dist-timeout=value
    Introduced 8.0.16-ndb-8.0.16
    System Variable ndb_schema_dist_timeout
    Scope Global
    Dynamic No
    SET_VAR Hint Applies No
    Type Integer
    Default Value 120
    Minimum Value 5
    Maximum Value 1200
    Unit seconds

    Number of seconds to wait before detecting a timeout during schema distribution. This can indicate that other SQL nodes are experiencing excessive activity, or that they are somehow being prevented from acquiring necessary resources at this time.

  • ndb_schema_dist_upgrade_allowed

    Command-Line Format --ndb-schema-dist-upgrade-allowed=value
    Introduced 8.0.17-ndb-8.0.17
    System Variable ndb_schema_dist_upgrade_allowed
    Scope Global
    Dynamic No
    SET_VAR Hint Applies No
    Type Boolean
    Default Value true

    Allow upgrading of the schema distribution table when connecting to NDB. When true (the default), this change is deferred until all SQL nodes have been upgraded to the same version of the NDB Cluster software.

    Note

    The performance of the schema distribution may be somewhat degraded until the upgrade has been performed.

  • ndb_show_foreign_key_mock_tables

    Command-Line Format --ndb-show-foreign-key-mock-tables[={OFF|ON}]
    System Variable ndb_show_foreign_key_mock_tables
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value OFF

    Show the mock tables used by NDB to support foreign_key_checks=0. When this is enabled, extra warnings are shown when creating and dropping the tables. The real (internal) name of the table can be seen in the output of SHOW CREATE TABLE.

  • ndb_slave_conflict_role

    Command-Line Format --ndb-slave-conflict-role=value
    Deprecated 8.0.23-ndb-8.0.23
    System Variable ndb_slave_conflict_role
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Enumeration
    Default Value NONE
    Valid Values

    NONE

    PRIMARY

    SECONDARY

    PASS

    Deprecated in NDB 8.0.23, and subject to removal in a future release. Use ndb_conflict_role instead.

  • ndb_table_no_logging

    System Variable ndb_table_no_logging
    Scope Session
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value OFF

    When this variable is set to ON or 1, it causes all tables created or altered using ENGINE NDB to be nonlogging; that is, no data changes for this table are written to the redo log or checkpointed to disk, just as if the table had been created or altered using the NOLOGGING option for CREATE TABLE or ALTER TABLE.

    For more information about nonlogging NDB tables, see NDB_TABLE Options.

    ndb_table_no_logging has no effect on the creation of NDB table schema files; to suppress these, use ndb_table_temporary instead.

  • ndb_table_temporary

    System Variable ndb_table_temporary
    Scope Session
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value OFF

    When set to ON or 1, this variable causes NDB tables not to be written to disk: This means that no table schema files are created, and that the tables are not logged.

    Note

    Setting this variable currently has no effect. This is a known issue; see Bug #34036.

  • ndb_use_copying_alter_table

    System Variable ndb_use_copying_alter_table
    Scope Global, Session
    Dynamic No
    SET_VAR Hint Applies No

    Forces NDB to use copying of tables in the event of problems with online ALTER TABLE operations. The default value is OFF.

  • ndb_use_exact_count

    System Variable ndb_use_exact_count
    Scope Global, Session
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value OFF

    Forces NDB to use a count of records during SELECT COUNT(*) query planning to speed up this type of query. The default value is OFF, which allows for faster queries overall.

  • ndb_use_transactions

    Command-Line Format --ndb-use-transactions[={OFF|ON}]
    System Variable ndb_use_transactions
    Scope Global, Session
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value ON

    You can disable NDB transaction support by setting this variable's value to OFF. This is generally not recommended, although it may be useful to disable transaction support within a given client session when that session is used to import one or more dump files with large transactions; this allows a multi-row insert to be executed in parts, rather than as a single transaction. In such cases, once the import has been completed, you should either reset the variable value for this session to ON, or simply terminate the session.

  • ndb_version

    System Variable ndb_version
    Scope Global
    Dynamic No
    SET_VAR Hint Applies No
    Type String
    Default Value

    NDB engine version, as a composite integer.

  • ndb_version_string

    System Variable ndb_version_string
    Scope Global
    Dynamic No
    SET_VAR Hint Applies No
    Type String
    Default Value

    NDB engine version in ndb-x.y.z format.

  • replica_allow_batching

    Command-Line Format --replica-allow-batching[={OFF|ON}]
    Introduced 8.0.26-ndb-8.0.26
    System Variable replica_allow_batching
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value (≥ 8.0.30-ndb-8.0.30) ON
    Default Value (≤ 8.0.29-ndb-8.0.29) OFF

    Whether or not batched updates are enabled on NDB Cluster replicas. Beginning with NDB 8.0.26, you should use replica_allow_batching in place of slave_allow_batching, which is deprecated in that release.

    Allowing batched updates on the replica greatly improves performance, particularly when replicating TEXT, BLOB, and JSON columns. For this reason, replica_allow_batching is enabled by default in NDB 8.0.30 and later.

    Setting this variable has an effect only when using replication with the NDB storage engine; in MySQL Server 8.0, it is present but does nothing. For more information, see Section 7.6, “Starting NDB Cluster Replication (Single Replication Channel)”.

  • ndb_replica_batch_size

    Command-Line Format --ndb-replica-batch-size=#
    Introduced 8.0.30-ndb-8.0.30
    System Variable ndb_replica_batch_size
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 2097152
    Minimum Value 0
    Maximum Value 2147483648
    Unit bytes

    Determines the batch size in bytes used by the replication applier thread. In NDB 8.0.30 and later, set this variable rather than the --ndb-batch-size option to apply this setting to the replica, exclusive of any other sessions.

    If this variable is unset (default 2 MB), its effective value is the greater of the value of --ndb-batch-size and 2 MB.

  • ndb_replica_blob_write_batch_bytes

    Command-Line Format --ndb-replica-blob-write-batch-bytes=#
    Introduced 8.0.30-ndb-8.0.30
    System Variable ndb_replica_blob_write_batch_bytes
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 2097152
    Minimum Value 0
    Maximum Value 2147483648
    Unit bytes

    Control the batch write size used for blob data by the replication applier thread.

    Beginning with NDB 8.0.30, you should set this variable rather than the --ndb-blob-write-batch-bytes option to control the blob batch write size on the replica, exclusive of any other sessions. The reason for this is that, when ndb_replica_blob_write_batch_bytes​is not set,​the effective blob batch size (that is, the maximum number of pending bytes to write for blob columns) is determined by the greater of the value of --ndb-blob-write-batch-bytes and 2 MB (the default for ndb_replica_blob_write_batch_bytes).

    Setting ndb_replica_blob_write_batch_bytes to 0 means that NDB imposes no limit on the size of blob batch writes on the replica.

  • server_id_bits

    Command-Line Format --server-id-bits=#
    System Variable server_id_bits
    Scope Global
    Dynamic No
    SET_VAR Hint Applies No
    Type Integer
    Default Value 32
    Minimum Value 7
    Maximum Value 32

    This variable indicates the number of least significant bits within the 32-bit server_id which actually identify the server. Indicating that the server is actually identified by fewer than 32 bits makes it possible for some of the remaining bits to be used for other purposes, such as storing user data generated by applications using the NDB API's Event API within the AnyValue of an OperationOptions structure (NDB Cluster uses the AnyValue to store the server ID).

    When extracting the effective server ID from server_id for purposes such as detection of replication loops, the server ignores the remaining bits. The server_id_bits variable is used to mask out any irrelevant bits of server_id in the I/O and SQL threads when deciding whether an event should be ignored based on the server ID.

    This data can be read from the binary log by mysqlbinlog, provided that it is run with its own server_id_bits variable set to 32 (the default).

    If the value of server_id greater than or equal to 2 to the power of server_id_bits; otherwise, mysqld refuses to start.

    This system variable is supported only by NDB Cluster. It is not supported in the standard MySQL 8.0 Server.

  • slave_allow_batching

    Command-Line Format --slave-allow-batching[={OFF|ON}]
    Deprecated 8.0.26-ndb-8.0.26
    System Variable slave_allow_batching
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value (≥ 8.0.30-ndb-8.0.30) ON
    Default Value (≤ 8.0.29-ndb-8.0.29) OFF

    Whether or not batched updates are enabled on NDB Cluster replicas. Beginning with NDB 8.0.26, this variable is deprecated, and you should use replica_allow_batching instead.

    Allowing batched updates on the replica greatly improves performance, particularly when replicating TEXT, BLOB, and JSON columns. For this reason, replica_allow_batching is ON by default in NDB 8.0.30 and later. Also beginning with NDB 8.0.30, a warning is issued whenever this variable is set to OFF.

    Setting this variable has an effect only when using replication with the NDB storage engine; in MySQL Server 8.0, it is present but does nothing. For more information, see Section 7.6, “Starting NDB Cluster Replication (Single Replication Channel)”.

  • transaction_allow_batching

    System Variable transaction_allow_batching
    Scope Session
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value OFF

    When set to 1 or ON, this variable enables batching of statements within the same transaction. To use this variable, autocommit must first be disabled by setting it to 0 or OFF; otherwise, setting transaction_allow_batching has no effect.

    It is safe to use this variable with transactions that performs writes only, as having it enabled can lead to reads from the “before” image. You should ensure that any pending transactions are committed (using an explicit COMMIT if desired) before issuing a SELECT.

    Important

    transaction_allow_batching should not be used whenever there is the possibility that the effects of a given statement depend on the outcome of a previous statement within the same transaction.

    This variable is currently supported for NDB Cluster only.

The system variables in the following list all relate to the ndbinfo information database.

  • ndbinfo_database

    System Variable ndbinfo_database
    Scope Global
    Dynamic No
    SET_VAR Hint Applies No
    Type String
    Default Value ndbinfo

    Shows the name used for the NDB information database; the default is ndbinfo. This is a read-only variable whose value is determined at compile time.

  • ndbinfo_max_bytes

    Command-Line Format --ndbinfo-max-bytes=#
    System Variable ndbinfo_max_bytes
    Scope Global, Session
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 0
    Minimum Value 0
    Maximum Value 65535

    Used in testing and debugging only.

  • ndbinfo_max_rows

    Command-Line Format --ndbinfo-max-rows=#
    System Variable ndbinfo_max_rows
    Scope Global, Session
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Integer
    Default Value 10
    Minimum Value 1
    Maximum Value 256

    Used in testing and debugging only.

  • ndbinfo_offline

    System Variable ndbinfo_offline
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value OFF

    Place the ndbinfo database into offline mode, in which tables and views can be opened even when they do not actually exist, or when they exist but have different definitions in NDB. No rows are returned from such tables (or views).

  • ndbinfo_show_hidden

    Command-Line Format --ndbinfo-show-hidden[={OFF|ON}]
    System Variable ndbinfo_show_hidden
    Scope Global, Session
    Dynamic Yes
    SET_VAR Hint Applies No
    Type Boolean
    Default Value OFF
    Valid Values

    ON

    OFF

    Whether or not the ndbinfo database's underlying internal tables are shown in the mysql client. The default is OFF.

    Note

    When ndbinfo_show_hidden is enabled, the internal tables are shown in the ndbinfo database only; they are not visible in TABLES or other INFORMATION_SCHEMA tables, regardless of the variable's setting.

  • ndbinfo_table_prefix

    System Variable ndbinfo_table_prefix
    Scope Global
    Dynamic No
    SET_VAR Hint Applies No
    Type String
    Default Value ndb$

    The prefix used in naming the ndbinfo database's base tables (normally hidden, unless exposed by setting ndbinfo_show_hidden). This is a read-only variable whose default value is ndb$; the prefix itself is determined at compile time.

  • ndbinfo_version

    System Variable ndbinfo_version
    Scope Global
    Dynamic No
    SET_VAR Hint Applies No
    Type String
    Default Value

    Shows the version of the ndbinfo engine in use; read-only.


PREV   HOME   UP   NEXT
Related Documentation
MySQL 8.0 Reference Manual
MySQL 8.0 Release Notes
Download this Excerpt
PDF (US Ltr) - 4.8Mb
PDF (A4) - 4.8Mb