Download the PHP package babenkoivan/elastic-migrations without Composer

Elastic Migrations

Elastic Migrations for Laravel allow you to easily modify and share indices schema across the application's environments.

Contents

• Compatibility
• Installation
• Configuration
• Writing Migrations
• Running Migrations
• Reverting Migrations
• Starting Over
• Migration Status
• Zero Downtime Migration
• Troubleshooting

Compatibility

The current version of Elastic Migrations has been tested with the following configuration:

• PHP 8.2
• Elasticsearch 8.x
• Laravel 11.x

If your project uses older Laravel (or PHP) version check the previous major version of the package.

Installation

The library can be installed via Composer:

If you want to use Elastic Migrations with Lumen framework check this guide.

Configuration

Elastic Migrations uses babenkoivan/elastic-client as a dependency. To change the client settings you need to publish the configuration file first:

In the newly created config/elastic.client.php file you can define the default connection name and describe multiple connections using configuration hashes. Please, refer to the elastic-client documentation for more details.

It is recommended to publish Elastic Migrations settings as well:

This will create the config/elastic.migrations.php file, which allows you to configure the following options:

• storage.default_path - the default location of your migration files
• database.table - the table name that holds executed migration names
• database.connection - the database connection you wish to use
• prefixes.index - the prefix of your indices
• prefixes.alias - the prefix of your aliases

If you store some migration files outside the default path and want them to be visible by the package, you may use registerPaths method to inform Elastic Migrations how to load them:

Finally, don't forget to run Laravel database migrations to create Elastic Migrations table:

Writing Migrations

You can effortlessly create a new migration file using an Artisan console command:

Every migration has two methods: up and down. up is used to alternate the index schema and down is used to revert that action.

You can use Elastic\Migrations\Facades\Index facade to perform basic operations over Elasticsearch indices:

Create Index

You can create an index with the default settings:

You can use a modifier to configure mapping and settings:

There is also the createRaw method in your disposal:

Finally, it is possible to create an index only if it doesn't exist:

Update Mapping

You can use a modifier to adjust the mapping:

Alternatively, you can use the putMappingRaw method as follows:

Update Settings

You can use a modifier to change an index configuration:

The same result can be achieved with the putSettingsRaw method:

It is possible to update analysis settings only on closed indices. The pushSettings method closes the index, updates the configuration and opens the index again:

The same can be done with the pushSettingsRaw method:

Drop Index

You can unconditionally delete the index:

or delete it only if it exists:

Create Alias

You can create an alias with optional filter query:

Delete Alias

You can delete an alias by its name:

Multiple Connections

You can configure multiple connections to Elasticsearch in the client's configuration file, and then use a different connection for every operation:

More

Finally, you are free to inject Elastic\Elasticsearch\Client in the migration constructor and execute any supported by client actions.

Running Migrations

You can either run all migrations:

or run a specific one:

Use the --force option if you want to execute migrations on production environment:

Reverting Migrations

You can either revert the last executed migrations:

or rollback a specific one:

Use the elastic:migrate:reset command if you want to revert all previously migrated files:

Starting Over

Sometimes you just want to start over, rollback all the changes and apply them again:

Alternatively you can also drop all existing indices and rerun the migrations:

Note that this command uses wildcards to delete indices. This requires setting action.destructive_requires_name to false.

Migration Status

You can always check which files have been already migrated and what can be reverted by the elastic:migrate:rollback command (the last batch):

It is also possible to display only pending migrations:

Zero Downtime Migration

Changing an index mapping with zero downtime is not a trivial process and might vary from one project to another. Elastic Migrations library doesn't include such feature out of the box, but you can implement it in your project by following this guide.

Troubleshooting

If you see one of the messages below, follow the instructions:

• Migration table is not yet created - run the php artisan migrate command
• Migration directory is not yet created - create a migration file using the elastic:make:migration command or create migrations directory manually

In case one of the commands doesn't work as expected, try to publish configuration: