Docs

This documentation is a work in progress on hiatus, and likely to change, especially since the add-on is still in development may never be released.

Trek is a new add-on from BoldMinded that is currently in development. In short, it is a migrations add-on. Install it in your development or staging environment and manage your site like you normally do. Create new users, new entries, categories, update entries, categories, site settings, and almost anything else. Then when you're ready to push those changes to your production site, simply press a button and Trek migrates those changes to a remote environment.

License Agreement

Trek is a complicated add-on, as such, you should read the License Agreement before use.

How does it work?

Simple answer: it records all insert, update, delete, and alter queries performed on your database, then replays those queries in the same order on a remote environment.

Long answer: it records queries to migration files. Each save, update, or delete action taken in ExpressionEngine's control panel is saved to a single migration. Multiple migrations can be grouped into Releases, then you an run a release, which executes a batch of queries, on a remote environment. For most actions in the control panel it utilizes existing ExpressionEngine model hooks, so even if another 3rd party add-on updates an entry programmatically using ExpressionEngine's Entry model, the migration will be recorded. A small number of events that do not use models are also recorded. You can inspect Treks Config/settings.php file for more details on those actions.

Releases

You can't start a release, pause it, then start a different release, pause it, and start the original release again. This sequence will create queries that will not be replaced on remote environments in the same order, thus it may have disastrous effects on your site. For this reason, only a single release can ever be active at a given time. Once you finish a release you can only restart if if there is no other active release. Once a different new release has been started, the previous release will be locked into it's last state.

Upcoming

An upcoming release is one that you have created and is in queue for recording migrations to. It is common in software development to plan ahead for major releases or updates. An upcoming release is just a place holder for future work. For example, you know you have specific upcoming features planned, such as a release to support a holiday, or launching a new product or section of your site. After a release is created, no action is taken on it until you set it to Active. You can activate an upcoming release in any order, regardless of when you created it.

Active

Trek requires that you always have an active release, and you can only have 1 release in the active state at a time. This is the release that migrations are actively being recorded to. You can finish an active release at any time. When you finish an active the release you will not be permitted to take any further actions in the ExpressionEngine control panel until you start a new release. This is because all actions need to be time blocked within a releases start and finish time. You can re-activate the most recently finished release if you accidentally finished it too early, but only if there is no other active release.

Finished

A finished release is one that has a start and finish date, and is not currently active. Migrations have been recorded to it, and it is waiting to be released to a remote environment. You can have muliple finished releases in queue, but you can only release them to remote environments in the order of their start and end date. Releases are always linear and sequential.

Migrations

A migration is a single file that can contain multiple queries. Every time you save an entry, update a member's profile, or add a new category, multiple queries are executed to make those changes. Each of those queries is saved to a migration file. A migration is basically a single event or action taken in ExpressionEngine's control panel. It usually contains a single POST action, and whatever queries are performed during that POST request lifecycle.

Environments

Trek supports any number of remote environments. Each environment assumes a single database connection (multiple database connections may be supported in the future).

Backups

Trek provides a method of backing up a remote database prior to running a release on it. By default, when you run a release, and before the migrations in that release are exected on a remote database, Trek will create a local backup of that database. You can optionally disable backups before releases. In the event something goes wrong, Trek will not restore a full database from a backup. You will need to do that manually. However, Trek does use database transactions when executing a migration. In the event a query in a migration fails to execute on a remote environment it will issue a rollback command for every query executed up to the point of the failed query, which shouldn't leave you in a broken, half released state. Any errors should be logged to ExpressionEngine's Developer Log. If upon inspecting the error message you can not manually repair the situation, it may be necessary to manually restore the database from a backup file.

3rd party Add-on Support

In most cases, no additional support is required if you are an add-on developer. The migrate['postActions'] array will capture any POST events in your add-ons settings pages and record them as a migration. If you maintain a custom fieldtype, or create a custom fieldtype for your site, it will be included in the ChannelEntry model updates, and thus recorded as a migration.