Docs: Improve documentation for 5.x release

docs/en/index.rst

@@ -3,7 +3,7 @@ Migrations
 
 Migrations is a plugin that lets you track changes to your database schema over
 time as PHP code that accompanies your application. This lets you ensure each
-environment your application runs in can has the appropriate schema by applying
+environment your application runs in has the appropriate schema by applying
 migrations.
 
 Instead of writing schema modifications in SQL, this plugin allows you to
@@ -468,8 +468,8 @@ for use in unit tests), you can use the ``--generate-only`` flag:
 
     bin/cake bake migration_snapshot Initial --generate-only
 
-This will create the migration file but will not add an entry to the phinxlog
-table, allowing you to move the file to a different location without causing
+This will create the migration file but will not add an entry to the migrations
+tracking table, allowing you to move the file to a different location without causing
 "MISSING" status issues.
 
 The same logic will be applied implicitly if you wish to bake a snapshot for a
@@ -603,15 +603,15 @@ Cleaning up missing migrations
 -------------------------------
 
 Sometimes migration files may be deleted from the filesystem but still exist
-in the phinxlog table. These migrations will be marked as **MISSING** in the
-status output. You can remove these entries from the phinxlog table using the
+in the migrations tracking table. These migrations will be marked as **MISSING** in the
+status output. You can remove these entries from the tracking table using the
 ``--cleanup`` option:
 
 .. code-block:: bash
 
     bin/cake migrations status --cleanup
 
-This will remove all migration entries from the phinxlog table that no longer
+This will remove all migration entries from the tracking table that no longer
 have corresponding migration files in the filesystem.
 
 Marking a migration as migrated

docs/en/writing-migrations.rst

@@ -599,6 +599,72 @@ configuration key for the time being.
 
 To view available column types and options, see :ref:`adding-columns` for details.
 
+MySQL ALTER TABLE Options
+-------------------------
+
+.. versionadded:: 5.0.0
+    ``ALGORITHM`` and ``LOCK`` options were added in 5.0.0.
+
+When modifying tables in MySQL, you can control how the ALTER TABLE operation is
+performed using the ``algorithm`` and ``lock`` options. This is useful for performing
+zero-downtime schema changes on large tables in production environments.
+
+.. code-block:: php
+
+    <?php
+
+    use Migrations\BaseMigration;
+
+    class AddIndexToLargeTable extends BaseMigration
+    {
+        public function up(): void
+        {
+            $table = $this->table('large_table');
+            $table->addIndex(['status'], [
+                'name' => 'idx_status',
+            ]);
+            $table->update([
+                'algorithm' => 'INPLACE',
+                'lock' => 'NONE',
+            ]);
+        }
+    }
+
+Available ``algorithm`` values:
+
+============ ===========
+Algorithm    Description
+============ ===========
+DEFAULT      Let MySQL choose the algorithm (default behavior)
+INPLACE      Modify the table in place without copying data (when possible)
+COPY         Create a copy of the table with the changes (legacy method)
+INSTANT      Only modify metadata, no table rebuild (MySQL 8.0+, limited operations)
+============ ===========
+
+Available ``lock`` values:
+
+========= ===========
+Lock      Description
+========= ===========
+DEFAULT   Use minimal locking for the algorithm (default behavior)
+NONE      Allow concurrent reads and writes during the operation
+SHARED    Allow concurrent reads but block writes
+EXCLUSIVE Block all reads and writes during the operation
+========= ===========
+
+.. note::
+
+    Not all operations support all algorithm/lock combinations. MySQL will raise
+    an error if the requested combination is not possible for the operation.
+    The ``INSTANT`` algorithm is only available in MySQL 8.0+ and only for specific
+    operations like adding columns at the end of a table.
+
+.. warning::
+
+    Using ``ALGORITHM=INPLACE, LOCK=NONE`` does not guarantee zero-downtime for
+    all operations. Some operations may still require a table copy or exclusive lock.
+    Always test schema changes on a staging environment first.
+
 Table Partitioning
 ------------------