Migration
The contract of a versioned migration — one concrete subclass per evolution, named `Version<timestamp>_<Label>` and stored in the host project's migrations folder.
A migration is imperative (unlike the declarative structure handled by
doctor): it transforms data already in the database, an operation that
cannot be expressed as configuration. Subclasses implement up()
(mandatory) and optionally down() (the rollback); the engine never
guesses their content — migrate --create only generates the empty shell.
The façade ($db) and the low-level client are both reachable, plus a small toolbox of common operations (renameField() / dropField() / setDefault()) so routine migrations read as intent rather than raw AQL. For anything beyond the toolbox, query() runs arbitrary AQL.
class Version20260612090000_DescriptionMultilingue extends Migration
{
public function description() : string { return 'description → { fr, en }' ; }
public function up() : void
{
$this->query( 'FOR doc IN places FILTER TYPENAME(doc.description) == "string"
UPDATE doc WITH { description: { fr: doc.description, en: null } } IN places' ) ;
}
}
Tags
Table of Contents
Properties
Methods
- __construct() : mixed
- description() : string
- A one-line human description of what the migration does — shown in the `--status` table and stored on the tracking document. Defaults to the class short name.
- down() : void
- Reverts the migration (the rollback of {@see up()}). Optional — the default is a no-op, which makes the version irreversible: `--down` skips it. Implement it when the change can be undone.
- up() : void
- Applies the migration. Mandatory — this is the whole point of the version. Throwing aborts the run and marks the version `failed`.
- dropField() : void
- Removes a top-level attribute from every document of a collection — see {@see helpers\dropFieldQuery()}.
- query() : Cursor
- Runs an arbitrary AQL query — the escape hatch for anything the toolbox does not cover.
- renameField() : void
- Renames a top-level attribute on every document of a collection — see {@see helpers\renameFieldQuery()}.
- setDefault() : void
- Backfills a default value where a field is missing or `null` — see {@see helpers\setDefaultQuery()}.
Properties
$db
protected
ArangoDB
$db
Methods
__construct()
public
__construct(ArangoDB $db) : mixed
Parameters
- $db : ArangoDB
-
The façade — gives the migration the AQL access (via query()), the collection CRUD and the doctor primitives (collectionDrop, indexesSync, viewSync, …).
description()
A one-line human description of what the migration does — shown in the `--status` table and stored on the tracking document. Defaults to the class short name.
public
description() : string
Return values
stringdown()
Reverts the migration (the rollback of {@see up()}). Optional — the default is a no-op, which makes the version irreversible: `--down` skips it. Implement it when the change can be undone.
public
down() : void
up()
Applies the migration. Mandatory — this is the whole point of the version. Throwing aborts the run and marks the version `failed`.
public
abstract up() : void
dropField()
Removes a top-level attribute from every document of a collection — see {@see helpers\dropFieldQuery()}.
protected
dropField(string $collection, string $field) : void
Parameters
- $collection : string
-
The collection name.
- $field : string
-
The attribute to remove.
Tags
query()
Runs an arbitrary AQL query — the escape hatch for anything the toolbox does not cover.
protected
query(string $aql[, array<string, mixed> $bindVars = [] ]) : Cursor
Parameters
- $aql : string
-
The AQL query.
- $bindVars : array<string, mixed> = []
-
Bind variables.
Tags
Return values
CursorrenameField()
Renames a top-level attribute on every document of a collection — see {@see helpers\renameFieldQuery()}.
protected
renameField(string $collection, string $from, string $to) : void
Parameters
- $collection : string
-
The collection name.
- $from : string
-
The current attribute name.
- $to : string
-
The new attribute name.
Tags
setDefault()
Backfills a default value where a field is missing or `null` — see {@see helpers\setDefaultQuery()}.
protected
setDefault(string $collection, string $field, mixed $value) : void
Parameters
- $collection : string
-
The collection name.
- $field : string
-
The attribute to backfill.
- $value : mixed
-
The default value.