Weave Code
Opensearch Migrations Laravel Package
directorytree/opensearch-migrations
OpenSearch index migrations for Laravel. Create, configure, and run versioned index migrations with a familiar artisan workflow, including mappings, settings, index and alias prefixes, and publishing config files.
OpenSearch migrations for Laravel
Frequently asked questions about Opensearch Migrations
- How do I install OpenSearch Migrations in a Laravel application?
- Install it with composer require directorytree/opensearch-migrations, then run vendor:publish twice: once for the OpenSearch client service provider and once for the OpenSearchMigrations service provider. That publishes the client config plus config/opensearch-migrations.php. No extra infrastructure is needed because the migrations ledger lives in your existing application database.
- Which Artisan commands does the package provide for OpenSearch index migrations?
- It registers opensearch:make:migration, opensearch:migrate, opensearch:rollback, opensearch:reset, opensearch:refresh, opensearch:fresh, and opensearch:status. They mirror the familiar php artisan migrate command family, so the workflow feels like standard Laravel schema migrations. Use opensearch:make:migration to scaffold a migration class and opensearch:migrate to apply pending index changes.
- How do I create an index migration with mappings and settings?
- Run php artisan opensearch:make:migration create_posts_index and a migration class is created under opensearch/migrations by default. In the up method you call Index::create with a closure that receives Mapping and Settings objects, where you define your index mappings and settings. The storage path is configurable through the storage_directory config key.
- How does the package track which index migrations have run?
- Applied index migrations are recorded in a tracked migrations table, which defaults to opensearch_migrations and can be changed with the OPENSEARCH_MIGRATIONS_TABLE environment variable. That table state is read by opensearch:status and used by rollback and reset to decide what to reverse. Because the table lives in your application database, index migration state is tied to your database's availability and backup semantics.
- Can I configure index and alias prefixes per environment?
- Yes. The config file exposes index_name_prefix and alias_name_prefix, both of which default to the SCOUT_PREFIX environment variable, so Scout-style environment namespacing carries over to your indices and aliases. This helps keep staging and production indices from colliding. Having alias prefixes in config does not mean automatic alias swapping is implemented.
- Does OpenSearch Migrations support zero-downtime reindexing or alias swaps?
- No. Prefixes and aliases give you the building blocks Laravel teams commonly use for reindex-and-swap workflows, but the package does not ship alias-swap orchestration, so you implement that yourself. Verify behavior in the source before promising zero-downtime reindexing on your roadmap. Its scope is index creation and versioned mappings and settings.
- Is this a replacement for Laravel Scout or an OpenSearch query builder?
- Neither. OpenSearch Migrations is not a search abstraction or query builder; it only owns index creation and versioned mappings and settings. Your application code keeps issuing raw queries through the OpenSearch client. The package is designed to integrate alongside Laravel Scout rather than replace it.
- How do I roll back an OpenSearch index migration safely?
- Each migration class implements MigrationInterface with up and down methods, and opensearch:rollback reverses the last batch recorded in the ledger. Before relying on down methods in production, confirm in the source whether a rollback can delete a live index by default and whether the ledger write is committed before or after the cluster mutation. Also check whether any lock prevents concurrent deploys from double-applying migrations.
- What happens if my application database and the OpenSearch cluster get out of sync?
- Because the ledger is stored in your application database while indices live in OpenSearch, restoring a database backup can make the ledger claim migrations are applied against a cluster that was independently rebuilt or wiped. That divergence is the most important operational risk to plan around. Treat index definitions and cluster state as things to reconcile, and add your own verification or reindex runbook.
- How mature is this package and which Laravel versions does it support?
- Treat it as young: version 1.0.0 was the first release and 1.1.0 was a small follow-up, with effectively zero dependents, so you would be an early production reference. It is maintained by DirectoryTree with a maintainer bus factor of roughly one and no support contract, and it sits on a chain of two vendored packages. For Laravel and PHP version support, check the composer.json constraints on both packages and confirm they resolve against your OpenSearch client version before adopting.
Weaver
How can I help you explore Laravel packages today?