Skip to content

Add ALGORITHM and LOCK support for MySQL ALTER TABLE operations #955

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: 5.x
Choose a base branch
from
Open

Add ALGORITHM and LOCK support for MySQL ALTER TABLE operations #955

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d01babe
Add ALGORITHM and LOCK support for MySQL ALTER TABLE operations
dereuromark Nov 10, 2025
b4163a4
Fix ALGORITHM/LOCK implementation issues
dereuromark Nov 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
333 changes: 333 additions & 0 deletions src/Db/Adapter/MysqlAdapter.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,18 @@
use Cake\Database\Schema\SchemaDialect;
use Cake\Database\Schema\TableSchema;
use InvalidArgumentException;
use Migrations\Db\Action\AddColumn;
use Migrations\Db\Action\AddForeignKey;
use Migrations\Db\Action\AddIndex;
use Migrations\Db\Action\ChangeColumn;
use Migrations\Db\Action\ChangeComment;
use Migrations\Db\Action\ChangePrimaryKey;
use Migrations\Db\Action\DropForeignKey;
use Migrations\Db\Action\DropIndex;
use Migrations\Db\Action\DropTable;
use Migrations\Db\Action\RemoveColumn;
use Migrations\Db\Action\RenameColumn;
use Migrations\Db\Action\RenameTable;
use Migrations\Db\AlterInstructions;
use Migrations\Db\Table\CheckConstraint;
use Migrations\Db\Table\Column;
Expand Down Expand Up @@ -107,6 +119,77 @@ class MysqlAdapter extends AbstractAdapter

public const FIRST = 'FIRST';

/**
* MySQL ALTER TABLE ALGORITHM options
*
* These constants control how MySQL performs ALTER TABLE operations:
* - ALGORITHM_DEFAULT: Let MySQL choose the best algorithm
* - ALGORITHM_INSTANT: Instant operation (no table copy, MySQL 8.0+ / MariaDB 10.3+)
* - ALGORITHM_INPLACE: In-place operation (no full table copy)
* - ALGORITHM_COPY: Traditional table copy algorithm
*
* Usage:
* ```php
* use Migrations\Db\Adapter\MysqlAdapter;
*
* // ALGORITHM=INSTANT alone (recommended)
* $table->addColumn('status', 'string', [
* 'null' => true,
* 'algorithm' => MysqlAdapter::ALGORITHM_INSTANT,
* ]);
*
* // Or with ALGORITHM=INPLACE and explicit LOCK
* $table->addColumn('status', 'string', [
* 'algorithm' => MysqlAdapter::ALGORITHM_INPLACE,
* 'lock' => MysqlAdapter::LOCK_NONE,
* ]);
* ```
*
* Important: ALGORITHM=INSTANT cannot be combined with LOCK=NONE, LOCK=SHARED,
* or LOCK=EXCLUSIVE (MySQL restriction). Use ALGORITHM=INSTANT alone or with
* LOCK=DEFAULT only.
*
* Note: ALGORITHM_INSTANT requires MySQL 8.0+ or MariaDB 10.3+ and only works for
* compatible operations (adding nullable columns, dropping columns, etc.).
* If the operation cannot be performed instantly, MySQL will return an error.
*
* @see https://dev.mysql.com/doc/refman/8.0/en/alter-table.html
* @see https://dev.mysql.com/doc/refman/8.0/en/innodb-online-ddl-operations.html
* @see https://mariadb.com/kb/en/alter-table/#algorithm
*/
public const ALGORITHM_DEFAULT = 'DEFAULT';
public const ALGORITHM_INSTANT = 'INSTANT';
public const ALGORITHM_INPLACE = 'INPLACE';
public const ALGORITHM_COPY = 'COPY';

/**
* MySQL ALTER TABLE LOCK options
*
* These constants control the locking behavior during ALTER TABLE operations:
* - LOCK_DEFAULT: Let MySQL choose the appropriate lock level
* - LOCK_NONE: Allow concurrent reads and writes (least restrictive)
* - LOCK_SHARED: Allow concurrent reads, block writes
* - LOCK_EXCLUSIVE: Block all concurrent access (most restrictive)
*
* Usage:
* ```php
* use Migrations\Db\Adapter\MysqlAdapter;
*
* $table->changeColumn('name', 'string', [
* 'limit' => 500,
* 'algorithm' => MysqlAdapter::ALGORITHM_INPLACE,
* 'lock' => MysqlAdapter::LOCK_NONE,
* ]);
* ```
*
* @see https://dev.mysql.com/doc/refman/8.0/en/alter-table.html
* @see https://mariadb.com/kb/en/alter-table/#lock
*/
public const LOCK_DEFAULT = 'DEFAULT';
public const LOCK_NONE = 'NONE';
public const LOCK_SHARED = 'SHARED';
public const LOCK_EXCLUSIVE = 'EXCLUSIVE';

/**
* @inheritDoc
*/
Expand Down Expand Up @@ -1164,4 +1247,254 @@ protected function isMariaDb(): bool

return stripos($version, 'mariadb') !== false;
}

/**
* {@inheritDoc}
*
* Overridden to support ALGORITHM and LOCK clauses for MySQL ALTER TABLE operations.
*
* @throws \InvalidArgumentException
* @return void
*/
public function executeActions(TableMetadata $table, array $actions): void
{
// Extract algorithm and lock specifications from all actions
$algorithm = null;
$lock = null;

foreach ($actions as $action) {
if (!method_exists($action, 'getColumn')) {
continue;
}

$column = $action->getColumn();
if (!($column instanceof Column)) {
continue;
}

$colAlgorithm = $column->getAlgorithm();
$colLock = $column->getLock();

if ($colAlgorithm !== null) {
if ($algorithm !== null && $algorithm !== $colAlgorithm) {
throw new InvalidArgumentException(sprintf(
'Conflicting algorithm specifications in batched operations: "%s" and "%s". ' .
'All operations in a batch must use the same algorithm, or specify it on only one operation.',
$algorithm,
$colAlgorithm,
));
}
$algorithm = $colAlgorithm;
}

if ($colLock !== null) {
if ($lock !== null && $lock !== $colLock) {
throw new InvalidArgumentException(sprintf(
'Conflicting lock specifications in batched operations: "%s" and "%s". ' .
'All operations in a batch must use the same lock mode, or specify it on only one operation.',
$lock,
$colLock,
));
}
$lock = $colLock;
}
}

// If no algorithm/lock specified, use parent implementation
if ($algorithm === null && $lock === null) {
parent::executeActions($table, $actions);

return;
}

// Otherwise, execute with custom algorithm/lock support
$this->executeActionsWithAlgorithmAndLock($table, $actions, $algorithm, $lock);
}

/**
* Executes actions with ALGORITHM and LOCK clauses.
*
* @param \Migrations\Db\Table\TableMetadata $table The table metadata
* @param array $actions The actions to execute
* @param string|null $algorithm The algorithm to use
* @param string|null $lock The lock mode to use
* @throws \InvalidArgumentException
* @return void
*/
protected function executeActionsWithAlgorithmAndLock(
Copy link
Member

@markstory markstory Nov 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we not duplicate all of this logic? This feels like a big smell that we're missing a better design solution. Perhaps we could have an adapter hook method at the end of executeActions() that receives both the actions and instructions. That would allow the MySqlAdapter to append the lock/algorithm clauses without having to create all this duplication.

TableMetadata $table,
array $actions,
?string $algorithm,
?string $lock,
): void {
$instructions = new AlterInstructions();

// Build instructions (copied from AbstractAdapter::executeActions)
foreach ($actions as $action) {
switch (true) {
case $action instanceof AddColumn:
$instructions->merge($this->getAddColumnInstructions($table, $action->getColumn()));
break;

case $action instanceof AddIndex:
$instructions->merge($this->getAddIndexInstructions($table, $action->getIndex()));
break;

case $action instanceof AddForeignKey:
$instructions->merge($this->getAddForeignKeyInstructions($table, $action->getForeignKey()));
break;

case $action instanceof ChangeColumn:
$instructions->merge($this->getChangeColumnInstructions(
$table->getName(),
$action->getColumnName(),
$action->getColumn(),
));
break;

case $action instanceof DropForeignKey && !$action->getForeignKey()->getName():
$instructions->merge($this->getDropForeignKeyByColumnsInstructions(
$table->getName(),
$action->getForeignKey()->getColumns(),
));
break;

case $action instanceof DropForeignKey && $action->getForeignKey()->getName():
$instructions->merge($this->getDropForeignKeyInstructions(
$table->getName(),
(string)$action->getForeignKey()->getName(),
));
break;

case $action instanceof DropIndex && $action->getIndex()->getName():
$instructions->merge($this->getDropIndexByNameInstructions(
$table->getName(),
(string)$action->getIndex()->getName(),
));
break;

case $action instanceof DropIndex && !$action->getIndex()->getName():
$instructions->merge($this->getDropIndexByColumnsInstructions(
$table->getName(),
(array)$action->getIndex()->getColumns(),
));
break;

case $action instanceof DropTable:
$instructions->merge($this->getDropTableInstructions($table->getName()));
break;

case $action instanceof RemoveColumn:
$instructions->merge($this->getDropColumnInstructions(
$table->getName(),
(string)$action->getColumn()->getName(),
));
break;

case $action instanceof RenameColumn:
$instructions->merge($this->getRenameColumnInstructions(
$table->getName(),
(string)$action->getColumn()->getName(),
$action->getNewName(),
));
break;

case $action instanceof RenameTable:
$instructions->merge($this->getRenameTableInstructions(
$table->getName(),
$action->getNewName(),
));
break;

case $action instanceof ChangePrimaryKey:
$instructions->merge($this->getChangePrimaryKeyInstructions(
$table,
$action->getNewColumns(),
));
break;

case $action instanceof ChangeComment:
$instructions->merge($this->getChangeCommentInstructions(
$table,
$action->getNewComment(),
));
break;

default:
throw new InvalidArgumentException(
sprintf("Don't know how to execute action `%s`", get_class($action)),
);
}
}

// Build ALTER TABLE template with algorithm and lock
$alterTemplate = sprintf('ALTER TABLE %s %%s', $this->quoteTableName($table->getName()));

// Add algorithm and lock clauses
$algorithmLockClause = '';
Copy link
Member

@markstory markstory Nov 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Won't we be missing lock/algorithm when $adapter->addColumn() and changeColumn() are used because of where this logic is?

$upperAlgorithm = null;
$upperLock = null;

if ($algorithm !== null) {
$upperAlgorithm = strtoupper($algorithm);
$validAlgorithms = [
self::ALGORITHM_DEFAULT,
self::ALGORITHM_INSTANT,
self::ALGORITHM_INPLACE,
self::ALGORITHM_COPY,
];
if (!in_array($upperAlgorithm, $validAlgorithms, true)) {
throw new InvalidArgumentException(sprintf(
'Invalid algorithm "%s". Valid options: %s',
$algorithm,
implode(', ', $validAlgorithms),
));
}
$algorithmLockClause .= ', ALGORITHM=' . $upperAlgorithm;
}

if ($lock !== null) {
$upperLock = strtoupper($lock);
$validLocks = [
self::LOCK_DEFAULT,
self::LOCK_NONE,
self::LOCK_SHARED,
self::LOCK_EXCLUSIVE,
];
if (!in_array($upperLock, $validLocks, true)) {
throw new InvalidArgumentException(sprintf(
'Invalid lock "%s". Valid options: %s',
$lock,
implode(', ', $validLocks),
));
}
$algorithmLockClause .= ', LOCK=' . $upperLock;
}

// MySQL restriction: ALGORITHM=INSTANT cannot be combined with explicit LOCK modes
// except LOCK=DEFAULT. See: https://dev.mysql.com/doc/refman/8.0/en/innodb-online-ddl-operations.html
if ($upperAlgorithm === self::ALGORITHM_INSTANT && $upperLock !== null && $upperLock !== self::LOCK_DEFAULT) {
throw new InvalidArgumentException(
'ALGORITHM=INSTANT cannot be combined with LOCK=NONE, LOCK=SHARED, or LOCK=EXCLUSIVE. ' .
'Either use ALGORITHM=INSTANT alone, or use ALGORITHM=INSTANT with LOCK=DEFAULT.',
);
}

// Execute with custom template
if ($instructions->getAlterParts()) {
$alter = sprintf($alterTemplate, implode(', ', $instructions->getAlterParts()) . $algorithmLockClause);
$this->execute($alter);
}

// Execute post-steps
$state = [];
foreach ($instructions->getPostSteps() as $instruction) {
if (is_callable($instruction)) {
$state = $instruction($state);
continue;
}

$this->execute($instruction);
}
}
}
Loading