yiisoft/yii2 · error · yii\base\NotSupportedException

yii\db\sqlite\QueryBuilder::alterColumn is not supported by

Error message

yii\db\sqlite\QueryBuilder::alterColumn is not supported by SQLite.

What it means

yii\db\sqlite\QueryBuilder::alterColumn() always throws NotSupportedException: SQLite cannot change a column definition in place, since ALTER TABLE only supports RENAME TABLE and ADD COLUMN (plus limited RENAME COLUMN). Column type changes require the full table-rebuild pattern.

Source

Thrown at framework/db/sqlite/QueryBuilder.php:339

    public function renameTable($table, $newName)
    {
        return 'ALTER TABLE ' . $this->db->quoteTableName($table) . ' RENAME TO ' . $this->db->quoteTableName($newName);
    }

    /**
     * Builds a SQL statement for changing the definition of a column.
     * @param string $table the table whose column is to be changed. The table name will be properly quoted by the method.
     * @param string $column the name of the column to be changed. The name will be properly quoted by the method.
     * @param string $type the new column type. The [[getColumnType()]] method will be invoked to convert abstract
     * column type (if any) into the physical one. Anything that is not recognized as abstract type will be kept
     * in the generated SQL. For example, 'string' will be turned into 'varchar(255)', while 'string not null'
     * will become 'varchar(255) not null'.
     * @return string the SQL statement for changing the definition of a column.
     * @throws NotSupportedException this is not supported by SQLite
     */
    public function alterColumn($table, $column, $type)
    {
        throw new NotSupportedException(__METHOD__ . ' is not supported by SQLite.');
    }

    /**
     * Builds a SQL statement for adding a primary key constraint to an existing table.
     * @param string $name the name of the primary key constraint.
     * @param string $table the table that the primary key constraint will be added to.
     * @param string|array $columns comma separated string or array of columns that the primary key will consist of.
     * @return string the SQL statement for adding a primary key constraint to an existing table.
     * @throws NotSupportedException this is not supported by SQLite
     */
    public function addPrimaryKey($name, $table, $columns)
    {
        throw new NotSupportedException(__METHOD__ . ' is not supported by SQLite.');
    }

    /**
     * Builds a SQL statement for removing a primary key constraint to an existing table.
     * @param string $name the name of the primary key constraint to be removed.

View on GitHub (pinned to 66f00d18a2)

Solutions

On sqlite, rebuild the table: create a new table with the corrected column, copy data, drop the old one, rename.
Branch in migrations on $this->db->driverName === 'sqlite' and use the rebuild path there.
Catch NotSupportedException in generic migration runners.
Where possible, design the initial CREATE TABLE correctly instead of altering later on sqlite.

Example fix

// before
$this->alterColumn('user', 'name', $this->string(500));

// after
if ($this->db->driverName !== 'sqlite') {
    $this->alterColumn('user', 'name', $this->string(500));
} else {
    $this->execute('CREATE TABLE user_new (id INTEGER PRIMARY KEY AUTOINCREMENT, name VARCHAR(500))');
    $this->execute('INSERT INTO user_new (id, name) SELECT id, name FROM user');
    $this->execute('DROP TABLE user');
    $this->execute('ALTER TABLE user_new RENAME TO user');
}

Defensive patterns

Strategy: try-catch

Validate before calling

if ($db->driverName !== 'sqlite') {
    $db->createCommand()->alterColumn($table, $column, $type)->execute();
} else {
    // SQLite: create new table with corrected DDL, copy data, rename
}

Try / catch

try {
    $db->createCommand()->alterColumn($table, $column, $type)->execute();
} catch (\yii\db\NotSupportedException $e) {
    // SQLite: fall back to the recreate-and-copy rebuild pattern
}

Prevention

Get CREATE TABLE definitions right up front for sqlite-only apps; avoid later column changes.
Implement a reusable sqlite table-rebuild helper instead of ad-hoc SQL.
Test migrations on every driver you ship to, not just production's.

When it happens

Trigger: Running a migration with $this->alterColumn('tbl', 'col', $this->string(500)) or calling $db->createCommand()->alterColumn(...) on a sqlite connection.

Common situations: Test suites using sqlite in-memory databases where a migration alters a column; evolving schemas on lightweight sqlite deployments; up/down migrations shared across drivers.

Related errors

AI-assisted analysis of yiisoft/yii2@66f00d18a2 (2026-08-17). Data as JSON: /api/errors/4a125385af7f4ad7. Report an issue: GitHub.