diff --git a/docs/getting-started/schema-optimization.md b/docs/getting-started/schema-optimization.md
index 91ef689..fe5dcc5 100644
--- a/docs/getting-started/schema-optimization.md
+++ b/docs/getting-started/schema-optimization.md
@@ -5,7 +5,7 @@ title: Schema Optimization
 
 # Schema Optimization
 
-Releem's Schema Optimization feature automatically examines your database structure to identify schema issues that can impact performance, storage efficiency, and data integrity. It is like the schema watchdog that  detects problems before they become serious and provides ready-to-use SQL recommendations.
+Releem's Schema Optimization feature automatically examines your database structure to identify schema issues that can impact performance, storage efficiency, and data integrity. It is like the schema watchdog that detects problems before they become serious and provides ready-to-use SQL recommendations.
 
 ![Releem Schema Optimization](../../assets/images/releem-schema-optimization.png)
 
@@ -26,6 +26,10 @@ Schema optimization helps you detect and fix:
 4. Test changes in a development environment first
 5. Execute the SQL on your production database during low-traffic periods
 
+To let Releem apply approved schema changes for you instead of running SQL manually, follow [Automatic Schema Changes](/query-optimization/automatic-schema-changes).
+
+If an automatic schema change fails in Releem, use the [Schema Change Troubleshooting](/query-optimization/schema-change-troubleshooting) guide to match the error to the next action.
+
 For detailed information about each type of schema check and comprehensive best practices, see the [MySQL Database Schema Checks](https://releem.com/blog/mysql-database-schema-checks) article.
 
 Schema optimization is essential for maintaining long-term database health and performance as your application grows.
diff --git a/docs/query-optimization/automatic-schema-changes.md b/docs/query-optimization/automatic-schema-changes.md
new file mode 100644
index 0000000..d840587
--- /dev/null
+++ b/docs/query-optimization/automatic-schema-changes.md
@@ -0,0 +1,351 @@
+---
+id: automatic-schema-changes
+title: Automatic Schema Changes
+---
+
+# Automatic Schema Changes
+
+Releem can apply approved schema recommendations, such as creating indexes, directly from the Releem Dashboard. This is useful when you want Releem to complete the optimization workflow after you review and approve a change.
+
+Automatic schema changes are disabled by default. Enable them only on servers where the Releem Agent is allowed to run DDL statements and where you have checked the backup and disk-space requirements.
+
+Before applying a change, the Releem Agent checks that the operation can be completed safely. Depending on the recommendation and the server, the agent may:
+
+- test the change on a temporary table before touching the production table;
+- use native online DDL when MySQL or MariaDB can run the change without blocking the table;
+- use `pt-online-schema-change` when the server cannot run the change online by itself;
+- create a backup before the change when the recommendation requires it.
+
+If these checks fail, Releem does not apply the change automatically. See [Schema Change Troubleshooting](/query-optimization/schema-change-troubleshooting) for the next steps.
+
+## Before You Start
+
+Automatic schema changes require:
+
+- an installed and running Releem Agent;
+- [SQL Query Optimization](/query-optimization/enable-sql-query-optimization) enabled for the server;
+- MySQL or MariaDB configuration that allows Releem to validate the schema change and create a backup when needed;
+- a MySQL user used by the agent with permissions to apply the approved schema changes;
+- enough free disk space in the MySQL data directory and in the backup directory;
+- binary logs with at least 2 days of retention when Releem requires a pre-change backup;
+- additional tools installed on the same host as the agent when they are needed.
+
+For Linux servers, the default agent configuration file is:
+
+```bash
+/opt/releem/releem.conf
+```
+
+## Enable Automatic Schema Changes
+
+### 1. Install the Tools Used by the Agent
+
+Install the tools that match your database type and backup strategy.
+
+Some packages may not be available in the default operating system repositories. If your package manager cannot find a package, add the vendor repository first and then run the installation command again:
+
+- For `pt-online-schema-change` and Percona XtraBackup, follow [Install percona-release](https://docs.percona.com/percona-software-repositories/installing.html).
+- For MariaDB Backup, follow [MariaDB Package Repository Setup and Usage](https://mariadb.com/docs/server/server-management/install-and-upgrade-mariadb/installing-mariadb/binary-packages/mariadb-package-repository-setup-and-usage).
+
+For Debian or Ubuntu:
+
+```bash
+sudo apt-get update
+sudo apt-get install pt-online-schema-change
+```
+
+For RHEL, CentOS, Rocky Linux, or AlmaLinux:
+
+```bash
+sudo yum install pt-online-schema-change
+```
+
+On newer releases such as Rocky Linux 8+ or AlmaLinux 8+, use `dnf` instead of `yum`.
+
+For physical backups on MySQL, install Percona XtraBackup. The Percona repository is usually required first. Example:
+
+Debian or Ubuntu:
+
+```bash
+sudo apt-get install percona-xtrabackup-80
+```
+
+RHEL, CentOS, Rocky Linux, or AlmaLinux:
+
+```bash
+sudo yum install percona-xtrabackup-80
+```
+
+For MariaDB servers, install MariaDB Backup and point `xtrabackup_path` to `mariabackup`:
+
+Debian or Ubuntu:
+
+```bash
+sudo apt-get install mariadb-backup
+```
+
+RHEL, CentOS, Rocky Linux, or AlmaLinux:
+
+```bash
+sudo yum install MariaDB-backup
+```
+
+Package names can differ by operating system and repository. Use the official installation instructions linked at the end of this page for production servers.
+
+### 2. Configure MySQL for Automatic Schema Changes
+
+Releem uses MySQL metadata collected by the agent to decide whether a schema change can run automatically. Configure MySQL before enabling DDL execution in the agent.
+
+#### Enable point-in-time recovery for pre-change backups
+
+When Releem marks a schema change as requiring a pre-change backup, the change runs only if point-in-time recovery is available. Releem considers point-in-time recovery available when:
+
+- `log_bin` is `ON`;
+- binary log retention is at least 2 days.
+
+If these values are not available, the Releem Agent skips the schema change instead of applying it without the required recovery option.
+
+Add the settings to the MySQL or MariaDB server configuration file. Common locations are:
+
+- `/etc/mysql/mysql.conf.d/mysqld.cnf` for MySQL on Debian or Ubuntu;
+- `/etc/mysql/mariadb.conf.d/50-server.cnf` for MariaDB on Debian or Ubuntu;
+- `/etc/my.cnf` or a file under `/etc/my.cnf.d/` for RHEL-based distributions.
+
+For MySQL 8.0 and newer, set binary log retention in seconds:
+
+```ini
+[mysqld]
+log_bin=mysql-bin
+binlog_expire_logs_seconds=172800
+binlog_format=ROW
+```
+
+For MySQL 5.7 and MariaDB 10.5 or earlier, use `expire_logs_days`:
+
+```ini
+[mysqld]
+log_bin=mysql-bin
+expire_logs_days=2
+binlog_format=ROW
+```
+
+For MariaDB 10.6 and newer, either retention variable can be used. Releem reads `binlog_expire_logs_seconds` when it is available:
+
+```ini
+[mariadb]
+log_bin
+binlog_expire_logs_seconds=172800
+binlog_format=ROW
+```
+
+If binary logging is already enabled, keep your existing binary log basename and only adjust retention if it is lower than 2 days. After changing MySQL configuration, restart MySQL or MariaDB.
+
+Use the command that matches your service name:
+
+```bash
+sudo systemctl restart mysql
+sudo systemctl restart mysqld
+sudo systemctl restart mariadb
+```
+
+For managed database services, configure the equivalent database parameter or backup/binlog retention setting in the provider console. Releem must see `log_bin=ON` and retention of at least 2 days in the variables collected by the agent.
+
+Verify the effective values:
+
+```sql
+SHOW VARIABLES
+WHERE Variable_name IN (
+  'log_bin',
+  'binlog_expire_logs_seconds',
+  'expire_logs_days',
+  'binlog_format',
+  'datadir'
+);
+```
+
+#### Check table and execution requirements
+
+Releem checks each approved statement before sending it to the agent:
+
+- native Online DDL is allowed for InnoDB tables on MySQL 5.7+ or MariaDB 10+ when the statement is valid;
+- `pt-online-schema-change` is allowed only for InnoDB tables with a primary key, without triggers, and without referencing foreign keys;
+- online physical backup is selected only for InnoDB tables;
+- if neither native Online DDL nor `pt-online-schema-change` is safe, Releem does not run the change automatically.
+
+You can check the target table before approving a change:
+
+```sql
+SELECT ENGINE
+FROM information_schema.TABLES
+WHERE TABLE_SCHEMA='your_database'
+  AND TABLE_NAME='your_table';
+
+SHOW INDEX FROM `your_database`.`your_table` WHERE Key_name='PRIMARY';
+
+SHOW TRIGGERS FROM `your_database` LIKE 'your_table';
+
+SELECT TABLE_SCHEMA, TABLE_NAME, CONSTRAINT_NAME
+FROM information_schema.KEY_COLUMN_USAGE
+WHERE REFERENCED_TABLE_SCHEMA='your_database'
+  AND REFERENCED_TABLE_NAME='your_table';
+```
+
+#### Check disk-space requirements
+
+The agent checks disk capacity before execution:
+
+- the MySQL data directory must keep more than 10% free space;
+- projected MySQL data directory usage after the schema change must stay at or below 90%;
+- when a backup is required, `backup_dir` must have enough free space for the estimated backup size plus `backup_space_buffer`;
+- logical backups use `mysqldump`; physical backups use `xtrabackup` or `mariabackup`.
+
+Keep `disable_space_checks=false` for production use. Disable it only temporarily and only when you already have another capacity check in place.
+
+### 3. Configure the Releem Agent
+
+Open the agent configuration file:
+
+```bash
+sudo nano /opt/releem/releem.conf
+```
+
+Enable DDL execution and review the paths used by the agent:
+
+```
+enable_exec_ddl=true
+
+backup_dir="/tmp/backups"
+ptosc_path="pt-online-schema-change"
+mysqldump_path="mysqldump"
+xtrabackup_path="xtrabackup"
+backup_space_buffer=20.0
+online_ddl_test_schema="releem_online_ddl_test"
+disable_space_checks=false
+```
+
+Use full paths when a tool is not available on the agent process `PATH`. For example:
+
+```
+ptosc_path="/usr/bin/pt-online-schema-change"
+mysqldump_path="/usr/bin/mysqldump"
+xtrabackup_path="/usr/bin/xtrabackup"
+```
+
+For MariaDB Backup, set:
+
+```
+xtrabackup_path="mariabackup"
+```
+
+### 4. Prepare the Backup Directory
+
+Create the backup directory and make sure the Releem Agent process can write to it:
+
+```bash
+sudo mkdir -p /tmp/backups
+```
+
+
+### 5. Grant Database Permissions
+
+Connect to MySQL or MariaDB as an administrator and grant the required permissions to the same database user that the Releem Agent already uses.
+
+For schema changes on all databases:
+
+```sql
+GRANT CREATE, REFERENCES, INDEX, ALTER ON *.* TO `releem`@`127.0.0.1`;
+```
+
+Or grant permissions only for one database:
+
+```sql
+GRANT CREATE, REFERENCES, INDEX, ALTER ON `your_database`.* TO `releem`@`127.0.0.1`;
+```
+
+For the test schema used by the online DDL preflight:
+
+```sql
+CREATE DATABASE IF NOT EXISTS `releem_online_ddl_test`;
+GRANT CREATE, DROP, INDEX, ALTER ON `releem_online_ddl_test`.* TO `releem`@`127.0.0.1`;
+```
+
+If Releem may use `pt-online-schema-change`, grant the extra permissions needed by that tool:
+
+```sql
+GRANT SELECT, INSERT, DROP, RELOAD, SUPER, SHOW VIEW, TRIGGER ON *.* TO `releem`@`127.0.0.1`;
+```
+
+On MySQL 8 and newer, use the equivalent dynamic privileges required by your security policy when `SUPER` is not allowed.
+
+Replace `releem` and `127.0.0.1` with the user and host from your agent configuration if they are different.
+
+### 6. Restart the Releem Agent
+
+Restart the agent so it reads the new configuration:
+
+```bash
+sudo systemctl restart releem-agent
+```
+
+If your server uses the legacy service command:
+
+```bash
+sudo service releem-agent restart
+```
+
+### 7. Collect the Next Snapshot the Releem Agent
+
+After changing MySQL and Releem Agent settings, let the Releem Agent collect the next snapshot or run:
+
+```bash
+sudo /opt/releem/releem-agent -f
+```
+
+### 8. Approve the Schema Change in Releem
+
+Open the Releem Dashboard, review the query recommendation, and approve the change only when you are ready for the agent to apply it.
+
+After the task starts, Releem shows the result in the dashboard. If the task fails, open the failed task and use [Schema Change Troubleshooting](/query-optimization/schema-change-troubleshooting).
+
+## Agent Configuration Reference
+
+| Setting | Default | Description |
+| --- | --- | --- |
+| `enable_exec_ddl` | `false` | Enables automatic execution of approved schema changes. Keep it `false` when you want Releem to recommend changes only. |
+| `backup_dir` | `/tmp/backups` | Directory where the agent stores logical and physical backups before a schema change. |
+| `ptosc_path` | `pt-online-schema-change` | Path to the `pt-online-schema-change` binary. Used when Releem selects that method. |
+| `mysqldump_path` | `mysqldump` | Path to `mysqldump`. Used for logical table backups. |
+| `xtrabackup_path` | `xtrabackup` | Path to `xtrabackup` or `mariabackup`. Used for physical backups when Releem selects that method. |
+| `backup_space_buffer` | `20.0` | Extra free-space percentage required above the estimated backup size. |
+| `online_ddl_test_schema` | `releem_online_ddl_test` | Schema where the agent creates temporary tables to test online DDL before applying it to the production table. |
+| `disable_space_checks` | `false` | Disables disk-space checks when set to `true`. Use only temporarily and only when you have another capacity check in place. |
+
+## Additional Tool Installation Notes
+
+- `mysqldump` is needed only when Releem selects logical backup. Check that it already exists on the server or set `mysqldump_path` to the installed binary.
+- `pt-online-schema-change` is required only when Releem selects this execution method.
+- `xtrabackup` is installed from Percona XtraBackup packages.
+- `mariabackup` is installed from MariaDB Backup packages and should be used for MariaDB servers.
+
+After installing tools, check that the agent can find them:
+
+```bash
+which mysqldump
+which pt-online-schema-change
+which xtrabackup
+which mariabackup
+```
+
+Use the returned paths in `releem.conf` if needed.
+
+## Documentation Links
+
+- [Percona repository setup](https://docs.percona.com/percona-software-repositories/installing.html)
+- [pt-online-schema-change documentation](https://docs.percona.com/percona-toolkit/pt-online-schema-change.html)
+- [Percona XtraBackup installation](https://docs.percona.com/percona-xtrabackup/8.0/installation.html)
+- [MariaDB repository setup](https://mariadb.com/docs/server/server-management/install-and-upgrade-mariadb/installing-mariadb/binary-packages/mariadb-package-repository-setup-and-usage)
+- [MariaDB Backup documentation](https://mariadb.com/docs/server/server-usage/backup-and-restore/mariadb-backup/mariadb-backup-overview)
+- [MySQL binary logging options](https://dev.mysql.com/doc/refman/8.4/en/replication-options-binary-log.html)
+- [MariaDB binary log activation](https://mariadb.com/docs/server/server-management/server-monitoring-logs/binary-log/activating-the-binary-log)
+- [MariaDB binary log variables](https://mariadb.com/docs/server/ha-and-performance/standard-replication/replication-and-binary-log-system-variables)
+- [mysqldump documentation](https://dev.mysql.com/doc/refman/8.4/en/mysqldump.html)
diff --git a/docs/query-optimization/schema-change-troubleshooting.md b/docs/query-optimization/schema-change-troubleshooting.md
new file mode 100644
index 0000000..30bc670
--- /dev/null
+++ b/docs/query-optimization/schema-change-troubleshooting.md
@@ -0,0 +1,115 @@
+---
+id: schema-change-troubleshooting
+title: Schema Change Troubleshooting
+---
+
+# Schema Change Troubleshooting
+
+Use this guide when an automatic schema change fails in Releem.
+
+Open the failed task in the Releem Dashboard and check:
+
+1. the exact **Apply Index Error** message;
+2. the detailed error text shown after the main error title;
+3. the Releem Agent logs when the dashboard message is not enough.
+
+Some dashboard views show a generic title such as `Schema changes execution failed` and then append the detailed error sent by the agent. Match the detailed text against the tables below. For logs, see [How to Check Releem Agent Logs](/releem-agent/how-to-check-logs).
+
+For setup requirements, see [Automatic Schema Changes](/query-optimization/automatic-schema-changes).
+
+## Errors Before Execution Starts
+
+These errors happen before the agent runs a backup or DDL statement.
+
+| Error name | Error text contains | What to do |
+| --- | --- | --- |
+| Automatic schema changes are disabled | `schema change execution is disabled by config` | Set `enable_exec_ddl=true` in `/opt/releem/releem.conf`, restart the Releem Agent, and retry the task from Releem. |
+| Task data is invalid | `taskdetails JSON`, `schema_name is required`, `ddl_statement is required`, `analysis_results.schema_name is required`, or `analysis_results.table_name is required` | Contact Releem support with the task id. The task payload sent to the agent is incomplete or malformed and cannot be fixed only on the database server. |
+| No schema change was sent | `Invalid task_details: empty schema change list` | Retry from Releem. If the recommendation should contain a change, contact Releem support with the task id. |
+| SQL statement is invalid | `Statement N skipped: syntax validation failed` | Do not retry the same task. Fix or recreate the schema recommendation so the DDL is valid for the target MySQL or MariaDB version. |
+
+## Releem Did Not Find a Safe Automatic Method
+
+These errors happen during per-statement validation. The agent stops before running DDL.
+
+| Error name | Error text contains | What to do |
+| --- | --- | --- |
+| Releem cannot run this change online | `Statement N skipped: cannot be executed without blocking the table` | Apply the change manually during a maintenance window, or ask Releem support to review the recommendation. Releem did not allow native Online DDL or `pt-online-schema-change` for this statement. |
+| Point-in-time recovery is not ready | `Point-in-time recovery is not possible` | Enable binary logging and keep at least 2 days of binary log retention, then let the agent collect a fresh snapshot and retry. If this is a managed database, enable the provider's equivalent PITR/binlog retention setting. |
+
+## Backup or Execution Failed
+
+These errors mean the agent started the operational phase and then the backup or DDL execution failed. The dashboard may show `Schema changes execution failed` with the detailed agent error.
+
+Use the text after `Statement N failed:` or after the dashboard prefix to identify the exact issue.
+
+### Disk Space and Filesystem Checks
+
+| Error name | Error text contains | What to do |
+| --- | --- | --- |
+| MySQL data directory has too little free space | `insufficient datadir free space` | Free space on the filesystem that contains MySQL `datadir`, then retry. The agent requires more than 10% free space before it starts the change. |
+| MySQL data directory would become too full | `insufficient datadir capacity for table change` | Add storage, archive data, drop unused data, or reduce the target table size before retrying. Projected datadir usage after the change must stay at or below 90%. |
+| Agent cannot read the MySQL data directory | `failed to resolve datadir`, `datadir is empty`, `failed to check datadir filesystem capacity`, or `invalid datadir filesystem size` | Check that MySQL returns `SHOW VARIABLES LIKE 'datadir'`, that the path exists on the host where the agent runs, and that the agent can read filesystem capacity for that path. |
+| Agent cannot estimate the target table size | `failed to get table size` | Check that the table still exists and that the agent MySQL user can read `information_schema.TABLES` for the target schema and table. |
+
+Do not disable space checks for normal production use. Use `disable_space_checks=true` only temporarily and only when another capacity check is already in place.
+
+### Backup Directory Checks
+
+| Error name | Error text contains | What to do |
+| --- | --- | --- |
+| Backup directory does not have enough free space | `backup failed: insufficient disk space` | Free space on the filesystem used by `backup_dir`, or move `backup_dir` to a larger volume. Keep `backup_space_buffer` high enough for your safety margin. |
+| Backup directory cannot be checked | `backup failed: failed to check disk space` | Create `backup_dir` before retrying, confirm it is on a mounted filesystem, and make sure the agent process can access it. |
+| Backup directory cannot be created | `backup failed: failed to create backup directory` | Create the directory manually, fix ownership and permissions, and retry. |
+| Backup size cannot be estimated | `backup failed: failed to estimate backup size` | Check that the target table or database still exists and that the agent MySQL user can read metadata from `information_schema.TABLES`. |
+
+### Pre-change Backup Tools
+
+| Error name | Error text contains | What to do |
+| --- | --- | --- |
+| Backup connection settings are incomplete | `backup failed: mysql_host is required for backup` or `backup failed: config is required for backup` | Check the MySQL connection settings in `releem.conf`: `mysql_host`, `mysql_port`, `mysql_user`, and `mysql_password`. Restart the agent after changing the file. |
+| Logical backup with mysqldump failed | `backup failed: mysqldump failed` | Install `mysqldump`, set `mysqldump_path` if the binary is not on `PATH`, and confirm that the agent MySQL user can dump the target table. |
+| Physical backup with xtrabackup failed | `backup failed: xtrabackup backup failed` | Install a compatible Percona XtraBackup for MySQL, or use `mariabackup` for MariaDB by setting `xtrabackup_path="mariabackup"`. Check the tool output in the agent logs. |
+| Physical backup prepare step failed | `backup failed: xtrabackup prepare failed` | Check that the backup tool version matches the server type and version. Review the detailed tool output in the agent logs, fix the backup tool issue, and retry. |
+| Unsupported backup method was selected | `backup failed: unsupported backup method` | Contact Releem support with the task id and agent logs. This indicates an internal task or agent mismatch. |
+
+### Native Online DDL
+
+These errors are usually shown as `Schema changes execution failed: schema change execution failed: ...`.
+
+| Error name | Error text contains | What to do |
+| --- | --- | --- |
+| Online DDL test schema is not configured | `test schema is required for online DDL preflight` | Set `online_ddl_test_schema="releem_online_ddl_test"` or another schema name in `releem.conf`, grant the agent user access to it, restart the agent, and retry. |
+| Online DDL test schema cannot be created | `failed to create test schema` | Grant the agent MySQL user permission to create the configured test schema, or create the schema manually and grant access. |
+| Online DDL test table cannot be created | `failed to create test table` | Grant the agent user permission to create tables in `online_ddl_test_schema`. Also check that the source table still exists. |
+| Online DDL preflight failed | `online DDL preflight failed on test table` | The agent tested the DDL on an empty copy of the table and MySQL rejected it. Check the MySQL error after this message. Fix unsupported DDL, incompatible clauses, or missing privileges before retrying. |
+| DDL format is not supported for online execution | `empty SQL statement`, `unsupported DDL for online clauses`, `failed to prepare test DDL SQL`, or `could not locate target table in DDL statement` | Use a supported `ALTER TABLE` or `CREATE INDEX` statement that clearly targets the analyzed table. Recreate the recommendation if the DDL text no longer matches the table. |
+| Online DDL lock timeout cannot be set | `failed to set session lock_wait_timeout` | Grant the needed session-variable permission if required by your server, or check MySQL restrictions that prevent setting session variables. |
+| Online DDL is blocked or rejected on the production table | `schema change execution failed` with a MySQL error about locks, metadata locks, `ALGORITHM=INPLACE`, `LOCK=NONE`, or another server error | Clear blocking transactions, retry during a quieter period, or apply the change manually during a maintenance window. If the error says `Try ALGORITHM=COPY`, Releem can fall back to `pt-online-schema-change` only when that method was allowed for the statement. |
+
+### pt-online-schema-change
+
+These errors are usually shown as `Schema changes execution failed: pt-online-schema-change execution failed: ...`.
+
+| Error name | Error text contains | What to do |
+| --- | --- | --- |
+| pt-online-schema-change connection settings are incomplete | `mysql_host is required for pt-online-schema-change` or `config is required for pt-online-schema-change` | Check `mysql_host`, `mysql_port`, `mysql_user`, and `mysql_password` in `releem.conf`. Restart the agent after changing the file. |
+| pt-online-schema-change cannot parse the table name | `pt-online-schema-change execution failed: failed to parse table name` | Confirm that `analysis_results.schema_name` and `analysis_results.table_name` match an existing table and use a valid `schema.table` form. |
+| pt-online-schema-change dry run failed | `pt-online-schema-change dry-run failed` | Install or update `pt-online-schema-change`, set `ptosc_path` if needed, and grant the permissions required by `pt-online-schema-change`. Run a manual dry run with the same connection settings if you need the full tool output. |
+| pt-online-schema-change execution failed | `pt-online-schema-change failed` | The dry run passed, but the actual execution failed. Check the tool output in agent logs. Common causes include missing privileges, replica lag, triggers, foreign key restrictions, disk limits, or table changes after the recommendation was generated. |
+
+`pt-online-schema-change` may require privileges such as `SELECT`, `INSERT`, `DROP`, `RELOAD`, `SUPER`, `SHOW VIEW`, and `TRIGGER`, depending on the server version and topology.
+
+### Other Execution Errors
+
+| Error name | Error text contains | What to do |
+| --- | --- | --- |
+| Target table is missing from the task | `table name is required for schema change execution` | Contact Releem support with the task id. The task reached the agent without the analyzed table name. |
+| Target table name cannot be parsed | `failed to parse table name` | Check that the recommendation still points to an existing `schema.table`. If the table was renamed or dropped after the recommendation was generated, recreate the recommendation. |
+| No execution method was available during execution | `schema change could not be executed` | Contact Releem support with the task id and agent logs. This should normally be caught earlier by validation. |
+
+## No Statement Was Applied
+
+| Error name | Error text contains | What to do |
+| --- | --- | --- |
+| Task finished without applying a change | `No schema changes were executed` | Review the full task output and agent logs. Retry from Releem if the recommendation is still valid, or contact support if the task should have applied a change. |
diff --git a/docs/releem-agent/configuration-settings.md b/docs/releem-agent/configuration-settings.md
index c533704..b37c7ea 100644
--- a/docs/releem-agent/configuration-settings.md
+++ b/docs/releem-agent/configuration-settings.md
@@ -94,6 +94,30 @@ query_optimization=false
 # List of databases for query optimization (comma-separated)
 databases_query_optimization=""
 
+# Enable automatic execution of approved schema changes
+enable_exec_ddl=false
+
+# Directory for schema-change backups
+backup_dir="/tmp/backups"
+
+# Path to pt-online-schema-change binary
+ptosc_path="pt-online-schema-change"
+
+# Path to mysqldump binary
+mysqldump_path="mysqldump"
+
+# Path to xtrabackup or mariabackup binary
+xtrabackup_path="xtrabackup"
+
+# Extra free-space buffer percentage for backups
+backup_space_buffer=20.0
+
+# Scratch schema used for Online DDL preflight checks
+online_ddl_test_schema="releem_online_ddl_test"
+
+# Disable disk space checks for schema-change execution
+disable_space_checks=false
+
 # Server data storage region - EU or empty
 releem_region=""
 ```
@@ -107,6 +131,8 @@ releem_region=""
 - PostgreSQL monitoring is enabled when `pg_user` and `pg_password` are configured.
 - Set `query_optimization=true` to enable SQL query optimization features where supported.
 - Use `databases_query_optimization` to specify which databases to monitor for query optimization (leave empty for all databases).
+- Set `enable_exec_ddl=true` only when the Releem Agent is allowed to apply approved schema changes automatically.
+- Keep `disable_space_checks=false` for production use unless you have a separate capacity check in place.
 - The `releem_region` field can be set to `EU` for European data storage or left empty for default storage.
 
 ## Restarting the Agent
diff --git a/sidebars.js b/sidebars.js
index 62d0c72..d77b0c5 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -93,6 +93,8 @@ const sidebars = {
         'query-optimization/enable-sql-query-optimization',
         'query-optimization/disable-sql-query-optimization',
         'query-optimization/prepared-statements-issue',
+        'query-optimization/automatic-schema-changes',
+        'query-optimization/schema-change-troubleshooting',
       ],
     },
     {