Overview of Contember Migrations

Contember is a powerful platform that simplifies the development of content-driven applications. One of its core features is the ability to handle database schema changes over time through migrations. Migrations in Contember are crucial for maintaining consistency and functionality as your application evolves.

Types of Migrations

There are primarily two types of migrations in Contember:

Schema Migrations: These migrations deal with changes in the database schema, such as adding or removing tables, columns, or relationships.
Content Migrations: These migrations handle changes in the content stored in the database. This could involve transforming data, populating new fields, or cleaning up old data.

Both types of migrations ensure that changes to the application’s database are carried out systematically, safely, and can be replicated across different environments.

CLI Commands

Contember provides a set of Command Line Interface (CLI) commands to facilitate the migration process. These commands help developers to generate, apply, describe, and manage migrations efficiently. Some of the basic commands include:

migrations:diff: Generates a new migration based on the differences between the current schema and the existing database structure.
migrations:execute: Applies pending migrations.
migrations:describe: Provides a detailed description of a specific migration.
migrations:init-state: Enables schema state mode for an existing project.

Note

To execute migrations, you need appropriate permissions.

Every schema change is tracked

In Contember, every change made to the schema is tracked so that it can be applied consistently across all environments. This keeps changes reversible and helps maintain the integrity of the application and its data.

By default, schema changes — including changes to the Access Control List (ACL), validation, actions and settings — are tracked through schema migrations. The non-model parts of the schema can alternatively be managed through schema state mode, which stores ACL, validation, actions and settings as JSON files in a state/ directory instead of as migrations. New projects use this mode by default.

In the following sections of this documentation, we will delve deeper into each aspect of migrations, providing you with the knowledge and tools you need to manage your Contember application successfully.

Migration constraints

Contember includes constraints to prevent database inconsistencies. Namely:

you can't change content of executed migration
you can't execute a migration, which precedes already executed migration

Therefore, you should:

never modify or delete a migration, which has been executed on live environment,
ensure, that new migration is always last (e.g. when merging a branch).