README

This extension provides a CLI for doctrine migrations to manage database migrations in TYPO3. Migrations are defined in versioned files, which can be created and executed via the CLI.

Installation (Composer)

Add the extension by executing composer req itx/doctrine-migrations
Create a folder e.g. Classes/Migrations inside your extension's folder
In the TYPO3 Backend, add the path where you want to save your version files and the appropriate namespace at Settings > Extension Configuration > doctrine_migrations
Alternatively you can configure these paths inside your additional.php file e.g.

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['doctrine_migrations']['migrationFilesLocation'] = 'EXT:your_extension/Migrations';
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['doctrine_migrations']['migrationFilesNamespace'] = 'YourVendor\YourExtension\Migrations';

Optionally you can override the default doctrine migrations configuration by providing an array like so in your additional.php file:

$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['doctrine_migrations']['overrideConfiguration'] = [
	'table_storage' => [
			'table_name' => 'different_table_name_xyz',
	],
];

Usage

The extension is controlled via CLI
You can use commands with vendor/bin/typo3 migrations:<command> <option>

Walkthrough

Creating a version file

To generate a version file at your chosen location, use vendor/bin/typo3 migrations:generate
The created file is named Version{date}, {date} being its' time of creation in YmdHis format
This file comes with three pregenerated, empty functions: getDescription(), up() and down()
Enter the necessary SQL Code for your desired migration into the up() function, and the code which can revert the migration into the down() function like this: $this->addSql('<your sql goes here>');
Take care to escape any single quotes inside the addSql() function

Working with version files

vendor/bin/typo3 migrations:status show the current status of the migrations: which version is currently in use, which is previous/next/latest one etc.
Once you have a migration file prepared with the desired changes to your database, you can execute it by running either:
- vendor/bin/typo3 migrations:migrate to automatically run every version file from your current state to the latest one, or
- vendor/bin/typo3 migrations:execute "Path\To\Your\File" --up to only run the up() method of your selected version file
- Using --down instead of --up in the above command executes the version file's down() function instead
Alternatively, you can use the keywords first, latest, prev or next after vendor/bin/typo3 migrations:migrate to migrate to the first, latest, previous or next migration file respectively
For more information on these and some more commands and their options refer to this

Troubleshooting

If you get permission errors while trying to save your modified version files, try running chmod g+w -R * in the container bash

Further Info

For more information on doctrine migrations, refer to the official doctrine documentation

itx / doctrine-migrations

Maintainers

Details