DbUpgrade
extends AbstractPlugin
in package
Action helper to perform database upgrades
Tags
Table of Contents
- $adapter : Adapter
- Database adapter
- $dbCommands : array<string|int, mixed>
- Database commands to generate table
- $deprecatedColumns : array<string|int, mixed>
- Deprecated columns, keyed by table name
- $tableInfo : array<string|int, mixed>
- Table metadata
- columnIsMissing() : bool
- Support method for getModifiedColumns() -- check if the current column is in the missing column list so we can avoid modifying something that does not exist.
- constraintIsMissing() : bool
- Support method for getModifiedConstraints() -- check if the current constraint is in the missing constraint list so we can avoid modifying something that does not exist.
- createMissingColumns() : string
- Create missing columns based on the output of getMissingColumns().
- createMissingConstraints() : string
- Create missing constraints based on the output of getMissingConstraints().
- createMissingTables() : string
- Create missing tables based on the output of getMissingTables().
- fixCharsetAndCollationProblems() : string
- Fix character set and collation problems based on the output of getCharsetAndCollationProblems().
- getAdapter() : Adapter
- Get the database adapter.
- getCharsetAndCollationProblems() : array<string|int, mixed>
- Get information on character set and collation problems. Return value is an associative array of table name => correct character set and collation values.
- getDeprecatedColumns() : array<string|int, mixed>
- Get a list of deprecated columns found in the database.
- getMissingColumns() : array<string|int, mixed>
- Get a list of missing columns in the database tables (associative array, key = table name, value = array of missing column definitions).
- getMissingConstraints() : array<string|int, mixed>
- Get a list of missing constraints in the database tables (associative array, key = table name, value = array of missing constraint definitions).
- getMissingTables() : array<string|int, mixed>
- Get a list of missing tables in the database.
- getModifiedColumns() : array<string|int, mixed>
- Get a list of changed columns in the database tables (associative array, key = table name, value = array of column name => new data type).
- getModifiedConstraints() : array<string|int, mixed>
- Get a list of modified constraints in the database tables (associative array, key = table name, value = array of modified constraint definitions).
- getModifiedKeys() : array<string|int, mixed>
- Get a list of modified keys in the database tables (associative array, key = table name, value = array of modified key definitions).
- getTableStatus() : array<string|int, mixed>
- Retrieve (and statically cache) table status information.
- loadSql() : void
- Given a SQL file, parse it for table creation commands.
- query() : string
- Execute a query.
- removeDeprecatedColumns() : string
- Remove deprecated columns based on the output of getDeprecatedColumns().
- setAdapter() : DbUpgrade
- Set a database adapter.
- updateModifiedColumns() : string
- Modify columns based on the output of getModifiedColumns().
- updateModifiedConstraints() : string
- Modify constraints based on the output of getModifiedConstraints().
- updateModifiedKeys() : string
- Update keys based on the output of getModifiedKeys().
- compareConstraintActions() : array<string|int, mixed>
- Compare expected vs. actual constraint actions and return an array of SQL clauses required to create the modified constraints.
- compareConstraints() : array<string|int, mixed>
- Compare expected vs. actual constraints and return an array of SQL clauses required to create the missing constraints.
- defaultMatches() : bool
- Given a current row default, return true if the current default matches the one found in the SQL provided as the $sql parameter. Return false if there is a mismatch that will require table structure updates.
- explodeFields() : array<string|int, mixed>
- Given a field list extracted from a MySQL table definition (e.g. `a`,`b`) return an array of fields (e.g. ['a', 'b']).
- getAllTables() : array<string|int, mixed>
- Get a list of all tables in the database.
- getCharsetAndCollationProblemsForTable() : bool|string
- Check whether the actual table charset and collation match the expected ones; return false if there is no problem, the desired character set and collation otherwise.
- getCharsetAndCollationProblemsForTableColumns() : array<string|int, mixed>
- Support method for getCharsetAndCollationProblemsForTable() -- get column details
- getTableColumns() : array<string|int, mixed>
- Get information on all columns in a table, keyed by column name.
- getTableConstraints() : array<string|int, mixed>
- Get information on all constraints in a table, keyed by type and constraint name. Primary key is double-keyed as ['primary']['primary'] to keep the structure consistent (since primary keys are not explicitly named in the source SQL).
- getTableInfo() : array<string|int, mixed>
- Load table metadata.
- normalizeConstraints() : array<string|int, mixed>
- Normalize constraint values.
- nullableMatches() : bool
- Given a current row default, return true if the current nullability matches the one found in the SQL provided as the $sql parameter. Return false if there is a mismatch that will require table structure updates.
- parseKeysFromCreateTable() : array<string|int, mixed>
- Parse keys from a "create table" statement
- typeMatches() : bool
- Given a table column object, return true if the object's type matches the specified $type parameter. Return false if there is a mismatch that will require table structure updates.
Properties
$adapter
Database adapter
protected
Adapter
$adapter
$dbCommands
Database commands to generate table
protected
array<string|int, mixed>
$dbCommands
= []
$deprecatedColumns
Deprecated columns, keyed by table name
protected
array<string|int, mixed>
$deprecatedColumns
= ['search' => ['folder_id']]
$tableInfo
Table metadata
protected
array<string|int, mixed>
$tableInfo
= false
Methods
columnIsMissing()
Support method for getModifiedColumns() -- check if the current column is in the missing column list so we can avoid modifying something that does not exist.
public
columnIsMissing(string $column, array<string|int, mixed> $missing) : bool
Parameters
- $column : string
-
Column to check
- $missing : array<string|int, mixed>
-
Missing column list for column's table.
Return values
bool —constraintIsMissing()
Support method for getModifiedConstraints() -- check if the current constraint is in the missing constraint list so we can avoid modifying something that does not exist.
public
constraintIsMissing(string $constraint, array<string|int, mixed> $missing) : bool
Parameters
- $constraint : string
-
Column to check
- $missing : array<string|int, mixed>
-
Missing constraint list for constraint's table.
Return values
bool —createMissingColumns()
Create missing columns based on the output of getMissingColumns().
public
createMissingColumns(array<string|int, mixed> $columns[, bool $logsql = false ]) : string
Parameters
- $columns : array<string|int, mixed>
-
Output of getMissingColumns()
- $logsql : bool = false
-
Should we return the SQL as a string rather than execute it?
Tags
Return values
string —SQL if $logsql is true, empty string otherwise
createMissingConstraints()
Create missing constraints based on the output of getMissingConstraints().
public
createMissingConstraints(array<string|int, mixed> $constraints[, bool $logsql = false ]) : string
Parameters
- $constraints : array<string|int, mixed>
-
Output of getMissingConstraints()
- $logsql : bool = false
-
Should we return the SQL as a string rather than execute it?
Tags
Return values
string —SQL if $logsql is true, empty string otherwise
createMissingTables()
Create missing tables based on the output of getMissingTables().
public
createMissingTables(array<string|int, mixed> $tables[, bool $logsql = false ]) : string
Parameters
- $tables : array<string|int, mixed>
-
Output of getMissingTables()
- $logsql : bool = false
-
Should we return the SQL as a string rather than execute it?
Tags
Return values
string —SQL if $logsql is true, empty string otherwise
fixCharsetAndCollationProblems()
Fix character set and collation problems based on the output of getCharsetAndCollationProblems().
public
fixCharsetAndCollationProblems(array<string|int, mixed> $tables[, bool $logsql = false ]) : string
Parameters
- $tables : array<string|int, mixed>
-
Output of getCharsetAndCollationProblems()
- $logsql : bool = false
-
Should we return the SQL as a string rather than execute it?
Tags
Return values
string —SQL if $logsql is true, empty string otherwise
getAdapter()
Get the database adapter.
public
getAdapter() : Adapter
Return values
Adapter —getCharsetAndCollationProblems()
Get information on character set and collation problems. Return value is an associative array of table name => correct character set and collation values.
public
getCharsetAndCollationProblems() : array<string|int, mixed>
Tags
Return values
array<string|int, mixed> —getDeprecatedColumns()
Get a list of deprecated columns found in the database.
public
getDeprecatedColumns() : array<string|int, mixed>
Return values
array<string|int, mixed> —getMissingColumns()
Get a list of missing columns in the database tables (associative array, key = table name, value = array of missing column definitions).
public
getMissingColumns([array<string|int, mixed> $missingTables = [] ]) : array<string|int, mixed>
Parameters
- $missingTables : array<string|int, mixed> = []
-
List of missing tables
Tags
Return values
array<string|int, mixed> —getMissingConstraints()
Get a list of missing constraints in the database tables (associative array, key = table name, value = array of missing constraint definitions).
public
getMissingConstraints([array<string|int, mixed> $missingTables = [] ]) : array<string|int, mixed>
Parameters
- $missingTables : array<string|int, mixed> = []
-
List of missing tables
Tags
Return values
array<string|int, mixed> —getMissingTables()
Get a list of missing tables in the database.
public
getMissingTables() : array<string|int, mixed>
Tags
Return values
array<string|int, mixed> —getModifiedColumns()
Get a list of changed columns in the database tables (associative array, key = table name, value = array of column name => new data type).
public
getModifiedColumns([array<string|int, mixed> $missingTables = [] ][, array<string|int, mixed> $missingColumns = [] ]) : array<string|int, mixed>
Parameters
- $missingTables : array<string|int, mixed> = []
-
List of missing tables
- $missingColumns : array<string|int, mixed> = []
-
List of missing columns
Tags
Return values
array<string|int, mixed> —getModifiedConstraints()
Get a list of modified constraints in the database tables (associative array, key = table name, value = array of modified constraint definitions).
public
getModifiedConstraints([array<string|int, mixed> $missingTables = [] ][, array<string|int, mixed> $missingConstraints = [] ]) : array<string|int, mixed>
Parameters
- $missingTables : array<string|int, mixed> = []
-
List of missing tables
- $missingConstraints : array<string|int, mixed> = []
-
List of missing constraints
Tags
Return values
array<string|int, mixed> —getModifiedKeys()
Get a list of modified keys in the database tables (associative array, key = table name, value = array of modified key definitions).
public
getModifiedKeys([array<string|int, mixed> $missingTables = [] ]) : array<string|int, mixed>
Parameters
- $missingTables : array<string|int, mixed> = []
-
List of missing tables
Tags
Return values
array<string|int, mixed> —getTableStatus()
Retrieve (and statically cache) table status information.
public
getTableStatus() : array<string|int, mixed>
Return values
array<string|int, mixed> —loadSql()
Given a SQL file, parse it for table creation commands.
public
loadSql(string $file) : void
Parameters
- $file : string
-
Filename to load.
Return values
void —query()
Execute a query.
public
query(string $sql, bool $logsql) : string
Parameters
- $sql : string
-
SQL to run
- $logsql : bool
-
Should we return the SQL as a string rather than execute it?
Return values
string —SQL if $logsql is true, empty string otherwise
removeDeprecatedColumns()
Remove deprecated columns based on the output of getDeprecatedColumns().
public
removeDeprecatedColumns(array<string|int, mixed> $details[, bool $logsql = false ]) : string
Parameters
- $details : array<string|int, mixed>
-
Output of getDeprecatedColumns()
- $logsql : bool = false
-
Should we return the SQL as a string rather than execute it?
Tags
Return values
string —SQL if $logsql is true, empty string otherwise
setAdapter()
Set a database adapter.
public
setAdapter(Adapter $adapter) : DbUpgrade
Parameters
- $adapter : Adapter
-
Adapter to set
Return values
DbUpgrade —updateModifiedColumns()
Modify columns based on the output of getModifiedColumns().
public
updateModifiedColumns(array<string|int, mixed> $columns[, bool $logsql = false ]) : string
Parameters
- $columns : array<string|int, mixed>
-
Output of getModifiedColumns()
- $logsql : bool = false
-
Should we return the SQL as a string rather than execute it?
Tags
Return values
string —SQL if $logsql is true, empty string otherwise
updateModifiedConstraints()
Modify constraints based on the output of getModifiedConstraints().
public
updateModifiedConstraints(array<string|int, mixed> $constraints[, bool $logsql = false ]) : string
Parameters
- $constraints : array<string|int, mixed>
-
Output of getModifiedConstraints()
- $logsql : bool = false
-
Should we return the SQL as a string rather than execute it?
Tags
Return values
string —SQL if $logsql is true, empty string otherwise
updateModifiedKeys()
Update keys based on the output of getModifiedKeys().
public
updateModifiedKeys(array<string|int, mixed> $tables[, bool $logsql = false ]) : string
Parameters
- $tables : array<string|int, mixed>
-
Output of getModifiedKeys()
- $logsql : bool = false
-
Should we return the SQL as a string rather than execute it?
Tags
Return values
string —SQL if $logsql is true, empty string otherwise
compareConstraintActions()
Compare expected vs. actual constraint actions and return an array of SQL clauses required to create the modified constraints.
protected
compareConstraintActions(array<string|int, mixed> $expected, array<string|int, mixed> $actual) : array<string|int, mixed>
Parameters
- $expected : array<string|int, mixed>
-
Expected constraints (based on mysql.sql)
- $actual : array<string|int, mixed>
-
Actual constraints (pulled from database metadata)
Return values
array<string|int, mixed> —compareConstraints()
Compare expected vs. actual constraints and return an array of SQL clauses required to create the missing constraints.
protected
compareConstraints(array<string|int, mixed> $expected, array<string|int, mixed> $actual) : array<string|int, mixed>
Parameters
- $expected : array<string|int, mixed>
-
Expected constraints (based on mysql.sql)
- $actual : array<string|int, mixed>
-
Actual constraints (pulled from database metadata)
Return values
array<string|int, mixed> —defaultMatches()
Given a current row default, return true if the current default matches the one found in the SQL provided as the $sql parameter. Return false if there is a mismatch that will require table structure updates.
protected
defaultMatches(string $currentDefault, string $sql) : bool
Parameters
- $currentDefault : string
-
Object to check
- $sql : string
-
SQL to compare against
Return values
bool —explodeFields()
Given a field list extracted from a MySQL table definition (e.g. `a`,`b`) return an array of fields (e.g. ['a', 'b']).
protected
explodeFields(string $fields) : array<string|int, mixed>
Parameters
- $fields : string
-
Field list
Return values
array<string|int, mixed> —getAllTables()
Get a list of all tables in the database.
protected
getAllTables() : array<string|int, mixed>
Tags
Return values
array<string|int, mixed> —getCharsetAndCollationProblemsForTable()
Check whether the actual table charset and collation match the expected ones; return false if there is no problem, the desired character set and collation otherwise.
protected
getCharsetAndCollationProblemsForTable(array<string|int, mixed> $table) : bool|string
Parameters
- $table : array<string|int, mixed>
-
Information about a table (from getTableStatus())
Return values
bool|string —getCharsetAndCollationProblemsForTableColumns()
Support method for getCharsetAndCollationProblemsForTable() -- get column details
protected
getCharsetAndCollationProblemsForTableColumns(string $table, string $collation) : array<string|int, mixed>
Parameters
- $table : string
-
Table to check
- $collation : string
-
The desired collation
Tags
Return values
array<string|int, mixed> —getTableColumns()
Get information on all columns in a table, keyed by column name.
protected
getTableColumns(string $table) : array<string|int, mixed>
Parameters
- $table : string
-
Table to describe.
Tags
Return values
array<string|int, mixed> —getTableConstraints()
Get information on all constraints in a table, keyed by type and constraint name. Primary key is double-keyed as ['primary']['primary'] to keep the structure consistent (since primary keys are not explicitly named in the source SQL).
protected
getTableConstraints(string $table) : array<string|int, mixed>
Parameters
- $table : string
-
Table to describe.
Tags
Return values
array<string|int, mixed> —getTableInfo()
Load table metadata.
protected
getTableInfo([bool $reload = false ]) : array<string|int, mixed>
Parameters
- $reload : bool = false
-
Force a reload? (Default is false).
Return values
array<string|int, mixed> —normalizeConstraints()
Normalize constraint values.
protected
normalizeConstraints(array<string|int, mixed> $constraints) : array<string|int, mixed>
Parameters
- $constraints : array<string|int, mixed>
-
Constraints to normalize
Return values
array<string|int, mixed> —nullableMatches()
Given a current row default, return true if the current nullability matches the one found in the SQL provided as the $sql parameter. Return false if there is a mismatch that will require table structure updates.
protected
nullableMatches(bool $currentNullable, string $sql) : bool
Parameters
- $currentNullable : bool
-
Current nullability
- $sql : string
-
SQL to compare against
Return values
bool —parseKeysFromCreateTable()
Parse keys from a "create table" statement
protected
parseKeysFromCreateTable(string $createSql) : array<string|int, mixed>
Parameters
- $createSql : string
-
Create table statement
Return values
array<string|int, mixed> —typeMatches()
Given a table column object, return true if the object's type matches the specified $type parameter. Return false if there is a mismatch that will require table structure updates.
protected
typeMatches(ColumnObject $column, string $expectedType) : bool
Parameters
- $column : ColumnObject
-
Object to check
- $expectedType : string
-
Type to compare