Skip to content

Commit e442fa9

Browse files
authored
PS-9797 [DOCS] - update enforce-engine 8.0 (#508)
modified: docs/enforce-engine.md
1 parent 706a2e8 commit e442fa9

File tree

1 file changed

+90
-20
lines changed

1 file changed

+90
-20
lines changed

docs/enforce-engine.md

Lines changed: 90 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,24 @@
1-
# Enforcing storage engine
1+
# Enforce storage engine
22

3-
*Percona Server for MySQL* has implemented variable which can be used for enforcing the
4-
use of a specific storage engine.
3+
Percona Server for MySQL lets you enforce a specific storage engine for table creation. You do this with the [`enforce_storage_engine`](#enforce_storage_engine) variable.
54

6-
When this variable is specified and a user tries to create a table using an
7-
explicit storage engine that is not the specified enforced engine, the user
8-
will get either an error if the `NO_ENGINE_SUBSTITUTION` SQL mode is enabled
9-
or a warning if `NO_ENGINE_SUBSTITUTION` is disabled and the table
10-
will be created anyway using the enforced engine (this is consistent with the
11-
default *MySQL* way of creating the default storage engine if other engines
12-
are not available unless `NO_ENGINE_SUBSTITUTION` is set).
5+
## Benefits
136

14-
In case user tries to enable [enforce_storage_engine](#enforce_storage_engine) with engine that isn’t available, system will not start.
7+
The option allows you to enforce a specific storage engine for all table creations. This ability can be useful for:
158

16-
!!! note
179

18-
If you’re using enforce_storage_engine, you must either disable
19-
it before doing `mysql_upgrade` or perform `mysql_upgrade` with server
20-
started with `--skip-grants-tables`.
10+
When `enforce_storage_engine` is set, Percona Server behaves as follows:
2111

22-
## Version specific information
12+
| Benefit | Description |
13+
|------------------------|-------------------------------------------------------------------------------------------------|
14+
| Ensuring consistency | Prevents creating tables with different storage engines, ensuring consistent behavior and performance. |
15+
| Simplifying administration | Centralizing the storage engine selection streamlines database administration procedures. |
16+
| Optimizing performance | Improves performance when an application is designed for a specific storage engine. |
17+
| Compliance | Enforces a specific storage engine to meet regulatory or compliance requirements. |
2318

24-
* [Percona Server for MySQL 8.0.13-4](release-notes/Percona-Server-8.0.13-4.md#id1): The feature was ported from *Percona Server for MySQL* 5.7.
19+
## Version information
20+
21+
* [Percona Server for MySQL 8.0.13-4](release-notes/Percona-Server-8.0.13-4.md#id1): The feature was ported from Percona Server for MySQL 5.7.
2522

2623
## System variables
2724

@@ -36,12 +33,85 @@ In case user tries to enable [enforce_storage_engine](#enforce_storage_engine) w
3633
| Data type | String |
3734
| Default value | NULL |
3835

39-
This variable is not case sensitive.
36+
This variable is not case-sensitive.
37+
38+
When `enforce_storage_engine` is set, the server enforces specfic rules for table creation.
39+
40+
If [`NO_ENGINE_SUBSTITUTION`](https://dev.mysql.com/doc/refman/8.0/en/sql-mode.html#sqlmode_no_engine_substitution) SQL mode is enabled.
41+
42+
The server enforces strict storage engine rules during table creation. If you specify a storage engine that differs from the enforced engine, the server will do the following:
43+
44+
* Generates an error
45+
46+
* Does not create a table
47+
48+
If [`NO_ENGINE_SUBSTITUTION`](https://dev.mysql.com/doc/refman/8.0/en/sql-mode.html#sqlmode_no_engine_substitution) SQL mode is disabled.
49+
50+
When you specify a storage engine that differs from the enforced engine, the server does the following:
51+
52+
* Creates the table using the enforced storage engine
53+
54+
* Issues a warning about engine substitution
55+
56+
You can check the current SQL mode settings:
57+
58+
```{.bash data-prompt="mysql>"}
59+
mysql> SELECT @sql_mode;
60+
```
61+
62+
The server requires a valid storage engine setting for `enforce_storage_engine`. If the storage engine is not available, the server does not start.
63+
64+
You can check the available storage engines with the following command:
65+
66+
```{.bash data-prompt="mysql>"}
67+
mysql> SHOW ENGINES;
68+
```
69+
70+
??? example "Expected output"
71+
72+
```{.text .no-copy}
73+
Engine | Support | Comment
74+
------------|---------|------------------
75+
InnoDB | DEFAULT | Supports transactions, foreign keys
76+
MyISAM | YES | MySQL storage engine
77+
MEMORY | YES | Hash based, stored in memory
78+
CSV | YES | CSV storage engine
79+
ARCHIVE | YES | Archive storage engine
80+
```
81+
82+
The `Support` column indicates the following:
83+
84+
* `DEFAULT`: The default engine
85+
86+
* `YES`: Engine is supported
87+
88+
* `NO`: Engine is not supported
89+
90+
* `DISABLED`: Engine is disabled
91+
92+
93+
!!! important
94+
95+
If you use `enforce_storage_engine`, you must either disable
96+
it before doing `mysql_upgrade` or run `mysql_upgrade` with the server
97+
started with the `--skip-grants-tables` option.
98+
4099

41100
## Example
42101

43-
Adding following option to [my.cnf](glossary.md#my.cnf) will start the server with InnoDB as enforced storage engine.
102+
To enforce the InnoDB storage engine, add this option to your [my.cnf](glossary.md#my.cnf) file:
103+
104+
```ini
44105

45-
```text
106+
[mysqld]
46107
enforce_storage_engine=InnoDB
108+
109+
```
110+
111+
Changes to the `my.cnf` do not affect a running server. You must restart the server for the change to take effect:
112+
113+
```{.bash data-prompt="$"}
114+
$ sudo systemctl restart mysqld
47115
```
116+
117+

0 commit comments

Comments
 (0)