PHPackages                             babenkoivan/elastic-migrations - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Search & Filtering](/categories/search)
4. /
5. babenkoivan/elastic-migrations

ActiveLibrary[Search & Filtering](/categories/search)

babenkoivan/elastic-migrations
==============================

Elasticsearch migrations for Laravel

v5.0.0(6mo ago)1962.5M—6.8%366MITPHPPHP ^8.2CI passing

Since May 1Pushed 2mo ago2 watchersCompare

[ Source](https://github.com/babenkoivan/elastic-migrations)[ Packagist](https://packagist.org/packages/babenkoivan/elastic-migrations)[ Fund](https://ko-fi.com/ivanbabenko)[ Fund](https://paypal.me/babenkoi)[ RSS](/packages/babenkoivan-elastic-migrations/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (6)Versions (29)Used By (6)

Elastic Migrations
==================

[](#elastic-migrations)

[![Latest Stable Version](https://camo.githubusercontent.com/bbc5665c2dbb4ac1ca14df69f932c564af70de6c351ca4e53b49e7c775481ff5/68747470733a2f2f706f7365722e707567782e6f72672f626162656e6b6f6976616e2f656c61737469632d6d6967726174696f6e732f762f737461626c65)](https://packagist.org/packages/babenkoivan/elastic-migrations)[![Total Downloads](https://camo.githubusercontent.com/d4bdd5059ee37ff0fcbfefbf9e0ef164212ed28a75f637f94e641ca7dea5250a/68747470733a2f2f706f7365722e707567782e6f72672f626162656e6b6f6976616e2f656c61737469632d6d6967726174696f6e732f646f776e6c6f616473)](https://packagist.org/packages/babenkoivan/elastic-migrations)[![License](https://camo.githubusercontent.com/53a3fc344d478a37bc06195bb3f2377cc6633ba8280b246e9ae20c1130a90dfa/68747470733a2f2f706f7365722e707567782e6f72672f626162656e6b6f6976616e2f656c61737469632d6d6967726174696f6e732f6c6963656e7365)](https://packagist.org/packages/babenkoivan/elastic-migrations)[![Tests](https://github.com/babenkoivan/elastic-migrations/workflows/Tests/badge.svg)](https://github.com/babenkoivan/elastic-migrations/actions?query=workflow%3ATests)[![Code style](https://github.com/babenkoivan/elastic-migrations/workflows/Code%20style/badge.svg)](https://github.com/babenkoivan/elastic-migrations/actions?query=workflow%3A%22Code+style%22)[![Static analysis](https://github.com/babenkoivan/elastic-migrations/workflows/Static%20analysis/badge.svg)](https://github.com/babenkoivan/elastic-migrations/actions?query=workflow%3A%22Static+analysis%22)[![Donate PayPal](https://camo.githubusercontent.com/0b8a275d67dfb2aa74ac299fa07b7fce95217f6620448d88cf05ff9e3653e9bf/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f646f6e6174652d70617970616c2d626c7565)](https://paypal.me/babenkoi)

 [![Support the project!](https://camo.githubusercontent.com/201ef269611db7eb6b5d08e9f756ab8980df3014b64492770bdf13a6ed924641/68747470733a2f2f6b6f2d66692e636f6d2f696d672f676974687562627574746f6e5f736d2e737667)](https://ko-fi.com/ivanbabenko)

---

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

Contents
--------

[](#contents)

- [Compatibility](#compatibility)
- [Installation](#installation)
- [Configuration](#configuration)
- [Writing Migrations](#writing-migrations)
- [Running Migrations](#running-migrations)
- [Reverting Migrations](#reverting-migrations)
- [Starting Over](#starting-over)
- [Migration Status](#migration-status)
- [Zero Downtime Migration](#zero-downtime-migration)
- [Troubleshooting](#migration-status)

Compatibility
-------------

[](#compatibility)

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

- PHP 8.2
- Elasticsearch 9.x
- Laravel 12.x

If your project uses older Elasticsearch, Laravel, or PHP version check [the previous major version](https://github.com/babenkoivan/elastic-migrations/tree/v4.0.1#compatibility) of the package.

Installation
------------

[](#installation)

The library can be installed via Composer:

```
composer require babenkoivan/elastic-migrations
```

If you want to use Elastic Migrations with [Lumen framework](https://lumen.laravel.com/) check [this guide](https://github.com/babenkoivan/elastic-migrations/wiki/Lumen-Installation).

Configuration
-------------

[](#configuration)

Elastic Migrations uses [babenkoivan/elastic-client](https://github.com/babenkoivan/elastic-client) as a dependency. To change the client settings you need to publish the configuration file first:

```
php artisan vendor:publish --provider="Elastic\Client\ServiceProvider"
```

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](https://github.com/babenkoivan/elastic-client) for more details.

It is recommended to publish Elastic Migrations settings as well:

```
php artisan vendor:publish --provider="Elastic\Migrations\ServiceProvider"
```

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:

```
class MyAppServiceProvider extends Illuminate\Support\ServiceProvider
{
    public function boot()
    {
        resolve(MigrationStorage::class)->registerPaths([
            '/my_app/elastic/migrations1',
            '/my_app/elastic/migrations2',
        ]);
    }
}
```

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

```
php artisan migrate
```

Writing Migrations
------------------

[](#writing-migrations)

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

```
// create a migration file with "create_my_index.php" name in the default directory
php artisan elastic:make:migration create_my_index

// create a migration file with "create_my_index.php" name in "/my_path" directory
// note, that you need to specify the full path to the file in this case
php artisan elastic:make:migration /my_path/create_my_index.php
```

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

[](#create-index)

You can create an index with the default settings:

```
Index::create('my-index');
```

You can use a modifier to configure mapping and settings:

```
Index::create('my-index', function (Mapping $mapping, Settings $settings) {
    // to add a new field to the mapping use method name as a field type (in Camel Case),
    // first argument as a field name and optional second argument for additional field parameters
    $mapping->text('title', ['boost' => 2]);
    $mapping->float('price');

    // you can define a dynamic template as follows
    $mapping->dynamicTemplate('my_template_name', [
        'match_mapping_type' => 'long',
        'mapping' => [
            'type' => 'integer',
        ],
    ]);

    // you can also change the index settings and the analysis configuration
    $settings->index([
         'number_of_replicas' => 2,
         'refresh_interval' => -1
    ]);

    $settings->analysis([
        'analyzer' => [
            'title' => [
                'type' => 'custom',
                'tokenizer' => 'whitespace'
            ]
        ]
    ]);
});
```

There is also the `createRaw` method in your disposal:

```
$mapping = [
    'properties' => [
        'title' => [
            'type' => 'text'
        ]
    ]
];

$settings = [
    'number_of_replicas' => 2
];

Index::createRaw('my-index', $mapping, $settings);
```

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

```
// you can use a modifier as shown above
Index::createIfNotExists('my-index', $modifier);
// or you can use raw mapping and settings
Index::createIfNotExistsRaw('my-index', $mapping, $settings);
```

#### Update Mapping

[](#update-mapping)

You can use a modifier to adjust the mapping:

```
Index::putMapping('my-index', function (Mapping $mapping) {
    $mapping->text('title', ['boost' => 2]);
    $mapping->float('price');
});
```

Alternatively, you can use the `putMappingRaw` method as follows:

```
Index::putMappingRaw('my-index', [
    'properties' => [
        'title' => [
            'type' => 'text',
            'boost' => 2
        ],
        'price' => [
            'price' => 'float'
        ]
    ]
]);
```

#### Update Settings

[](#update-settings)

You can use a modifier to change an index configuration:

```
Index::putSettings('my-index', function (Settings $settings) {
    $settings->index([
         'number_of_replicas' => 2,
         'refresh_interval' => -1
    ]);
});
```

The same result can be achieved with the `putSettingsRaw` method:

```
Index::putSettingsRaw('my-index', [
    'index' => [
        'number_of_replicas' => 2,
        'refresh_interval' => -1
    ]
]);
```

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:

```
Index::pushSettings('my-index', function (Settings $settings) {
    $settings->analysis([
        'analyzer' => [
            'title' => [
                'type' => 'custom',
                'tokenizer' => 'whitespace'
            ]
        ]
    ]);
});
```

The same can be done with the `pushSettingsRaw` method:

```
Index::pushSettingsRaw('my-index', [
    'analysis' => [
        'analyzer' => [
            'title' => [
                'type' => 'custom',
                'tokenizer' => 'whitespace'
            ]
        ]
    ]
]);
```

#### Drop Index

[](#drop-index)

You can unconditionally delete the index:

```
Index::drop('my-index');
```

or delete it only if it exists:

```
Index::dropIfExists('my-index');
```

#### Create Alias

[](#create-alias)

You can create an alias with optional filter query:

```
Index::putAlias('my-index', 'my-alias', [
    'is_write_index' => true,
    'filter' => [
        'term' => [
            'user_id' => 1,
        ],
    ],
]);
```

#### Delete Alias

[](#delete-alias)

You can delete an alias by its name:

```
Index::deleteAlias('my-index', 'my-alias');
```

#### Multiple Connections

[](#multiple-connections)

You can configure multiple connections to Elasticsearch in the [client's configuration file](https://github.com/babenkoivan/elastic-client/tree/master#configuration), and then use a different connection for every operation:

```
Index::connection('my-connection')->drop('my-index');
```

#### More

[](#more)

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

Running Migrations
------------------

[](#running-migrations)

You can either run all migrations:

```
php artisan elastic:migrate
```

or run a specific one:

```
// execute a migration located in one of the registered paths
php artisan elastic:migrate 2018_12_01_081000_create_my_index

// execute a migration located in "/my_path" directory
// note, that you need to specify the full path to the file in this case
php artisan elastic:migrate /my_path/2018_12_01_081000_create_my_index.php
```

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

```
php artisan elastic:migrate --force
```

Reverting Migrations
--------------------

[](#reverting-migrations)

You can either revert the last executed migrations:

```
php artisan elastic:migrate:rollback
```

or rollback a specific one:

```
// rollback a migration located in one of the registered paths
php artisan elastic:migrate:rollback 2018_12_01_081000_create_my_index

// rollback a migration located in "/my_path" directory
// note, that you need to specify the full path to the file in this case
php artisan elastic:migrate:rollback /my_path/2018_12_01_081000_create_my_index
```

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

```
php artisan elastic:migrate:reset
```

Starting Over
-------------

[](#starting-over)

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

```
php artisan elastic:migrate:refresh
```

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

```
php artisan elastic:migrate:fresh
```

**Note** that this command uses wildcards to delete indices. This requires setting [action.destructive\_requires\_name](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-management-settings.html#action-destructive-requires-name) to `false`.

Migration Status
----------------

[](#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):

```
php artisan elastic:migrate:status
```

It is also possible to display only pending migrations:

```
php artisan elastic:migrate:status --pending
```

Zero Downtime Migration
-----------------------

[](#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](https://github.com/babenkoivan/elastic-migrations/wiki/Changing-Mapping-with-Zero-Downtime).

Troubleshooting
---------------

[](#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:

```
php artisan vendor:publish --provider="Elastic\Migrations\ServiceProvider"
```

###  Health Score

65

—

FairBetter than 99% of packages

Maintenance78

Regular maintenance activity

Popularity60

Solid adoption and visibility

Community26

Small or concentrated contributor base

Maturity79

Established project with proven stability

 Bus Factor1

Top contributor holds 83.9% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~79 days

Total

28

Last Release

71d ago

Major Versions

v1.6.2 → v2.0.02021-10-05

v2.0.1 → v3.0.02022-07-27

v3.4.1 → v4.0.02024-06-18

v4.0.1 → v5.0.02025-11-16

PHP version history (5 changes)v1.0.1PHP ^7.2

v1.4.0PHP ^7.2 || ^8.0

v2.0.0PHP ^7.3 || ^8.0

v3.0.0PHP ^7.4 || ^8.0

v4.0.0PHP ^8.2

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/25812954?v=4)[Ivan Babenko](/maintainers/babenkoivan)[@babenkoivan](https://github.com/babenkoivan)

---

Top Contributors

[![babenkoivan](https://avatars.githubusercontent.com/u/25812954?v=4)](https://github.com/babenkoivan "babenkoivan (104 commits)")[![stevebauman](https://avatars.githubusercontent.com/u/6421846?v=4)](https://github.com/stevebauman "stevebauman (17 commits)")[![andrey-helldar](https://avatars.githubusercontent.com/u/10347617?v=4)](https://github.com/andrey-helldar "andrey-helldar (1 commits)")[![jasonwinn](https://avatars.githubusercontent.com/u/10801?v=4)](https://github.com/jasonwinn "jasonwinn (1 commits)")[![Yi-pixel](https://avatars.githubusercontent.com/u/31845646?v=4)](https://github.com/Yi-pixel "Yi-pixel (1 commits)")

---

Tags

elasticsearchlaravelmigrationsphpphplaravelelasticsearchmigrationselastic

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/babenkoivan-elastic-migrations/health.svg)

```
[![Health](https://phpackages.com/badges/babenkoivan-elastic-migrations/health.svg)](https://phpackages.com/packages/babenkoivan-elastic-migrations)
```

###  Alternatives

[babenkoivan/elastic-scout-driver

Elasticsearch driver for Laravel Scout

2773.8M5](/packages/babenkoivan-elastic-scout-driver)[babenkoivan/elastic-scout-driver-plus

Extension for Elastic Scout Driver

2862.8M1](/packages/babenkoivan-elastic-scout-driver-plus)[babenkoivan/elastic-client

The official PHP Elasticsearch client integrated with Laravel

544.0M6](/packages/babenkoivan-elastic-client)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)