Download the PHP package restruct/silverstripe-database-migrations without Composer

On this page you can find all versions of the php package restruct/silverstripe-database-migrations. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package silverstripe-database-migrations

SilverStripe Database Migrations

Maintained by Restruct. If this module saves you time, you can support ongoing maintenance.

Database migration utilities for Silverstripe 5 and 6.
Handles table renames, classname value remapping, column renames and table merges during dev/build.

Migrations applied during dev/build

Features

Requirements

Release Branch Silverstripe PHP
0.3 main 5 / 6 8.1+ (8.3+ on Silverstripe 6)
0.1, 0.2 tags only 5 8.1+

composer.json is the source of truth. Silverstripe 5 is supported until its end of life in April 2027; Silverstripe 4 is not supported.

The SQL the module runs (RENAME TABLE, ALTER TABLE ... RENAME COLUMN / CHANGE, UPDATE ... JOIN, SHOW COLUMNS, SHOW CREATE TABLE) is MySQL/MariaDB only.

Installation

The extension is applied automatically to the class that runs dev/build: SilverStripe\ORM\DatabaseAdmin on Silverstripe 5, SilverStripe\Dev\Command\DbBuild on Silverstripe 6. There is nothing to configure until you have something to migrate.

Usage

DataObject Migrations

Add legacy mappings directly to your DataObjects:

Config-based Migrations

For join tables, versioned tables, or other non-DataObject tables:

Config options

All on Restruct\SilverStripe\Migrations\DatabaseMigrationExtension, all default to []:

Option Format Runs
classname_mappings 'Old\Class': 'New\Class' registered before the schema build, applied in the populate phase
table_mappings OldTable: NewTable before the schema build
column_renames Table: { OldColumn: NewColumn } before the schema build
table_merges SourceTable: { target, columns, marker, versioned } after the schema build

A column rename keeps the column's whole definition (type, NULL, default, AUTO_INCREMENT, ON UPDATE, collation, comment): it uses RENAME COLUMN on MySQL 8.0+ / MariaDB 10.5.2+, and on older servers a CHANGE that repeats the definition SHOW CREATE TABLE reports for the column.

On DataObjects, uninherited private static config:

Option Format
legacy_classnames list of old class names that map to this class
legacy_table_names list of old table names to rename to this class's $table_name (requires $table_name on the class itself)

Running Migrations

Table and column migrations run automatically before Silverstripe processes any schema updates. Classname remapping is applied in the populate phase, so a build run without populating (db:build --no-populate on Silverstripe 6) registers the mappings but does not apply them.

How ClassName Remapping Works

SilverStripe stores the fully-qualified class name in a ClassName column for polymorphic queries. When you rename or move a class, existing database records still reference the old class name:

Without remapping, SilverStripe cannot instantiate these records because the old class no longer exists.

What happens during dev/build:

  1. The extension collects mappings from:

    • $legacy_classnames on each DataObject
    • classname_mappings config (for cases where you can't modify the class)
  2. Injects them into Silverstripe's built-in classname_value_remapping config, on the class that runs the build: DatabaseAdmin on Silverstripe 5, DbBuild on Silverstripe 6. (On Silverstripe 6, remapping you configure yourself must be keyed to SilverStripe\Dev\Command\DbBuild too: a SilverStripe\ORM\DatabaseAdmin block is silently ignored there.)

  3. SilverStripe runs UPDATE queries to fix the values:

After remapping:

When to use $legacy_classnames vs classname_mappings config

Use $legacy_classnames on your DataObject when:

Use classname_mappings in YAML config when:

Common use cases:

How Table Migrations Work

The extension hooks into the build's onBeforeBuild (DatabaseAdmin on Silverstripe 5, DbBuild on Silverstripe 6) and renames tables before Silverstripe processes schema updates.

Conflict handling: If both old and new tables exist:

How Table Merges Work

Table merges handle the case where you're consolidating two block types (or similar DataObjects) into one. This is different from a simple rename because the target table already has its own data.

Use case: Merging BlockBanner into BlockHero with a "banner" style variation:

What happens during dev/build:

  1. onBeforeBuild (before schema):

    • ClassName remapping is registered (Silverstripe applies it in the populate phase, after the schema build) -> BlockBanner records end up with ClassName = 'BlockHero'
    • Column renames -> BannerImageID becomes HeroImageID
  2. Schema build (SilverStripe):

    • Creates/updates BlockHero table structure
  3. onAfterBuild (after schema):
    • Table merge:
      • Inserts BlockBanner records that don't exist in BlockHero
      • If no rows needed inserting (every source ID already exists in the target), copies the mapped and same-named columns from source onto the target rows with the same ID. This overwrites the target values, it does not only fill empty ones. It only happens when there is more than one column pair (ID counts as one), so a merge whose only shared column is ID updates nothing.
      • Partial overlap: if some source rows are new and others already exist in the target by ID, the new rows are inserted and the existing target rows are NOT updated at all. The build prints an error-type message naming both tables and the number of rows skipped, e.g. ! TableMerge: BlockBanner -> BlockHero: 3 source row(s) already exist in BlockHero by ID and were NOT updated (existing rows are only updated when a merge inserts nothing). The same rules apply to the _Live table; _Versions rows are only ever inserted (matched on RecordID + Version).
      • Sets Element.Style = 'banner-style' on migrated records
      • Handles _Live and _Versions tables if versioned: true
      • Moves BlockBanner tables to _obsolete_BlockBanner (with counter suffix if already exists)

Marker field: The marker config is useful for:

After Migrations: Cleanup Options

Once migrations have successfully run on all environments (dev, staging, production), you have two options:

Option 1: Remove migration config (recommended for one-time migrations)

After deployment, you can safely remove:

The migrations are idempotent (they check if old tables/values exist before acting), so keeping them has no functional impact. However, removing them:

Option 2: Keep migration config (recommended for distributed systems)

You may want to keep migration config in place when:

Performance impact: Minimal. The extension iterates through DataObject classes once during dev/build to collect mappings. Table/column checks only run if mappings are found, and bail out early if old tables/columns don't exist.

Hybrid approach

Keep migration config during a transition period, then remove it in a future release once all environments are confirmed migrated.

Running the tests

The suite needs a booted Silverstripe app and a MySQL/MariaDB database. Install the module into a host project as a symlinked path repository (/tests is export-ignore, so a Packagist install contains no tests), map Restruct\SilverStripe\Migrations\Tests\ to vendor/restruct/silverstripe-database-migrations/tests/ in the host's autoload-dev, then:

.github/workflows/ci.yml builds exactly such a host for every supported major.

License

MIT, see LICENSE.


All versions of silverstripe-database-migrations with dependencies

PHP Build Version
Package Version
Requires php Version ^8.1
silverstripe/framework Version ^5 || ^6
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package restruct/silverstripe-database-migrations contains the following files

Loading the files please wait ...