Skip to content

PXC-5210 [DOCS] - Set sql_require_primary_key=1 when using pxc_strict… #337

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
patrickbirch wants to merge 1 commit into
base: 8.4
Choose a base branch
from
Open

PXC-5210 [DOCS] - Set sql_require_primary_key=1 when using pxc_strict… #337

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 29 additions & 16 deletions docs/limitation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@ The following limitations apply to Percona XtraDB Cluster:

* Unsupported queries:

`LOCK TABLES` and `UNLOCK TABLES` is not supported in multi-source setups
- `LOCK TABLES` and `UNLOCK TABLES` are not supported in multi-source configurations.

Lock functions, such as `GET_LOCK()`, `RELEASE_LOCK()`, and so on
- Lock functions, such as `GET_LOCK()` and `RELEASE_LOCK()`, are not supported.

* Query log cannot be directed to table.

Expand All @@ -22,13 +22,17 @@ The following limitations apply to Percona XtraDB Cluster:

Use `general_log` and `general_log_file` to choose query logging and the log file name.

* Maximum allowed transaction size is defined by the [`wsrep_max_ws_rows`](wsrep-system-index.md#wsrep_max_ws_rows) and [`wsrep_max_ws_size`](wsrep-system-index.md#wsrep_max_ws_size) variables.
* Maximum allowed transaction size is defined by the [`wsrep_max_ws_rows`](wsrep-system-index.md#wsrep_max_ws_rows) and [`wsrep_max_ws_size`](wsrep-system-index.md#wsrep_max_ws_size) variables.

`LOAD DATA INFILE` processing will commit every 10 000 rows. So large transactions due to `LOAD DATA` will be split into a series of small transactions.
`LOAD DATA INFILE` processing commits every 10 000 rows.
Percona XtraDB Cluster splits large `LOAD DATA` transactions into a series of smaller transactions.

* Transaction issuing `COMMIT` may still be aborted at that stage.

Due to cluster-level optimistic concurrency control, there can be two transactions writing to the same rows and committing on separate Percona XtraDB Cluster nodes, and only one of them can successfully commit. The failing one will be aborted. For cluster-level aborts, Percona XtraDB Cluster returns a deadlock error code:
Cluster-level optimistic concurrency control allows two transactions to write to the same rows on separate Percona XtraDB Cluster nodes.
Only one of these transactions commits successfully.
The other transaction is aborted.
Percona XtraDB Cluster returns the following deadlock error code for cluster-level aborts:

??? example "Error message"

Expand All @@ -42,37 +46,46 @@ The following limitations apply to Percona XtraDB Cluster:

* Write throughput of the whole cluster is limited by the weakest node.

If one node becomes slow, the whole cluster slows down. If you have requirements for stable high performance, it should be supported by corresponding hardware.
A slow node slows the entire cluster.
Provision matching hardware on every node when you require stable high performance.

* Minimal recommended size of cluster is three nodes.
* The minimum recommended cluster size is three nodes.

The 3rd node can be an arbitrator.
The third node can act as an arbitrator.

* `enforce_storage_engine=InnoDB` is not compatible with `wsrep_replicate_myisam=OFF`

[`wsrep_replicate_myisam`](wsrep-system-index.md#wsrep_replicate_myisam) is set to `OFF` by default.

* Avoid `ALTER TABLE ... IMPORT/EXPORT` workloads when running Percona XtraDB Cluster in cluster mode.

It can lead to node inconsistency if not executed in sync on all nodes.
These statements can produce node inconsistency when not run in sync on every node.

* All tables must have a primary key.

This ensures that the same rows appear in the same order on different nodes. The `DELETE` statement is not supported on tables without a primary key.
A primary key keeps row order identical on every node.
The `DELETE` statement is not supported on tables without a primary key.

When [`pxc_strict_mode`](wsrep-system-index.md#pxc_strict_mode) is `ENFORCING` or `MASTER`, Percona XtraDB Cluster sets [`sql_require_primary_key` :octicons-link-external-16:](https://dev.mysql.com/doc/refman/{{vers}}/en/server-system-variables.html#sysvar_sql_require_primary_key) to `ON`.
The cluster rejects any attempt to set `sql_require_primary_key` to `OFF`.
`CREATE TABLE` and `ALTER TABLE` statements that would leave a table without a primary key fail.
For details, see [Primary key requirement](strict-mode.md#primary-key-requirement).

!!! admonition "See also"

[MariaDB Galera Documentation: Tables without Primary Keys :octicons-link-external-16:](https://mariadb.com/docs/server/server-usage/tables/mariadb-indexes-guide-1#finding-tables-without-primary-keys)

* When configuring Percona XtraDB Cluster, your server must create a local socket.

You can set up a socket by providing a path, or you can skip creating one explicitly. However, do not leave the <socket> variable in my.cnf empty, like this: `socket=`. If you do, the server won't create a socket.
Configure the socket by providing a path, or skip the explicit configuration to use the default.
Do not leave the `socket` variable in `my.cnf` empty, as in `socket=`.
An empty value prevents the server from creating a socket.

State Snapshot Transfer (SST) requires the socket for the following tasks:

* Taking backup using Percona XtraBackup
- Detecting keyring component status

* Detecting keyring component status
- Taking a backup with Percona XtraBackup

* Avoid reusing the names of persistent tables for temporary tables

Expand Down Expand Up @@ -117,9 +130,9 @@ The following limitations apply to Percona XtraDB Cluster:

For more information on the audit log filter, see the [Percona Server 8.4 Audit Log Filter overview :octicons-link-external-16:](https://docs.percona.com/percona-server/8.4/audit-log-filter-overview.html).

An INPLACE [ALTER TABLE :octicons-link-external-16:](https://dev.mysql.com/doc/refman/{{vers}}/en/alter-table.html) query takes an internal shared lock on the table during the execution of the query. Due to this change, the `LOCK=NONE` clause is no longer allowed for all `INPLACE ALTER TABLE` queries.

This change addresses a deadlock, which could cause a cluster node to hang in the following scenario:
An `INPLACE` [`ALTER TABLE` :octicons-link-external-16:](https://dev.mysql.com/doc/refman/{{vers}}/en/alter-table.html) query takes an internal shared lock on the table during query execution.
The `LOCK=NONE` clause is no longer allowed for any `INPLACE ALTER TABLE` query.
The lock change addresses a deadlock that could cause a cluster node to hang in the following scenario:

* An INPLACE `ALTER TABLE` query in one session or being applied as Total Order Isolation (TOI)

Expand Down
62 changes: 43 additions & 19 deletions docs/strict-mode.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -195,36 +195,60 @@ At runtime, any attempt to change [`wsrep_replicate_myisam`](wsrep-system-index.

The [`wsrep_replicate_myisam`](wsrep-system-index.md#wsrep_replicate_myisam) variable controls *replication* for MyISAM tables, and this validation only checks whether it is allowed. Undesirable operations for MyISAM tables are restricted using the Storage engine validation.

### Tables without primary keys
### Primary key requirement

Percona XtraDB Cluster cannot properly propagate certain write operations
to tables that do not have primary keys defined.
Undesirable operations include data manipulation statements
that perform writing to table (especially `DELETE`).
Percona XtraDB Cluster requires every replicated table to have an explicit primary key.
A missing primary key prevents write-set replication from guaranteeing identical row order across nodes.
The `DELETE` statement also fails on tables without a primary key.
For related guidance, see [Limitations](limitation.md) and [`wsrep_certify_nonPK`](wsrep-system-index.md#wsrep_certify_nonpk).

Depending on the selected mode, the following happens:
The [`sql_require_primary_key` :octicons-link-external-16:](https://dev.mysql.com/doc/refman/{{vers}}/en/server-system-variables.html#sysvar_sql_require_primary_key) variable rejects `CREATE TABLE` and `ALTER TABLE` statements that would leave a table without a primary key.
When [`pxc_strict_mode`](wsrep-system-index.md#pxc_strict_mode) is `ENFORCING` or `MASTER`, Percona XtraDB Cluster manages `sql_require_primary_key` to align both policies.

`DISABLED`
The following rules apply while [`pxc_strict_mode`](wsrep-system-index.md#pxc_strict_mode) is `ENFORCING` or `MASTER`:

At startup, no validation is performed.
* Switching to `ENFORCING` or `MASTER` sets the global `sql_require_primary_key` to `ON` when the previous value was `OFF`. The server log records the change:

At runtime, all operations are permitted.
```{.text .no-copy}
Setting sql_require_primary_key=ON because pxc_strict_mode is being changed to ENFORCING.
```

`PERMISSIVE`
* Setting `sql_require_primary_key=OFF` is rejected. Both `SET GLOBAL` and `SET SESSION` return the following error:

At startup, no validation is performed.
```{.text .no-copy}
ERROR 42000: Variable 'sql_require_primary_key' can't be set to the value of 'OFF'
```

At runtime, all operations are permitted,
but a warning is logged when an undesirable operation
is performed on a table without an explicit primary key defined.
The error log records the reason:

`ENFORCING` or `MASTER`
```{.text .no-copy}
Cannot set sql_require_primary_key=OFF while pxc_strict_mode is ENFORCING.
```

At startup, no validation is performed.
* Existing sessions retain their session value of `sql_require_primary_key`. Reconnect or update the session value explicitly to inherit the updated global default.

* Lowering [`pxc_strict_mode`](wsrep-system-index.md#pxc_strict_mode) to `DISABLED` or `PERMISSIVE` does not reset `sql_require_primary_key`. Set the variable explicitly to allow tables without a primary key.

The following table summarizes startup and runtime behavior by mode:

| Mode | Startup behavior | Runtime behavior |
|------------------------|-------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `DISABLED` | No validation runs. `sql_require_primary_key` keeps the configured value. | All operations are permitted. `sql_require_primary_key` accepts `ON` or `OFF`. |
| `PERMISSIVE` | No validation runs. `sql_require_primary_key` keeps the configured value. | All operations are permitted. A warning is logged for any undesirable operation on a table without an explicit primary key. `sql_require_primary_key` accepts `ON` or `OFF`. |
| `ENFORCING` / `MASTER` | If Galera is active and `sql_require_primary_key` is `OFF`, Percona XtraDB Cluster forces the value to `ON`. | Switching to this mode sets `sql_require_primary_key` to `ON` when the previous value was `OFF`. Setting `sql_require_primary_key=OFF` is rejected. Creating or altering a table without a primary key fails. |

??? example "Error message when creating or altering a table without a primary key"

```{.text .no-copy}
ERROR HY000: Unable to create or change a table without a primary key, when the system variable 'sql_require_primary_key' is set. Add a primary key to the table or unset this variable to avoid this message. Note that tables without a primary key can cause performance problems in row-based replication, so please consult your DBA before changing this setting.
```

!!! note

At runtime, any undesirable operation
performed on a table without an explicit primary key
is denied and an error is logged.
Replication applier threads use replicated session metadata for each event.
Events that originated on a non-strict source continue to apply on a strict-mode node.
The events apply even when the source had `sql_require_primary_key` set to `OFF`.
Use [`wsrep_certify_nonPK`](wsrep-system-index.md#wsrep_certify_nonpk) only as a fallback for existing tables without a primary key.

### Log output

Expand Down
52 changes: 27 additions & 25 deletions docs/wsrep-system-index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,40 +69,42 @@ For more information, see [Assisted Maintenance Mode](load-balance-proxysql.md#a
| Dynamic: | Yes |
| Default Value: | ``ENFORCING`` or ``DISABLED`` |

Controls [PXC Strict Mode](strict-mode.md#percona-xtradb-cluster-strict-mode), which runs validations to avoid the use of experimental and unsupported features in Percona XtraDB Cluster.
Controls [PXC Strict Mode](strict-mode.md#percona-xtradb-cluster-strict-mode).
Strict Mode runs validations that block experimental and unsupported features in Percona XtraDB Cluster.

Depending on the actual mode you select, upon encountering a failed validation, the server will either throw an error (halting startup or denying the operation) or log a warning and continue running as normal.
The following modes are available:
When a validation fails, the server takes one of the following actions:

* `DISABLED`: Do not perform strict mode validations
and run as normal.
* Throw an error and halt startup or deny the operation.

* `PERMISSIVE`: If a validation fails, log a warning and continue running
as normal.
* Log a warning and continue running.

* `ENFORCING`: If a validation fails during startup, halt the server and throw an error.
If a validation fails during runtime,
deny the operation and throw an error.
The action depends on the selected mode. The following modes are available:

* `MASTER`: The same as `ENFORCING` except that the validation of
[explicit table locking](strict-mode.md#explicit-table-locking) is not performed.
This mode can be used with clusters in which write operations are isolated to a single node.
* `DISABLED`: skip strict mode validations and run normally.

By default, [`pxc_strict_mode`](wsrep-system-index.md#pxc_strict_mode) is set to `ENFORCING`,
except if the node is acting as a standalone server
or the node is bootstrapping, then [`pxc_strict_mode`](wsrep-system-index.md#pxc_strict_mode) defaults to `DISABLED`.
* `PERMISSIVE`: log a warning when a validation fails, then continue running.

* `ENFORCING`: throw an error on validation failure. Halt the server at startup. Deny the operation at runtime.

* `MASTER`: behave as `ENFORCING` but skip the [explicit table locking](strict-mode.md#explicit-table-locking) validation. Use this mode with clusters in which write operations are isolated to a single node.

By default, [`pxc_strict_mode`](wsrep-system-index.md#pxc_strict_mode) is set to `ENFORCING`.
The variable defaults to `DISABLED` when the node acts as a standalone server or during bootstrapping.

!!! note

When changing the value of `pxc_strict_mode`
from `DISABLED` or `PERMISSIVE` to `ENFORCING` or `MASTER`,
ensure that the following configuration is used:

* `wsrep_replicate_myisam=OFF`

* `log_output=FILE` or `log_output=NONE` or `log_output=FILE,NONE`

The `SERIALIZABLE` method of isolation is not allowed in `ENFORCING` mode.
When changing `pxc_strict_mode` from `DISABLED` or `PERMISSIVE` to `ENFORCING` or `MASTER`, apply the following configuration:

* `log_output=FILE`, `NONE`, or `FILE,NONE`

* `wsrep_replicate_myisam=OFF`

The `SERIALIZABLE` isolation level is not allowed in `ENFORCING` mode.

Switching to `ENFORCING` or `MASTER` also sets [`sql_require_primary_key` :octicons-link-external-16:](https://dev.mysql.com/doc/refman/{{vers}}/en/server-system-variables.html#sysvar_sql_require_primary_key) to `ON` when the previous value was `OFF`.
Setting `sql_require_primary_key=OFF` is rejected while strict mode remains `ENFORCING` or `MASTER`.
Existing sessions retain their session value until each session reconnects or updates the value explicitly.
For details, see [Primary key requirement](strict-mode.md#primary-key-requirement).

For more information, see [PXC Strict Mode](strict-mode.md#percona-xtradb-cluster-strict-mode).

Expand Down
Loading