WireDatabaseBackup::preflight() method

Find data in this (MySQL) database that another database type would reject or change, before copying it there

Moving a site to another database (by a profile export, or a backup restored there) copies its rows as they are. PostgreSQL rejects some values MySQL holds, and a restore stops at the first. This reports them first, so that they can be fixed on the MySQL site:

  • range (error): values out of range of the column's PostgreSQL type, which keeps no UNSIGNED, i.e. INT UNSIGNED over 2147483647 (PostgreSQL integer), SMALLINT UNSIGNED over 32767, BIGINT UNSIGNED over 9223372036854775807.
  • nul (error): NUL bytes in text columns, which PostgreSQL text cannot hold (BLOB columns are bytea, and may).
  • charset (warning): non-ASCII text in columns whose character set is not UTF-8 (i.e. latin1). They are converted to UTF-8 when copied, which is right unless they hold UTF-8 already, as on many older sites: those rows come out double-encoded ("é" for "é").

Invalid UTF-8 is not checked: MySQL does not store it in UTF-8 columns (strict mode rejects it and other modes replace it), and other character sets are converted to valid UTF-8 when read. SQLite stores all of the above.

Available since version 3.0.274.

Example

foreach($database->backups()->preflight('pgsql') as $finding) {
  echo "$finding[level]: $finding[message]\n";
}

Usage

// basic usage
$array = $backup->preflight();

// usage with all arguments
$array = $backup->preflight(string $dbType = 'pgsql', array $options = []);

Arguments

NameType(s)Description
$dbType (optional)string

Database type the data will be copied to: 'pgsql' or 'sqlite' (or 'mysql')

$options (optional)array
  • tables (array): check only these tables Default: all tables

Return value

array

Findings, each [ 'table', 'column', 'check' => 'range', 'nul' or 'charset', 'level' => 'error' or 'warning', 'rows' => number of rows, 'example' => [ primary key column => value ] of one of them (or null), 'message' ]

Exceptions

Method can throw exceptions on error:

  • \Exception - If this database is not MySQL

$backup methods and properties

API reference based on ProcessWire core version 3.0.275