├── .gitignore ├── docs ├── css │ ├── nocopy.css │ ├── extra.css │ ├── rating.css │ └── mysql.css ├── _static │ ├── mkdocs.png │ ├── new-topic.png │ ├── pdf-logo.png │ ├── auth-plugin.png │ ├── jira-ticket.png │ ├── create-issue.png │ ├── percona-xtradb.png │ ├── confirm-password.png │ ├── percona-favicon.ico │ ├── percona-favicon.png │ ├── strong-password.png │ ├── Percona_Logo_Color.png │ ├── percona-mysql-logo.png │ ├── mysql-authentication.png │ ├── percona-favicon.svg │ └── percona-logo.svg ├── fonts │ ├── Poppins-Light.ttf │ ├── Poppins-Italic.ttf │ ├── Poppins-Medium.ttf │ ├── Poppins-Regular.ttf │ ├── Poppins-SemiBold.ttf │ ├── Poppins-LightItalic.ttf │ ├── Poppins-MediumItalic.ttf │ └── Poppins-SemiBoldItalic.ttf ├── js │ ├── consent.js │ ├── version-select.js │ └── promptremover.js ├── ssl-improvement.md ├── encrypt-doublewrite-file-pages.md ├── uninstall-js-lang.md ├── release-notes │ ├── 8.4.1.md │ └── release-notes-index.md ├── templates │ └── pdf_cover_page.tpl ├── install-component.md ├── audit-log-filter-security.md ├── extended-select-into-outfile.md ├── encrypt-system-tablespace.md ├── log-connection-error.md ├── source-tarball.md ├── uninstall-audit-log-filter.md ├── uninstall-data-masking-component.md ├── apt-pinning.md ├── copyright-and-licensing-information.md ├── yum-uninstall.md ├── keyring-components-plugins-overview.md ├── install-js-lang.md ├── encrypt-file-per-table-tablespace.md ├── disable-audit-log-filter.md ├── js-lang-privileges.md ├── myrocks-gap-locks-detection.md ├── uninstall-component.md ├── binary-tarball-install.md ├── extended-set-var.md ├── apt-uninstall-server.md ├── performance-schema-myrocks-changes.md ├── myrocks-added-features.md ├── server-version-numbers.md ├── advisors.md ├── use-keyring-file.md ├── ai-docs.md ├── thread-based-profiling.md ├── percona-xtradb.md ├── udf-percona-toolkit.md ├── myrocks-differences.md ├── js-lang-procedures.md ├── rotate-master-key.md ├── prefix-index-queries-optimization.md ├── extended-mysqldump.md ├── sql-basics.md ├── binlog-space.md ├── download-instructions.md ├── installation.md ├── psmysql-pro.md ├── index-info-schema-tables.md ├── manage-audit-log-filter.md ├── reading-audit-log-filter-files.md ├── audit-log-filter-formats.md ├── additional-selinux-tools.md ├── install-data-masking-component.md ├── apt-run.md ├── stacktrace.md ├── js-lang-troubleshoot.md ├── enforce-engine.md ├── modify-tables.md ├── build-apt-packages.md ├── assets │ ├── mysql-mark.svg │ └── mysql-fav.svg ├── yum-run.md ├── disable-apparmor.md ├── myrocks-index.md ├── apparmor.md ├── log-warnings-suppress.md ├── apt-download-deb.md ├── show-engines.md ├── group-replication-flow-control.md ├── aio-page-requests.md ├── compile-percona-server.md ├── percona-toolkit-8.4-updates.md ├── faq.md ├── proxy-protocol-support.md ├── adaptive-network-buffers.md ├── innodb-fts-improvements.md ├── downgrade-from-pro.md ├── quickstart-overview.md ├── apt-files.md ├── select.md ├── using-kmip.md ├── encrypt-binary-relay-log-files.md ├── audit-log-filter-naming.md ├── audit-log-filter-restrictions.md ├── binary-tarball-names.md ├── sql-errors.md ├── index.md ├── troubleshoot-apparmor.md ├── delete.md ├── docker-config.md ├── slowlog-rotation.md ├── telemetry.md ├── troubleshooting-sql.md ├── audit-log-filter-overview.md ├── data-at-rest-encryption.md ├── create-table.md ├── apparmor-profiles.md ├── innodb-fragmentation-count.md ├── mysql-upgrade-paths.md ├── yum-files.md ├── innodb-corrupt-table-action.md ├── innodb-io.md ├── isolation-levels.md ├── pro-files.md ├── downgrade.md └── development.md ├── snippets ├── get-help-snip.md ├── storage-engines.md ├── percona-release.md ├── pro-build-announcement.md ├── experimental.md ├── install-flag.md ├── tech.preview.md └── keyring-components-installation.md ├── _resource ├── .icons │ ├── edit_page.png │ ├── file-document-edit-outline.svg │ ├── file-eye-outline.svg │ ├── percona │ │ └── logo.svg │ └── groups.svg ├── overrides │ ├── 404.html │ └── partials │ │ └── source-file.html └── templates │ └── styles.scss ├── variables.yml ├── _resourcepdf └── overrides │ ├── 404.html │ └── partials │ ├── edit.html │ ├── copyright.html │ └── banner.html ├── mkdocs.yml ├── requirements.txt ├── mkdocs-percona.yml ├── db_terms.txt ├── archive ├── extended-mysqlbinlog.md └── upgrade-myrocks.md ├── README.md ├── .github └── workflows │ └── main.yml └── scripts └── generate_index.py /.gitignore: -------------------------------------------------------------------------------- 1 | **/.DS_Store 2 | COMMIT_MESSAGE 3 | site/ -------------------------------------------------------------------------------- /docs/css/nocopy.css: -------------------------------------------------------------------------------- 1 | .highlight.no-copy .md-clipboard { display: none; } -------------------------------------------------------------------------------- /snippets/get-help-snip.md: -------------------------------------------------------------------------------- 1 | Review [Get more help](get-help.md) for ways that we can work with you. -------------------------------------------------------------------------------- /docs/_static/mkdocs.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/percona/psmysql-docs/HEAD/docs/_static/mkdocs.png -------------------------------------------------------------------------------- /docs/_static/new-topic.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/percona/psmysql-docs/HEAD/docs/_static/new-topic.png -------------------------------------------------------------------------------- /docs/_static/pdf-logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/percona/psmysql-docs/HEAD/docs/_static/pdf-logo.png -------------------------------------------------------------------------------- /docs/_static/auth-plugin.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/percona/psmysql-docs/HEAD/docs/_static/auth-plugin.png -------------------------------------------------------------------------------- /docs/_static/jira-ticket.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/percona/psmysql-docs/HEAD/docs/_static/jira-ticket.png -------------------------------------------------------------------------------- /docs/fonts/Poppins-Light.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/percona/psmysql-docs/HEAD/docs/fonts/Poppins-Light.ttf -------------------------------------------------------------------------------- /_resource/.icons/edit_page.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/percona/psmysql-docs/HEAD/_resource/.icons/edit_page.png -------------------------------------------------------------------------------- /docs/_static/create-issue.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/percona/psmysql-docs/HEAD/docs/_static/create-issue.png -------------------------------------------------------------------------------- /docs/_static/percona-xtradb.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/percona/psmysql-docs/HEAD/docs/_static/percona-xtradb.png -------------------------------------------------------------------------------- /docs/fonts/Poppins-Italic.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/percona/psmysql-docs/HEAD/docs/fonts/Poppins-Italic.ttf -------------------------------------------------------------------------------- /docs/fonts/Poppins-Medium.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/percona/psmysql-docs/HEAD/docs/fonts/Poppins-Medium.ttf -------------------------------------------------------------------------------- /docs/fonts/Poppins-Regular.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/percona/psmysql-docs/HEAD/docs/fonts/Poppins-Regular.ttf -------------------------------------------------------------------------------- /docs/fonts/Poppins-SemiBold.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/percona/psmysql-docs/HEAD/docs/fonts/Poppins-SemiBold.ttf -------------------------------------------------------------------------------- /docs/_static/confirm-password.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/percona/psmysql-docs/HEAD/docs/_static/confirm-password.png -------------------------------------------------------------------------------- /docs/_static/percona-favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/percona/psmysql-docs/HEAD/docs/_static/percona-favicon.ico -------------------------------------------------------------------------------- /docs/_static/percona-favicon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/percona/psmysql-docs/HEAD/docs/_static/percona-favicon.png -------------------------------------------------------------------------------- /docs/_static/strong-password.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/percona/psmysql-docs/HEAD/docs/_static/strong-password.png -------------------------------------------------------------------------------- /docs/_static/Percona_Logo_Color.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/percona/psmysql-docs/HEAD/docs/_static/Percona_Logo_Color.png -------------------------------------------------------------------------------- /docs/_static/percona-mysql-logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/percona/psmysql-docs/HEAD/docs/_static/percona-mysql-logo.png -------------------------------------------------------------------------------- /docs/fonts/Poppins-LightItalic.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/percona/psmysql-docs/HEAD/docs/fonts/Poppins-LightItalic.ttf -------------------------------------------------------------------------------- /docs/fonts/Poppins-MediumItalic.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/percona/psmysql-docs/HEAD/docs/fonts/Poppins-MediumItalic.ttf -------------------------------------------------------------------------------- /docs/_static/mysql-authentication.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/percona/psmysql-docs/HEAD/docs/_static/mysql-authentication.png -------------------------------------------------------------------------------- /docs/fonts/Poppins-SemiBoldItalic.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/percona/psmysql-docs/HEAD/docs/fonts/Poppins-SemiBoldItalic.ttf -------------------------------------------------------------------------------- /docs/js/consent.js: -------------------------------------------------------------------------------- 1 | var consent = __md_get("__consent") 2 | if (consent && consent.custom) { 3 | /* The user accepted the cookie */ 4 | } else { 5 | /* The user rejected the cookie */ 6 | } 7 | -------------------------------------------------------------------------------- /snippets/storage-engines.md: -------------------------------------------------------------------------------- 1 | 2 | Percona Server for MySQL 8.4.x comes with the MyRocks storage engine. This storage engine is installed as a plugin. For information on installing and configuring MyRocks, refer to the [Percona MyRocks Installation Guide](install-myrocks.md). 3 | -------------------------------------------------------------------------------- /docs/ssl-improvement.md: -------------------------------------------------------------------------------- 1 | # SSL improvements 2 | 3 | Percona Server for MySQL passes Elliptic Curve Cryptography (ECC) ciphers to OpenSSL by default. 4 | 5 | !!! note 6 | 7 | Although documented as supported, elliptic-curve crypto-based ciphers do not work with *MySQL*. 8 | -------------------------------------------------------------------------------- /docs/encrypt-doublewrite-file-pages.md: -------------------------------------------------------------------------------- 1 | # Encrypt doublewrite file pages 2 | 3 | InnoDB encrypts doublewrite file pages associated with encrypted tablespaces automatically. Doublewrite files can contain the following page types: 4 | 5 | * Unencrypted 6 | * Uncompressed 7 | * Encrypted 8 | * Compressed 9 | -------------------------------------------------------------------------------- /_resource/.icons/file-document-edit-outline.svg: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /variables.yml: -------------------------------------------------------------------------------- 1 | # variables for HTML output 2 | 3 | release: '8.4.6-6' 4 | version: '8.4' 5 | vers: '8.4' # we are going to use it instead of version 6 | pkg: 'ps-84-lts' 7 | pro_release: '8.4.6-6' 8 | tag: '8.4.6' 9 | arm_tag: '8.4.6-aarch64' 10 | year_tag: '2025' 11 | release_date: '2025-09-08' 12 | title_date: '2025-09-08' 13 | -------------------------------------------------------------------------------- /docs/uninstall-js-lang.md: -------------------------------------------------------------------------------- 1 | # Uninstall the js_lang component 2 | 3 | The uninstall works only when no connections are using JavaScript stored programs. If there are connections, the procedure fails with an error. 4 | 5 | To remove the component, run the following: 6 | 7 | ```{.bash data-prompt="mysql>"} 8 | mysql> UNINSTALL COMPONENT 'file://component_js_lang'; 9 | ``` -------------------------------------------------------------------------------- /snippets/percona-release.md: -------------------------------------------------------------------------------- 1 | The `percona-release` tool is a command-line utility that simplifies the management and installation of Percona software packages, providing access to the latest versions and ensuring consistency across environments. For more information, refer to the [Percona Software Repositories Documentation](https://docs.percona.com/percona-software-repositories/index.html). -------------------------------------------------------------------------------- /_resource/overrides/404.html: -------------------------------------------------------------------------------- 1 | {#- 2 | This file was automatically generated - do not edit 3 | -#} 4 | {% extends "main.html" %} 5 | {% block content %} 6 |

404 - Not found

7 |

8 | We can't find the page you are looking for. Try using the Search or return to homepage .

9 | {% endblock %} 10 | -------------------------------------------------------------------------------- /docs/release-notes/8.4.1.md: -------------------------------------------------------------------------------- 1 | # Percona Server for MySQL 8.4.1 2 | 3 | Due to a critical fix, MySQL Community Server 8.4.2 was released shortly (22 days later) after MySQL Community Server 8.4.1. Percona has skipped the release of Percona Server for MySQL 8.4.1. Percona Server for MySQL 8.4.2-2 contains all bug fixes and contents from MySQL Community Server 8.4.1 and MySQL Community Server 8.4.2. 4 | -------------------------------------------------------------------------------- /_resourcepdf/overrides/404.html: -------------------------------------------------------------------------------- 1 | {#- 2 | This file was automatically generated - do not edit 3 | -#} 4 | {% extends "main.html" %} 5 | {% block content %} 6 |

404 - Not found

7 |

8 | We can't find the page you are looking for. Try using the Search or return to homepage .

9 | {% endblock %} -------------------------------------------------------------------------------- /docs/templates/pdf_cover_page.tpl: -------------------------------------------------------------------------------- 1 | 2 | {{ config.extra.added_key }} 3 |

4 | 5 |

6 |

Percona Server for MySQL

7 | {% if config.site_description %} 8 |

{{ config.site_description }}

9 | {% endif %} 10 |

8.4.6-6 (September 08, 2025)

11 | -------------------------------------------------------------------------------- /snippets/pro-build-announcement.md: -------------------------------------------------------------------------------- 1 | Percona Server for MySQL Pro includes the [capabilities](psmysql-pro.md#capabilities) that are typically requested by large enterprises. Percona Server for MySQL Pro contains packages created and tested by Percona. These packages are supported only for Percona Customers with a subscription. 2 | 3 | [Become a Percona Customer](https://www.percona.com/about/contact){.md-button} 4 | -------------------------------------------------------------------------------- /mkdocs.yml: -------------------------------------------------------------------------------- 1 | # MkDocs configuration for PDF builds 2 | # Usage: mkdocs build -f mkdocs-pdf.yml 3 | 4 | INHERIT: mkdocs-base.yml 5 | 6 | site_url: "https://docs.percona.com/percona-server/" 7 | 8 | # Material theme features 9 | theme: 10 | name: material 11 | custom_dir: _resourcepdf/overrides/ 12 | 13 | extra: 14 | # Google Analytics configuration 15 | analytics: 16 | provider: google 17 | property: G-J4J70BNH0G 18 | -------------------------------------------------------------------------------- /_resource/.icons/file-eye-outline.svg: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | Markdown 2 | mkdocs 3 | mkdocs-versioning 4 | mkdocs-macros-plugin 5 | mkdocs-exclude 6 | markdown-include 7 | mkdocs-material 8 | mkdocs-with-pdf 9 | mkdocs-material-extensions 10 | mkdocs-bootstrap-tables-plugin 11 | mkdocs-section-index 12 | mkdocs-htmlproofer-plugin 13 | mkdocs-meta-descriptions-plugin 14 | mike 15 | mkdocs-open-in-new-tab 16 | mkdocs-print-site-plugin 17 | mkdocs-git-committers-plugin-2 18 | mkdocs-git-revision-date-localized-plugin -------------------------------------------------------------------------------- /_resourcepdf/overrides/partials/edit.html: -------------------------------------------------------------------------------- 1 |
2 |
3 | 4 | 5 | {% set icon = config.theme.icon.edit or "material/file-edit-outline" %} 6 | {% include ".icons/" ~ icon ~ ".svg" %} 7 | 8 | Edit this page on GitHub 9 | 10 |
11 |
-------------------------------------------------------------------------------- /snippets/experimental.md: -------------------------------------------------------------------------------- 1 | **This feature is in the experimental phase. An experimental feature is included in an experimental release for users to provide feedback. The feature is either updated, released as general availability(GA), or removed if not useful. The functionality can change from experimental to GA.** 2 | 3 | **The feature is only available in the Percona experimental repository. You should review the [Percona release configuration instructions](https://docs.percona.com/percona-software-repositories/percona-release.html)** -------------------------------------------------------------------------------- /docs/install-component.md: -------------------------------------------------------------------------------- 1 | # INSTALL COMPONENT 2 | 3 | The `INSTALL COMPONENT` does the following: 4 | 5 | * Installs the component 6 | * Activates the component 7 | 8 | If an error, such as a misspelled component name, occurs, the statement fails and nothing happens. 9 | 10 | You can install multiple components at the same time. 11 | 12 | ## Example 13 | 14 | The following is an example of the `INSTALL COMPONENT` statement. 15 | 16 | ```{.bash data-prompt="mysql>"} 17 | mysql> INSTALL COMPONENT 'file://componentA'; 18 | ``` -------------------------------------------------------------------------------- /docs/release-notes/release-notes-index.md: -------------------------------------------------------------------------------- 1 | # Percona Server for MySQL {{vers}} release notes index 2 | 3 | * [Percona Server for MySQL 8.4.6-6 (2025-09-08)](8.4.6-6.md) 4 | 5 | * [Percona Server for MySQL 8.4.5-5 (2025-05-29)](8.4.5-5.md) 6 | 7 | * [Percona Server for MySQL 8.4.4-4 (2025-03-18)](8.4.4-4.md) 8 | 9 | * [Percona Server for MySQL 8.4.3-3 (2024-12-18)](8.4.3-3.md) 10 | 11 | * [Percona Server for MySQL 8.4.2-2 (2024-11-04)](8.4.2-2.md) 12 | 13 | * [Percona Server for MySQL 8.4.1](8.4.1.md) 14 | 15 | * [Percona Server for MySQL 8.4.0-1 (2024-08-28)](8.4.0-1.md) 16 | 17 | 18 | 19 | 20 | -------------------------------------------------------------------------------- /_resource/.icons/percona/logo.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | -------------------------------------------------------------------------------- /mkdocs-percona.yml: -------------------------------------------------------------------------------- 1 | # MkDocs configuration for Percona website builds 2 | 3 | INHERIT: mkdocs-base.yml 4 | 5 | site_url: "https://docs.percona.com/percona-server/innovation-release/index.html" 6 | 7 | plugins: 8 | bootstrap-tables: {} 9 | 10 | theme: 11 | name: material 12 | custom_dir: _resource/theme 13 | 14 | extra_css: 15 | - css/version-select.css 16 | - css/toctree.css 17 | - css/percona.css 18 | - css/details.css 19 | 20 | extra: # Used in main.html template and can't be externalized 21 | edit_page_text: ' Edit this page' 22 | updated_text: ' Page updated' 23 | -------------------------------------------------------------------------------- /docs/audit-log-filter-security.md: -------------------------------------------------------------------------------- 1 | # Audit Log Filter security 2 | 3 | The Audit Log Filter component generates audit log filter files. The directory 4 | that contains these files should be accessible only to the following: 5 | 6 | * Users who must be able to view the log 7 | 8 | * Server must be able to write to the directory 9 | 10 | The files are not encrypted by default and may contain sensitive information. 11 | 12 | The default name for the file in the data directory is `audit_filter.log`. If needed, use the `audit_log_filter.file` system variable at server startup to change the location. Due to the log rotation, multiple audit log files may exist. 13 | -------------------------------------------------------------------------------- /docs/extended-select-into-outfile.md: -------------------------------------------------------------------------------- 1 | # Extended SELECT INTO OUTFILE/DUMPFILE 2 | 3 | Percona Server for MySQL extends the `SELECT INTO ... OUTFILE` and `SELECT INTO 4 | DUMPFILE` [commands] to add support for UNIX sockets and named pipes. Before this was implemented 5 | the database would return an error for such files. 6 | 7 | This feature allows using `LOAD DATA LOCAL INFILE` in combination with 8 | `SELECT INTO OUTFILE` to quickly load multiple partitions across the network 9 | or in other setups, without having to use an intermediate file that wastes 10 | space and I/O. 11 | 12 | [commands]: https://dev.mysql.com/doc/refman/{{vers}}/en/select-into.html 13 | -------------------------------------------------------------------------------- /docs/encrypt-system-tablespace.md: -------------------------------------------------------------------------------- 1 | # Encrypt system tablespace 2 | 3 | By default, the system tablespace, which contains the system database and the data dictionary tables, is unencrypted. To change the encryption requires the `CREATE TABLESPACE` privilege on all tables in the instance. 4 | 5 | In an `ALTER TABLESPCE` statement, add the `ENCRYPTION` option with the tablespace name to enable encryption. 6 | 7 | ```{.bash data-prompt="mysql>"} 8 | mysql> ALTER TABLESPACE mysql ENCRYPTION='Y'; 9 | ``` 10 | Disable encryption by setting the `ENCRYPTION` option to 'N". 11 | 12 | ```{.bash data-prompt="mysql>"} 13 | mysql> ALTER TABLESPACE mysql ENCRYPTION='N'; 14 | ``` 15 | -------------------------------------------------------------------------------- /docs/log-connection-error.md: -------------------------------------------------------------------------------- 1 | # Too many connections warning 2 | 3 | If the [log_error_verbosity] system variable is set to `2` or higher, this 4 | feature generates the `Too many connections` warning in the log. 5 | 6 | !!! tip "Troubleshooting Connection Issues" 7 | For comprehensive guidance on managing database connections and 8 | performance, [Percona Support](https://www.percona.com/services/support) 9 | can provide expert assistance in diagnosing and resolving connection 10 | management challenges. 11 | 12 | [log_error_verbosity]: https://dev.mysql.com/doc/refman/{{vers}}/en/server-system- 13 | variables.html#sysvar_log_error_verbosity 14 | 15 | -------------------------------------------------------------------------------- /docs/source-tarball.md: -------------------------------------------------------------------------------- 1 | # Install Percona Server for MySQL from a source tarball 2 | 3 | Fetch and extract the source tarball. For example: 4 | 5 | ```{.bash data-prompt="$"} 6 | $ wget https://downloads.percona.com/downloads/Percona-Server-innovative-release/Percona-Server-{{release}}/binary/tarball/Percona-Server-{{release}}-Linux.x86_64.glibc2.35.tar.gz 7 | ``` 8 | 9 | Unpack the download to get the packages: 10 | 11 | ```{.bash data-prompt="$"} 12 | $ tar xfz Percona-Server-{{release}}-Linux.x86_64.glibc2.35.tar.gz 13 | ``` 14 | 15 | To complete the installation, follow the instructions in [Compile Percona Server for MySQL from Source](compile-percona-server.md). 16 | -------------------------------------------------------------------------------- /docs/uninstall-audit-log-filter.md: -------------------------------------------------------------------------------- 1 | # Uninstall Audit Log Filter 2 | 3 | If you no longer need the audit log filter functionality, you can remove the component from server using the following command: 4 | 5 | ```{.bash data-prompt="mysql>"} 6 | mysql> UNINSTALL COMPONENT 'file://component_audit_log_filter'; 7 | ``` 8 | 9 | This command does the following: 10 | 11 | * `UNINSTALL COMPONENT`: This tells the server to remove a plugin or feature that was previously installed. 12 | 13 | * `file://component_audit_log_filter`: This is the identifier for the Audit Log Filter Component, which is responsible for applying rules to decide which audit log events are recorded. 14 | -------------------------------------------------------------------------------- /snippets/install-flag.md: -------------------------------------------------------------------------------- 1 | 2 | The `-y` flag automatically confirms all actions without asking for user input. This makes running commands smoother, especially in situations where you can't or don't want to interact, like during unattended installations or automated scripts. However, keep in mind that using the `-y` flag skips confirmation prompts, which means you won't have a chance to review any changes before they're made. So, it's best to use this flag only when you're sure about the command you're executing. 3 | 4 | The recommended syntax for using this flag with the `percona-release setup` is: 5 | 6 | ``` {.bash data-prompt="$"} 7 | $ percona-release setup -y ps-84-lts 8 | ``` -------------------------------------------------------------------------------- /_resourcepdf/overrides/partials/copyright.html: -------------------------------------------------------------------------------- 1 | {#- 2 | This file was automatically generated - do not edit 3 | -#} 4 |
5 |
6 | Percona LLC and/or its affiliates, © {{ build_date_utc.strftime('%Y') }} — Cookie Preferences 7 |
8 | {% if not config.extra.generator == false %} 9 | Made with 10 | 11 | Material for MkDocs 12 | 13 | {% endif %} 14 |
-------------------------------------------------------------------------------- /docs/_static/percona-favicon.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | -------------------------------------------------------------------------------- /_resource/overrides/partials/source-file.html: -------------------------------------------------------------------------------- 1 | {#- 2 | This file was automatically generated - do not edit 3 | -#} 4 |
5 |
6 | 7 | {% if page.meta.git_revision_date_localized %} 8 | {{ lang.t("source.file.date.updated") }}: 9 | {{ page.meta.git_revision_date_localized }} 10 | {% if page.meta.git_creation_date_localized %} 11 |
12 | {{ lang.t("source.file.date.created") }}: 13 | {{ page.meta.git_creation_date_localized }} 14 | {% endif %} 15 | {% elif page.meta.revision_date %} 16 | {{ lang.t("source.file.date.updated") }}: 17 | {{ page.meta.revision_date }} 18 | {% endif %} 19 | 20 |
-------------------------------------------------------------------------------- /db_terms.txt: -------------------------------------------------------------------------------- 1 | InnoDB 2 | GTID 3 | xtrabackup 4 | percona 5 | utf8mb4 6 | sha256 7 | UUID 8 | wsrep 9 | sql_mode 10 | binlog 11 | replication 12 | transaction 13 | mysql 14 | cluster 15 | backup 16 | restore 17 | redo 18 | undo 19 | snapshot 20 | lock 21 | index 22 | buffer 23 | cache 24 | binlog 25 | DDL 26 | DML 27 | row 28 | table 29 | column 30 | schema 31 | user 32 | privilege 33 | query 34 | join 35 | view 36 | trigger 37 | event 38 | plugin 39 | thread 40 | performance 41 | connection 42 | timeout 43 | error 44 | log 45 | binary 46 | compression 47 | encryption 48 | authentication 49 | authorization 50 | SSL 51 | TLS 52 | audit 53 | monitoring 54 | tech preview 55 | storage engine 56 | engine 57 | XtraDB 58 | LSN 59 | -------------------------------------------------------------------------------- /docs/uninstall-data-masking-component.md: -------------------------------------------------------------------------------- 1 | # Uninstall the component 2 | 3 | The following steps uninstall the component: 4 | {.power-number} 5 | 6 | 1. Uninstall the component with [`UNINSTALL_COMPONENT`](uninstall-component.md) and the loadable functions. 7 | 8 | ```{.bash data-prompt="mysql>"} 9 | mysql> UNINSTALL COMPONENT 'file://component_masking_functions'; 10 | ``` 11 | 12 | 2. Drop `masking_dictionaries`. 13 | 14 | ```{.bash data-prompt="mysql>"} 15 | mysql> DROP TABLE mysql.masking_dictionaries; 16 | ``` 17 | 18 | ## Useful links 19 | 20 | [Install the data masking component](install-data-masking-component.md) 21 | 22 | [Data masking component functions](data-masking-function-list.md) -------------------------------------------------------------------------------- /docs/css/extra.css: -------------------------------------------------------------------------------- 1 | @media print { 2 | /* Adjusts positioning of admonition icon */ 3 | .md-typeset :is(.admonition-title,summary):before { 4 | top: 0.6rem; 5 | left: 0.6rem; 6 | } 7 | } 8 | 9 | .md-sidebar__inner { 10 | font-size: 0.65rem; /* Font size */ 11 | line-height: 1.6; 12 | } 13 | 14 | .edit-page-link { 15 | white-space: nowrap; 16 | display: inline-flex; 17 | align-items: center; 18 | gap: 0.5em; 19 | font-size: 1.2rem; 20 | font-weight: normal; 21 | color: var(--md-typeset-a-color); 22 | text-decoration: underline; 23 | } 24 | 25 | .edit-page-icon svg { 26 | width: 1.40em; 27 | height: 1.40em; 28 | fill: currentColor; 29 | vertical-align: middle; 30 | } 31 | -------------------------------------------------------------------------------- /docs/apt-pinning.md: -------------------------------------------------------------------------------- 1 | # Apt pinning the Percona Server for MySQL {{vers}} packages 2 | 3 | Pinning allows you to stay on a release and get packages from a different version. In some cases, you can pin selected packages and avoid accidentally upgrading all the packages. 4 | 5 | The pinning takes place in the `preference` file. To pin a package, set the `Pin-Priority` to higher numbers. 6 | 7 | Make a new file `/etc/apt/preferences.d/00percona.pref`. For example, add the following to the `preference` file: 8 | 9 | ```text 10 | Package: 11 | Pin: release o=Percona Development Team 12 | Pin-Priority: 1001 13 | ``` 14 | 15 | For more information about the pinning, you can check the official [debian wiki](https://wiki.debian.org/AptConfiguration?action=show&redirect=AptPreferences). 16 | -------------------------------------------------------------------------------- /docs/copyright-and-licensing-information.md: -------------------------------------------------------------------------------- 1 | # Copyright and licensing information 2 | 3 | ## Documentation licensing 4 | 5 | Percona Server for MySQL documentation is (C)2009-2025 Percona LLC and/or its affiliates and is distributed under the [Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/). 6 | 7 | ## Software license 8 | 9 | Percona Server for MySQL is built upon MySQL from Oracle. Along with making our own 10 | modifications, we merge in changes from other sources such as community 11 | contributions and changes from MariaDB. 12 | 13 | The original SHOW USER/TABLE/INDEX statistics code came from Google. 14 | 15 | Percona does not require copyright assignment. 16 | 17 | See the COPYING files accompanying the software distribution. 18 | -------------------------------------------------------------------------------- /docs/yum-uninstall.md: -------------------------------------------------------------------------------- 1 | # Uninstall Percona Server for MySQL 2 | 3 | To completely uninstall Percona Server for MySQL, remove all the installed packages and data files. 4 | {.power-number} 5 | 6 | 1. Stop the Percona Server for MySQL service: 7 | 8 | ```{.bash data-prompt="$"} 9 | $ sudo service mysql stop 10 | ``` 11 | 12 | 2. Remove the packages: 13 | 14 | ```{.bash data-prompt="$"} 15 | $ sudo yum remove percona-server* 16 | ``` 17 | 18 | 3. Remove the data and configuration files: 19 | 20 | !!! warning 21 | 22 | This step removes all the packages and deletes all the data files (databases, tables, logs, etc.). Take a backup before this operation in case you need the data. 23 | 24 | ```{.bash data-prompt="$"} 25 | $ rm -rf /var/lib/mysql 26 | $ rm -f /etc/my.cnf 27 | ``` -------------------------------------------------------------------------------- /docs/keyring-components-plugins-overview.md: -------------------------------------------------------------------------------- 1 | # Keyring components overview 2 | 3 | Percona Server supports a keyring that enables internal server components to store sensitive information securely for later retrieval. 4 | 5 | !!! warning 6 | 7 | Enable only one keyring component at a time for each server instance. Enabling multiple keyring components is not supported and may result in data loss. 8 | 9 | Percona Server supports the following keyring components: 10 | 11 | [Use the keyring file component](use-keyring-file.md){.md-button} 12 | 13 | [Use the keyring vault component](use-keyring-vault-component.md){.md-button} 14 | 15 | [Use the Key Management Interoperability Protocol (KMIP)](using-amz-kms.md){.md-button} 16 | 17 | [Use the Amazon Key Management Service (AWS KMS)](using-kmip.md){.md-button} 18 | -------------------------------------------------------------------------------- /docs/install-js-lang.md: -------------------------------------------------------------------------------- 1 | # Install js_lang component 2 | 3 | --8<--- "experimental.md" 4 | 5 | The `plugin_dir` system variable specifies where the component library is located. If you need to, you should set the `plugin_dir` variable when you start the server. 6 | 7 | To install the `js_lang` component, you need to run the following command: 8 | 9 | ```{.bash data-prompt="mysql>"} 10 | mysql> INSTALL COMPONENT 'file://component_js_lang'; 11 | ``` 12 | 13 | If you decide to uninstall the component, you may have to restart the server before you can reinstall it. 14 | 15 | When you install the `component_js_lang`, it gives you a new global privilege called `CREATE_JS_ROUTINE`. This privilege allows you to create JS routines within the database. 16 | 17 | For more details, check out [INSTALL COMPONENT](install-component.md). -------------------------------------------------------------------------------- /_resource/.icons/groups.svg: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /archive/extended-mysqlbinlog.md: -------------------------------------------------------------------------------- 1 | # Extended mysqlbinlog 2 | 3 | 4 | 5 | !!! note 6 | 7 | The `--compress` option was marked as deprecated and may be removed in a future version of Percona Server for MySQL. 8 | 9 | Percona Server for MySQL has implemented compression support for mysqlbinlog. This is similar to support that both `mysql` and 10 | `mysqldump` programs include (the `-C`, `--compress` options “Use 11 | compression in server/client protocol”). Using the compressed protocol helps 12 | reduce the bandwidth use and speed up transfers. 13 | 14 | Percona Server for MySQL has also implemented support for `SSL`. 15 | mysqlbinlog now accepts the `SSL` connection options as all the 16 | other client programs. This feature can be useful with 17 | `--read-from-remote-server` option. 18 | 19 | -------------------------------------------------------------------------------- /snippets/tech.preview.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | ## feature 4 | 5 | This feature is a [tech preview](glossary.md#tech-preview). Before using this feature in production, we recommend that you test restoring production from physical backups in your environment, and also use the alternative backup method for redundancy. 6 | 7 | ## variable 8 | 9 | These variables are [tech preview](glossary.md#tech-preview). Before using these variables in production, we recommend that you test restoring production from physical backups in your environment, and also use the alternative backup method for redundancy. 10 | 11 | This variable is [tech preview](glossary.md#tech-preview). Before using this variable in production, we recommend that you test restoring production from physical backups in your environment and also use the alternative backup method for redundancy. 12 | -------------------------------------------------------------------------------- /docs/encrypt-file-per-table-tablespace.md: -------------------------------------------------------------------------------- 1 | # Encrypt File-Per-Table Tablespace 2 | 3 | The file_per_table tablespace inherits the default schema encryption setting. Use the `ENCRYPTION` clause in the in `CREATE TABLE` statement to explicitly set the encryption. 4 | 5 | ```{.bash data-prompt="mysql>"} 6 | mysql> CREATE TABLE ... ENCRYPTION='Y'; 7 | ``` 8 | To change the encryption setting for an existing file_per_table tablespace, add the `ENCRYPTION` clause. The `ALTER TABLE` statement without the `ENCRYPTION` clause does not change the encryption state. 9 | 10 | ```{.bash data-prompt="mysql>"} 11 | mysql> ALTER TABLE ... ENCRYPTION='Y'; 12 | ``` 13 | 14 | If the `table_encryption_privilege_check` is enabled, the `TABLE_ENCRYPTION_ADMIN` privilige is required to change the file_per_table encryption setting from the default schema encryption. 15 | -------------------------------------------------------------------------------- /docs/disable-audit-log-filter.md: -------------------------------------------------------------------------------- 1 | # Disable Audit Log Filter logging 2 | 3 | The `audit_log_filter.disable` system variable lets you disable or enable logging for all connections based on the value: 4 | 5 | | Value | Actions | 6 | |---|---| 7 | | `audit_log_filter.disable = true` |Disables logging. | 8 | | `audit_log_filter.disable = false` | Enables logging. | 9 | 10 | You can set the variable in the following ways: 11 | 12 | * Specify in the option file. 13 | 14 | * Include in the command-line startup string. 15 | 16 | * Use a SET statement during runtime. 17 | 18 | ```{.bash data-prompt="mysql>"} 19 | mysql> SET GLOBAL audit_log_filter.disable = true; 20 | ``` 21 | 22 | ## Privileges required 23 | 24 | Setting the value of `audit_log_filter.disable` at runtime requires the following: 25 | 26 | * `AUDIT_ADMIN` privilege 27 | * `SYSTEM_VARIABLES_ADMIN` privilege -------------------------------------------------------------------------------- /docs/js-lang-privileges.md: -------------------------------------------------------------------------------- 1 | # JS privileges 2 | 3 | --8<--- "experimental.md" 4 | 5 | Privileges control what users can do. You use them to give specific permissions to different users. This ability helps you keep your data secure by only allowing authorized users to access and change information in the database. 6 | 7 | ## Privileges 8 | 9 | To create routines within a database, you must be granted the `CREATE_JS_ROUTINE` privilege and the standard `CREATE ROUTINE` privilege. 10 | 11 | ```{.bash data-prompt="mysql>"} 12 | mysql> GRANT CREATE_JS_ROUTINE ON *.* TO user1@localhost; 13 | ``` 14 | 15 | If a user is granted the ability to create routines and holds the CREATE_JS_ROUTINE privilege, they are capable of creating stored functions and procedures using JS. 16 | 17 | However, it is important to note that at this time, the creation of JS triggers or events is not supported. -------------------------------------------------------------------------------- /docs/myrocks-gap-locks-detection.md: -------------------------------------------------------------------------------- 1 | # Gap locks detection 2 | 3 | The [Gap locks] detection is based on a Facebook *MySQL* patch. 4 | 5 | If a transactional storage engine does not support gap locks (for example 6 | MyRocks) and a gap lock is being attempted while the transaction isolation 7 | level is either `REPEATABLE READ` or `SERIALIZABLE`, the following SQL 8 | error will be returned to the client and no actual gap lock will be taken 9 | on the effected rows. 10 | 11 | ??? example "Error message" 12 | 13 | ```text 14 | ERROR HY000: Using Gap Lock without full unique key in multi-table or multi-statement transactions is not allowed. You need to either rewrite queries to use all unique key columns in WHERE equal conditions, or rewrite to single-table, single-statement transaction. 15 | ``` 16 | 17 | [Gap locks]: https://dev.mysql.com/doc/refman/{{vers}}/en/innodb-locking.html#innodb-gap-locks -------------------------------------------------------------------------------- /docs/uninstall-component.md: -------------------------------------------------------------------------------- 1 | # UNINSTALL COMPONENT 2 | 3 | The `UNINSTALL COMPONENT` does the following: 4 | 5 | * Deactivates the component 6 | * Uninstalls the component 7 | 8 | If the statement does not undo any persisted variables. 9 | 10 | If an error, such as a misspelled component name, occurs, the statement fails and nothing happens. 11 | 12 | You can uninstall multiple components at the same time. 13 | 14 | ## Required privilege 15 | 16 | The statement requires the `DELETE` privilege for the `mysql.component` system table. Executing the statement removes the registration row from this table. 17 | 18 | ## Example 19 | 20 | The following is an example of the `UNINSTALL COMPONENT` statement. 21 | 22 | ```{.bash data-prompt="mysql>"} 23 | mysql > UNINSTALL COMPONENT 'file://componentA' ; 24 | ``` 25 | 26 | Find more information in the [UNINSTALL COMPONENT](uninstall-component.md) document. 27 | 28 | 29 | 30 | -------------------------------------------------------------------------------- /docs/_static/percona-logo.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | -------------------------------------------------------------------------------- /docs/binary-tarball-install.md: -------------------------------------------------------------------------------- 1 | # Install Percona Server for MySQL {{vers}} from a binary tarball 2 | 3 | A binary tarball contains a group of files, including the source code, bundled together into one file using the `tar` command and compressed using `gzip`. 4 | 5 | See the list of the [binary tarball available based on the Percona Server for MySQL version](binary-tarball-names.md) to select the right tarball for your environment. 6 | 7 | You can download the binary tarballs from the `Linux - Generic` [section] on the download page. 8 | 9 | Fetch and extract the correct binary tarball. For example for Ubuntu 22.04: 10 | 11 | ```{.bash data-prompt="$"} 12 | $ wget https://downloads.percona.com/downloads/Percona-Server-innovative-release/Percona-Server-{{release}}/binary/tarball/Percona-Server-{{release}}-Linux.x86_64.glibc2.35.tar.gz 13 | ``` 14 | 15 | [section]: https://www.percona.com/downloads/Percona-Server-{{vers}}/LATEST/binary/tarball/ 16 | 17 | -------------------------------------------------------------------------------- /docs/extended-set-var.md: -------------------------------------------------------------------------------- 1 | # Extended SET VAR optimizer hint 2 | 3 | Percona Server for MySQL extends the `SET_VAR` introduced in MySQL {{vers}} 4 | effectively replacing the `SET STATEMENT ... FOR` statement. `SET_VAR` is an 5 | optimizer hint that can be applied to session variables. 6 | 7 | Percona Server for MySQL {{vers}} extends the `SET_VAR` hint to support the 8 | following: 9 | 10 | 11 | * The `OPTIMIZE TABLE` statement 12 | 13 | 14 | * MyISAM session variables 15 | 16 | 17 | * Plugin or Storage Engine variables 18 | 19 | 20 | * InnoDB Session variables 21 | 22 | 23 | * The `ALTER TABLE` statement 24 | 25 | 26 | * `CALL stored_proc()` statement 27 | 28 | 29 | * The `ANALYZE TABLE` statement 30 | 31 | 32 | * The `CHECK TABLE` statement 33 | 34 | 35 | * The `LOAD INDEX` statement (used for MyISAM) 36 | 37 | 38 | * The `CREATE TABLE` statement 39 | 40 | Percona Server for MySQL also supports setting the following variables by using `SET_VAR`: 41 | -------------------------------------------------------------------------------- /docs/apt-uninstall-server.md: -------------------------------------------------------------------------------- 1 | # Uninstall Percona Server for MySQL {{vers}} using the APT package manager 2 | 3 | To uninstall Percona Server for MySQL you’ll need to remove all the installed 4 | packages. Removing packages with apt remove does not remove the 5 | configuration and data files. Removing the packages with apt purge does remove the packages with configuration files and data files (all 6 | the databases). Depending on your needs you can choose which command better 7 | suits you. 8 | 9 | 1. Stop the Percona Server for MySQL service: `service mysql stop` 10 | 11 | 2. Remove the packages 12 | 13 | 1. Remove the packages. This will leave the data files (databases, tables, logs, configuration, etc.) behind. In case you don’t need them you’ll need to remove them manually: `apt remove percona-server\` 14 | 15 | 2. Purge the packages. This command removes all the packages and deletes all the data files (databases, tables, logs, and so on.): `apt purge percona-server\` 16 | -------------------------------------------------------------------------------- /docs/performance-schema-myrocks-changes.md: -------------------------------------------------------------------------------- 1 | # Performance Schema MyRocks changes 2 | 3 | RocksDB WAL file information can be seen in the 4 | [performance_schema.log_status](https://dev.mysql.com/doc/refman/{{vers}}/en/performance-schema-log-status-table.html) 5 | table in the `STORAGE ENGINE` column. 6 | 7 | ## Example 8 | 9 | ```{.bash data-prompt="mysql>"} 10 | mysql> select * from performance_schema.log_status\G 11 | ``` 12 | 13 | ??? example "Expected output" 14 | 15 | ```{.text .no-copy} 16 | *************************** 1. row *************************** 17 | 18 | SERVER_UUID: f593b4f8-6fde-11e9-ad90-080027c2be11 19 | LOCAL: {"gtid_executed": "", "binary_log_file": "binlog.000004", "binary_log_position": 1698222} 20 | REPLICATION: {"channels": []} 21 | STORAGE_ENGINES: {"InnoDB": {"LSN": 36810235, "LSN_checkpoint": 36810235}, "RocksDB": {"wal_files": [{"path_name": "/000026.log", "log_number": 26, "size_file_bytes": 371869}]}} 22 | 1 row in set (0.00 sec) 23 | ``` 24 | -------------------------------------------------------------------------------- /docs/myrocks-added-features.md: -------------------------------------------------------------------------------- 1 | # Updated supported features 2 | 3 | The following is a list of the latest supported features: 4 | 5 | * Percona Server for MySQLsupports `SELECT FOR UPDATE SKIP LOCKED/NOWAIT`. The transaction isolation level must be `READ COMMITTED`. 6 | 7 | * Percona Server for MySQL adds the ability to cancel ongoing manual compactions. The cancel methods are the following: 8 | 9 | * Using either Control+C (from a session) or KILL (from another session) for client sessions running manual compactions by `SET GLOBAL rocksdb_compact_cf (variable)`. 10 | 11 | * Using a global variable `rocksdb_cancel_manual_compactions` to cancel all ongoing manual compactions. 12 | 13 | * Percona Server for MySQL adds supported for [Generated Columns](https://dev.mysql.com/doc/refman/{{vers}}/en/create-table-generated-columns.html) and index are supported. 14 | 15 | * Percona Server for MySQL adds support for [explicit DEFAULT value expressions](https://dev.mysql.com/doc/refman/{{vers}}/en/data-type-defaults.html). 16 | -------------------------------------------------------------------------------- /docs/server-version-numbers.md: -------------------------------------------------------------------------------- 1 | # Understand version numbers 2 | 3 | A version number identifies the innovtion product release. The product contains the latest features, improvements, and bug fixes at the time of that release. 4 | 5 | | 8.1.0 | -1 | 6 | |---|---|---| 7 | | Base version | Minor build version | 8 | 9 | Percona uses semantic version numbering, which follows the pattern of base version and build version. Percona assigns unique, non-negative integers in increasing order for each version release. The version number combines the base [MySQL {{vers}}](https://dev.mysql.com/doc/relnotes/mysql/{{vers}}/en/) version number and the minor build version. 10 | 11 | The version numbers for Percona Server for MySQL {{release}} define the following information: 12 | 13 | * Base version - the leftmost numbers indicate [MySQL {{vers}}](https://dev.mysql.com/doc/relnotes/mysql/{{vers}}/en/) version used as a base. 14 | 15 | * Minor build version - an internal number that increases by one every time Percona Server for MySQL is released. 16 | -------------------------------------------------------------------------------- /docs/advisors.md: -------------------------------------------------------------------------------- 1 | # Use Percona Monitoring and Management (PMM) Advisors 2 | 3 | [Percona Monitoring and Management (PMM)](https://www.percona.com/software/database- 4 | tools/percona-monitoring-and-management) provides several categories of Advisors. 5 | Each Advisor contains a set of automated checks. These checks investigate your 6 | database settings for a specific range of possible issues. 7 | 8 | The PMM Server automatically downloads the Advisors if the `Advisors` and 9 | `Telemetry` options are enabled in `Configuration > Settings > Advanced Settings`. 10 | Both options are enabled by default. 11 | 12 | !!! note "Need Additional Guidance?" 13 | If you encounter complex advisor recommendations or require expert 14 | interpretation, [Percona Support](https://www.percona.com/services/support) 15 | offers professional assistance to help you optimize your database 16 | configuration and resolve any identified issues. 17 | 18 | !!! admonition "See also" 19 | [PMM documentation - Advisor checks](https://docs.percona.com/percona-platform/ 20 | advisors.html) 21 | -------------------------------------------------------------------------------- /docs/use-keyring-file.md: -------------------------------------------------------------------------------- 1 | # Use the keyring file component 2 | 3 | The `keyring_file` component is part of the component-based MySQL infrastructure which extends the server capabilities. 4 | 5 | !!! important 6 | 7 | Percona Server for MySQL {{vers}} does not support the `keyring_file` plugin. 8 | 9 | See the MySQL documentation on the [component installation] and on the [keyring_file component usage] for more information. 10 | 11 | --8<--- "keyring-components-installation.md" 12 | 13 | An example of a manifest and a configuration file is the following: 14 | 15 | An example of `./bin/mysqld.my`: 16 | 17 | ```json 18 | { 19 | "components": "file://component_keyring_file" 20 | } 21 | ``` 22 | 23 | An example of `/lib/plugin/component_keyring_file.cnf`: 24 | 25 | ```json 26 | { 27 | "path": "/var/lib/mysql-keyring/keyring_file", "read_only": false 28 | } 29 | ``` 30 | 31 | [component installation]: https://dev.mysql.com/doc/refman/{{vers}}/en/keyring-component-installation.html 32 | [keyring_file component usage]: https://dev.mysql.com/doc/refman/{{vers}}/en/keyring-file-component.html -------------------------------------------------------------------------------- /docs/css/rating.css: -------------------------------------------------------------------------------- 1 | .rating-widget:hover, 2 | #feedback-form:hover { 3 | box-shadow: 4 | 0px 1px 10px 0px rgba(0, 0, 0, 0.12), 5 | 0px 4px 5px 0px rgba(0, 0, 0, 0.14), 6 | 0px 2px 4px -1px rgba(0, 0, 0, 0.20); 7 | } 8 | 9 | /* Title color */ 10 | .rating-widget .rating-title { 11 | color: var(--md-typeset-a-color, #0E5FB5); 12 | } 13 | 14 | /* Dark mode title */ 15 | @media (prefers-color-scheme: dark) { 16 | .rating-widget .rating-title { 17 | color: var(--md-typeset-a-color, #93C7FF) !important; 18 | } 19 | } 20 | 21 | /* Feedback status */ 22 | #feedback-status { 23 | color: var(--md-typeset-a-color); 24 | } 25 | 26 | @media (prefers-color-scheme: dark) { 27 | #feedback-status { 28 | color: var(--md-typeset-a-color, #93C7FF) !important; 29 | } 30 | } 31 | 32 | /* Light mode: Send button */ 33 | #submit-feedback { 34 | color: white !important; 35 | } 36 | 37 | /* Dark mode: Send button */ 38 | @media (prefers-color-scheme: dark) { 39 | #submit-feedback { 40 | background-color: var(--md-typeset-a-color, #93C7FF) !important; 41 | color: #999 !important; 42 | } 43 | } 44 | -------------------------------------------------------------------------------- /docs/ai-docs.md: -------------------------------------------------------------------------------- 1 | # How we use artificial intelligence 2 | 3 | The technical writer oversees the integration of AI-driven tools and platforms into the documentation workflow, ensuring that AI-generated text meets the standards for clarity, coherence, and accuracy. While AI assists in tasks such as content generation, language enhancement, and formatting optimization, the technical writer is responsible for validating and refining the output to ensure its suitability for the intended audience. 4 | 5 | Throughout the documentation process, the technical writer reviews the quality and relevance of AI-generated content in detail and with critical judgment. By leveraging their expertise in language, communication, and subject matter knowledge, the technical writer collaborates with AI systems to refine and tailor the documentation to meet the specific needs and preferences of the audience. 6 | 7 | While AI accelerates the documentation process and enhances productivity, the technical writer verifies the information's accuracy and maintains consistency in terminology, style, and tone. The technical writer ensures that the final document reflects the company's commitment to excellence. -------------------------------------------------------------------------------- /docs/thread-based-profiling.md: -------------------------------------------------------------------------------- 1 | # Thread based profiling 2 | 3 | Percona Server for MySQL now uses thread based profiling by default, 4 | instead of process based profiling. This was implemented because with 5 | process based profiling, threads on the server, other than the one being 6 | profiled, can affect the profiling information. 7 | 8 | Thread based profiling is using the information provided by the kernel 9 | [getrusage](https://kernel.org/doc/man-pages/online/pages/man2/getrusage.2.html) 10 | function. Since the 2.6.26 kernel version, thread based resource usage 11 | is available with the **RUSAGE_THREAD**. This means that the thread based 12 | profiling will be used if you're running the 2.6.26 kernel or newer, or 13 | if the **RUSAGE_THREAD** has been ported back. 14 | 15 | This feature is enabled by default if your system supports it, in other 16 | cases it uses process based profiling. 17 | 18 | !!! note "Performance Profiling Challenges?" 19 | For advanced performance tuning and profiling strategies, 20 | [Percona Support](https://www.percona.com/services/support) provides 21 | expert consultation to optimize your database performance. 22 | 23 | -------------------------------------------------------------------------------- /docs/percona-xtradb.md: -------------------------------------------------------------------------------- 1 | # The Percona XtraDB storage engine 2 | 3 | Percona XtraDB is an enhanced version of the *InnoDB* storage engine, designed 4 | to better scale on modern hardware. It also includes a variety of other 5 | features useful in high-performance environments. It is fully backward 6 | compatible, and so can be used as a drop-in replacement for standard *InnoDB*. 7 | 8 | Percona XtraDB includes all of *InnoDB* ‘s robust, reliable `ACID`-compliant 9 | design and advanced `MVCC` architecture, and builds on that solid foundation 10 | with more features, more tunability, more metrics, and more scalability. In 11 | particular, it is designed to scale better on many cores, use memory more 12 | efficiently, and be more convenient and useful. The new features are 13 | specially designed to alleviate some of *InnoDB*’s limitations. We choose 14 | features and fixes based on customer requests and on our best judgment of 15 | real-world needs as a high-performance consulting company. 16 | 17 | Percona XtraDB engine will not have further binary releases, it is 18 | distributed as part of the *Percona Server for MySQL*. 19 | 20 | 21 | 22 | -------------------------------------------------------------------------------- /docs/udf-percona-toolkit.md: -------------------------------------------------------------------------------- 1 | # Percona Toolkit UDFs 2 | 3 | These Percona Toolkit user-defined functions (UDFs) offer faster checksum calculations compared to standard methods: 4 | 5 | * `libfnv1a_udf` 6 | 7 | * `libfnv_udf` 8 | 9 | * `libmurmur_udf` 10 | 11 | ## Other information 12 | 13 | * Author/Origin: Baron Schwartz 14 | 15 | ## Installation 16 | 17 | Once the installation is complete, execute the following command to install these functions: 18 | 19 | ```{.bash data-prompt="mysql>"} 20 | mysql> mysql -e "INSTALL COMPONENT 'file://component_percona_udf'" 21 | ``` 22 | 23 | ## Troubleshooting 24 | 25 | If the `INSTALL COMPONENT` command fails, try these steps: 26 | 27 | * Check the error message for clues about what went wrong. 28 | 29 | * Verify the component path `'file://component_percona_udf'` 30 | is correct and accessible. 31 | 32 | * Ensure you have the necessary permissions to install 33 | components in MySQL. 34 | 35 | If you're still facing issues, consider reaching out to 36 | [Percona Support](https://www.percona.com/services/support) 37 | for further assistance. 38 | 39 | ## Other reading 40 | 41 | * Percona Toolkit [documentation](https://docs.percona.com/percona-toolkit/) 42 | -------------------------------------------------------------------------------- /docs/myrocks-differences.md: -------------------------------------------------------------------------------- 1 | # Differences between Percona MyRocks and Facebook MyRocks 2 | 3 | The original MyRocks was developed by Facebook 4 | and works with their implementation of MySQL. 5 | *Percona MyRocks* is a branch of MyRocks for *Percona Server for MySQL* 6 | and includes the following differences from the original implementation: 7 | 8 | * The behavior of the `START TRANSACTION WITH CONSISTENT SNAPSHOT` statement 9 | depends on the [transaction isolation level](https://dev.mysql.com/doc/refman/5.7/en/innodb-transaction-isolation-levels.html). 10 | 11 | | Storage Engine| Transaction isolation level | | 12 | | ------------- | --------------------------- | ---------------------------- | 13 | | | `READ COMMITTED` | `REPEATABLE READ` | 14 | | InnoDB | Success | Success | 15 | | Facebook MyRocks | Fail | Success (MyRocks engine only; read-only, as all MyRocks engine snapshots)| 16 | | Percona MyRocks | Fail with any DML which would violate the read-only snapshot constraint | Success (read-only snapshots independent of the engines in use) | 17 | 18 | * Percona MyRocks includes the `lz4` and `zstd` statically linked libraries. 19 | -------------------------------------------------------------------------------- /docs/js-lang-procedures.md: -------------------------------------------------------------------------------- 1 | # JS stored function or procedure 2 | 3 | --8<--- "experimental.md" 4 | 5 | Once the component's installed, you can write stored functions and procedures in JavaScript. The syntax looks like this: 6 | 7 | ```{.text .no-copy} 8 | CREATE 9 | [DEFINER = user] 10 | FUNCTION [IF NOT EXISTS] sp_name ([func_parameter[,...]]) 11 | RETURNS type 12 | LANGUAGE JS [other-func-characteristic ...] AS js_routine_body 13 | 14 | CREATE 15 | [DEFINER = user] 16 | PROCEDURE [IF NOT EXISTS] sp_name ([proc_parameter[,...]]) 17 | LANGUAGE JS [other-proc-characteristic ...] AS js_routine_body 18 | 19 | routine_body: 20 | text_string_literal | dollar_quoted_string 21 | ``` 22 | 23 | Use the `LANGUAGE JS` clause when creating a routine. 24 | 25 | ```{.bash data-prompt="mysql>"} 26 | mysql> CREATE FUNCTION f1(n INT) RETURNS INT LANGUAGE JS AS $$ 27 | return n*42; 28 | $$ 29 | 30 | mysql> CREATE PROCEDURE p1(a INT, b INT, OUT r INT) LANGUAGE JS AS $$ 31 | r = a * b; 32 | $$ 33 | ``` 34 | 35 | You can modify or delete stored programs in JS by using the standard `ALTER PROCEDURE/FUNCTION` and `DROP PROCEDURE/FUNCTION` statements. These statements do not require the `CREATE_JS_ROUTINE` privilege. 36 | 37 | -------------------------------------------------------------------------------- /docs/rotate-master-key.md: -------------------------------------------------------------------------------- 1 | # Rotate the master encryption key 2 | 3 | Rotate the master encryption key periodically and if the key has been compromised. 4 | 5 | Rotating the master encryption key changes that key and tablespace keys are re-encrypted and updated in the tablespace headers. The rotation only succeeds if all operations are successful. If the rotation is interrupted, the operation is rolled forward when the server restarts. 6 | 7 | The rotation operation does not affect tablespace data. To change a tablespace key, disable and then re-enable encryption for that tablespace. 8 | 9 | The `ENCRYPTION_KEY_ADMIN` privilege is required to rotate the master encryption key. 10 | 11 | InnoDB reads the encryption data from the tablespace header, if certain tablespace keys have been encrypted with the prior master key, InnoDB retrieves the master key from the keyring to decrypt the tablespace key. InnoDB re-encrypts the tablespace key with the new Master key. 12 | 13 | Rotate the master encryption key with following statement: 14 | 15 | ```{.bash data-prompt="mysql>"} 16 | mysql> ALTER INSTANCE ROTATE INNODB MASTER KEY; 17 | ``` 18 | 19 | The rotation operation must complete before any tablespace encryption operation 20 | can begin. 21 | -------------------------------------------------------------------------------- /docs/prefix-index-queries-optimization.md: -------------------------------------------------------------------------------- 1 | # Prefix index queries optimization 2 | 3 | *Percona Server for MySQL* has ported Prefix Index Queries Optimization feature from 4 | Facebook patch for *MySQL*. 5 | 6 | Prior to this *InnoDB* would always fetch the clustered index for all prefix 7 | columns in an index, even when the value of a particular record was smaller 8 | than the prefix length. This implementation optimizes that case to use the 9 | record from the secondary index and avoid the extra lookup. 10 | 11 | ## Status variables 12 | 13 | ### `Innodb_secondary_index_triggered_cluster_reads` 14 | 15 | | Option | Description | 16 | | -------------- | ------------------ | 17 | | Scope: | Global | 18 | | Data type: | Numeric | 19 | 20 | This variable shows the number of times secondary index lookup triggered 21 | cluster lookup. 22 | 23 | ### `Innodb_secondary_index_triggered_cluster_reads_avoided` 24 | 25 | | Option | Description | 26 | | -------------- | ------------------ | 27 | | Scope: | Global | 28 | | Data type: | Numeric | 29 | 30 | This variable shows the number of times prefix optimization avoided 31 | triggering cluster lookup. 32 | 33 | 34 | -------------------------------------------------------------------------------- /docs/extended-mysqldump.md: -------------------------------------------------------------------------------- 1 | # Extended mysqldump 2 | 3 | ## Backup locks support 4 | 5 | When used together with the `–single-transaction` option, the 6 | lock-for-backup option makes `mysqldump` issue `LOCK 7 | TABLES FOR BACKUP` before starting the dump operation to prevent 8 | unsafe statements that would normally result in an inconsistent 9 | backup. 10 | 11 | More information can be found in [Backup Locks](backup-locks.md). 12 | 13 | ## Compressed columns support 14 | 15 | **mysqldump** supports the Compressed columns with dictionaries feature. 16 | 17 | More information can be found in 18 | [Compressed columns with dictionaries](compressed-columns.md). 19 | 20 | ## Taking backup by descending primary key order 21 | 22 | –order-by-primary-desc tells `mysqldump` to take the backup by 23 | descending primary key order (`PRIMARY KEY DESC`) which can be useful if 24 | the storage engine is using the reverse order column for a primary key. 25 | 26 | ## RocksDB support 27 | 28 | **mysqldump** detects when MyRocks is installed and available. 29 | If there is a session variable named 30 | `rocksdb_skip_fill_cache`, **mysqldump** sets the variable to **1**. 31 | 32 | **mysqldump** automatically enables `rocksdb_bulk_load` if the the target server supports the variable. 33 | 34 | -------------------------------------------------------------------------------- /docs/sql-basics.md: -------------------------------------------------------------------------------- 1 | # SQL basics 2 | 3 | SQL stands for Structured Query Language. It's a powerful tool used to communicate with databases. Think of a database as a digital filing cabinet where you store and organize information. SQL is like the language you use to talk to that filing cabinet and ask questions or tell it what you want to do with the data inside. 4 | 5 | With SQL, you can do a variety of tasks: 6 | 7 | * Retrieve Data: You can ask the database to give you specific information, like all the names of customers who bought a certain product. 8 | 9 | * Insert Data: You can add new information into the database, such as adding a new customer's details. 10 | 11 | * Update Data: If information changes, like a customer's address, you can update it in the database. 12 | 13 | * Delete Data: If information is no longer needed, you can remove it from the database. 14 | 15 | SQL provides a standardized way to interact with a database. It uses simple commands and statements to perform these tasks, making it easy to learn and use for managing data effectively. 16 | 17 | Fundamental SQL links: 18 | 19 | * [Common SQL](common-sql.md) 20 | * [SELECT](select.md) 21 | * [INSERT](insert.md) 22 | * [DELETE](delete.md) 23 | * [UPDATE](update.md) 24 | * [SQL Operators](sql-operators.md) -------------------------------------------------------------------------------- /docs/binlog-space.md: -------------------------------------------------------------------------------- 1 | # Managing binary log disk space 2 | 3 | Controlling binary log disk usage can be difficult because binary log sizes vary. The database writes each transaction in full to a single binary log file and cannot split a write across multiple files. This requirement can lead to large log files, especially when transactions are large. 4 | 5 | ## binlog_space_limit 6 | 7 | | Attribute | Description | 8 | | --- | --- | 9 | | Uses the command line | Yes | 10 | | Uses the configuration file | Yes | 11 | | Scope | Global | 12 | | Dynamic | No | 13 | | Variable type | ULONG_MAX | 14 | | Default value | 0 (unlimited) | 15 | | Maximum value - 64-bit platform | 18446744073709547520 | 16 | 17 | This variable sets an upper limit on the total size of all binary logs in bytes. When the combined size exceeds this limit, the server automatically purges the oldest binary logs until the total size falls below the limit or only the active log remains. 18 | 19 | A default value of 0 disables this feature. In this case, the server does not enforce a size limit and continues to write binary logs until the binary logs exhaust the available disk space. 20 | 21 | ## Example 22 | 23 | Set the `binlog_space_limit` to 50 GB in the `my.cnf` file: 24 | 25 | ```text 26 | [mysqld] 27 | ... 28 | binlog_space_limit = 50G 29 | ... 30 | ``` 31 | -------------------------------------------------------------------------------- /docs/download-instructions.md: -------------------------------------------------------------------------------- 1 | # Percona Product Download Instructions 2 | 3 | ## Select the software 4 | 5 | Do the following steps to select the software: 6 | 7 | 1. Open [Percona Software Downloads](https://www.percona.com/downloads) 8 | 2. Locate the Percona Software, for example, Percona Server for MySQL 9 | 3. In `Select Product`, select the which product, for example, Percona Server {{vers}} 10 | 4. In `Select Product Version`, select the version, for example, PERCONA-SERVER-{{release}} 11 | 5. In `Select Software`, select the operating system, for example, DEBIAN GNU/LINUX 12.0 ("BOOKWORM"). 12 | 13 | The easiest method is to download all packages. 14 | 15 | The `Package Download Options` may mix `AMD64` and `ARM64` packages. Select the correct CPU architecture for your system. 16 | 17 | ## Download to a local computer 18 | 19 | In `Package Download Options`, select a specific package or select the `DOWNLOAD ALL PACKAGES` button. 20 | 21 | The selected packages are downloaded to the local computer. 22 | 23 | ## Download to another computer 24 | 25 | In `Package Download Options`, select a specific package or select the `DOWNLOAD ALL PACKAGES` button, and hover your cursor over the `DOWNLOAD` arrow. Right-click and in the drop-down menu, select `Copy Link`. 26 | 27 | Paste the link in your terminal to download the selected package. 28 | -------------------------------------------------------------------------------- /docs/installation.md: -------------------------------------------------------------------------------- 1 | # Install Percona Server for MySQL 2 | 3 | Before installing, read the [Percona Server for MySQL {{vers}} Release notes](release-notes/release-notes-index.md). 4 | 5 | We gather [Telemetry data] in the Percona packages and Docker images. 6 | 7 | ## Install Percona Server for MySQL from Repositories 8 | 9 | Percona provides repositories for yum (`RPM` packages for Red Hat, CentOS and Amazon Linux AMI) and apt (`.deb` packages for Ubuntu and Debian) for software such as Percona Server for MySQL, Percona XtraBackup, and Percona Toolkit. This makes it easy to install and update your software and its dependencies through your operating system’s package manager. This is the recommended way of installing where possible. 10 | 11 | The following guides describe the installation process for using the official Percona repositories for the `.deb` and `.rpm` packages. 12 | 13 | [Install Percona Server for MySQL on Debian and Ubuntu](apt-repo.md){.md-button} [Install Percona Server for MySQL on Red Hat Enterprise Linux and CentOS](yum-repo.md){.md-button} 14 | 15 | ## Other Installation Methods 16 | 17 | [Install Percona Server for MySQL from Binaries](binary-tarball-install.md){.md-button}
[Compile Percona Server for MySQL from Source](source-tarball.md){.md-button}
[Run Percona Server for MySQL in a Docker container](docker.md){.md-button} 18 | 19 | [Telemetry data]: telemetry.md 20 | -------------------------------------------------------------------------------- /docs/psmysql-pro.md: -------------------------------------------------------------------------------- 1 | # Percona Server for MySQL Pro 2 | 3 | --8<--- "pro-build-announcement.md" 4 | 5 | ## Capabilities 6 | 7 | The following capabilities have been tested for {{release}} and are available in Percona Server for MySQL Pro: 8 | 9 | | Name | Available since | Description | 10 | | ----------------------------------- | ------------- | -------------| 11 | | Available on [Amazon Linux 2023](install-pro.md)| 8.4.4 | Amazon Linux 2023 is a purpose-built Linux distribution optimized for AWS. It’s designed for performance, security, and seamless integration with the broader AWS ecosystem. We support both AMD64 and ARM64 versions of Amazon Linux 2023. | 12 | | [FIPS compliance](fips.md)| 8.4.0 | FIPS compliance enables all commercial cloud service providers who want to sell and increase their presence for US government entities. | 13 | 14 | ## What's in it for you? 15 | 16 | * Save on deploying and maintaining build infrastructure as we do the build and testing for you 17 | * Longer support for older versions of operating systems. 18 | 19 | [Install Percona Server for MySQL Pro](install-pro.md){.md-button} 20 | 21 | If you already use Percona Server for MySQL, you can 22 | 23 | [Upgrade to Percona Server for MySQL Pro](upgrade-pro.md){.md-button} 24 | 25 | Community users can receive all these capabilities by [building Percona Server for MySQL from the same source code](compile-percona-server.md). -------------------------------------------------------------------------------- /docs/index-info-schema-tables.md: -------------------------------------------------------------------------------- 1 | # Index of INFORMATION_SCHEMA tables 2 | 3 | This is a list of the `INFORMATION_SCHEMA TABLES` that exist in Percona Server for MySQL with XtraDB. The entry for each table points to the page in the documentation where it’s described. 4 | 5 | * [INFORMATION_SCHEMA.CLIENT_STATISTICS](user-stats.md#information_schemaclient_statistics) 6 | 7 | * [INFORMATION_SCHEMA.GLOBAL_TEMPORARY_TABLES](misc-info-schema-tables.md#information_schemaglobal_temporary_tables) 8 | 9 | * [INFORMATION_SCHEMA.INDEX_STATISTICS](user-stats.md#information_schemaindex_statistics) 10 | 11 | * [PROCFS](procfs-plugin.md#procfs) 12 | 13 | * [INFORMATION_SCHEMA.QUERY_RESPONSE_TIME](https://docs.percona.com/percona-server/5.7/diagnostics/response_time_distribution.html#query-response-time) 14 | 15 | * [INFORMATION_SCHEMA.TABLE_STATISTICS](user-stats.md#information_schematable_statistics) 16 | 17 | * [INFORMATION_SCHEMA.TEMPORARY_TABLES](misc-info-schema-tables.md#information_schematemporary_tables) 18 | 19 | * [INFORMATION_SCHEMA.THREAD_STATISTICS](user-stats.md#information_schemathread_statistics) 20 | 21 | * [INFORMATION_SCHEMA.USER_STATISTICS](user-stats.md#information_schemauser_statistics) 22 | 23 | * [INFORMATION_SCHEMA.XTRADB_INTERNAL_HASH_TABLES](innodb-show-status.md#information_schemaxtradb_internal_hash_tables) 24 | 25 | * [INFORMATION_SCHEMA.XTRADB_READ_VIEW](innodb-show-status.md#information_schemaxtradb_read_view) 26 | 27 | -------------------------------------------------------------------------------- /docs/manage-audit-log-filter.md: -------------------------------------------------------------------------------- 1 | # Manage the Audit Log Filter files 2 | 3 | The Audit Log Filter files have the following potential results: 4 | 5 | * Consume a large amount of disk space 6 | * Grow large 7 | 8 | You can manage the space by using log file rotation. This operation renames and then rotates the current log file and then uses the original name on a new current log file. You can rotate the file either manually or automatically. 9 | 10 | If automatic rotation is enabled, you can prune the log file. This pruning operation can be based on either the log file age or combined log file size. 11 | 12 | ## Manual log rotation 13 | 14 | The default setting for [`audit_log_filter.rotate_on_size`](audit-log-filter-variables.md#audit_log_filterrotate_on_size) is 1GB. If this option is set to `0`, the audit log filter component does not do an automatic rotation of the log file. You must do the rotation manually with this setting. 15 | 16 | The `SELECT audit_log_rotate()` command renames the file and creates a new audit log filter file with the original name. You must have the `AUDIT_ADMIN` privilege. 17 | 18 | The files are pruned if either `audit_log_filter.max_size` or `audit_log_filter.prune_seconds` have a value greater than 0 (zero) and `audit_log_filter.rotate_on_size` > 0. 19 | 20 | After the files have been renamed, you must manually remove any archived audit log filter files. The renamed audit log filter files can be read by `audit_log_read()`. The `audit_log_read()` does not find the logs if the name pattern differs from the current pattern. 21 | -------------------------------------------------------------------------------- /docs/reading-audit-log-filter-files.md: -------------------------------------------------------------------------------- 1 | # Reading Audit Log Filter files 2 | 3 | The Audit Log Filter functions can provide a SQL interface to read JSON-format audit log files. The functions cannot read log files in other formats. Configuring the component for JSON logging lets the functions use the directory that contains the current audit log filter file and search in that location for readable files. The value of the `audit_log_filter.file` system variable provides the file location, base name, and the suffix and then searches for names that match the pattern. 4 | 5 | If the file is renamed and no longer fits the pattern, the file is ignored. 6 | 7 | ## Functions used for reading the files 8 | 9 | The following functions read the files in the JSON-format: 10 | 11 | * [`audit_log_read`](audit-log-filter-variables.md#audit_log_read) - reads audit log filter events 12 | 13 | * [`audit_log_read_bookmark`](audit-log-filter-variables.md#audit_log_read_bookmark) - for the most recently read event, returns a bookmark. This bookmark can be passed to `audit_log_read()`. 14 | 15 | Initialize a read sequence by using a bookmark or an argument that specifies the start position: 16 | 17 | ```{.bash data-prompt="mysql>"} 18 | mysql> SELECT audit_log_read(audit_log_read_bookmark()); 19 | ``` 20 | 21 | The following example continues reading from the current position: 22 | 23 | ```{.bash data-prompt="mysql>"} 24 | mysql> SELECT audit_log_read(); 25 | ``` 26 | 27 | Reading a file is closed when the session ends or calling `audit_log_read()` with another argument. 28 | 29 | -------------------------------------------------------------------------------- /docs/audit-log-filter-formats.md: -------------------------------------------------------------------------------- 1 | # Audit Log Filter file format overview 2 | 3 | When an auditable event occurs, the component writes a record to the log file. 4 | 5 | After the component starts, the first record lists the description of the server and the options at startup. After the first record, the auditable events are connections, disconnections, SQL statements executed, and so on. Statements within stored procedures or triggers are not logged, only the top-level statements. 6 | 7 | If files are referenced by `LOAD_DATA`, the contents are not logged. 8 | 9 | Set with the `audit_log_filter.format` system variable at startup. The available format types are the following; 10 | 11 | | Format Type | Command | Description | 12 | |---|---|---| 13 | | [XML (new style)](audit-log-filter-new.md) | `audit_log_filter.format=NEW` | The default format | 14 | | [XML (old style)](audit-log-filter-old.md) | `audit_log_filter.format=OLD` | The original version of the XML format | 15 | | [JSON](audit-log-filter-json.md) | `audit_log_filter.format=JSON` | Files written as a JSON array | 16 | 17 | By default, the file contents in the new-style XML format are not compressed or encrypted. 18 | 19 | Changing the `audit_log_filter.format`, you should also change 20 | the `audit_log_filter.file` name. For example, changing the `audit_log_filter.format` 21 | to JSON, change the `audit_log_filter.file` to `audit.json`. If you don't change 22 | the `audit_log_filter.file` name, then all audit log filter files have the same 23 | base name and you won't be able to easily find when the format changed. 24 | 25 | -------------------------------------------------------------------------------- /docs/additional-selinux-tools.md: -------------------------------------------------------------------------------- 1 | # Additional SELinux tools and management 2 | 3 | ## Installing SELinux management tools 4 | 5 | To install SELinux management tools on Red Hat Enterprise Linux 8 or later, run the following command as root: 6 | 7 | ```{.bash data-prompt="$"} 8 | $ yum -y install policycoreutils-python-utils 9 | ``` 10 | 11 | Ensure you have root privileges to execute these commands. 12 | 13 | ## Switching SELinux mode 14 | 15 | SELinux can operate in three modes: Disabled, Permissive, and Enforcing. 16 | 17 | To switch SELinux mode until the next reboot, use either of the following commands as root: 18 | 19 | ```{.bash data-prompt="$"} 20 | $ setenforce Enforcing 21 | ``` 22 | or 23 | ```{.bash data-prompt="$"} 24 | $ setenforce 1 25 | ``` 26 | 27 | To view the current SELinux mode, use either of the following commands: 28 | 29 | ```{.bash data-prompt="$"} 30 | $ getenforce 31 | ``` 32 | or 33 | ```{.bash data-prompt="$"} 34 | $ sestatus | grep -i mode 35 | ``` 36 | 37 | ## Managing SELinux policies 38 | 39 | ### Using the semanage command 40 | 41 | To add a service to the permissive domain, execute the following as root: 42 | 43 | ```{.bash data-prompt="$"} 44 | $ semanage permissive -a 45 | ``` 46 | 47 | To delete a service from the permissive domain, run: 48 | 49 | ```{.bash data-prompt="$"} 50 | $ semanage permissive -d 51 | ``` 52 | 53 | ### List the current Permissive domains 54 | 55 | To list the current permissive domains, use the following command: 56 | 57 | ```{.bash data-prompt="$"} 58 | $ semanage permissive -l 59 | ``` 60 | -------------------------------------------------------------------------------- /docs/install-data-masking-component.md: -------------------------------------------------------------------------------- 1 | # Install the data masking component 2 | 3 | The component has the following parts: 4 | 5 | * A database server system table used to store the terms and dictionaries 6 | * A `component_masking_functions` component that contains the loadable functions 7 | 8 | The `MASKING_DICTIONARIES_ADMIN` privilege may be required by some functions. 9 | 10 | ## Install the component 11 | 12 | The following steps install the component: 13 | {.power-number} 14 | 15 | 1. Create `masking_dictionaries`. 16 | 17 | ```{.bash data-prompt="mysql>"} 18 | mysql> CREATE TABLE IF NOT EXISTS 19 | mysql.masking_dictionaries( 20 | Dictionary VARCHAR(256) NOT NULL, 21 | Term VARCHAR(256) NOT NULL, 22 | UNIQUE INDEX dictionary_term_idx (Dictionary, Term) 23 | ) ENGINE = InnoDB DEFAULT CHARSET=utf8mb4; 24 | ``` 25 | 26 | 2. Install the data masking components and the loadable functions. 27 | 28 | ```{.bash data-prompt="mysql>"} 29 | mysql> INSTALL COMPONENT 'file://component_masking_functions'; 30 | ``` 31 | 32 | 3. The `MASKING_DICTIONARIES_ADMIN` is required to use the the following functions: 33 | 34 | * `masking_dictionary_term_add` 35 | 36 | * `masking_dictionary_term_remove` 37 | 38 | * `masking_dictionary_remove` 39 | 40 | ```{.bash data-prompt="mysql>"} 41 | mysql> GRANT MASKING_DICTIONARIES_ADMIN ON *.* TO ; 42 | ``` 43 | 44 | ## Useful links 45 | 46 | [Uninstall the data masking component](uninstall-data-masking-component.md) 47 | 48 | [Data masking component functions](data-masking-function-list.md) -------------------------------------------------------------------------------- /docs/apt-run.md: -------------------------------------------------------------------------------- 1 | # Run Percona Server for MySQL {{vers}} after APT repository installation 2 | 3 | Percona Server for MySQL stores the data files in `/var/lib/mysql/` by 4 | default. You can find the configuration file that is used to manage Percona Server for MySQL in `/etc/mysql/my.cnf`. 5 | 6 | !!! note 7 | 8 | Debian and Ubuntu installation doesn’t automatically create a special `debian-sys-maint` user which can be used by the control scripts to control the Percona Server for MySQL `mysqld` and `mysqld_safe` services which was the case with previous Percona Server for MySQL versions. If you still require this user you’ll need to create it manually. 9 | 10 | Run the following commands as root or by using the sudo command 11 | {.power-number} 12 | 13 | 1. Starting the service 14 | 15 | Percona Server for MySQL is started automatically after it gets installed unless it 16 | encounters errors during the installation process. You can also manually 17 | start it by running: `service mysql start` 18 | 19 | 20 | 2. Confirming that service is running. You can check the service status by 21 | running: `service mysql status` 22 | 23 | 24 | 3. Stopping the service 25 | 26 | You can stop the service by running: `service mysql stop` 27 | 28 | 29 | 4. Restarting the service. `service mysql restart` 30 | 31 | !!! note 32 | 33 | Debian 9.0 (stretch) and Ubuntu 18.04 LTS (bionic) come with [systemd](http://freedesktop.org/wiki/Software/systemd/) as the default system and service manager. You can invoke all the above commands with `systemctl` instead of `service`. Currently, both are supported. 34 | 35 | ## Working with AppArmor 36 | 37 | For information on AppArmor, see [Working with AppArmor](apparmor.md). 38 | 39 | -------------------------------------------------------------------------------- /docs/stacktrace.md: -------------------------------------------------------------------------------- 1 | # Stack trace 2 | 3 | Developers use the stack trace in the debug process, either an interactive 4 | investigation or during the post-mortem. No configuration is required to 5 | generate a stack trace. 6 | 7 | Stack trace adds the following: 8 | 9 | | Name | Description | 10 | |--------------------------------------|------------------------------------------------------------------| 11 | | Prints binary BuildID | The Strip utility removes unneeded sections and debugging | 12 | | | information to reduce the size. This method is standard with | 13 | | | containers where the image size is essential. The BuildID lets | 14 | | | you resolve the stack trace when the Strip utility removes the | 15 | | | binary symbols table. | 16 | | Print the server version information | The version information establishes the starting point for | 17 | | | analysis. Some applications, such as MySQL, only print this | 18 | | | information to a log on startup, and when the crash occurs, the | 19 | | | log may be large, rotated, or truncated. | 20 | 21 | !!! tip "Need Help Interpreting Stack Traces?" 22 | [Percona Support](https://www.percona.com/services/support) offers 23 | expert debugging and performance analysis to help you understand 24 | complex stack trace diagnostics. 25 | -------------------------------------------------------------------------------- /docs/js-lang-troubleshoot.md: -------------------------------------------------------------------------------- 1 | # Troubleshoot JS procedures and functions 2 | 3 | --8<--- "experimental.md" 4 | 5 | The component includes a set of User-Defined Functions (UDFs) that retrieve and clear information about the last JS error that occurred in the current connection for the current user. This information updates each time a JS error occurs for the current connection and user. Successful execution of JS code does not change this state. 6 | 7 | The following UDFs are helpful for debugging JS code. 8 | 9 | * `JS_GET_LAST_ERROR()`: Returns the error message for the last JS error that occurred in the current connection for the current user. 10 | 11 | * `JS_GET_LAST_ERROR_INFO()`: Provides detailed information about the last JS error that occurred in the current connection for the current user including the error message, the exact line and column where the problem occurred, and the stack trace if available. 12 | 13 | * `JS_CLEAR_LAST_ERROR()`: Resets the information about the last JS error for the current connection and user, as if no error had occurred. 14 | 15 | To terminate a connection or statement executing a JS routine, you can take immediate action to abort the execution, ensuring that any unintended operations can be swiftly stopped. 16 | 17 | This functionality is crucial for managing and controlling the execution of routines, ensuring that any unintended or potentially harmful operations can be swiftly terminated to maintain the stability and performance of the database environment. 18 | 19 | If the `MAX_EXECUTION_TIME` timeout is exceeded for a statement running a JS routine, the execution aborts execution without much delay. You can use this option to limit the execution time of a JS routine that's performing a long computation. -------------------------------------------------------------------------------- /docs/enforce-engine.md: -------------------------------------------------------------------------------- 1 | # Enforcing storage engine 2 | 3 | Percona Server for MySQL implements a variable to enforce the 4 | use of a specific storage engine. 5 | 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). 13 | 14 | In case a user tries to enable [enforce_storage_engine](#enforce_storage_engine) with an engine that isn’t available, the system will not start. 15 | 16 | !!! note 17 | 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`. 21 | 22 | ## System variables 23 | 24 | ### `enforce_storage_engine` 25 | 26 | | Option | Description | 27 | | -------------- | ------------------ | 28 | | Command Line: | Yes | 29 | | Config file | Yes | 30 | | Scope: | Global | 31 | | Dynamic: | No | 32 | | Data type | String | 33 | | Default value | NULL | 34 | 35 | This variable is not case sensitive. 36 | 37 | ## Example 38 | 39 | Adding following option to [my.cnf](glossary.md#mycnf) will start the server with InnoDB as enforced storage engine. 40 | 41 | ```text 42 | enforce_storage_engine=InnoDB 43 | ``` 44 | -------------------------------------------------------------------------------- /docs/modify-tables.md: -------------------------------------------------------------------------------- 1 | # Modify a table 2 | 3 | The `ALTER TABLE` command acts like a toolkit that allows you to change the structure of existing tables. You can add new sections (columns), remove old ones, or change how information is stored [(data types)](data-types-basic.md). This command helps you adapt your database to new needs or improve efficiency. 4 | 5 | ## Things to Watch Out For 6 | 7 | * Data loss: Be careful when modifying tables! Deleting a section (column) or changing its format might erase existing data in that section. 8 | 9 | * Slowdowns: Altering large tables or making complex changes can slow down the database, especially during busy times. It might take longer for things to work while the changes are applied. 10 | 11 | * Locks: MySQL might temporarily lock the tables you're working on when making changes. This operation means other users can't access or modify that data until the changes are complete, which can cause delays for others. 12 | 13 | ## Modify table example 14 | 15 | After a table has been created, you may need to modify its structure or properties. Percona Server for MySQL provides the `ALTER TABLE` command for making such modifications. You can add, modify, or drop columns, change data types, add constraints, and more using this command. 16 | 17 | The following is an example using an `ALTER TABLE` command: 18 | 19 | ```{.bash data-prompt="mysql>"} 20 | mysql> ALTER TABLE users 21 | ADD COLUMN age INT, 22 | MODIFY COLUMN email VARCHAR(255), 23 | DROP COLUMN username; 24 | ``` 25 | 26 | ## Database management 27 | 28 | * [Database](database.md) 29 | * [Tables](table.md) 30 | * [Create table](create-table.md) 31 | * [Isolation Levels](isolation-levels.md) 32 | * [Transaction Management](transaction-mgmt.md) 33 | * [Views](views.md) 34 | -------------------------------------------------------------------------------- /docs/build-apt-packages.md: -------------------------------------------------------------------------------- 1 | # Build APT packages 2 | 3 | If you wish to build your own Debian/Ubuntu (dpkg) packages of Percona Server for MySQL, 4 | you first need to start with a source tarball, either from the Percona 5 | website or by generating your own by following the instructions above ([Installing Percona Server for MySQL from the Git Source Tree](source-tarball.md)). 6 | 7 | Extract the source tarball: 8 | 9 | ```{.bash data-prompt="$"} 10 | $ tar xfz Percona-Server-{{release}}-Linux.x86_64.ssl102.tar.gz 11 | $ cd Percona-Server-{{release}} 12 | ``` 13 | 14 | Copy the Debian packaging in the directory that Debian expects it to be in: 15 | 16 | ```{.bash data-prompt="$"} 17 | $ cp -ap build-ps/debian debian 18 | ``` 19 | 20 | Update the changelog for your distribution (here we update for the unstable 21 | distribution - sid), setting the version number appropriately. The trailing one 22 | in the version number is the revision of the Debian packaging. 23 | 24 | ```{.bash data-prompt="$"} 25 | $ dch -D unstable --force-distribution -v "8.0.13-3-1" "Update to 8.0.13-3" 26 | ``` 27 | 28 | Build the Debian source package: 29 | 30 | ```{.bash data-prompt="$"} 31 | $ dpkg-buildpackage -S 32 | ``` 33 | 34 | Use sbuild to build the binary package in a chroot: 35 | 36 | ```{.bash data-prompt="$"} 37 | $ sbuild -d sid percona-server-{{vers}}_{{release}}.dsc 38 | ``` 39 | 40 | You can give different distribution options to `dch` and `sbuild` to build binary 41 | packages for all Debian and Ubuntu releases. 42 | 43 | !!! note 44 | 45 | [PAM Authentication Plugin](pam-plugin.md) is not built with the server by default. In order to build the Percona Server for MySQL with PAM plugin, an additional option `-DWITH_PAM=ON` should be used. 46 | -------------------------------------------------------------------------------- /docs/assets/mysql-mark.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | -------------------------------------------------------------------------------- /docs/yum-run.md: -------------------------------------------------------------------------------- 1 | # Run Percona Server for MySQL 2 | 3 | Percona Server for MySQL stores the data files in `/var/lib/mysql/` by 4 | default. The configuration file used to manage Percona Server for MySQL is the `/etc/my.cnf`. 5 | 6 | The following commands start, provide the server status, stop the server, and restart the server. 7 | {.power-number} 8 | 9 | !!! note 10 | 11 | The RHEL distributions and derivatives come with [systemd](https:/freedesktop.org/wiki/Software/systemd/) as the default system and service manager so you can invoke all of the commands with `sytemctl` instead of `service`. Currently, both options are supported. 12 | 13 | 1. Percona Server for MySQL is not started automatically on the RHEL distributions and derivatives after installation. Start the server with the following command: 14 | 15 | ```{.bash data-prompt="$"} 16 | $ sudo service mysql start 17 | ``` 18 | 19 | 2. Review the service status with the following command: 20 | 21 | ```{.bash data-prompt="$"} 22 | $ sudo service mysql status 23 | ``` 24 | 25 | 3. Stop the service with the following command: 26 | 27 | ```{.bash data-prompt="$"} 28 | $ sudo service mysql stop 29 | ``` 30 | 31 | 4. Restart the service with the following command: 32 | 33 | ```{.bash data-prompt="$"} 34 | $ sudo service mysql restart 35 | ``` 36 | 37 | ## SELinux and security considerations 38 | 39 | For information on working with SELinux, see [Working with SELinux](selinux.md). 40 | 41 | The RHEL 8 distributions and derivatives have added [system-wide cryptographic policies component](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/using-the-system-wide-cryptographic-policies_security-hardening). This component allows the configuration of cryptographic subsystems. 42 | -------------------------------------------------------------------------------- /snippets/keyring-components-installation.md: -------------------------------------------------------------------------------- 1 | 2 | The component must be installed with a manifest. A keyring component is not loaded with the `--early-plugin-load` option on the server. The server uses a manifest and the component consults its configuration file during initialization. You should only load a keyring component with a manifest file. Do not use the `INSTALL_COMPONENT` statement, which loads the keyring components too late in the startup sequence of the server. For example, `InnoDB` requires the component, but because the components are registered in the `mysql.component` table, this table is loaded after `InnoDB` initialization. 3 | 4 | You should create a global manifest file named `mysqld.my` in the installation directory and, optionally, create a local manifest file, also named `mysqld.my` in a data directory. 5 | 6 | To install a keyring component, do the following: 7 | 8 | 1. Write a manifest in a valid JSON format 9 | 10 | 2. Write a configuration file 11 | 12 | A manifest file indicates which component to load. If the manifest file does not exist, the server does not load the component associated with that file. During startup, the server reads the global manifest file from the installation directory. The global manifest file can contain the required information or point to a local manifest file located in the data directory. If you have multiple server instances that use different keyring components use a local manifest file in each data directory to load the correct keyring component for that instance. 13 | 14 | !!! warning 15 | 16 | Enable only one keyring plugin or one keyring component at a time for each server instance. Enabling multiple keyring plugins or keyring components or mixing keyring plugins or keyring components is not supported and may result in data loss. -------------------------------------------------------------------------------- /docs/disable-apparmor.md: -------------------------------------------------------------------------------- 1 | # Disable AppArmor 2 | 3 | ## Disable AppArmor Risks 4 | 5 | Using AppArmor might seem like an extra step, but if you disable it, your server could face security risks. 6 | 7 | Do not disable AppArmor in production environments. This action can have the following risks: 8 | 9 | | Risk | Description | 10 | |---|---| 11 | | Increased Attack Surface | Disabling AppArmor removes security restrictions, potentially allowing unauthorized access to Percona Server for MySQL's files and functionalities. This creates an attractive target for attackers seeking to exploit vulnerabilities or gain control of your database. | 12 | | Unforeseen Security Holes | AppArmor can help mitigate even unknown vulnerabilities by restricting unexpected behaviors. Disabling it leaves your system more susceptible to these hidden security holes. | 13 | | Accidental Misconfigurations | Even with good intentions, manual configuration of access controls can be error-prone. AppArmor provides a pre-defined security layer, reducing the risk of human error in managing permissions. | 14 | 15 | Instead, use AppArmor's security features and configure it to fit your needs. 16 | 17 | ## Disable procedure 18 | 19 | If AppArmor must be disabled, run the following commands: 20 | {.power-number} 21 | 22 | 1. Check the status. 23 | 24 | ```{.bash data-prompt="$"} 25 | $ sudo apparmor_status 26 | ``` 27 | 28 | 2. Stop and disable AppArmor. 29 | 30 | ```{.bash data-prompt="$"} 31 | $ sudo systemctl stop apparmor 32 | $ sudo systemctl disable apparmor 33 | ``` 34 | 35 | ## AppArmor links 36 | 37 | [AppArmor](apparmor.md)
38 | [AppArmor Profiles](apparmor-profiles.md)
39 | [Manage AppArmor Profiles](manage-apparmor-profiles.md)
40 | [Configure AppArmor](configure-apparmor.md)
41 | [Troubleshoot AppArmor](troubleshoot-apparmor.md) -------------------------------------------------------------------------------- /docs/myrocks-index.md: -------------------------------------------------------------------------------- 1 | # Percona MyRocks introduction 2 | 3 | [MyRocks](https://myrocks.io) is a storage engine 4 | for [MySQL](https://www.mysql.com) based on [RocksDB](https://rocksdb.org/), 5 | an embeddable, persistent key-value store. 6 | *Percona MyRocks* is an implementation 7 | for [Percona Server for MySQL](https://www.percona.com/software/percona-server). 8 | 9 | The RocksDB store is based on the log-structured merge-tree (or LSM 10 | tree). It is optimized for fast storage and combines outstanding 11 | space and write efficiency with acceptable read performance. As a 12 | result, MyRocks has the following advantages compared to other storage 13 | engines, if your workload uses fast storage, such as SSD: 14 | 15 | * Requires less storage space 16 | 17 | * Provides more storage endurance 18 | 19 | * Ensures better IO capacity 20 | 21 | !!! important 22 | 23 | The latest MyRocks storage engine is based on recent RocksDB source code, with minor modifications applied by Percona. 24 | 25 | To check the RocksDB version currently used by MyRocks, run the following command: 26 | 27 | ```{.bash data-prompt="$"} 28 | $ head storage/rocksdb/rocksdb/HISTORY.md 29 | ``` 30 | 31 | ??? example "Expected output" 32 | 33 | ```{.text .no-copy} 34 | ... 35 | ## 8.5.1 (08/31/2023) 36 | ... 37 | ``` 38 | 39 | [Percona MyRocks Installation Guide](install-myrocks.md) 40 | 41 | [MyRocks Limitations](myrocks-limitations.md) 42 | 43 | [Differences between Percona MyRocks and Facebook MyRocks](myrocks-differences.md) 44 | 45 | [*MyRocks* Column Families](myrocks-column-families.md) 46 | 47 | [MyRocks Server Variables](myrocks-server-variables.md) 48 | 49 | [MyRocks Information Schema Tables](myrocks-information-schema-tables.md) 50 | 51 | [Performance Schema MyRocks changes](performance-schema-myrocks-changes.md) 52 | -------------------------------------------------------------------------------- /docs/apparmor.md: -------------------------------------------------------------------------------- 1 | # Secure Percona Server for MySQL with AppArmor 2 | 3 | The operating system has a Discretionary Access Controls (DAC) system. AppArmor supplements the DAC with a Mandatory Access Control (MAC) system. AppArmor is the default security module for Ubuntu or Debian systems and uses profiles to define how programs access resources. 4 | 5 | AppArmor is path-based and restricts processes by using profiles. Each profile contains a set of policy rules. Some applications may install their profile along with the application. If an installation does not also install a profile, that application is not part of the AppArmor subsystem. You can also create profiles since they are simple text files stored in the `/etc/apparmor.d` directory. 6 | 7 | AppArmor enhances system security by enforcing strict access controls and protecting against unauthorized access and potential threats. It achieves this by defining profiles that specify how programs interact with system resources. These profiles act as a set of rules dictating a program's actions and the resources it can access. By confining each program to its designated profile, AppArmor limits the damage in case of a compromise and prevents unauthorized escalation of privileges. Additionally, AppArmor provides fine-grained control over program behavior, allowing administrators to tailor security policies to specific application requirements and minimize the attack surface. Overall, AppArmor is crucial in bolstering system security for MySQL developers, maintaining system integrity, and mitigating the risks associated with security breaches. 8 | 9 | ## AppArmor links: 10 | 11 | [AppArmor Profiles](apparmor-profiles.md)
12 | [Manage AppArmor Profiles](manage-apparmor-profiles.md)
13 | [Disable AppArmor](disable-apparmor.md)
14 | [Configure AppArmor](configure-apparmor.md)
15 | [Troubleshoot AppArmor](troubleshoot-apparmor.md) -------------------------------------------------------------------------------- /docs/css/mysql.css: -------------------------------------------------------------------------------- 1 | /* Overrides */ 2 | 3 | :root { 4 | --md-primary-fg-color--dark: var(--sky700) 5 | } 6 | .md-header, 7 | .md-tabs { 8 | background: 9 | -o-linear-gradient( 10 | 340deg, 11 | rgba(0,0,0,0.1) 33%, 12 | rgba(0,0,0,0.2) 95% 13 | ), 14 | -o-linear-gradient( 15 | 340deg, 16 | rgb(14,95,181) 33%, 17 | rgb(48,209,178) 95% 18 | ); 19 | background: 20 | linear-gradient( 21 | 110deg, 22 | rgba(0,0,0,0.1) 33%, 23 | rgba(0,0,0,0.2) 95% 24 | ), 25 | linear-gradient( 26 | 110deg, 27 | rgb(14,95,181) 33%, 28 | rgb(48,209,178) 95% 29 | ); 30 | } 31 | @media screen and (max-width: 76.1875em) { 32 | .md-nav--primary .md-nav__title[for="__drawer"], 33 | .md-nav--primary .md-nav__title { 34 | background: 35 | -o-linear-gradient( 36 | 340deg, 37 | rgba(0,0,0,0.1) 33%, 38 | rgba(0,0,0,0.2) 95% 39 | ), 40 | -o-linear-gradient( 41 | 340deg, 42 | rgb(14,95,181) 33%, 43 | rgb(48,209,178) 95% 44 | ); 45 | background: 46 | linear-gradient( 47 | 110deg, 48 | rgba(0,0,0,0.1) 33%, 49 | rgba(0,0,0,0.2) 95% 50 | ), 51 | linear-gradient( 52 | 110deg, 53 | rgb(14,95,181) 33%, 54 | rgb(48,209,178) 95% 55 | ); 56 | } 57 | } 58 | .superNav, 59 | .md-nav__source { 60 | background-color: rgb(14,95,181); 61 | background-image: 62 | linear-gradient( 63 | 110deg, 64 | rgba(0,0,0,0.25) 33%, 65 | rgba(0,0,0,0.25) 95% 66 | ); 67 | } -------------------------------------------------------------------------------- /docs/log-warnings-suppress.md: -------------------------------------------------------------------------------- 1 | # Suppress warning messages 2 | 3 | This feature is intended to provide a general mechanism (using `log_warnings_silence`) to disable certain warning messages to the log file. Currently, it is only implemented for disabling message #1592 warnings. This feature does not influence warnings delivered to a client. Please note that warning code needs to be a string: 4 | 5 | ```{.bash data-prompt="mysql>"} 6 | mysql> SET GLOBAL log_warnings_suppress = '1592'; 7 | ``` 8 | 9 | ??? example "Expected output" 10 | 11 | ```{.text .no-copy} 12 | Query OK, 0 rows affected (0.00 sec) 13 | ``` 14 | 15 | ## System variables 16 | 17 | ### `log_warnings_suppress` 18 | 19 | | Option | Description | 20 | |--------------|----------------------| 21 | | Command-line | Yes | 22 | | Config file | Yes | 23 | | Scope | Global | 24 | | Dynamic | Yes | 25 | | Data type | SET | 26 | | Default | (empty string) | 27 | | Range | (empty string), 1592 | 28 | 29 | It is intended to provide a more general mechanism for disabling warnings than existed previously with variable suppress_log_warning_1592. 30 | When set to the empty string, no warnings are disabled. When set to `1592`, warning #1592 messages (unsafe statement for binary logging) are suppressed. 31 | In the future, the ability to optionally disable additional warnings may also be added. 32 | 33 | ## Related reading 34 | 35 | * [MySQL bug 42851](https://bugs.mysql.com/bug.php?id=42851) 36 | 37 | * [MySQL InnoDB replication](https://dev.mysql.com/doc/refman/{{vers}}/en/innodb-and-mysql-replication.html) 38 | 39 | * [InnoDB Startup Options and System Variables](https://dev.mysql.com/doc/refman/{{vers}}/en/innodb-parameters.html) 40 | 41 | * [InnoDB Error Handling](https://dev.mysql.com/doc/refman/{{vers}}/en/innodb-error-handling.html) 42 | -------------------------------------------------------------------------------- /docs/apt-download-deb.md: -------------------------------------------------------------------------------- 1 | # Install Percona Server for MySQL {{vers}} using downloaded DEB packages 2 | 3 | Download the packages from [Percona Product Downloads](https://www.percona.com/downloads). If needed, [Instructions for the Percona Product Download](download-instructions.md) are available. 4 | 5 | The following example downloads Percona Server for MySQL {{release}} release packages for Ubuntu 22.04: 6 | 7 | ```{.bash data-prompt="$"} 8 | $ wget https://downloads.percona.com/downloads/Percona-Server-8.4/Percona-Server-8.4.0-1/binary/debian/jammy/x86_64/Percona-Server-8.4.0-1-r238b3c02-jammy-x86_64-bundle.tar 9 | ``` 10 | 11 | Unpack the download to get the packages: 12 | 13 | ```{.bash data-prompt="$"} 14 | $ tar xvf Percona-Server-8.4.0-1-r71449379-buster-x86_64-bundle.tar 15 | ``` 16 | ??? example "Expected output" 17 | 18 | ```text 19 | libperconaserverclient21_{{release}}-1.buster_amd64.deb 20 | libperconaserverclient21-dev_{{release}}-1.buster_amd64.deb 21 | percona-mysql-router_{{release}}-1.buster_amd64.deb 22 | percona-server-client_{{release}}-1.buster_amd64.deb 23 | percona-server-common_{{release}}-1.buster_amd64.deb 24 | percona-server-dbg_{{release}}-1.buster_amd64.deb 25 | percona-server-rocksdb_{{release}}-1.buster_amd64.deb 26 | percona-server-server_{{release}}-1.buster_amd64.deb 27 | percona-server-source_{{release}}-1.buster_amd64.deb 28 | percona-server-test_{{release}}-1.buster_amd64.deb 29 | ``` 30 | 31 | Install Percona Server for MySQL using `dpkg`. Run this command as root or use the sudo command: 32 | 33 | ```{.bash data-prompt="$"} 34 | $ sudo dpkg -i *.deb 35 | ``` 36 | 37 | !!! warning 38 | 39 | When installing packages manually like this, you’ll need to resolve all the dependencies and install missing packages yourself. The following packages will need to be installed before you can manually install Percona Server: `mysql-common`, `libjemalloc1`, `libaio1`, and `libmecab2`. 40 | -------------------------------------------------------------------------------- /docs/show-engines.md: -------------------------------------------------------------------------------- 1 | # Show storage engines 2 | 3 | This feature changes the comment field displayed when the `SHOW STORAGE ENGINES` command is executed and *XtraDB* is the storage engine. 4 | 5 | Before the Change: 6 | 7 | ```{.bash data-prompt="mysql>"} 8 | mysql> show storage engines; 9 | ``` 10 | 11 | ??? example "Expected output" 12 | 13 | ```{.text .no-copy} 14 | +------------+---------+----------------------------------------------------------------+--------------+------+------------+ 15 | | Engine | Support | Comment | Transactions | XA | Savepoints | 16 | +------------+---------+----------------------------------------------------------------+--------------+------+------------+ 17 | | InnoDB | YES | Supports transactions, row-level locking, and foreign keys | YES | YES | YES | 18 | ... 19 | +------------+---------+----------------------------------------------------------------+--------------+------+------------+ 20 | ``` 21 | 22 | After the Change: 23 | 24 | ```{.bash data-prompt="mysql>"} 25 | mysql> show storage engines; 26 | ``` 27 | 28 | ??? example "Expected output" 29 | 30 | ```{.text .no-copy} 31 | +------------+---------+----------------------------------------------------------------------------+--------------+------+------------+ 32 | | Engine | Support | Comment | Transactions | XA | Savepoints | 33 | +------------+---------+----------------------------------------------------------------------------+--------------+------+------------+ 34 | | InnoDB | YES | Percona-XtraDB, Supports transactions, row-level locking, and foreign keys | YES | YES | YES | 35 | ... 36 | +------------+---------+----------------------------------------------------------------------------+--------------+------+------------+ 37 | ``` -------------------------------------------------------------------------------- /docs/group-replication-flow-control.md: -------------------------------------------------------------------------------- 1 | # Manage group replication flow control 2 | 3 | In replication, flow control prevents one member from falling too far behind the cluster and avoids excessive buffering. A cluster is not required to keep members in sync together for replication. The pending transactions in the relay log only increase for the lagging replica. Each member sends statistics to the group. 4 | 5 | Flow control sets a threshold on the queue for transactions waiting in the certification queue or the transactions waiting in the applier queue. If the thresholds are exceeded, and during the duration that they are exceeded, flow control adjusts the writer members to the capacity of the delayed member. This action ensures that all members are in sync. 6 | 7 | Flow controls work asynchronously and depend on the following: 8 | 9 | * Monitoring the throughput and queue sizes of each member 10 | * Throttling members to avoid writing beyond the capacity available 11 | 12 | The following system variables set flow control behavior for Group Replication: 13 | 14 | * [group_replication_flow_control_mode] 15 | * [group_replication_flow_control_certifier_threshold] 16 | * [group_replication_flow_control_applier_threshold] 17 | 18 | Flow control is enabled and disabled by selecting a value in the group_replication_flow_control_mode variable. Flow control can also be enabled on the certifier or applier level or both and sets the threshold level. 19 | 20 | [group_replication_flow_control_mode]: https://dev.mysql.com/doc/refman/{{vers}}/en/group-replication-options.html#sysvar_group_replication_flow_control_mode 21 | [group_replication_flow_control_certifier_threshold]: https://dev.mysql.com/doc/refman/{{vers}}/en/group-replication-options.html#sysvar_group_replication_flow_control_certifier_threshold 22 | [group_replication_flow_control_applier_threshold]: https://dev.mysql.com/doc/refman/{{vers}}/en/group-replication-options.html#sysvar_group_replication_flow_control_applier_threshold -------------------------------------------------------------------------------- /docs/aio-page-requests.md: -------------------------------------------------------------------------------- 1 | # Multiple page asynchronous I/O requests 2 | 3 | The I/O unit size in *InnoDB* is only one page, even if the server doing read ahead. A 16KB 4 | I/O unit size is too small for sequential reads, and less efficient than a larger I/O unit size. *InnoDB* uses Linux asynchronous I/O (`aio`) by default. By submitting multiple, consecutive 16KB read requests at the same time, Linux internally merges the requests and 5 | reads more efficiently. 6 | 7 | This feature is able to submit multiple page I/O requests and works in the background. You can manage the feature with the [linear read-ahead technique]. This technique adds pages to the buffer pool based on the buffer pool pages being accessed sequentially. The [`innodb_read_ahead_threshold`] configuration parameter controls this operation. 8 | 9 | [On a HDD RAID 1+0 environment](http://yoshinorimatsunobu.blogspot.hr/2013/10/making-full-table-scan-10x-faster-in.html), 10 | more than 1000MB/s disk reads can be achieved by submitting 64 consecutive pages 11 | requests at once, while only 12 | 160MB/s disk reads is shown by submitting single page request. 13 | 14 | ## Status variables 15 | 16 | ### `Innodb_buffered_aio_submitted` 17 | 18 | | Option | Description | 19 | | -------------- | ------------------ | 20 | | Scope: | Global | 21 | | Data type: | Numeric | 22 | 23 | This variable shows the number of submitted buffered asynchronous I/O requests. 24 | 25 | ## Other reading 26 | 27 | * [Making full table scan 10x faster in InnoDB](https://yoshinorimatsunobu.blogspot.hr/2013/10/making-full-table-scan-10x-faster-in.html) 28 | 29 | * [Bug #68659 InnoDB Linux native aio should submit more i/o requests at once](https://bugs.mysql.com/bug.php?id=68659) 30 | 31 | [linear read-ahead technique]: https://dev.mysql.com/doc/refman/{{vers}}/en/innodb-performance-read_ahead.html 32 | 33 | [`innodb_read_ahead_threshold`]: https://dev.mysql.com/doc/refman/{{vers}}/en/innodb-parameters.html#sysvar_innodb_read_ahead_threshold -------------------------------------------------------------------------------- /docs/compile-percona-server.md: -------------------------------------------------------------------------------- 1 | # Compile Percona Server for MySQL from source 2 | 3 | The following instructions install Percona Server for MySQL {{vers}}. 4 | 5 | ## Install Percona Server for MySQL from the Git Source Tree 6 | 7 | Percona uses the [Github](https://github.com/) revision 8 | control system for development. To build the latest Percona Server for MySQL 9 | from the source tree, you will need `git` installed on your system. 10 | 11 | You can now fetch the latest Percona Server for MySQL {{vers}} sources. 12 | 13 | ```{.bash data-prompt="$"} 14 | $ git clone https://github.com/percona/percona-server.git 15 | $ cd percona-server 16 | $ git checkout {{vers}} 17 | $ git submodule init 18 | $ git submodule update 19 | ``` 20 | 21 | If you are going to be making changes to Percona Server for MySQL {{vers}} and wanting 22 | to distribute the resulting work, you can generate a new source tarball 23 | (exactly the same way as we do for release): 24 | 25 | ```{.bash data-prompt="$"} 26 | $ cmake . 27 | $ make dist 28 | ``` 29 | 30 | After either fetching the source repository or extracting a source tarball 31 | (from Percona or one you generated yourself), you will now need to 32 | configure and build Percona Server for MySQL. 33 | 34 | First, run CMake to configure the build. Here you can specify all the normal 35 | build options as you do for a normal MySQL build. Depending on what 36 | options you wish to compile Percona Server for MySQL with, you may need other 37 | libraries installed on your system. Here is an example using a 38 | configure line similar to the options that Percona uses to produce 39 | binaries: 40 | 41 | ```{.bash data-prompt="$"} 42 | $ cmake . -DCMAKE_BUILD_TYPE=RelWithDebInfo -DBUILD_CONFIG=mysql_release -DFEATURE_SET=community 43 | ``` 44 | 45 | ## Compile from source 46 | 47 | Now, compile using make: 48 | 49 | ```{.bash data-prompt="$"} 50 | $ make 51 | ``` 52 | 53 | Install: 54 | 55 | ```{.bash data-prompt="$"} 56 | $ make install 57 | ``` 58 | 59 | Percona Server for MySQL {{vers}} is installed on your system. 60 | -------------------------------------------------------------------------------- /docs/percona-toolkit-8.4-updates.md: -------------------------------------------------------------------------------- 1 | # Percona Toolkit updates for {{vers}} 2 | 3 | Percona Toolkit has been updated to support MySQL {{vers}}, addressing terminology, deprecations, and authentication improvements. If your automation or runbooks use these tools, plan updates alongside the database upgrade. 4 | 5 | ## Terminology alignment 6 | 7 | * Toolkit commands and output now use SOURCE/REPLICA terminology consistent with MySQL {{vers}}. 8 | 9 | ## Renamed tools 10 | 11 | * `pt-slave-find` → `pt-replica-find` 12 | * `pt-slave-restart` → `pt-replica-restart` 13 | 14 | Aliases with the old names remain for a transition period; update scripts and runbooks to the new names. 15 | 16 | ## Deprecated tool 17 | 18 | * `pt-slave-delay` is deprecated and does not support MySQL {{vers}}. Use built-in delayed replication features instead. 19 | 20 | ## Authentication and SSL 21 | 22 | * Enhanced SSL/TLS handling and improved support for `caching_sha2_password` and `sha256_password` authentication plugins. 23 | 24 | ## What to change in your environment 25 | 26 | * Update automation and scripts: replace `pt-slave-find` with `pt-replica-find`, and `pt-slave-restart` with `pt-replica-restart`. 27 | * Remove dependencies on `pt-slave-delay`; use native delayed replication features instead. 28 | * Validate Toolkit connectivity using your TLS settings and modern authentication plugins. 29 | 30 | ## Further reading 31 | 32 | * [Upgrade overview](./upgrade.md) 33 | * [Upgrade checklist for {{vers}}](./upgrade-checklist-8.4.md) 34 | * [Upgrade procedures for {{vers}}](./upgrade-procedures.md) 35 | * [Upgrade strategies](./upgrade-strategies.md) 36 | * [MySQL upgrade paths and supported methods](./mysql-upgrade-paths.md) 37 | * [Upgrade from plugins to components](./upgrade-components.md) 38 | * [Downgrade options](./downgrade.md) 39 | * [Breaking and incompatible changes in {{vers}}](./8.4-breaking-changes.md) 40 | * [Compatibility and removed items in {{vers}}](./8.4-compatibility-and-removed-items.md) 41 | * [Defaults and tuning guidance for {{vers}}](./8.4-defaults-and-tuning.md) 42 | 43 | -------------------------------------------------------------------------------- /docs/faq.md: -------------------------------------------------------------------------------- 1 | # Frequently asked questions 2 | 3 | ## Q: Will *Percona Server for MySQL* with *XtraDB* invalidate our *MySQL* support? 4 | 5 | A: We don’t know the details of your support contract. You should check with 6 | your *Oracle* representative. We have heard anecdotal stories from *MySQL* 7 | Support team members that they have customers who use *Percona Server for MySQL* with 8 | *XtraDB*, but you should not base your decision on that. 9 | 10 | ## Q: Will we have to *GPL* our whole application if we use *Percona Server for MySQL* with *XtraDB*? 11 | 12 | A: This is a common misconception about the *GPL*. We suggest reading the *Free 13 | Software Foundation* ‘s excellent reference material on the [GPL Version 2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html), which is the license 14 | that applies to *MySQL* and therefore to *Percona Server for MySQL* with *XtraDB*. That 15 | document contains links to many other documents which should answer your 16 | questions. *Percona* is unable to give legal advice about the *GPL*. 17 | 18 | ## Q: Do I need to install *Percona* client libraries? 19 | 20 | A: No, you don’t need to change anything on the clients. *Percona Server for MySQL* is 21 | 100% compatible with all existing client libraries and connectors. 22 | 23 | ## Q: When using the *Percona XtraBackup* to set up a replication replica on Debian-based systems I’m getting: “ERROR 1045 (28000): Access denied for user [‘debian-sys-maint’@’localhost](mailto:'debian-sys-maint'@'localhost)’ (using password: YES)” 24 | 25 | A: In case you’re using the init script on Debian-based system to start `mysqld`, 26 | be sure that the password for `debian-sys-maint` user has been updated and 27 | it’s the same as that user’s password from the server that the backup has been 28 | taken from. The password can be seen and updated in 29 | `/etc/mysql/debian.cnf`. For more information on how to set up a 30 | replication replica using *Percona XtraBackup* see [this how-to]. 31 | 32 | [this how-to]: https://docs.percona.com/percona-xtrabackup/innovation-release/set-up-replication.html 33 | 34 | -------------------------------------------------------------------------------- /docs/proxy-protocol-support.md: -------------------------------------------------------------------------------- 1 | # Support for PROXY protocol 2 | 3 | The proxy protocol allows an intermediate proxying server speaking proxy protocol (ie. HAProxy) between the server and the ultimate client (i.e. mysql client etc) to provide the source client address to the server, which normally would only see the proxying server address instead. 4 | 5 | As the proxy protocol amounts to spoofing the client address, it is disabled by default, and can be enabled on per-host or per-network basis for the trusted source addresses where trusted proxy servers are known to run. Unproxied connections are not allowed from these source addresses. 6 | 7 | !!! note 8 | 9 | Ensure that proper firewall access control lists (ACL) are in place when this feature is enabled. 10 | 11 | Proxying is supported only for TCP over IPv4 and IPv6 connections. The UNIX socket connections can not be proxied and do not fall under the effect of using the asterisk symbol (*). 12 | 13 | You cannot have a proxied IP address that is `127.0.0.1` or `::1`, even if the IP address is in the proxy_protocol_networks. 14 | 15 | ## System variables 16 | 17 | ### `proxy_protocol_networks` 18 | 19 | | Option | Description | 20 | |--------------|----------------| 21 | | Command-line | Yes | 22 | | Config file | Yes | 23 | | Scope | Global | 24 | | Dynamic | No | 25 | | Default | (empty string) | 26 | 27 | This variable is a global-only, read-only variable, which is either an asterisk symbol(*), or a list of comma-separated IPv4 and IPv6 network and host addresses. For security reasons we do not recommend using an asterisk symbol for the IP address. This symbol causes the server to accept the proxy protocol from any host. Network addresses are specified in CIDR notation, i.e. `192.168.0.0/24`. To prevent source host spoofing, the setting of this variable must be as restrictive as possible to include only trusted proxy hosts. 28 | 29 | ## Related reading 30 | 31 | * [PROXY protocol specification](http://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) 32 | -------------------------------------------------------------------------------- /docs/adaptive-network-buffers.md: -------------------------------------------------------------------------------- 1 | # Adaptive network buffers 2 | 3 | To find the buffer size of the current connection, use the `network_buffer_length` status variable. Add `SHOW GLOBAL` to review the cumulative buffer sizes for all connections. This variable can help to estimate the maximum size of the network buffer’s overhead. 4 | 5 | Network buffers grow towards the [max_allowed_packet] size and do not shrink until the connection is terminated. For example, if the connections are selected at random from the pool, an occasional big query eventually increases the buffers of all connections. The combination of max_allowed packet set to a value between 64MB and 128MB and the connection number between 256 and 1024 can create a large memory overhead. 6 | 7 | Percona Server for MySQL implemented the [net_buffer_shrink_interval](#net_buffer_shrink_interval) variable to solve this issue. The default value is 0 (zero). If you set the value higher than 0, Percona Server records the network buffer’s maximum use size for the number of seconds set by net_buffer_shrink_interval. When the next interval starts, the network buffer is set to the recorded size. This action removes spikes in the buffer size. 8 | 9 | You can achieve similar results by disconnecting and reconnecting the TCP connections, but this solution is a heavier process. This process disconnects and reconnects connections with small buffers. 10 | 11 | ### `net_buffer_shrink_interval` 12 | 13 | | Option | Description | 14 | | -------------- | ----------------------------- | 15 | | Command-line: | –net-buffer-shrink-interval=# | 16 | | Scope: | Global | 17 | | Dynamic: | Yes | 18 | | Data type: | integer | 19 | | Default value: | 0 | 20 | 21 | The interval is measured in seconds. The default value is 0, which disables the functionality. The minimum value is 0, and the maximum value is 31536000. 22 | 23 | [max_allowed_packet]: https://dev.mysql.com/doc/refman/{{vers}}/en/server-system-variables.html#sysvar_max_allowed_packet 24 | -------------------------------------------------------------------------------- /docs/assets/mysql-fav.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | -------------------------------------------------------------------------------- /docs/innodb-fts-improvements.md: -------------------------------------------------------------------------------- 1 | # InnoDB full-text search improvements 2 | 3 | # Ignoring stopword list 4 | 5 | By default, all Full-Text Search indexes check the [stopwords list], to see if any indexed elements contain words on that list. 6 | 7 | Using this list for n-gram indexes isn’t always suitable, for example, any 8 | item that contains `a` or `i` will be ignored. Another word that can’t be 9 | searched is `east`, this one will find no matches because `a` is on the 10 | FTS stopword list. 11 | 12 | To resolve this issue, *Percona Server for MySQL* has the 13 | `innodb_ft_ignore_stopwords` variable to control whether 14 | *InnoDB* Full-Text Search should ignore the stopword list. 15 | 16 | Although this variable is introduced to resolve n-gram issues, it affects all Full-Text Search indexes as well. 17 | 18 | Being a stopword doesn’t just mean being one of the predefined 19 | words from the list. Tokens shorter than [innodb_ft_min_token_size] or longer than [innodb_ft_max_token_size] are also considered stopwords. Therefore, when 20 | innodb_ft_ignore_stopwords is set to `ON` even for non-ngram 21 | FTS, `innodb_ft_min_token_size` / `innodb_ft_max_token_size` will be 22 | ignored meaning that in this case very short and very long words will 23 | also be indexed. 24 | 25 | ## System variables 26 | 27 | ### `innodb_ft_ignore_stopwords` 28 | 29 | | Option | Description | 30 | |--------------|-----------------| 31 | | Command-line | Yes | 32 | | Config file | Yes | 33 | | Scope | Session, Global | 34 | | Dynamic | Yes | 35 | | Data type | Boolean | 36 | | Default | OFF | 37 | 38 | When enabled, this variable will instruct *InnoDB* Full Text Search parser to ignore the stopword list when building/updating an FTS index. 39 | 40 | [stopwords list]: https://dev.mysql.com/doc/refman/{{vers}}/en/fulltext-stopwords.html 41 | [innodb_ft_min_token_size]: https://dev.mysql.com/doc/refman/{{vers}}/en/innodb-parameters.html#sysvar_innodb_ft_min_token_size 42 | [innodb_ft_max_token_size]: https://dev.mysql.com/doc/refman/{{vers}}/en/innodb-parameters.html#sysvar_innodb_ft_max_token_size -------------------------------------------------------------------------------- /docs/downgrade-from-pro.md: -------------------------------------------------------------------------------- 1 | # Downgrade from Percona Server for MySQL Pro 2 | 3 | If you want to downgrade from Percona Server for MySQL Pro to the same version of Percona Server for MySQL, do the following: 4 | 5 | === "On Debian and Ubuntu" 6 | 7 | 1. Set up the Percona Server for MySQL 8.4 repository 8 | 9 | ```{.bash data-prompt="$"} 10 | $ sudo percona-release setup ps84 11 | ``` 12 | 13 | 2. Stop the `mysql` server. 14 | 15 | ```{.bash data-prompt="$"} 16 | $ sudo systemctl stop mysql 17 | ``` 18 | 19 | 3. Install the server package 20 | 21 | ```{.bash data-prompt="$"} 22 | $ sudo apt install percona-server-server 23 | ``` 24 | 25 | Install other required packages. [Check files in the DEB package built for Percona Server for MySQL 8.4](apt-files.md). 26 | 27 | 4. Start the `mysql` server 28 | 29 | ```{.bash data-prompt="$"} 30 | $ sudo systemctl start mysql 31 | ``` 32 | 33 | !!! note 34 | 35 | On Debian 12, if you want to remove the Percona Server for MySQL after the downgrade, you must stop the 36 | server manually. This behavior will be fixed in future releases. 37 | 38 | ```{.bash data-prompt="$"} 39 | $ sudo systemctl stop mysql 40 | ``` 41 | 42 | === "On RHEL and derivatives" 43 | 44 | 1. Set up the Percona Server for MySQL 8.4 repository 45 | 46 | ```{.bash data-prompt="$"} 47 | $ sudo percona-release setup ps84 48 | ``` 49 | 50 | 2. Stop the `mysql` server. 51 | 52 | ```{.bash data-prompt="$"} 53 | $ sudo systemctl stop mysql 54 | ``` 55 | 56 | 3. Install the server package 57 | 58 | ```{.bash data-prompt="$"} 59 | $ sudo yum --allowerasing install percona-server-server 60 | ``` 61 | 62 | Install other required packages. [Check files in the RPM package built for Percona Server for MySQL 8.4](yum-files.md). 63 | 64 | 4. Start the `mysql` server 65 | 66 | ```{.bash data-prompt="$"} 67 | $ sudo systemctl start mysql 68 | ``` 69 | -------------------------------------------------------------------------------- /docs/quickstart-overview.md: -------------------------------------------------------------------------------- 1 | # Overview 2 | 3 | Percona Server for MySQL is a freely available, fully compatible, enhanced, and open source drop-in replacement for any MySQL database and provides enterprise-grade features in security, availability, data management, visibility, instrumentation, and performance. 4 | 5 | --8<--- "get-help-snip.md" 6 | 7 | ## Install Percona Server for MySQL 8 | 9 | 10 | You can explore alternative installation options in the [Install] section of the Percona Server for MySQL documentation. 11 | 12 | 13 | ## Purpose of the Quickstart 14 | 15 | This document guides you through the initial setup process, including setting a root password in either APT or YUM, creating a database. 16 | 17 | You can also do the following: 18 | 19 | * [Download and install Percona Server for MySQL packages for your operating system](installation.md) 20 | 21 | * Work with [the Quickstart for the Percona Operator for MySQL based on the Percona Server for MySQL using Helm] or [the Quickstart for the Percona Operator for MySQL based on the Percona Server for MySQL using Minikube] to find out more about the Percona Operator. 22 | 23 | 24 | ## Steps for first-time users 25 | 26 | The following guides walk you through the setup process and working with a database for a developer. Select the installation method that works best in your environment. 27 | 28 | 29 | ## Next steps 30 | 31 | [Run and create database (container):material-arrow-right:](quickstart-docker.md){.md-button} 32 | 33 | [Install and create database (Ubuntu):material-arrow-right:](quickstart-apt.md){.md-button} 34 | 35 | [Install and create database (Oracle Linux):material-arrow-right:](quickstart-yum.md){.md-button} 36 | 37 | [Choose your next steps:material-arrow-right:](quickstart-next-steps.md){.md-button} 38 | 39 | 40 | 41 | 42 | 43 | [the Quickstart for the Percona Operator for MySQL based on the Percona Server for MySQL using Helm]: https://docs.percona.com/percona-operator-for-mysql/ps/helm.html 44 | 45 | [the Quickstart for the Percona Operator for MySQL based on the Percona Server for MySQL using Minikube]: https://docs.percona.com/percona-operator-for-mysql/ps/minikube.html 46 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ## Percona Server for MySQL 2 | 3 | ![PS logo](docs/_static/Percona_Logo_Color.png) 4 | 5 | Percona Server for MySQL is a free, fully compatible, enhanced, and open source drop-in replacement for any MySQL database. It provides superior performance, scalability, and instrumentation. 6 | 7 | Percona Server for MySQL is trusted by thousands of enterprises to provide better performance and concurrency for their most demanding workloads. It delivers higher value to MySQL server users with optimized performance, greater performance scalability and availability, enhanced backups, and increased visibility. 8 | 9 | ## Installation 10 | 11 | You can install Percona Server for MySQL using the following methods: 12 | - from the Percona repository 13 | - Build from the [source code](https://github.com/percona/percona-server) 14 | 15 | The installation instructions in the official documentation are [here](https://docs.percona.com/percona-server/8.0/installation.html). 16 | 17 | ## Submit a bug report or a feature request 18 | 19 | If you find a bug in Percona Server for MySQL, you can submit a report to the project's [Jira issue tracker](https://jira.percona.com/projects/PS/issues) 20 | 21 | As a general rule of thumb, please try to create a bug report that is: 22 | 23 | - Reproducible - include the steps on how to reproduce the issue 24 | - Specific - include as much detail as possible, such as which version, which environment, etc. 25 | - Unique - do not duplicate existing tickets 26 | - Scoped to a single issue - only one issue per report 27 | 28 | ## License 29 | 30 | Percona Server for MySQL documentation is licensed under a [Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/). 31 | 32 | ## Contribute to the documentation 33 | 34 | We encourage contributions and are always looking for new members that are as dedicated to serving the community as we are. The [Contributing Guide](https://github.com/percona/psmysql-docs/blob/8.0/contributing.md) contains how you can contribute. 35 | 36 | ## Contact 37 | 38 | You can reach us by using the [Forum](https://forums.percona.com/c/mysql-mariadb/percona-server-for-mysql-8-0). 39 | -------------------------------------------------------------------------------- /docs/apt-files.md: -------------------------------------------------------------------------------- 1 | # Files in the DEB package built for Percona Server for MySQL {{vers}} 2 | 3 | | Package | Contains | 4 | |------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 5 | | percona-server-server | The database server itself, the mysqld binary and associated files. | 6 | | percona-server-common | The files common to the server and client. | 7 | | percona-server-client | The command line client. | 8 | | percona-server-dbg | Debug symbols for the server. | 9 | | percona-server-test | The database test suite. | 10 | | percona-server-source | The server source. | 11 | | libperconaserverclient22-dev | Header files needed to compile software to use the client library. | 12 | | libperconaserverclient22 | The client-shared library. The version is incremented when there is an ABI change that requires software using the client library to be recompiled or its source code modified. | -------------------------------------------------------------------------------- /docs/select.md: -------------------------------------------------------------------------------- 1 | # SELECT statement 2 | 3 | The syntax of a SELECT statement in MySQL is straightforward. You start with the keyword SELECT, followed by the columns from which you want to retrieve data. You can specify the table from which to retrieve data using the FROM keyword. Optionally, you can include conditions to filter the results using the WHERE clause. 4 | 5 | The following table is a breakdown of the syntax: 6 | 7 | | Syntax | Description | 8 | |---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| 9 | | **SELECT** | This keyword indicates that you want to retrieve data from the database. | 10 | | **Columns** | Specify the columns you want to retrieve data from. You can use the asterisk (*) to select all columns or specify individual column names separated by commas. | 11 | | **FROM** | Use the FROM keyword to specify the table from which you want to retrieve data. | 12 | | **WHERE (optional)** | If you want to filter the results based on specific conditions, you can use the WHERE clause. This clause allows you to specify conditions using comparison operators like =, >, <, etc., and logical operators like AND, OR, NOT. | 13 | 14 | 15 | ```text 16 | SELECT column1, column2 17 | FROM table_name 18 | WHERE condition; 19 | ``` 20 | 21 | - `SELECT column1, column2` specifies that you want to retrieve data from column1 and column2. 22 | - `FROM table_name` specifies the table from which you want to retrieve data. 23 | - `WHERE condition` is an optional clause that filters the results based on the specified condition. 24 | 25 | Fundamental SQL links: 26 | 27 | * [Common SQL](common-sql.md) 28 | * [SQL Basics](sql-basics.md) 29 | * [INSERT](insert.md) 30 | * [DELETE](delete.md) 31 | * [UPDATE](update.md) 32 | * [SQL Operators](sql-operators.md) -------------------------------------------------------------------------------- /docs/using-kmip.md: -------------------------------------------------------------------------------- 1 | # Use the Key Management Interoperability Protocol (KMIP) 2 | 3 | Percona Server for MySQL supports the [OASIS Key Management Interoperability Protocol (KMIP)](https://docs.oasis-open.org/kmip/kmip-spec/v2.0/os/kmip-spec-v2.0-os.html). This implementation was tested with the [PyKMIP server](https://pykmip.readthedocs.io/en/latest/server.html) and the [HashiCorp Vault Enterprise KMIP Secrets Engine](https://www.vaultproject.io/docs/secrets/kmip). 4 | 5 | KMIP enables communication between key management systems and the database server. The protocol can do the following: 6 | 7 | * Streamline encryption key management 8 | 9 | * Eliminate redundant key management processes 10 | 11 | ## Component installation 12 | 13 | --8<--- "keyring-components-installation.md" 14 | 15 | For more information, see [Installing and Uninstalling Components]. 16 | 17 | The following is an example of a global manifest file that does not use local manifests: 18 | 19 | ```json 20 | { 21 | "read_local_manifest": false, 22 | "components": "file://component_keyring_kmip" 23 | } 24 | ``` 25 | 26 | The following is an example of a global manifest file that points to a local manifest file: 27 | 28 | ```json 29 | { 30 | "read_local_manifest": true 31 | } 32 | ``` 33 | 34 | The following is an example of a local manifest file: 35 | 36 | ```json 37 | { 38 | "components": "file://component_keyring_kmip" 39 | } 40 | ``` 41 | 42 | The configuration settings are either in a global configuration file or a local configuration file. The settings are the same. 43 | 44 | ??? example "Example of a configuration file in JSON format" 45 | 46 | ```json 47 | { 48 | "server_addr": "127.0.0.1", 49 | "server_port": "5696", 50 | "client_ca": "client_certificate.pem", 51 | "client_key": "client_key.pem", 52 | "server_ca": "root_certificate.pem" 53 | } 54 | ``` 55 | 56 | For more information, see [Keyring Component installation]. 57 | 58 | [Installing and Uninstalling Components]: https://dev.mysql.com/doc/refman/{{vers}}/en/component-loading.html 59 | [Keyring Component installation]: https://dev.mysql.com/doc/refman/{{vers}}/en/keyring-component-installation.html 60 | -------------------------------------------------------------------------------- /docs/encrypt-binary-relay-log-files.md: -------------------------------------------------------------------------------- 1 | # Encrypt binary log files and relay log files 2 | 3 | Encrypt the binary log files and the relay log files to protect them from unauthorized viewing. The encryption uses the Advanced Encryption Standard (AES) symmetric block cipher algorithm. Instead of bits, this algorithm works on bytes. 4 | 5 | Any supported encryption keyring plugin or component must be installed and configured to use encryption. 6 | 7 | Enabling binary log encryption at system start, the server generates a binary log encryption key before iniatializing the binary log and relay logs. The key encrypts a file password for each binary log, if binary logging is enabled, and relay log. Keys generated from the file passwords encrypt the data in the files. 8 | 9 | When used by the server, the binary log encryption key is called the binary log master key. This key can be rotated as needed and only the file password for each file is re-encrypted. 10 | 11 | The binary log index file and relay log index file is never encrypted. Relay log files are encrypted for all channels. 12 | 13 | To review if a binary log file is encrypted or not, use the `SHOW BINARY LOGS` statement. 14 | 15 | If the server is running, the `BINLOG_ENCRYPTION_ADMIN` privilege is required to enable or disable encryption. 16 | 17 | ## `binlog_encryption` 18 | 19 | | Option | Description | 20 | |--------------|---------------------------| 21 | | Command-line | `--binlog-encryption[= {ON \| OFF}]` | 22 | | Scope | Global | 23 | | Dynamic | Yes | 24 | | Data type | Boolean | 25 | | Default | OFF | 26 | 27 | This system variable enables binary log file encryption and relay log file encryption on the server. The default value is `OFF`. You can enable encryption for relay log files on a replica without a binary log. 28 | 29 | If you set the `binlog_encryption` to `OFF`, the server immediately rotates the binary log file and relay log files and all logging is not encrypted. For any previously encrypted files, the server can still read them and they are not decrypted. 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | -------------------------------------------------------------------------------- /.github/workflows/main.yml: -------------------------------------------------------------------------------- 1 | name: Build Percona Server 8.4 docs 2 | on: 3 | push: 4 | branches: 5 | - 8.4 6 | jobs: 7 | build: 8 | name: Deploy docs 9 | runs-on: ubuntu-latest 10 | 11 | steps: 12 | #Pull the latest changes 13 | - name: Chekout code 14 | uses: actions/checkout@v3 15 | with: 16 | fetch-depth: 0 17 | #Prepare the env 18 | - name: Set up Python 19 | uses: actions/setup-python@v3 20 | with: 21 | python-version: '3.x' 22 | 23 | #Configure git 24 | - name: Configure git 25 | env: 26 | ROBOT_TOKEN: ${{ secrets.ROBOT_TOKEN }} 27 | run: | 28 | git config --global url."https://percona-platform-robot:${ROBOT_TOKEN}@github.com".insteadOf "https://github.com" 29 | git config user.name "GitHub Action" 30 | git config user.email "github-action@users.noreply.github.com" 31 | git config user.password "${ROBOT_TOKEN}" 32 | echo "GIT_USER=percona-platform-robot:${ROBOT_TOKEN}" >> $GITHUB_ENV 33 | #Set up MkDocs 34 | - name: Install MkDocs 35 | run: | 36 | python -m pip install --upgrade pip 37 | pip install wheel 38 | if [ -f requirements.txt ]; then pip install -r requirements.txt; fi 39 | #Set up PlantUML 40 | - name: Setup PlantUML dependencies 41 | run: | 42 | sudo apt install -y graphviz 43 | 44 | # Deploy docs 45 | - name: Deploy docs 46 | run: | 47 | mike deploy 8.4 -b publish -p 48 | mike set-default 8.4 -b publish -p 49 | mike retitle 8.4 "8.4 (LATEST)" -b publish -p 50 | 51 | # - name: Install Node.js 14.x 52 | # uses: percona-platform/setup-node@v2 53 | # with: 54 | # node-version: "14" 55 | # 56 | # - name: Spelling 57 | # run: | 58 | # npx markdown-spellcheck --report --en-us --ignore-acronyms --ignore-numbers "docs/**/*.md" || true 59 | # Ignore errors, just inspect results 60 | # - name: Grammar 61 | # run: | 62 | # npx write-good --no-passive docs/**/*.md || true 63 | # # Ignore errors, just inspect results 64 | -------------------------------------------------------------------------------- /_resource/templates/styles.scss: -------------------------------------------------------------------------------- 1 | /* Style for PDF created by MkDocs with mkdocs-with-pdf plugin (https://pypi.org/project/mkdocs-with-pdf/) */ 2 | @media print { 3 | html { 4 | font-size: 100%; 5 | font-family: "Poppins", sans-serif; 6 | } 7 | 8 | body { 9 | font-family: "Poppins", sans-serif; 10 | color: #00162b; 11 | } 12 | 13 | article { 14 | font-family: "Poppins", sans-serif; 15 | text-align: justify; 16 | } 17 | 18 | pre, 19 | code, 20 | var, 21 | samp, 22 | kbd, 23 | tt { 24 | font-family: monospace; 25 | font-size: 110%; 26 | } 27 | 28 | pre code, 29 | pre var, 30 | pre samp, 31 | pre kbd, 32 | pre tt { 33 | font-size: 110%; 34 | } 35 | } 36 | 37 | @page { 38 | size: a4 portrait; 39 | margin: 25mm 20mm 25mm 20mm; 40 | counter-increment: page; 41 | white-space: pre; 42 | color: #00162b; 43 | 44 | @top-right { 45 | content: string(chapter); 46 | } 47 | 48 | @bottom-left { 49 | content: string(subtitle); 50 | } 51 | 52 | @bottom-center { 53 | content: counter(page)' of 'counter(pages); 54 | } 55 | 56 | @bottom-right { 57 | } 58 | } 59 | 60 | @page :first { 61 | @top-right { 62 | content: ''; 63 | } 64 | 65 | @bottom-right { 66 | content: ''; 67 | } 68 | 69 | @bottom-left { 70 | content: ''; 71 | } 72 | } 73 | 74 | article { 75 | page-break-before: always; 76 | min-height: 100%; 77 | } 78 | 79 | article { 80 | 81 | h1, 82 | h2, 83 | h3 { 84 | border-bottom: 0px solid #fff; 85 | } 86 | 87 | h1>.pdf-order, 88 | h2>.pdf-order, 89 | h3>.pdf-order { 90 | padding-left: 6px; 91 | padding-right: 0.8rem; 92 | } 93 | } 94 | 95 | article h1, 96 | h2, 97 | h3 { 98 | border-bottom: 0px solid #fff; 99 | color: #3e4875; 100 | } 101 | 102 | .admonition { 103 | font-size: 100%; 104 | } 105 | 106 | .md-typeset .admonition.note, 107 | .md-typeset details.note { 108 | color: #00162b; 109 | border-color: #fff; 110 | } -------------------------------------------------------------------------------- /docs/audit-log-filter-naming.md: -------------------------------------------------------------------------------- 1 | # Audit Log Filter file naming conventions 2 | 3 | ## Name qualities 4 | 5 | The audit log filter file name has the following qualities: 6 | 7 | * Optional directory name 8 | * Base name 9 | * Optional suffix 10 | 11 | Using either [compression](audit-log-filter-compression-encryption.md) or [encryption](audit-log-filter-compression-encryption.md) adds the following suffixes: 12 | 13 | * Compression adds the `.gz` suffix 14 | * Encryption adds the `pwd_id.enc` suffix 15 | 16 | The `pwd_id` represents the password used for encrypting the log files. The audit log filter component stores passwords in the keyring. 17 | 18 | You can combine compression and encryption, which adds both suffixes to the `audit_filter.log` name. 19 | 20 | The following table displays the possible ways a file can be named: 21 | 22 | | Default name | Enabled feature | 23 | | ----------------------- | ------------------------------ | 24 | | audit.log | No compression or encryption | 25 | | audit.log.gz | Compression | 26 | | audit.log.pwd_id.enc | Encryption | 27 | | audit.log.gz.pwd_id.enc | Compression, encryption | 28 | 29 | ### Encryption ID format 30 | 31 | The format for `pwd_id` is the following: 32 | 33 | * A UTC value in `YYYYMMDDThhmmss` format that represents when the password was created 34 | * A sequence number that starts at `1` and increases if passwords have the same timestamp value 35 | 36 | The following are examples of pwd_id values: 37 | 38 | ```text 39 | 20230417T082215-1 40 | 20230301T061400-1 41 | 20230301T061400-2 42 | ``` 43 | 44 | The following example is a list of the audit log filter files with the `pwd_id`: 45 | 46 | ```text 47 | audit_filter.log.20230417T082215-1.enc 48 | audit_filter.log.20230301T061400-1.enc 49 | audit_filter.log.20230301T061400-2.enc 50 | ``` 51 | 52 | The current password has the largest sequence number. 53 | 54 | ## Renaming operations 55 | 56 | During initialization, the component checks if a file with that name exists. 57 | If it does, the component renames the file. The component writes to an empty file. 58 | 59 | During termination, the component renames the file. 60 | 61 | 62 | -------------------------------------------------------------------------------- /docs/audit-log-filter-restrictions.md: -------------------------------------------------------------------------------- 1 | # Audit Log Filter restrictions 2 | 3 | ## General restrictions 4 | 5 | The Audit Log Filter has the following general restrictions: 6 | 7 | The Audit Log Filter has the following general restrictions: 8 | 9 | * Log only SQL statements. Statements made by NoSQL APIs, such as the 10 | Memcached API, are not logged. 11 | 12 | * Log only the top-level statement. Statements within a stored procedure 13 | or a trigger are not logged. Do not log the file contents for statements 14 | like `LOAD_DATA`. 15 | 16 | * Require the component to be installed on each server used to execute SQL 17 | on the cluster if used with a cluster. 18 | 19 | * Hold the application or user responsible for aggregating all the data from 20 | each server used in the cluster if used with a cluster. 21 | 22 | * Each server must have its own audit log filter rules. If you do not set up the rules on the replica server, that server does not record the corresponding entries in the audit log. This design requires that the audit log configuration be performed separately for each server. 23 | 24 | As by default the content of the `mysql.audit_log_filter` and `mysql.audit_log_user` tables may be replicated from source to replica and may affect audit log rules created on the replica, it is recommended to configure replication in such a way that the changes in these tables are simply ignored. 25 | 26 | Please notice that just changing the content of these tables (via replication channel) is not enough to automatically make changes to in-memory data structures in the `audit_log_filter` component that store information about active audit log filtering rules. However, this may happen after component reloading / server restart or manually calling `audit_log_filter_flush()`. 27 | 28 | * Filter only on string values. The audit log filter does not filter on integer values. All filter criteria must be specified as strings, even when the underlying value is numeric. For example, `connection_id` values must be specified as strings (for example, `"123"` rather than `123`), and status values must be specified as `"0"` or `"1"` rather than `0` or `1`. If you use integer values in your filter definition, you will see the error: `ERROR: Incorrect rule definition.` 29 | -------------------------------------------------------------------------------- /docs/js/version-select.js: -------------------------------------------------------------------------------- 1 | /* 2 | * Custom version of same taken from mike code for injecting version switcher into percona.com 3 | */ 4 | 5 | window.addEventListener("DOMContentLoaded", function() { 6 | // This is a bit hacky. Figure out the base URL from a known CSS file the 7 | // template refers to... 8 | var ex = new RegExp("/?css/version-select.css$"); 9 | var sheet = document.querySelector('link[href$="version-select.css"]'); 10 | 11 | var ABS_BASE_URL = sheet.href.replace(ex, ""); 12 | var CURRENT_VERSION = ABS_BASE_URL.split("/").pop(); 13 | 14 | function makeSelect(options, selected) { 15 | var select = document.createElement("select"); 16 | // select.classList.add("form-control"); 17 | select.classList.add("btn"); 18 | select.classList.add("btn-primary"); 19 | 20 | options.forEach(function(i) { 21 | var option = new Option(i.text, i.value, undefined, 22 | i.value === selected); 23 | select.add(option); 24 | }); 25 | 26 | return select; 27 | } 28 | 29 | var xhr = new XMLHttpRequest(); 30 | xhr.open("GET", ABS_BASE_URL + "/../versions.json"); 31 | xhr.onload = function() { 32 | var versions = JSON.parse(this.responseText); 33 | 34 | var realVersion = versions.find(function(i) { 35 | return i.version === CURRENT_VERSION || 36 | i.aliases.includes(CURRENT_VERSION); 37 | }).version; 38 | 39 | var select = makeSelect(versions.map(function(i) { 40 | return {text: i.title, value: i.version}; 41 | }), realVersion); 42 | select.addEventListener("change", function(event) { 43 | window.location.href = ABS_BASE_URL + "/../" + this.value; 44 | }); 45 | 46 | var container = document.createElement("div"); 47 | container.id = "custom_select"; 48 | container.classList.add("side-column-block"); 49 | 50 | // Label 51 | // var label = document.createElement("span"); 52 | // label.textContent = "PMM version: "; 53 | // container.appendChild(label); 54 | 55 | // Add menu 56 | container.appendChild(select); 57 | 58 | var sidebar = document.querySelector("#version-select-wrapper"); // Inject menu into element with this ID 59 | sidebar.appendChild(container); 60 | }; 61 | xhr.send(); 62 | }); 63 | -------------------------------------------------------------------------------- /docs/binary-tarball-names.md: -------------------------------------------------------------------------------- 1 | # Binary tarball file names available based on the Percona Server for MySQL version 2 | 3 | For later of Percona Server for MySQL, the tar files are organized by the `glibc2` version. You can find this version on your operating system with the following command: 4 | 5 | ```{.bash data-prompt="$"} 6 | $ ldd --version 7 | ``` 8 | 9 | ??? example "Expected output" 10 | ```text 11 | ldd (Ubuntu GLIBC 2.35-0ubuntu3.1) 2.35 12 | Copyright (C) 2022 Free Software Foundation, Inc. 13 | This is free software; see the source for copying conditions. There is NO 14 | warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 15 | Written by Roland McGrath and Ulrich Drepper. 16 | ``` 17 | 18 | If the `glibc2` version from your operating system is not listed, then this Percona Server for MySQL version does not support that operating system. 19 | 20 | ## Binary tarball file name organization 21 | 22 | The following lists the platform and the associated full binary file name used by Percona Server for MySQL tar files {{release}}. 23 | 24 | | Platform | Percona Server for MySQL tarball name | glibc2 version | 25 | |----------------------|--------------------------------------------------------------|-----------| 26 | | Ubuntu 22.04 | Percona-Server-{{release}}-Linux.x86_64.glibc2.35.tar.gz | glibc2.35 | 27 | | Ubuntu 20.04 | Percona-Server-{{release}}-Linux.x86_64.glibc2.31.tar.gz | glibc2.31 | 28 | | Red Hat Enterprise 9 | Percona-Server-{{release}}-Linux.x86_64.glibc2.34.tar.gz | glibc2.34 | 29 | | Red Hat Enterprise 8 | Percona-Server-{{release}}-Linux.x86_64.glibc2.28.tar.gz | glibc2.28 | 30 | | Red Hat Enterprise 7 | Percona-Server-{{release}}-Linux.x86_64.glibc2.17.tar.gz | glibc2.17 | 31 | 32 | The types of files are as follows: 33 | 34 | | Type | Name | Description | 35 | |---|---|---| 36 | | Full | Percona-Server-<version-number>-Linux.x86_64.<glibc2-version>.tar.gz | Contains all files available | 37 | | Minimal | Percona-Server-<version-number>-Linux.x86_64.<glibc2-version>.minimal.tar.gz | Contains binaries and libraries | 38 | | Debug | Percona-Server-<version-number>-Linux.x86_64.<glibc2-version>.debug.tar.gz | Contains the minimal build files and test files, and debug symbols | 39 | -------------------------------------------------------------------------------- /archive/upgrade-myrocks.md: -------------------------------------------------------------------------------- 1 | # Upgrade from systems that use the MyRocks storage engine and partitioned tables 2 | 3 | MySQL {{vers}} only provides support for partitioned table for the InnoDB storage engine. 4 | 5 | If you use partitioned tables with the *MyRocks* storage engine, the 6 | upgrade may fail if you do not enable the native partitioning provided by the storage engine. 7 | 8 | 9 | Before you attempt the upgrade, check whether you have any tables that are not using the native partitioning. 10 | 11 | ```{.bash data-prompt="$"} 12 | $ mysqlcheck -u root --all-databases --check-upgrade 13 | ``` 14 | 15 | If tables are found, **mysqlcheck** issues a warning: 16 | 17 | Enable either the rocksdb_enable_native_partition variable or 18 | the tokudb_enable_native_partition variable depending on the storage 19 | engine and restart the server. 20 | 21 | Your next step is to alter the tables that are not using the native partitioning with the 22 | `UPGRADE PARTITIONING` clause: 23 | 24 | ```text 25 | ALTER TABLE UPGRADE PARTITIONING 26 | ``` 27 | 28 | Complete these steps for each table that **mysqlcheck** list. Otherwise, the upgrade to {{vers}} fails and your error log contains messages like the following: 29 | 30 | ```text 31 | 2018-12-17T18:34:14.152660Z 2 [ERROR] [MY-013140] [Server] The 'partitioning' feature is not available; you need to remove '--skip-partition' or use MySQL built with '-DWITH_PARTITION_STORAGE_ENGINE=1' 32 | 2018-12-17T18:34:14.152679Z 2 [ERROR] [MY-013140] [Server] Can't find file: './comp_test/t1_RocksDB_lz4.frm' (errno: 0 - Success) 33 | 2018-12-17T18:34:14.152691Z 2 [ERROR] [MY-013137] [Server] Can't find file: './comp_test/t1_RocksDB_lz4.frm' (OS errno: 0 - Success) 34 | ``` 35 | 36 | ## Perform a distribution upgrade in-place on a system with installed Percona packages 37 | 38 | The following is the recommended process for performing a distribution upgrade on a system with the Percona packages installed: 39 | {.power-number} 40 | 41 | 1. Record the installed Percona packages. 42 | 43 | 2. Back up the data and configurations. 44 | 45 | 3. Uninstall the Percona packages without removing the configuration file or data. 46 | 47 | 4. Perform the upgrade by following the distribution upgrade instructions 48 | 49 | 5. Reboot the system. 50 | 51 | 6. Install the Percona packages intended for the upgraded version of the distribution. 52 | -------------------------------------------------------------------------------- /docs/sql-errors.md: -------------------------------------------------------------------------------- 1 | # Common SQL errors 2 | 3 | Error handling in SQL commands involves managing and responding to errors that may occur during database operations. It ensures that the database remains consistent and provides feedback to users when errors occur. 4 | 5 | ## SELECT statement 6 | 7 | When executing a SELECT statement, errors may occur due to invalid syntax, missing tables, or insufficient permissions. 8 | 9 | ```{.bash data-prompt="mysql>"} 10 | mysql> SELECT * FROM non_existent_table; 11 | ERROR 1146 (42S02): Table 'database_name.non_existent_table' doesn't exist 12 | ``` 13 | 14 | ## INSERT Statement 15 | 16 | Errors can occur during INSERT operations if data violates constraints or exceeds column limits. 17 | 18 | ```{.bash data-prompt="mysql>"} 19 | mysql> INSERT INTO table_name (id, name) VALUES (1, 'John'); 20 | ERROR 1136 (21S01): Column count doesn't match value count at row 1 21 | ``` 22 | 23 | ## UPDATE Statement 24 | 25 | UPDATE statements may encounter errors when attempting to modify non-existent rows or violating constraints. 26 | 27 | ```{.bash data-prompt="mysql>"} 28 | mysql> UPDATE table_name SET non_existent_column = 'value'; 29 | ERROR 1054 (42S22): Unknown column 'non_existent_column' in 'field list' 30 | ``` 31 | 32 | ## DELETE Statement 33 | 34 | Errors in DELETE statements can occur if the WHERE clause condition is invalid or violates constraints. 35 | 36 | ```{.bash data-prompt="mysql>"} 37 | mysql> DELETE FROM table_name WHERE id = 'non_numeric_value'; 38 | ERROR 1054 (42S22): Unknown column 'non_numeric_value' in 'where clause' 39 | ``` 40 | 41 | ## DDL Statements (CREATE, ALTER, DROP) 42 | 43 | DDL statements may fail due to syntax errors, existing object conflicts, or insufficient privileges. 44 | 45 | ```{.bash data-prompt="mysql>"} 46 | mysql> CREATE TABLE existing_table (id INT PRIMARY KEY); 47 | ERROR 1050 (42S01): Table 'existing_table' already exists 48 | ``` 49 | 50 | ## Advanced SQL features 51 | 52 | - [Data Types Basic](data-types-basic.md) 53 | - [Functions](functions.md) 54 | - [SQL Conventions](sql-conventions.md) 55 | - [SQL Syntax](sql-syntax.md) 56 | - [Stored Procedures](stored-procedures.md) 57 | - [Stored Procedure Error Handling](stored-procedure-error-handling.md) 58 | - [Stored Procedure Variables](stored-procedure-variables.md) 59 | - [Triggers](triggers.md) 60 | - [Troubleshooting SQL](troubleshooting-sql.md) -------------------------------------------------------------------------------- /docs/js/promptremover.js: -------------------------------------------------------------------------------- 1 | document.addEventListener("DOMContentLoaded", function(){ 2 | // get collection of code blocks: 3 | const collection = document.getElementsByClassName("highlight"); 4 | for (let i = 0; i < collection.length; i++) { 5 | const commandElement=collection.item(i); 6 | let commandButtonElement = commandElement.getElementsByTagName("button"); 7 | // read the prompt string from an attribute of the code block: 8 | let promptString = commandElement.getAttribute("data-prompt"); 9 | if (!promptString) continue; 10 | let commandCodeElement = commandElement.getElementsByTagName("code"); 11 | let commandCodeElementString = commandCodeElement.item(0).textContent; 12 | let trueCommand = commandCodeElementString; 13 | if (commandCodeElementString.startsWith(promptString)) { 14 | // remove the first occurrence of the prompt: 15 | trueCommand = commandCodeElementString.substring(promptString.length, commandCodeElementString.length).trim(); 16 | } 17 | // remove other occurrencies in case of a multi-line string: 18 | trueCommand = trueCommand.replaceAll("\n"+promptString, "\n").replace(/^[^\S\r\n]+/gm, ""); 19 | 20 | // CHECK IF THERE IS A SECOND PROMPT: 21 | promptString = commandElement.getAttribute("data-prompt-second"); 22 | if (promptString) { 23 | if (trueCommand.startsWith(promptString)) { 24 | trueCommand = trueCommand.substring(promptString.length, trueCommand.length).trim(); 25 | } 26 | trueCommand = trueCommand.replaceAll("\n"+promptString, "\n").replace(/^[^\S\r\n]+/gm, ""); 27 | } 28 | 29 | // CHECK IF THERE IS A THIRD PROMPT: 30 | promptString = commandElement.getAttribute("data-prompt-third"); 31 | if (promptString) { 32 | if (trueCommand.startsWith(promptString)) { 33 | trueCommand = trueCommand.substring(promptString.length, trueCommand.length).trim(); 34 | } 35 | trueCommand = trueCommand.replaceAll("\n"+promptString, "\n").replace(/^[^\S\r\n]+/gm, ""); 36 | } 37 | // attach the updated command as an attribute to the button where clipboard.js will find it: 38 | commandButtonElement.item(0).setAttribute("data-clipboard-text", trueCommand); 39 | } 40 | }); 41 | 42 | 43 | 44 | 45 | -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | # Percona Server for MySQL {{vers}} - Documentation 2 | 3 | !!! note "" 4 | 5 | This documentation is for the latest release: Percona Server for MySQL {{release}} ([Release Notes](release-notes/{{release}}.md)). 6 | 7 | Percona Server for MySQL is a freely available, fully compatible, enhanced, and open source drop-in replacement for any MySQL database. It provides superior and optimized performance, greater scalability and availability, enhanced backups, and increased visibility and instrumentation. 8 | 9 | Thousands of enterprises trust Percona Server for MySQL to provide better performance and concurrency for their most demanding workloads. 10 | 11 | ## For Monitoring and Management 12 | 13 | Percona Monitoring and Management (PMM )monitors and provides actionable performance data for MySQL variants, including Percona Server for MySQL, Percona XtraDB Cluster, Oracle MySQL Community Edition, Oracle MySQL Enterprise Edition, and MariaDB. PMM captures metrics and data for the InnoDB, XtraDB, and MyRocks storage engines, and has specialized dashboards for specific engine details. 14 | 15 | [Get started with PMM](https://docs.percona.com/percona-monitoring-and-management/3/quickstart/quickstart.html). 16 | 17 | --8<--- "get-help-snip.md" 18 | 19 |
20 | 21 | ## :material-progress-download: Quickstart guide { .title } 22 | 23 | Get started quickly with our Quickstart guide. 24 | 25 | [Quickstart guide](quickstart-overview.md){ .md-button } 26 | 27 |
28 | 29 | ### :material-progress-download: Installation guides { .title } 30 | 31 | Find the best installation solution with our step-by-step installation instructions. 32 | 33 | [Installation instructions](installation.md){ .md-button } 34 | 35 |
36 | 37 | ### :material-backup-restore: Percona Server for MySQL Pro { .title } 38 | 39 | Enjoy the benefits of Percona Server for MySQL Pro build. 40 | 41 | [Percona Server for MySQL Pro](psmysql-pro.md){ .md-button } 42 | 43 |
44 | 45 | ## :fontawesome-solid-gears: Audit Log Filter plugin { .title } 46 | 47 | Learn about the Audit Log Filter plugin that allows you to monitor, log, and block a connection or query actively executed on the selected server. 48 | 49 | [Audit Log Filter](audit-log-filter-overview.md){ .md-button} 50 | 51 |
52 |
53 | -------------------------------------------------------------------------------- /docs/troubleshoot-apparmor.md: -------------------------------------------------------------------------------- 1 | # Troubleshoot AppArmor profiles 2 | 3 | Troubleshooting AppArmor profiles ensure that applications can access necessary resources without compromising system security. 4 | 5 | --8<--- "get-help-snip.md" 6 | 7 | ## Profile Modes 8 | 9 | AppArmor profiles operate in different modes: 10 | 11 | | Mode | Description | 12 | |----------|----------------------------------------------------------------------------------------------| 13 | | Enforce | Applications are restricted by profile rules, and any violation results in denial of access. | 14 | | Complain | Applications are allowed to take restricted actions, but these actions are logged. | 15 | | Disabled | Profile restrictions are turned off, allowing applications to take any action without logging. | 16 | 17 | ### Check status 18 | 19 | Use commands like `aa-status` to check the current status of AppArmor profiles. This check helps identify if profiles are enforcing or complaining about actions. 20 | 21 | ### Switch modes 22 | 23 | You may need to switch profiles between `enforce` and `complain` modes when troubleshooting. Use `aa-enforce` to switch to enforce mode and `aa-complain` to switch to complain mode. 24 | 25 | ### Disable profiles 26 | 27 | If necessary, profiles can be temporarily disabled. However, this is not recommended for security reasons. Use commands like `ln -s` or `aa-disable` to disable profiles. 28 | 29 | ### Reload profiles 30 | 31 | After making changes to profiles or switching modes, reloading profiles for changes to take effect is essential. Use commands like `service apparmor reload` or `apparmor_parser -r` to reload profiles. 32 | 33 | ### Check Log Entries 34 | 35 | Monitor log entries for DENIED or ALLOWED actions. DENIED entries indicate that a profile is blocking an action, while ALLOWED entries suggest that an action is permitted. 36 | 37 | ### Edit Profiles 38 | 39 | You may need to edit AppArmor profiles to troubleshoot access issues and allow specific actions. Edit the profile files in the `/etc/apparmor.d/` directory to adjust access permissions. 40 | 41 | ## AppArmor links 42 | 43 | [AppArmor](apparmor.md)
44 | [AppArmor Profiles](apparmor-profiles.md)
45 | [Manage AppArmor Profiles](manage-apparmor-profiles.md)
46 | [Disable AppArmor](disable-apparmor.md)
47 | [Configure AppArmor](configure-apparmor.md) 48 | -------------------------------------------------------------------------------- /docs/delete.md: -------------------------------------------------------------------------------- 1 | # DELETE statement 2 | 3 | The DELETE statement removes one or more rows from a table based on specified conditions. It allows developers to selectively delete data from a table, providing a way to manage and maintain the database by removing unnecessary or outdated records. 4 | 5 | ## Advantages and Disadvantages of Using DELETE Statement 6 | 7 | | Trade-offs | Description | 8 | |--------------|------------------------------------------------------------------------------------------------------------------------------------| 9 | | Advantages | Allows selective removal of specific rows from a table, helping to maintain data integrity and manage database resources efficiently. | 10 | | | Can be combined with WHERE clause to delete rows that meet certain conditions, providing flexibility in data manipulation. | 11 | | | Provides a straightforward way to remove unwanted data without affecting the structure of the table or other related tables. | 12 | | Disadvantages| Deleting large amounts of data can impact performance and may require careful consideration to avoid unintended consequences. | 13 | | | Deletes are permanent and irreversible, so it's crucial to double-check conditions and backup data before executing DELETE queries. | 14 | 15 | ## Syntax of DELETE Statement 16 | 17 | The statement has the following options: 18 | 19 | | Option | Description | 20 | |---|---| 21 | | `DELETE FROM table_name` | This clause specifies the table from which you want to delete rows. | 22 | | `WHERE condition` (Optional) | This clause filters the rows to be deleted based on a specific condition. If omitted, all rows in the table will be deleted. | 23 | 24 | The syntax of the DELETE statement is as follows: 25 | 26 | ```text 27 | DELETE FROM table_name 28 | [WHERE condition]; 29 | ``` 30 | 31 | ## Example of DELETE Statement 32 | 33 | This example deletes all rows from the `orders` table where the `order_date` is before January 1, 2023. 34 | 35 | ```{.bash data-prompt="mysql>"} 36 | DELETE FROM orders 37 | WHERE order_date < '2023-01-01'; 38 | ``` 39 | 40 | Fundamental SQL links: 41 | 42 | * [Common SQL](common-sql.md) 43 | * [SQL Basics](sql-basics.md) 44 | * [SELECT](select.md) 45 | * [INSERT](insert.md) 46 | * [UPDATE](update.md) 47 | * [SQL Operators](sql-operators.md) -------------------------------------------------------------------------------- /docs/docker-config.md: -------------------------------------------------------------------------------- 1 | # Docker environment variables 2 | 3 | When running a Docker container with Percona Server, 4 | you can adjust the configuration of the instance 5 | Add one or more environment variables to the `docker run` command. 6 | 7 | These variables will not affect you if you start the container with a data directory that already contains a database. Any pre-existing database remains untouched on the container startup. 8 | 9 | The variables are optional, but you must specify at least one of the following: 10 | 11 | * `MYSQL_DATABASE` - the database schema name that is created when the container starts 12 | 13 | * `MYSQL_USER` - create a user account when the container starts 14 | 15 | * `MYSQL_PASSWORD` - used with `MYSQL_USER` to create a password for that user account. 16 | 17 | * `MYSQL_ALLOW_EMPTY_PASSWORD` - creates a root user with an empty password. This option is insecure and only should be used for testing or proof of concept when the database can be removed afterward. Anyone can connect as `root`. 18 | 19 | * `MYSQL_ROOT_PASSWORD` - this password is used for the `root` user account. This option is not recommended for production. 20 | 21 | * `MYSQL_RANDOM_ROOT_PASSWORD` - set this variable instead of `MYSQL_ROOT_PASSWORD` when you want Percona Server to generate a password for you. The generated password is available in the container's logs only during the first start of the container. Use `docker logs`. You cannot retrieve the password after the first start. 22 | 23 | To further secure your instance, use the `MYSQL_ONETIME_PASSWORD` variable. 24 | 25 | These variables are visible to anyone able to run `Docker inspect`. 26 | 27 | ```{.bash data-prompt="$"} 28 | $ docker inspect ps 29 | ``` 30 | 31 | ??? example "Expected output" 32 | 33 | ```{.text .no-copy} 34 | ... 35 | "Env": [ 36 | "MYSQL_ROOT_PASSWORD=root", 37 | "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin", 38 | "PS_VERSION={{release}}", 39 | "OS_VER=el8", 40 | "FULL_PERCONA_VERSION={{release}}.el8" 41 | ] 42 | ... 43 | ``` 44 | 45 | You should use `Docker secrets` or volumes instead. 46 | 47 | Percona Server for MySQL also allows adding the `_FILE` suffix to a variable name. This suffix lets you add the value in a path so that the value cannot be inspected from outside the container. 48 | 49 | 50 | 51 | 52 | -------------------------------------------------------------------------------- /docs/slowlog-rotation.md: -------------------------------------------------------------------------------- 1 | # Slow query log rotation and expiration 2 | 3 | Percona has implemented two new variables, `max_slowlog_size` and `max_slowlog_files` to provide users with ability to control the slow query log disk usage. These variables have the same behavior as the [max_binlog_size variable] and the [max_binlog_files variable] used for controlling the binary log. 4 | 5 | 6 | ## `max_slowlog_size` 7 | 8 | | Option | Description | 9 | |--------------|----------------| 10 | | Command-line | Yes | 11 | | Config file | Yes | 12 | | Scope | Global | 13 | | Dynamic | Yes | 14 | | Data type | numeric | 15 | | Default | 0 (unlimited) | 16 | | Range | 0 - 1073741824 | 17 | 18 | The `max_slowlog_size` variable controls when the server rotates the slow query log file based on size. 19 | 20 | By default, the value is set to `0`, which means the server does not automatically rotate the slow query log file. 21 | 22 | The block size is `4096` bytes. If you set a value that is not a multiple of `4096`, the server rounds it down to the nearest multiple of `4096`. For example, setting `max_slowlog_size` to any value less than `4096` will effectively set the value to `0`. 23 | 24 | If you set a limit for this size and enable this feature, the server will rename the slow query log file to `slow_query_log_file.000001` once it reaches the specified size. 25 | 26 | ## `max_slowlog_files` 27 | 28 | | Option | Description | 29 | |--------------|---------------| 30 | | Command-line | Yes | 31 | | Config file | Yes | 32 | | Scope | Global | 33 | | Dynamic | Yes | 34 | | Data type | numeric | 35 | | Default | 0 (unlimited) | 36 | | Range | 0 - 102400 | 37 | 38 | This variable limits the total amount of slow query log files and is used with max_slowlog_size. 39 | 40 | The server creates and adds slow query logs until reaching the range’s upper value. When the upper value is reached, the server creates a new slow query log file with a higher sequence number and deletes the log file with the lowest sequence number maintaining the total amount defined in the range. 41 | 42 | [max_binlog_size variable]: https://dev.mysql.com/doc/refman/{{vers}}/en/replication-options-binary-log.html#sysvar_max_binlog_size 43 | 44 | [max_binlog_files variable]: https://dev.mysql.com/doc/refman/{{vers}}/en/replication-options-binary-log -------------------------------------------------------------------------------- /scripts/generate_index.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | 3 | """ 4 | generate_index.py - Generate an index of Markdown files in the top-level docs/ directory. 5 | 6 | How to run: 7 | 8 | cd scripts 9 | python3 generate_index.py 10 | 11 | Run from the root directory of your project. 12 | """ 13 | 14 | import os 15 | 16 | def strip_prefixes(s): 17 | prefixes = ('The ', 'Work with ') 18 | s_lower = s.lower() 19 | for prefix in prefixes: 20 | if s_lower.startswith(prefix.lower()): 21 | return s[len(prefix):] 22 | return s 23 | 24 | # Define path to docs/ and the output file 25 | script_dir = os.path.dirname(os.path.abspath(__file__)) 26 | docs_dir = os.path.abspath(os.path.join(script_dir, '..', 'docs')) 27 | index_file_path = os.path.join(docs_dir, 'index-contents.md') 28 | 29 | # Files to exclude 30 | exclude_files = {'404.md', 'index-contents.md'} 31 | 32 | # Delete old index file 33 | if os.path.exists(index_file_path): 34 | os.remove(index_file_path) 35 | print(f"Deleted existing index file: {index_file_path}") 36 | 37 | index_content = '# Index\n\n' 38 | 39 | # Only list .md files in the top-level docs directory 40 | file_entries = [] 41 | 42 | for file in os.listdir(docs_dir): 43 | if file.endswith('.md') and file not in exclude_files: 44 | filepath = os.path.join(docs_dir, file) 45 | relative_path = os.path.relpath(filepath, docs_dir).replace(os.sep, '/') 46 | 47 | display_name = '' 48 | try: 49 | with open(filepath, 'r', encoding='utf-8') as md_file: 50 | for line in md_file: 51 | if line.strip().startswith('# '): 52 | display_name = line.strip()[2:].strip() 53 | break 54 | except Exception as e: 55 | print(f"Error reading file {filepath}: {e}") 56 | continue 57 | 58 | if not display_name: 59 | display_name = os.path.splitext(file)[0] 60 | 61 | sort_key = strip_prefixes(display_name).strip().lower() 62 | file_entries.append((sort_key, display_name, relative_path)) 63 | 64 | file_entries.sort() 65 | 66 | for _, display_name, relative_path in file_entries: 67 | index_content += f'- [{display_name}]({relative_path})\n' 68 | 69 | # Write the new index 70 | with open(index_file_path, 'w', encoding='utf-8') as index_file: 71 | index_file.write(index_content) 72 | 73 | print(f"Index generated at {index_file_path}") -------------------------------------------------------------------------------- /docs/telemetry.md: -------------------------------------------------------------------------------- 1 | # Telemetry on Percona Server for MySQL 2 | 3 | Percona telemetry fills in the gaps in our understanding of how you use Percona Server for MySQL to improve our products. Participation in the anonymous program is optional. You can opt-out if you prefer to not share this information. 4 | 5 | ## What information is collected 6 | 7 | At this time, telemetry is added only to the Percona packages and Docker images. Percona Server for MySQL collects only information about the installation environment. Future releases may add additional metrics. 8 | 9 | Be assured that access to this raw data is rigorously controlled. Percona does not collect personal data. All data is anonymous and cannot be traced to a specific user. To learn more about our privacy practices, read our [Percona Privacy statement]. 10 | 11 | An example of the data collected is the following: 12 | 13 | ```JSON 14 | [{"id" : "c416c3ee-48cd-471c-9733-37c2886f8231", 15 | "product_family" : "PRODUCT_FAMILY_PS", 16 | "instanceId" : "6aef422e-56a7-4530-af9d-94cc02198343", 17 | "createTime" : "2023-10-16T10:46:23Z", 18 | "metrics": 19 | [{"key" : "deployment","value" : "PACKAGE"}, 20 | {"key" : "pillar_version","value" : "8.1.0-1"}, 21 | {"key" : "OS","value" : "Oracle Linux Server 8.8"}, 22 | {"key" : "hardware_arch","value" : "x86_64 x86_64"}]}] 23 | ``` 24 | 25 | ## Disable telemetry 26 | 27 | Telemetry is enabled by default. If you decide not to send usage data to Percona, you can set the `PERCONA_TELEMETRY_DISABLE=1` environment variable for either the root user or in the operating system prior to the installation process. 28 | 29 | === "Debian-derived distribution" 30 | 31 | Add the environment variable before the install process. 32 | 33 | ```{.bash data-prompt="$"} 34 | $ sudo PERCONA_TELEMETRY_DISABLE=1 apt install percona-server-server 35 | ``` 36 | 37 | === "Red Hat-derived distribution" 38 | 39 | Add the environment variable before the install process. 40 | 41 | ```{.bash data-prompt="$"} 42 | $ sudo PERCONA_TELEMETRY_DISABLE=1 yum install percona-server-server 43 | ``` 44 | 45 | === "DOCKER" 46 | 47 | Add the environment variable when running a command in a new container. 48 | 49 | ```{.bash data-prompt="$"} 50 | $ docker run -d -e MYSQL_ROOT_PASSWORD=test1234# -e PERCONA_TELEMETRY_DISABLE=1 -e --name=percona-server percona/percona-server:8.1 51 | ``` 52 | 53 | [Percona Privacy statement]: https://www.percona.com/privacy-policy#h.e34c40q8sb1a -------------------------------------------------------------------------------- /docs/troubleshooting-sql.md: -------------------------------------------------------------------------------- 1 | # Troubleshoot SQL code 2 | 3 | --8<--- "get-help-snip.md" 4 | 5 | ## Troubleshooting SQL Code 6 | 7 | To troubleshoot SQL code, follow these steps: 8 | 9 | | Action | Description | 10 | |--------------|--------------------------------------------------------------------------------------------------------------------------------| 11 | | Review Error Messages | Carefully read any error messages returned by the MySQL server. They often provide valuable clues about what went wrong. | 12 | | Check Syntax | Verify that the SQL syntax is correct. A single typo or missing keyword can cause errors. | 13 | | Verify Table and Column Names | Ensure that table and column names are spelled correctly and match the actual names in the database. | 14 | | Test in Isolation | Test each part of the SQL statement separately to identify which part is causing the issue. | 15 | | Use Logging Tools | Enable query logging or use debugging tools to track the execution of SQL queries and identify any issues. | 16 | | Review Documentation | Consult the MySQL documentation to understand the correct usage of SQL statements and functions. | 17 | | Seek Help | Don't hesitate to ask for help from more experienced developers or consult online forums and communities for assistance. | 18 | 19 | Troubleshooting SQL Code example: 20 | 21 | Suppose you have the following SQL query that is not returning the expected results: 22 | 23 | ```text 24 | SELECT * FORM users WHERE age = 30; 25 | ``` 26 | 27 | After reviewing the error message returned by MySQL, you notice a typo in the query. The keyword "FORM" should be "FROM". After correcting the typo, the query becomes: 28 | 29 | ```text 30 | SELECT * FROM users WHERE age = 30; 31 | ``` 32 | 33 | Now, the query should execute successfully and return the desired results. 34 | 35 | ## Advanced SQL features 36 | 37 | * [Data Types Basic](data-types-basic.md) 38 | * [Functions](functions.md) 39 | * [SQL Conventions](sql-conventions.md) 40 | * [SQL Errors](sql-errors.md) 41 | * [SQL Syntax](sql-syntax.md) 42 | * [Stored Procedures](stored-procedures.md) 43 | * [Stored Procedure Error Handling](stored-procedure-error-handling.md) 44 | * [Stored Procedure Variables](stored-procedure-variables.md) 45 | * [Triggers](triggers.md) -------------------------------------------------------------------------------- /docs/audit-log-filter-overview.md: -------------------------------------------------------------------------------- 1 | # Audit Log Filter overview 2 | 3 | The Audit Log Filter component allows you to monitor, log, and block a connection or query actively executed on the selected server. 4 | 5 | Enabling the component produces a log file that contains a record of server activity. The log file has information on connections and databases accessed by that connection. 6 | 7 | The component uses the `mysql` system database to store filter and user account data. Set the [`audit_log_filter.database`](audit-log-filter-variables.md#audit_log_filterdatabase) variable at server startup to select a different database. 8 | 9 | The `AUDIT_ADMIN` privilege is required to enable users to manage the Audit Log Filter component. 10 | 11 | ## Privileges 12 | 13 | Define the privilege at runtime at the startup of the server. The associated Audit Log Filter privilege can be unavailable if the component is not enabled. 14 | 15 | ### `AUDIT_ADMIN` 16 | 17 | This privilege is defined by the server and enables the user to configure the component. 18 | 19 | ### `AUDIT_ABORT_EXEMPT` 20 | 21 | This privilege allows queries from a user account to always be executed. An `abort` item does not block them. This ability lets the user account regain access to a system if an audit is misconfigured. The query is logged due to the privilege. User accounts with the `SYSTEM_USER` privilege have the `AUDIT_ABORT_EXEMPT` privilege. 22 | 23 | ## Audit Log Filter tables 24 | 25 | The Audit Log Filter component uses `mysql` system database tables in the `InnoDB` storage engine. These tables store user account data and filter data. When you start the server, change the component's database with the `audit_log_filter.database` variable. 26 | 27 | The `audit_log_filter` table stores the definitions of the filters and has the following column definitions: 28 | 29 | | Column name | Description | 30 | |-------------|---------------------------------------------------------------| 31 | | NAME | Name of the filter | 32 | | FILTER | Definition of the filter linked to the name as a JSON value | 33 | 34 | The `audit_log_user` table stores account data and has the following column definitions: 35 | 36 | | Column name | Description | 37 | |--------------|-------------------------------------| 38 | | USER | The account name of the user | 39 | | HOST | The account name of the host | 40 | | FILTERNAME | The account filter name | 41 | -------------------------------------------------------------------------------- /docs/data-at-rest-encryption.md: -------------------------------------------------------------------------------- 1 | # Data at Rest Encryption 2 | 3 | Data security is a concern for institutions and organizations. `Transparent 4 | Data Encryption (TDE)` or `Data at Rest Encryption` encrypts 5 | data files. Data at rest is 6 | any data that is not accessed or changed frequently, stored on different 7 | types of storage devices. Encryption ensures that if an unauthorized user 8 | accesses the data files from the file system, the user cannot read the contents. 9 | 10 | If the user uses master key encryption, the MySQL keyring plugin stores the 11 | InnoDB master key, used for the master key encryption implemented by *MySQL*. 12 | The master key is also used to encrypt redo logs, and undo logs, along with the 13 | tablespaces. 14 | 15 | The InnoDB tablespace encryption has the following components: 16 | 17 | * The database instance has a master key for tablespaces and a master key 18 | for binary log encryption. 19 | 20 | * Each tablespace has a tablespace key. The key is used to encrypt the 21 | Tablespace data pages. Encrypted tablespace keys are written on 22 | the tablespace header. In the master key implementation, the tablespace key 23 | cannot be changed unless you rebuild the table. 24 | 25 | Two separate keys allow the master key to be rotated in a minimal operation. 26 | When the master key is rotated, each tablespace key is decrypted and 27 | re-encrypted with the new master key. The key rotation only reads and writes to the first page of each tablespace file (.ibd). 28 | 29 | An InnoDB tablespace file is comprised of multiple logical and physical pages. 30 | Page 0 is the tablespace header page and keeps the metadata for the tablespace. 31 | The encryption information is stored on page 0 and the tablespace key is 32 | encrypted. 33 | 34 | An encrypted page is decrypted at the I/O 35 | layer, added to the buffer pool, and used to access the data. A buffer pool page is not encrypted. The page is encrypted by the I/O layer before the page is flushed to disk. 36 | 37 | --8<--- "get-help-snip.md" 38 | 39 | ## Percona XtraBackup support 40 | 41 | Percona XtraBackup version {{vers}} supports the backup of encrypted general tablespaces. 42 | 43 | Percona XtraBackup only supports features that are [Generally Available (GA)](glossary.md#general-availability-ga) in Percona Server for MySQL. Due to time constraints, a GA feature may be supported in a later Percona XtraBackup release. Review the [Percona XtraBackup release notes] for more information. 44 | 45 | [Percona XtraBackup release notes]: https://docs.percona.com/percona-xtrabackup/{{vers}}/release-notes/release-notes.html 46 | -------------------------------------------------------------------------------- /docs/create-table.md: -------------------------------------------------------------------------------- 1 | # Create a table 2 | 3 | Creating a table is essential to organizing and storing your data effectively when working with a database. Here's a step-by-step guide on how to create a table in such a database: 4 | 5 | ## Permissions Required 6 | 7 | To create a table in a database, you need appropriate permissions. Typically, you'll need the `CREATE TABLE` privilege, which allows you to create new tables within a database. This privilege is usually granted to database users by database administrators or through predefined user roles. If you do not have the necessary permissions, you'll need to contact your database administrator to grant them. 8 | 9 | ## Define the table structure 10 | 11 | Now, define the structure of your table by specifying its columns along with their data types and any additional properties. Each column represents a different attribute of your data. 12 | 13 | Here's the syntax for creating a table: 14 | 15 | ```text 16 | CREATE TABLE table_name ( 17 | column1_name data_type constraints, 18 | column2_name data_type constraints, 19 | ... 20 | ); 21 | ``` 22 | 23 | Replace `table_name` with the desired name for your table. For each column, provide a name, data type, and constraints such as `NOT NULL`, `PRIMARY KEY`, `AUTO_INCREMENT`. 24 | 25 | ## Create the table 26 | 27 | Execute the `CREATE TABLE` command to create the table in the database. For example, to create a table named `employees` with columns for `id`, `name`, and `salary`, you would run the following SQL command: 28 | 29 | ```{.bash data-prompt="mysql>"} 30 | CREATE TABLE employees ( 31 | id INT PRIMARY KEY AUTO_INCREMENT, 32 | name VARCHAR(50) NOT NULL, 33 | salary DECIMAL(10, 2) 34 | ); 35 | ``` 36 | 37 | This command creates a table named `employees` with three columns: `id`, `name`, and `salary`. The `id` column is an integer type and serves as the primary key with auto-increment functionality. The `name` column is a variable-length string, and the `salary` column is a decimal number with a precision of 10 digits and a scale of 2. 38 | 39 | ## Verify Table Creation 40 | 41 | After executing the `CREATE TABLE` command, verify that the table has been successfully created. You can use various SQL commands such as `SHOW TABLES` or `DESCRIBE table_name` to check the existence and structure of the newly created table. 42 | 43 | ```{.bash data-prompt="mysql>"} 44 | mysql> SHOW TABLES; 45 | mysql> DESCRIBE employees; 46 | ``` 47 | 48 | ## Database management 49 | 50 | * [Database](database.md) 51 | * [Tables](table.md) 52 | * [Isolation Levels](isolation-levels.md) 53 | * [Transaction Management](transaction-mgmt.md) 54 | * [Views](views.md) -------------------------------------------------------------------------------- /docs/apparmor-profiles.md: -------------------------------------------------------------------------------- 1 | # AppArmor profile modes 2 | 3 | AppArmor profile modes determine how applications interact with system resources. You can mix enforce mode profiles and complain mode profiles in your server. 4 | 5 | | Mode | Description | 6 | |------------|--------------------------------------------------------------------------------------------------------------------------| 7 | | Enforce | Restricts MySQL processes according to the rules defined in the profile. Any action violating these rules is denied. | 8 | | Complain | Allows MySQL processes to take restricted actions, but logs these actions for review. | 9 | | Disabled | Turns off profile restrictions entirely, allowing MySQL processes to take any action without logging. | 10 | 11 | Understanding these modes helps MySQL developers ensure that their applications can access necessary resources while maintaining system security. 12 | 13 | ## Benefits 14 | 15 | | Benefit | Description | 16 | |-------------------|---------------------------------------------------------------------------------------------------------------------| 17 | | Enhanced Security | AppArmor profile modes, such as Enforce and Complain, help enforce security policies to prevent unauthorized access. | 18 | | Easy Troubleshooting | Profile modes provide flexibility in troubleshooting access issues by allowing developers to switch between modes. | 19 | 20 | ### Disadvantages 21 | 22 | | Disadvantage | Description | 23 | |--------------------|----------------------------------------------------------------------------------------------------------------------| 24 | | Limited Flexibility | Profile modes may restrict certain actions or access, potentially limiting the functionality of MySQL applications. | 25 | | Complexity | Understanding and managing different profile modes can be complex for beginner developers, leading to errors. | 26 | | Debugging Challenges | Troubleshooting issues related to profile modes, such as DENIED entries in logs, may require additional expertise. | 27 | 28 | ## AppArmor links: 29 | 30 | [AppArmor](apparmor.md)
31 | [Manage AppArmor Profiles](manage-apparmor-profiles.md)
32 | [Disable AppArmor](disable-apparmor.md)
33 | [Configure AppArmor](configure-apparmor.md)
34 | [Troubleshoot AppArmor](troubleshoot-apparmor.md) 35 | 36 | -------------------------------------------------------------------------------- /docs/innodb-fragmentation-count.md: -------------------------------------------------------------------------------- 1 | # InnoDB page fragmentation counters 2 | 3 | *InnoDB* page fragmentation is caused by random insertion or deletion from a 4 | secondary index. This means that the physical ordering of the index pages on 5 | the disk is not same as the index ordering of the records on the pages. As a 6 | consequence this means that some pages take a lot more space and that queries 7 | which require a full table scan can take a long time to finish. 8 | 9 | To provide more information about the *InnoDB* page fragmentation 10 | *Percona Server for MySQL* now provides the following counters as status variables: 11 | Innodb_scan_pages_contiguous, 12 | Innodb_scan_pages_disjointed, Innodb_scan_data_size, 13 | Innodb_scan_deleted_recs_size, and 14 | Innodb_scan_pages_total_seek_distance. 15 | 16 | ## Status variables 17 | 18 | ### `Innodb_scan_pages_contiguous` 19 | 20 | | Option | Description | 21 | |-----------|-------------| 22 | | Scope | Session | 23 | | Data type | Numeric | 24 | 25 | This variable shows the number of contiguous page reads inside a query. 26 | 27 | ### `Innodb_scan_pages_disjointed` 28 | 29 | | Option | Description | 30 | |-----------|-------------| 31 | | Scope | Session | 32 | | Data type | Numeric | 33 | 34 | This variable shows the number of disjointed page reads inside a query. 35 | 36 | ### `Innodb_scan_data_size` 37 | 38 | 39 | | Option | Description | 40 | |-----------|-------------| 41 | | Scope | Session | 42 | | Data type | Numeric | 43 | 44 | This variable shows the size of data in all *InnoDB* pages read inside a 45 | query (in bytes) - calculated as the sum of `page_get_data_size(page)` for 46 | every page scanned. 47 | 48 | ### `Innodb_scan_deleted_recs_size` 49 | 50 | 51 | | Option | Description | 52 | |-----------|-------------| 53 | | Scope | Session | 54 | | Data type | Numeric | 55 | 56 | This variable shows the size of deleted records (marked as `deleted` in 57 | `page_delete_rec_list_end()`) in all *InnoDB* pages read inside a query 58 | (in bytes) - calculated as the sum of `page_header_get_field(page, 59 | PAGE_GARBAGE)` for every page scanned. 60 | 61 | ### `Innodb_scan_pages_total_seek_distance` 62 | 63 | | Option | Description | 64 | |-----------|-------------| 65 | | Scope | Session | 66 | | Data type | Numeric | 67 | 68 | This variable shows the total seek distance when moving between pages. 69 | 70 | ## Related reading 71 | 72 | * [InnoDB: look after fragmentation](https://www.percona.com/blog/2009/11/05/innodb-look-after-fragmentation/) 73 | 74 | * [Defragmenting a Table] 75 | 76 | [Defragmenting a Table]: https://dev.mysql.com/doc/refman/{{vers}}/en/innodb-file-defragmenting.html 77 | -------------------------------------------------------------------------------- /docs/mysql-upgrade-paths.md: -------------------------------------------------------------------------------- 1 | # MySQL upgrade paths and supported methods 2 | 3 | MySQL supports different upgrade paths depending on the source and target versions. Choose the appropriate method based on your current version and target. 4 | 5 | ## Upgrade path matrix 6 | 7 | | Upgrade Path | Path Examples | Supported Upgrade Methods | 8 | | --- | --- | --- | 9 | | Within an LTS or Bugfix series | 8.0.37 to 8.0.41 or 8.4.0 to 8.4.4 | In-place upgrade, logical dump and load, replication, and MySQL Clone | 10 | | From an LTS or Bugfix series to the next LTS series | 8.0.37 to 8.4.x LTS | In-place upgrade, logical dump and load, and replication | 11 | | From an LTS or Bugfix release to an Innovation release before the next LTS series | 8.0.34 to 8.3.0 or 8.4.0 to 9.0.0 | In-place upgrade, logical dump and load, and replication | 12 | | From the Innovation series to the next LTS series | 8.3.0 to 8.4 LTS | In-place upgrade, logical dump and load, and replication | 13 | | From an Innovation series to an Innovation release after the next LTS series | Not allowed, two steps are required: 8.3.0 to 8.4 LTS, and 8.4 LTS to 9.x Innovation | In-place upgrade, logical dump and load, and replication | 14 | 15 | ## Key considerations 16 | 17 | * **LTS to LTS**: Direct upgrade from 8.0 LTS to 8.4 LTS is supported with multiple methods. 18 | * **Innovation to Innovation**: Cannot skip LTS releases; must upgrade through the LTS series first. 19 | * **MySQL Clone**: Only available for upgrades within the same major version series. 20 | * **Replication**: Available for most upgrade paths but requires careful planning for cross-version replication. 21 | 22 | ## Choosing your upgrade method 23 | 24 | * **In-place upgrade**: Fastest but highest risk; requires downtime. 25 | * **Logical dump and load**: Cleanest but slowest for large datasets; requires downtime. 26 | * **Replication**: Minimal downtime but requires additional infrastructure; good for high-availability setups. 27 | * **MySQL Clone**: Fastest for same-series upgrades; requires compatible versions. 28 | 29 | ## Further reading 30 | 31 | * [Upgrade overview](./upgrade.md) 32 | * [Upgrade checklist for {{vers}}](./upgrade-checklist-8.4.md) 33 | * [Upgrade procedures for {{vers}}](./upgrade-procedures.md) 34 | * [Upgrade strategies](./upgrade-strategies.md) 35 | * [Upgrade from plugins to components](./upgrade-components.md) 36 | * [Downgrade options](./downgrade.md) 37 | * [Breaking and incompatible changes in {{vers}}](./8.4-breaking-changes.md) 38 | * [Compatibility and removed items in {{vers}}](./8.4-compatibility-and-removed-items.md) 39 | * [Defaults and tuning guidance for {{vers}}](./8.4-defaults-and-tuning.md) 40 | * [Percona Toolkit updates for {{vers}}](./percona-toolkit-8.4-updates.md) 41 | -------------------------------------------------------------------------------- /docs/yum-files.md: -------------------------------------------------------------------------------- 1 | # Yum repository package list - Percona Server for MySQL {{vers}} 2 | 3 | 4 | | Package Name | Description | 5 | |---------------|-------------| 6 | | percona-icu-data-files | Provides ICU (International Components for Unicode) data files required by Percona Server for locale, collation, and Unicode character set support. | 7 | | percona-mysql-router | A lightweight routing middleware that directs client connections to backend MySQL or Percona Server instances, often used in high availability setups. | 8 | | percona-mysql-router-debuginfo | Debug symbols for `percona-mysql-router`, used for troubleshooting or analyzing router crashes and performance issues. | 9 | | percona-server-client | Command-line client utilities for connecting to and managing MySQL/Percona Server instances, including tools like `mysql` and `mysqldump`. | 10 | | percona-server-client-debuginfo | Debug symbols for the client utilities, useful for diagnosing crashes or debugging client-related issues. | 11 | | percona-server-debuginfo | Debug symbols for the main Percona Server binaries, required when debugging or profiling the server process. | 12 | | percona-server-debugsource | Source code corresponding to the debug build of Percona Server, used for in-depth debugging and code-level analysis. | 13 | | percona-server-devel | Development files and headers for building applications that link against Percona Server client libraries. | 14 | | percona-server-rocksdb | The RocksDB storage engine plugin, providing high-performance key-value storage optimized for write-heavy workloads. | 15 | | percona-server-rocksdb-debuginfo | Debug symbols for the RocksDB plugin, useful for diagnosing issues or profiling RocksDB engine performance. | 16 | | percona-server-server | The main Percona Server daemon (`mysqld`) and associated server-side components for database management and operations. | 17 | | percona-server-server-debuginfo | Debug symbols for the Percona Server daemon, enabling developers to trace or debug server-level issues. | 18 | | percona-server-shared | Shared libraries used by both the Percona Server and client utilities, providing common functionality and APIs. | 19 | | percona-server-shared-debuginfo | Debug symbols for the shared libraries, useful for debugging applications that depend on these libraries. | 20 | | percona-server-test | A collection of tests used to verify the correctness and stability of Percona Server, typically used in QA or CI environments. | 21 | | percona-server-test-debuginfo | Debug symbols for the test suite, aiding developers in diagnosing issues encountered during test runs. | 22 | | percona-telemetry-agent | A lightweight agent that collects anonymous usage and performance data to help Percona improve its products. Optional and can be disabled. | 23 | -------------------------------------------------------------------------------- /docs/innodb-corrupt-table-action.md: -------------------------------------------------------------------------------- 1 | # Handle corrupted tables 2 | 3 | When a server subsystem tries to access a corrupted table, 4 | the server may crash. If this outcome is not desirable when a corrupted 5 | table is encountered, set the new system innodb_corrupt_table_action 6 | variable to a value which allows the ongoing operation to continue 7 | without crashing the server. 8 | 9 | The server error log registers attempts to access corrupted table pages. 10 | 11 | ### Interacting with the innodb_force_recovery variable 12 | 13 | The innodb_corrupt_table_action variable may work in conjunction with 14 | the innodb_force_recovery variable which considerably reduces the effect 15 | of *InnoDB* subsystems running in the background. 16 | 17 | If the innodb_force_recovery option is <4, corrupted pages are lost and 18 | the server may continue to run due to the innodb_corrupt_table_action 19 | variable having a non-default value. 20 | 21 | !!! warning "Complex Database Recovery Scenarios" 22 | Navigating table corruption and recovery can be challenging. 23 | [Percona Support](https://www.percona.com/services/support) offers 24 | expert guidance for complex database recovery and optimization 25 | strategies. 26 | 27 | For more information about the innodb_force_recovery variable, see 28 | [Forcing InnoDB Recovery] from the MySQL Reference Manual. 29 | 30 | This feature adds a system variable. 31 | 32 | ## System variables 33 | 34 | ### `innodb_corrupt_table_action` 35 | 36 | | Option | Description | 37 | |--------------|-----------------------| 38 | | Command-line | Yes | 39 | | Config file | Yes | 40 | | Scope | Global | 41 | | Dynamic | Yes | 42 | | Data type | ULONG | 43 | | Default | assert | 44 | | Range | assert, warn, salvage | 45 | 46 | * Enabling `innodb_file_per_table` and using the `assert` value creates 47 | an assertion failure which causes *XtraDB* to intentionally crash the 48 | server. This action is expected when detecting corrupted data in a 49 | single-table tablespace. 50 | 51 | * Enabling `innodb_file_per_table` and using the `warn` value causes 52 | *XtraDB* to pass the table corruption as `corrupt table` instead of 53 | crashing the server. Detecting the file as corrupt also disables the 54 | file I/O for that data file, except for the deletion operation. 55 | 56 | * Enabling `innodb_file_per_table` and using the `salvage` value causes 57 | *XtraDB* to allow read access to the corrupted tablespace but ignores 58 | any corrupted pages. 59 | 60 | [Forcing InnoDB Recovery]: https://dev.mysql.com/doc/refman/{{vers}}/en/ 61 | forcing-innodb-recovery.html 62 | -------------------------------------------------------------------------------- /docs/innodb-io.md: -------------------------------------------------------------------------------- 1 | # Improved InnoDB I/O scalability 2 | 3 | Because *InnoDB* is a complex storage engine it must be configured properly in 4 | order to perform at its best. Some points are not configurable in standard 5 | *InnoDB*. The goal of this feature is to provide a more exhaustive set of 6 | options for *XtraDB*. 7 | 8 | ## System variables 9 | 10 | ### `innodb_flush_method` 11 | 12 | | Option | Description | 13 | |----------------|-----------------------------------------------------------------| 14 | | Command-line | Yes | 15 | | Config file | Yes | 16 | | Scope | Global | 17 | | Dynamic | No | 18 | | Data type | Enumeration | 19 | | Default | NULL | 20 | | Allowed values | fsync, O_DSYNC, O_DIRECT, O_DIRECT_NO_FSYNC, littlesync, nosync | 21 | 22 | The following values are allowed: 23 | 24 | * `fdatasync`: use `fsync()` to flush data, log, and parallel doublewrite files. 25 | 26 | * `O_SYNC`: use `O_SYNC` to open and flush the log and parallel doublewrite files; use `fsync()` to flush the data files. Do not use `fsync()` to flush the parallel doublewrite file. 27 | 28 | * `O_DIRECT`: use O_DIRECT to open the data files and `fsync()` system call to flush data, log, and parallel doublewrite files. 29 | 30 | * `O_DIRECT_NO_FSYNC`: use O_DIRECT to open the data files and parallel doublewrite files, but does not use the `fsync()` system call to flush the data files, log files, and parallel doublewrite files. Do not use this option for the *XFS* file system. 31 | 32 | !!! note 33 | 34 | On an ext4 filesystem, set `innodb_log_write_ahead_size` to match the filesystem's write-ahead block size. This variable avoids `unaligned AIO/DIO` warnings. 35 | 36 | ## Status variables 37 | 38 | The following information has been added to `SHOW ENGINE INNODB STATUS` to confirm the checkpointing activity: 39 | 40 | ```text 41 | The current checkpoint age target 42 | The current age of the oldest page modification which has not been flushed to disk yet. 43 | The current age of the last checkpoint 44 | ... 45 | --- 46 | LOG 47 | --- 48 | Log sequence number 0 1059494372 49 | Log flushed up to 0 1059494372 50 | Last checkpoint at 0 1055251010 51 | Max checkpoint age 162361775 52 | Checkpoint age target 104630090 53 | Modified age 4092465 54 | Checkpoint age 4243362 55 | 0 pending log writes, 0 pending chkp writes 56 | ... 57 | ``` 58 | 59 | -------------------------------------------------------------------------------- /docs/isolation-levels.md: -------------------------------------------------------------------------------- 1 | # Isolation levels 2 | 3 | In databases, isolation levels define how transactions interact with each other and the data they access. They determine the level of concurrency and consistency in a multi-user database environment. 4 | 5 | In MySQL, there are four isolation levels available, each offering different trade-offs between concurrency and consistency: 6 | 7 | Each isolation level offers a different balance between concurrency and consistency, and the choice depends on the application's specific requirements. By selecting the appropriate isolation level, developers can ensure their MySQL database applications' desired data integrity and performance level. 8 | 9 | 10 | ## Read Uncommitted 11 | 12 | In the Read Uncommitted isolation level, transactions can read data that has been modified by other transactions but not yet committed. This level allows for the highest concurrency but can lead to dirty reads. 13 | 14 | ```{.bash data-prompt="mysql>"} 15 | SET TRANSACTION ISOLATION LEVEL READ UNCOMMITTED; 16 | 17 | -- Perform a SELECT query to read uncommitted data 18 | SELECT * FROM table_name; 19 | ``` 20 | 21 | ## Read Committed 22 | 23 | In Read Committed isolation level, transactions can only read data that has been committed by other transactions. This level prevents dirty reads but allows for non-repeatable reads and phantom reads. 24 | 25 | ```{.bash data-prompt="mysql>"} 26 | SET TRANSACTION ISOLATION LEVEL READ COMMITTED; 27 | 28 | -- Perform a SELECT query to read committed data 29 | SELECT * FROM table_name; 30 | ``` 31 | 32 | ## Repeatable Read 33 | 34 | In Repeatable Read isolation level, transactions can only read data that has been committed by other transactions at the start of the transaction. This level prevents dirty reads and non-repeatable reads but allows for phantom reads. 35 | 36 | ```{.bash data-prompt="mysql>"} 37 | SET TRANSACTION ISOLATION LEVEL REPEATABLE READ; 38 | 39 | -- Perform a SELECT query to read data consistently within the transaction 40 | SELECT * FROM table_name; 41 | ``` 42 | 43 | ## Serializable 44 | 45 | In Serializable isolation level, transactions are executed serially, preventing any concurrent access to the data. This level provides the highest level of isolation but can lead to reduced concurrency and potential deadlock situations. 46 | 47 | ```{.bash data-prompt="mysql>"} 48 | SET TRANSACTION ISOLATION LEVEL SERIALIZABLE; 49 | 50 | -- Perform a SELECT query within a serializable transaction 51 | SELECT * FROM table_name; 52 | ``` 53 | 54 | These examples demonstrate how to set and use different isolation levels in SQL transactions, each providing consistency and concurrency control. 55 | 56 | ## Database management 57 | 58 | * [Database](database.md) 59 | * [Modify Tables](modify-tables.md) 60 | * [Transaction Management](transaction-mgmt.md) 61 | * [Views](views.md) 62 | -------------------------------------------------------------------------------- /docs/pro-files.md: -------------------------------------------------------------------------------- 1 | # Files in packages built for Percona Server for MySQL Pro 2 | 3 | --8<--- "pro-build-announcement.md" 4 | 5 | ## Files in the DEB package 6 | 7 | | Package | Contains | 8 | |------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 9 | | percona-server-server-pro | The database server itself, the mysqld binary and associated files. | 10 | | percona-server-pro-common | The files common to the server and client. | 11 | | percona-server-client-pro | The command line client. | 12 | | percona-server-test-pro | The database test suite. | 13 | | percona-server-pro-source | The server source. | 14 | | percona-mysql-router-pro | The mysql router. | 15 | | percona-server-rocksdb-pro | The files for rocksdb installation. | 16 | | percona-server-pro-dbg | The debug symbols. | 17 | 18 | ## Files in the RPM package 19 | 20 | | Package | Contains | 21 | |------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 22 | | percona-server-server-pro | The database server itself, the mysqld binary and associated files. | 23 | | percona-server-client-pro | The command line client. | 24 | | percona-server-test-pro | The database test suite. | 25 | | percona-server-rocksdb-pro | The files for rocksdb installation. | 26 | | percona-mysql-router-pro | The mysql router. | 27 | | percona-server-shared-pro | Client shared library. | 28 | | percona-server-pro-debuginfo | The debug symbols. | 29 | | percona-server-devel-pro | Header files needed to compile software using the client library. | 30 | 31 | ## Next steps 32 | 33 | [Install Percona Server for MySQL Pro](install-pro.md){.md-button} 34 | -------------------------------------------------------------------------------- /docs/downgrade.md: -------------------------------------------------------------------------------- 1 | # Downgrade Percona Server for MySQL 2 | 3 | --8<--- "get-help-snip.md" 4 | 5 | Downgrading to a 5.7 or earlier series is not supported. 6 | 7 | Between versions within the same Long-Term Support (LTS) series, you can downgrade from 8.4.y LTS to 8.4.x LTS using the following methods: 8 | 9 | * Performing an in-place upgrade 10 | 11 | * Creating a logical dump and loading it 12 | 13 | * Use MySQL Clone functionality 14 | 15 | * Set up replication between the versions 16 | 17 | Between one LTS or Bugfix series to the previous LTS or Bugfix series, such as moving from 8.4.x LTS to 8.0.y, you have two primary options: 18 | 19 | * Create a logical dump of your data and load it into the older version 20 | 21 | * Set up replication between the versions. 22 | 23 | !!! important "Important" 24 | This downgrade path is only supported when no new server functionality has been applied to your data. 25 | 26 | Between an LTS or Bugfix series to an earlier Innovation series (after the previous LTS release), such as from 8.4.x LTS to 8.3.0 Innovation, you have the following options: 27 | 28 | * Create a logical dump of your data and load it into the older version 29 | 30 | * Set up replication between the versions. 31 | 32 | !!! important "Important" 33 | This downgrade path is only supported when no new server functionality has been applied to your data. 34 | 35 | We don't support downgrades with any 8.0.x release below 8.0.34. 36 | Releases in the range above 8.0.34 can be downgraded to any release within that range, including 8.0.34. 37 | 38 | ## Downgrading risks 39 | 40 | Downgrading has the following risks: 41 | 42 | | Risk | Description | 43 | |---|---| 44 | | Data loss | If the downgrade process has issues, you may lose your data. It is crucial that you back up your data before attempting to downgrade. | 45 | | Incompatibility | If you use any feature or improvement in the latest version, downgrading could result in incompatibility issues. | 46 | | Performance | Downgrading may result in a loss of performance | 47 | | Security | Newer versions have security updates that are not available in the older versions, which could lead to exposure. | 48 | 49 | ## Further reading 50 | 51 | * [Upgrade overview](./upgrade.md) 52 | * [Upgrade checklist for {{vers}}](./upgrade-checklist-8.4.md) 53 | * [Upgrade procedures for {{vers}}](./upgrade-procedures.md) 54 | * [Upgrade strategies](./upgrade-strategies.md) 55 | * [MySQL upgrade paths and supported methods](./mysql-upgrade-paths.md) 56 | * [Upgrade from plugins to components](./upgrade-components.md) 57 | * [Breaking and incompatible changes in {{vers}}](./8.4-breaking-changes.md) 58 | * [Compatibility and removed items in {{vers}}](./8.4-compatibility-and-removed-items.md) 59 | * [Defaults and tuning guidance for {{vers}}](./8.4-defaults-and-tuning.md) 60 | * [Percona Toolkit updates for {{vers}}](./percona-toolkit-8.4-updates.md) 61 | -------------------------------------------------------------------------------- /docs/development.md: -------------------------------------------------------------------------------- 1 | # Development of Percona Server for MySQL 2 | 3 | Percona Server for MySQL is an open source project to produce a distribution 4 | of the *MySQL* Server with improved performance, scalability and 5 | diagnostics. 6 | 7 | ## Submit changes 8 | 9 | We keep the trunk in a constant state of stability to allow for a release at 10 | any time and to minimize wasted time by developers due to broken code. 11 | 12 | ### Overview 13 | 14 | At Percona we use [Git](https://git-scm.com) for source control, [GitHub](https://github.com/percona) for code hosting, and [Jira](https://jira.percona.com) for release management. 15 | 16 | We change our software to implement new features and/or to fix bugs. Refactoring 17 | could be classed either as a new feature or a bug depending on the scope of 18 | work. 19 | 20 | 21 | 22 | New features and bugs are targeted to specific releases. A 23 | release is part of a series. For example, 2.4 is a series in Percona 24 | XtraBackup and 2.4.15, 2.4.16, and 2.4.17 are releases in this series. 25 | 26 | Code is proposed for merging in the form of pull requests on GitHub. 27 | 28 | For *Percona Server for MySQL*, we have several Git branches on which development occurs: 29 | 5.5, 5.6, 5.7, and 8.0. As *Percona Server for MySQL* is not a traditional project, instead 30 | of being a set of patches against an existing product, these branches are not 31 | related. In other words, we do not merge from one release branch to another. To 32 | have your changes in several branches, you must propose branches to each release 33 | branch. 34 | 35 | ### Making a change to a project 36 | 37 | In this case, we are going to use `percona-xtrabackup` as an example. The 38 | workflow is similar for *Percona Server for MySQL*, but the patch will need to be modified 39 | in all release branches of *Percona Server for MySQL*. 40 | 41 | 42 | * `git branch https://github.com/percona/percona-xtrabackup/featureX` (where ‘featureX’ is a 43 | sensible name for the task at hand) 44 | 45 | 46 | * (developer makes changes in featureX, testing locally) 47 | 48 | 49 | * The Developer pushes to `https://github.com/percona/username/percona-xtrabackup/featureX` 50 | 51 | 52 | * The developer can submit a pull request to [https://github.com/percona/percona-xtrabackup](https://github.com/percona/percona-xtrabackup), 53 | 54 | 55 | * Code undergoes a review 56 | 57 | 58 | * Once code is accepted, it can be merged 59 | 60 | If the change also applies to a stable release (e.g. 2.4) then changes should be 61 | made on a branch of 2.4 and merged to a branch of the trunk. In this case, there 62 | should be two branches run through the param build and two merge proposals (one 63 | for the stable release and one with the changes merged to the trunk). This prevents 64 | somebody else from having to guess how to merge your changes. 65 | 66 | ### Percona Server for MySQL 67 | 68 | The same process for *Percona Server for MySQL*, but we have several different branches 69 | (and merge requests). 70 | -------------------------------------------------------------------------------- /_resourcepdf/overrides/partials/banner.html: -------------------------------------------------------------------------------- 1 |
2 |

3 |

For help, click the link below to get free database assistance or contact our experts for personalized support.

4 | 5 |
6 | 7 | Get help from Percona 8 |
9 |
--------------------------------------------------------------------------------