Manager

Relational Database Schema Manager.

Constants

MACRO_VARIABLE

public const MACRO_VARIABLE = 1

MACRO_LOOKUP

public const MACRO_LOOKUP = 2

Properties

schemaInfoTable

public string $schemaInfoTable = 'schema_version'

dbi

private Adapter $dbi

config

private array $config

workDir

private string $workDir

migrateDir

private string $migrateDir

versions

private array $versions

currentVersion

private Version $currentVersion

appliedVersions

private array $appliedVersions

missingVersions

private array $missingVersions

public  $

Methods

__construct

public __construct(array $dbiConfig, ?\Closure $logHandler): void

Parameters

Parameter	Type	Description
$dbiConfig	array
$logHandler	\Closure

getAdapter

Retrieves the database adapter instance.

public getAdapter(): Adapter

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

getVersions

Gets all the available schema versions from the migration directory.

public getVersions(bool $mergeApplied = false): 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 = false): ?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 = false): 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 = false): 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

connect

Connects to the database.

private connect(?array $config): bool

Parameters

Parameter	Type	Description
$config	array	The database configuration

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