Manager

Relational Database Schema Manager.

Properties

schemaInfoTable

public string $schemaInfoTable = 'schema_version'

dbi

private Adapter $dbi

config

The configuration array for the manager. This includes database connection details and other settings.

private array $config

workDir

The working directory for the manager. This is where migration files and other internal files are stored.

private string $workDir

migrateDir

The directory where migration files are stored.

private string $migrateDir

versions

The collection of available schema versions. This is populated by reading migration files from the migrate directory.

private array $versions

Each version is represented as a Version object, and the array is indexed by the version number.

currentVersion

The currently applied schema version. This is determined by querying the database for the highest applied version number.

private Version $currentVersion

If no versions have been applied, this will be null.

appliedVersions

The collection of schema versions that have been applied to the database. This is populated by querying the database

private array $appliedVersions

for applied versions. Each version is represented as a Version object, and the array is indexed by the version number. If a version exists in this collection but not in the available versions collection, it is marked as invalid.

missingVersions

The collection of schema versions that are available but have not been applied to the database. This is determined by

private array $missingVersions

comparing the available versions with the applied versions. If a specific version number is provided, this collection will be filtered to include only versions up to that number.

public  $

Methods

__construct

public __construct(?\Closure $logHandler): void

Parameters

Parameter	Type	Description
$logHandler	\Closure

getAdapter

Retrieves the database adapter instance.

public getAdapter(): Adapter

If the adapter is not already set, it will establish a connection first.

getSchemaName

Retrieves the current schema name.

public getSchemaName(): string

This method checks the configuration for a defined schema. If no schema is defined in the configuration, it defaults to 'public'.

getVersions

Gets all the available schema versions from the migration directory.

public getVersions(bool $mergeApplied): void

Parameters

Parameter	Type	Description
$mergeApplied	bool

getVersion

Retrieves a specific version from the internal collection of versions.

public getVersion(int $version): ?Version

This method checks if the requested version key exists in the versions array, returning the associated Version instance if found, or null otherwise.

Parameters

Parameter	Type	Description
$version	int	The version number to look up

getAppliedVersions

Retrieves the list of schema versions that have been applied to the database.

public getAppliedVersions(): void

getAppliedVersion

Retrieves an applied version from the schema information table based on the provided version number.

public getAppliedVersion(int $version): ?Version

If the database connection is not established, it attempts to connect first. Once connected, it searches for the matching version. If no version is found, it returns null; otherwise, it returns the corresponding Version model.

Parameters

Parameter	Type	Description
$version	int	version number to look up

getMissingVersions

Retrieves the list of schema versions that have not been applied to the database.

public getMissingVersions(?int $version): void

Parameters

Parameter	Type	Description
$version	int

getCurrentVersion

Returns the currently applied schema version.

public getCurrentVersion(): ?Version

getLatestVersion

Returns the version number of the latest schema version.

public getLatestVersion(): ?Version

isLatest

Boolean indicator for when the current schema version is the latest.

public isLatest(): bool

hasUpdates

Boolean indicator for when there are migrations that have not been applied.

public hasUpdates(): bool

getSchema

Retrieves a schema based on the specified versions.

public getSchema(bool $allSchema): ?Schema

Determines whether to use all schema versions or only the applied versions, returning a loaded Schema object. If no versions exist, null is returned.

Parameters

Parameter	Type	Description
$allSchema	bool	flag to retrieve all available schema versions or only the applied versions

migrate

Database migration method.

public migrate(?int $version): bool

This method does some fancy database migration magic. It makes use of the 'db' subdirectory in the project directory which should contain the at least a migrate directory that contains schema migrations.

A few things can occur here.

If the database schema does not exist, then a new schema will be created using the current schema. The current

schema is resolved in-memory by loading all the migration files in the migrate directory and applying them in order. This will create the database at the latest version of the schema.

If the database schema already exists, then the function will search for missing versions between the current

schema version and the latest schema version. If no versions are missing, then the function will return false.

If versions are missing, then the function will replay all the missing versions in order to bring the database

schema up to the $version parameter. If no version is requested ($version is NULL) then the latest version number is used.

If the version numbers are different, then a migration will be performed.

# If the requested version is greater than the current version, the migration mode will be 'up'.

# If the requested version is less than the current version, the migration mode will be 'down'.

All migration files between the two selected versions (current and requested) will be replayed using the migration mode.

This process can be used to bring a database schema up to the latest version using database migration files stored in the db/migrate project subdirectory. These migration files are typically created using the \Hazaar\DBI\Manager::snapshot() method although they can be created manually.

The migration is performed in a database transaction (if the database supports it) so that if anything goes wrong there is no damage to the database. If something goes wrong, errors will be available in the migration log accessible with \Hazaar\DBI\Manager::getMigrationLog(). Errors in the migration files can be fixed and the migration retried.

Parameters

Parameter	Type	Description
$version	int	The target version to migrate to. If null, migrates to the latest version.

rollback

Undo a migration version.

public rollback(int $versionNumber): bool

This method rolls back a specific migration version. It first checks if the database interface (DBI) is connected, and if not, it establishes a connection. Then, it retrieves the applied version of the migration. If the version has not been applied, it logs a message and skips the rollback. Otherwise, it performs the rollback using the DBI.

Parameters

Parameter	Type	Description
$versionNumber	int	the version number of the migration to be rolled back

rollbackVersion

public rollbackVersion(Version $version): bool

Parameters

Parameter	Type	Description
$version	Version

replay

Replays the specified version of the database changes.

public replay(int $version): bool

This method ensures that the database connection is established, retrieves the specified version, rolls back the changes of that version, and then replays the changes.

Parameters

Parameter	Type	Description
$version	int	the version number to replay

snapshot

Snapshot the database schema and create a new schema version with migration replay files.

public snapshot(?string $comment, bool $test): bool

This method is used to create the database schema migration files. These files are used by the \Hazaar\Adapter::migrate() method to bring a database up to a certain version. Using this method simplifies creating these migration files and removes the need to create them manually when there are trivial changes.

Current supported database objects and operations are:

Operation	CREATE	ALTER	DROP	RENAME
Extension	X		X
Table	X	X	X	X
Constraint	X		X
Index	X		X
View	X	X	X
Function	X	X	X
Trigger	X	X	X
-----------	--------	-------	------	--------

!!! notice

Table rename detection works by comparing new tables with removed tables for tables that have the same columns. Because of this, rename detection will not work if columns are added or removed at the same time the table is renamed. If you want to rename a table, make sure that this is the only operation being performed on the table for a single snapshot. Modifying other tables will not affect this. If you want to rename a table AND change it's column layout, make sure you do either the rename or the modifications first, then snapshot, then do the other operation before snapshotting again.

Parameters

Parameter	Type	Description
$comment	string	optional comment for the snapshot
$test	bool	if true, the method will only test for changes without saving the snapshot

sync

public sync(?array $dataSchema, bool $force): bool

Parameters

Parameter	Type	Description
$dataSchema	array
$force	bool

checkpoint

Creates a checkpoint in the database.

public checkpoint(?string $comment): bool

This method creates a checkpoint by taking a snapshot of the current master schema and saving it. It also truncates the schema info table and inserts the checkpoint version.

Parameters

Parameter	Type	Description
$comment	string	an optional comment for the checkpoint

deleteEverything

Drops all database objects.

public deleteEverything(): bool

WARNING: This will delete all tables, views, functions, and extensions in the database!

getMigrationLog

Returns the migration log.

public getMigrationLog(): void

Snapshots and migrations are complex processes where many things happen in a single execution. This means stuff can go wrong and you will probably want to know what/why/when they do.

When running \Hazaar\Adapter::snapshot() or \Hazaar\Adapter::migrate() a log of what has been done is stored internally in an array of timestamped messages. You can use the \Hazaar\Adapter::getMigrationLog() method to retrieve this log so that if anything goes wrong, you can see what and fix it/

registerLogHandler

public registerLogHandler(\Closure $handler): void

Parameters

Parameter	Type	Description
$handler	\Closure

migrateDBIFileBackend

public migrateDBIFileBackend(): bool

connect

Connects to the database.

public connect(Adapter $dbi): bool

Parameters

Parameter	Type	Description
$dbi	Adapter

createSchemaVersionTable

Creates the schema version table if it does not already exist.

private createSchemaVersionTable(): bool

This method checks if the schema version table exists in the database. If it does not exist, it creates the table with the following columns:

• number: A bigint that serves as the primary key.
• applied_on: A timestamp with time zone that defaults to the current timestamp.
• comment: A text field that can be null.
• migrate: A jsonb field that can be null.

---

Generated by Hazaar API Doc Generator on Sun, 01 Mar 2026 09:22:25 +0000