{"id":15885766,"url":"https://github.com/babenkoivan/elastic-migrations","last_synced_at":"2025-10-08T06:51:21.109Z","repository":{"id":42638451,"uuid":"226658086","full_name":"babenkoivan/elastic-migrations","owner":"babenkoivan","description":"Elasticsearch migrations for Laravel","archived":false,"fork":false,"pushed_at":"2025-04-07T07:08:29.000Z","size":172,"stargazers_count":194,"open_issues_count":0,"forks_count":34,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-16T16:07:23.899Z","etag":null,"topics":["elasticsearch","laravel","migrations","php"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/babenkoivan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"ko_fi":"ivanbabenko","custom":["https://paypal.me/babenkoi"]}},"created_at":"2019-12-08T11:40:41.000Z","updated_at":"2025-05-12T18:37:50.000Z","dependencies_parsed_at":"2025-04-14T12:01:08.203Z","dependency_job_id":null,"html_url":"https://github.com/babenkoivan/elastic-migrations","commit_stats":{"total_commits":111,"total_committers":5,"mean_commits":22.2,"dds":0.1711711711711712,"last_synced_commit":"158e0a5401a937da312372dce504737712541f3e"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/babenkoivan/elastic-migrations","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/babenkoivan%2Felastic-migrations","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/babenkoivan%2Felastic-migrations/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/babenkoivan%2Felastic-migrations/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/babenkoivan%2Felastic-migrations/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/babenkoivan","download_url":"https://codeload.github.com/babenkoivan/elastic-migrations/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/babenkoivan%2Felastic-migrations/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278903007,"owners_count":26065786,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["elasticsearch","laravel","migrations","php"],"created_at":"2024-10-06T05:07:29.164Z","updated_at":"2025-10-08T06:51:21.070Z","avatar_url":"https://github.com/babenkoivan.png","language":"PHP","funding_links":["https://ko-fi.com/ivanbabenko","https://paypal.me/babenkoi"],"categories":[],"sub_categories":[],"readme":"# Elastic Migrations\n\n[![Latest Stable Version](https://poser.pugx.org/babenkoivan/elastic-migrations/v/stable)](https://packagist.org/packages/babenkoivan/elastic-migrations)\n[![Total Downloads](https://poser.pugx.org/babenkoivan/elastic-migrations/downloads)](https://packagist.org/packages/babenkoivan/elastic-migrations)\n[![License](https://poser.pugx.org/babenkoivan/elastic-migrations/license)](https://packagist.org/packages/babenkoivan/elastic-migrations)\n[![Tests](https://github.com/babenkoivan/elastic-migrations/workflows/Tests/badge.svg)](https://github.com/babenkoivan/elastic-migrations/actions?query=workflow%3ATests)\n[![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)\n[![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)\n[![Donate PayPal](https://img.shields.io/badge/donate-paypal-blue)](https://paypal.me/babenkoi)\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://ko-fi.com/ivanbabenko\" target=\"_blank\"\u003e\u003cimg src=\"https://ko-fi.com/img/githubbutton_sm.svg\" alt=\"Support the project!\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nElastic Migrations for Laravel allow you to easily modify and share indices schema across the application's environments.\n\n## Contents\n\n* [Compatibility](#compatibility)\n* [Installation](#installation) \n* [Configuration](#configuration)\n* [Writing Migrations](#writing-migrations)\n* [Running Migrations](#running-migrations)\n* [Reverting Migrations](#reverting-migrations)\n* [Starting Over](#starting-over)\n* [Migration Status](#migration-status)\n* [Zero Downtime Migration](#zero-downtime-migration)\n* [Troubleshooting](#migration-status)\n\n## Compatibility\n\nThe current version of Elastic Migrations has been tested with the following configuration:\n\n* PHP 8.2\n* Elasticsearch 8.x\n* Laravel 11.x\n\nIf your project uses older Laravel (or PHP) version check [the previous major version](https://github.com/babenkoivan/elastic-migrations/tree/v3.4.1#compatibility) of the package.\n\n## Installation\n\nThe library can be installed via Composer:\n\n```bash\ncomposer require babenkoivan/elastic-migrations\n```\n\nIf 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).\n\n## Configuration\n\nElastic Migrations uses [babenkoivan/elastic-client](https://github.com/babenkoivan/elastic-client) as a dependency.\nTo change the client settings you need to publish the configuration file first:\n\n```bash\nphp artisan vendor:publish --provider=\"Elastic\\Client\\ServiceProvider\"\n```\n\nIn the newly created `config/elastic.client.php` file you can define the default connection name and describe multiple\nconnections using configuration hashes. Please, refer to the [elastic-client documentation](https://github.com/babenkoivan/elastic-client) for more details.\n\nIt is recommended to publish Elastic Migrations settings as well:\n\n```bash\nphp artisan vendor:publish --provider=\"Elastic\\Migrations\\ServiceProvider\"\n```\n\nThis will create the `config/elastic.migrations.php` file, which allows you to configure the following options:\n\n* `storage.default_path` - the default location of your migration files\n* `database.table` - the table name that holds executed migration names\n* `database.connection` - the database connection you wish to use\n* `prefixes.index` - the prefix of your indices\n* `prefixes.alias` - the prefix of your aliases\n\nIf you store some migration files outside the default path and want them to be visible by the package, you may use \n`registerPaths` method to inform Elastic Migrations how to load them:\n\n```php\nclass MyAppServiceProvider extends Illuminate\\Support\\ServiceProvider\n{\n    public function boot()\n    {\n        resolve(MigrationStorage::class)-\u003eregisterPaths([\n            '/my_app/elastic/migrations1',\n            '/my_app/elastic/migrations2',\n        ]);\n    }\n}\n```\n\n\nFinally, don't forget to run Laravel database migrations to create Elastic Migrations table:\n\n```bash\nphp artisan migrate\n```\n\n## Writing Migrations\n\nYou can effortlessly create a new migration file using an Artisan console command:\n\n```bash\n// create a migration file with \"create_my_index.php\" name in the default directory\nphp artisan elastic:make:migration create_my_index\n\n// create a migration file with \"create_my_index.php\" name in \"/my_path\" directory \n// note, that you need to specify the full path to the file in this case\nphp artisan elastic:make:migration /my_path/create_my_index.php\n```\n\nEvery migration has two methods: `up` and `down`. `up` is used to alternate the index schema and `down` is used to revert that action.\n\nYou can use `Elastic\\Migrations\\Facades\\Index` facade to perform basic operations over Elasticsearch indices:\n\n#### Create Index\n\nYou can create an index with the default settings: \n\n```php\nIndex::create('my-index');\n``` \n\nYou can use a modifier to configure mapping and settings:\n\n```php\nIndex::create('my-index', function (Mapping $mapping, Settings $settings) {\n    // to add a new field to the mapping use method name as a field type (in Camel Case), \n    // first argument as a field name and optional second argument for additional field parameters  \n    $mapping-\u003etext('title', ['boost' =\u003e 2]);\n    $mapping-\u003efloat('price');\n\n    // you can define a dynamic template as follows\n    $mapping-\u003edynamicTemplate('my_template_name', [\n        'match_mapping_type' =\u003e 'long',\n        'mapping' =\u003e [\n            'type' =\u003e 'integer',\n        ],\n    ]);\n    \n    // you can also change the index settings and the analysis configuration\n    $settings-\u003eindex([\n         'number_of_replicas' =\u003e 2,\n         'refresh_interval' =\u003e -1\n    ]);\n    \n    $settings-\u003eanalysis([\n        'analyzer' =\u003e [\n            'title' =\u003e [\n                'type' =\u003e 'custom',\n                'tokenizer' =\u003e 'whitespace'    \n            ]\n        ]\n    ]);\n});\n```\n\nThere is also the `createRaw` method in your disposal:\n\n```php\n$mapping = [\n    'properties' =\u003e [\n        'title' =\u003e [\n            'type' =\u003e 'text'\n        ]\n    ]\n];\n\n$settings = [\n    'number_of_replicas' =\u003e 2\n];\n\nIndex::createRaw('my-index', $mapping, $settings);\n```\n\nFinally, it is possible to create an index only if it doesn't exist:\n\n```php\n// you can use a modifier as shown above\nIndex::createIfNotExists('my-index', $modifier);\n// or you can use raw mapping and settings \nIndex::createIfNotExistsRaw('my-index', $mapping, $settings);\n```\n\n#### Update Mapping\n\nYou can use a modifier to adjust the mapping:\n\n```php\nIndex::putMapping('my-index', function (Mapping $mapping) {\n    $mapping-\u003etext('title', ['boost' =\u003e 2]);\n    $mapping-\u003efloat('price');\n});\n```\n\nAlternatively, you can use the `putMappingRaw` method as follows:\n\n```php\nIndex::putMappingRaw('my-index', [\n    'properties' =\u003e [\n        'title' =\u003e [\n            'type' =\u003e 'text',\n            'boost' =\u003e 2\n        ],\n        'price' =\u003e [\n            'price' =\u003e 'float'\n        ]      \n    ]   \n]);\n```\n\n#### Update Settings\n\nYou can use a modifier to change an index configuration:\n\n```php\nIndex::putSettings('my-index', function (Settings $settings) {\n    $settings-\u003eindex([\n         'number_of_replicas' =\u003e 2,\n         'refresh_interval' =\u003e -1\n    ]);\n});\n``` \n\nThe same result can be achieved with the `putSettingsRaw` method:\n\n```php\nIndex::putSettingsRaw('my-index', [\n    'index' =\u003e [\n        'number_of_replicas' =\u003e 2,\n        'refresh_interval' =\u003e -1\n    ]\n]); \n```\n\nIt is possible to update analysis settings only on closed indices. The `pushSettings` method closes the index, \nupdates the configuration and opens the index again:\n\n```php\nIndex::pushSettings('my-index', function (Settings $settings) {\n    $settings-\u003eanalysis([\n        'analyzer' =\u003e [\n            'title' =\u003e [\n                'type' =\u003e 'custom',\n                'tokenizer' =\u003e 'whitespace'\n            ]\n        ]\n    ]);\n});\n```\n\nThe same can be done with the `pushSettingsRaw` method:\n\n```php\nIndex::pushSettingsRaw('my-index', [\n    'analysis' =\u003e [\n        'analyzer' =\u003e [\n            'title' =\u003e [\n                'type' =\u003e 'custom',\n                'tokenizer' =\u003e 'whitespace'\n            ]\n        ]\n    ]\n]); \n```\n\n#### Drop Index\n\nYou can unconditionally delete the index:\n\n```php\nIndex::drop('my-index');\n```\n\nor delete it only if it exists:\n\n```php\nIndex::dropIfExists('my-index');\n```\n\n#### Create Alias\n\nYou can create an alias with optional filter query:\n\n```php\nIndex::putAlias('my-index', 'my-alias', [\n    'is_write_index' =\u003e true,\n    'filter' =\u003e [\n        'term' =\u003e [\n            'user_id' =\u003e 1,\n        ],\n    ],\n]);\n```\n\n#### Delete Alias\n\nYou can delete an alias by its name:\n\n```php\nIndex::deleteAlias('my-index', 'my-alias');\n```\n\n#### Multiple Connections\n\nYou can configure multiple connections to Elasticsearch in the [client's configuration file](https://github.com/babenkoivan/elastic-client/tree/master#configuration),\nand then use a different connection for every operation:\n\n```php\nIndex::connection('my-connection')-\u003edrop('my-index');\n```\n\n#### More\n\nFinally, you are free to inject `Elastic\\Elasticsearch\\Client` in the migration constructor and execute any supported by client actions.\n\n## Running Migrations\n\nYou can either run all migrations:\n\n```bash\nphp artisan elastic:migrate\n```\n\nor run a specific one:\n\n```bash\n// execute a migration located in one of the registered paths\nphp artisan elastic:migrate 2018_12_01_081000_create_my_index\n\n// execute a migration located in \"/my_path\" directory\n// note, that you need to specify the full path to the file in this case\nphp artisan elastic:migrate /my_path/2018_12_01_081000_create_my_index.php\n```\n\nUse the `--force` option if you want to execute migrations on production environment:\n\n```bash\nphp artisan elastic:migrate --force\n```\n\n## Reverting Migrations\n\nYou can either revert the last executed migrations:\n\n```bash\nphp artisan elastic:migrate:rollback \n```\n\nor rollback a specific one:\n\n```bash\n// rollback a migration located in one of the registered paths\nphp artisan elastic:migrate:rollback 2018_12_01_081000_create_my_index\n\n// rollback a migration located in \"/my_path\" directory\n// note, that you need to specify the full path to the file in this case\nphp artisan elastic:migrate:rollback /my_path/2018_12_01_081000_create_my_index\n```\n\nUse the `elastic:migrate:reset` command if you want to revert all previously migrated files:\n\n```bash\nphp artisan elastic:migrate:reset \n```\n\n## Starting Over\n\nSometimes you just want to start over, rollback all the changes and apply them again:\n\n```bash\nphp artisan elastic:migrate:refresh\n```\n\nAlternatively you can also drop all existing indices and rerun the migrations:\n\n```bash\nphp artisan elastic:migrate:fresh\n```\n\n**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`.\n\n## Migration Status\n\nYou can always check which files have been already migrated and what can be reverted by the `elastic:migrate:rollback` command (the last batch):\n\n```bash\nphp artisan elastic:migrate:status\n```\n\nIt is also possible to display only pending migrations:\n\n```bash\nphp artisan elastic:migrate:status --pending\n```\n\n## Zero Downtime Migration\n\nChanging an index mapping with zero downtime is not a trivial process and might vary from one project to another.\nElastic 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).\n\n## Troubleshooting\n\nIf you see one of the messages below, follow the instructions:\n\n* `Migration table is not yet created` - run the `php artisan migrate` command\n* `Migration directory is not yet created` - create a migration file using the `elastic:make:migration` command or \ncreate `migrations` directory manually\n  \nIn case one of the commands doesn't work as expected, try to publish configuration:\n\n```bash\nphp artisan vendor:publish --provider=\"Elastic\\Migrations\\ServiceProvider\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbabenkoivan%2Felastic-migrations","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbabenkoivan%2Felastic-migrations","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbabenkoivan%2Felastic-migrations/lists"}