Opensearch Migrations Laravel Package

Product Decisions This Supports

• Build vs. buy for search infrastructure management. If your product runs on OpenSearch (or Elasticsearch) and you already have a Laravel codebase, this package answers a narrower question than "should we build a search platform": it decides whether index definitions live as reviewed, versioned files in your repo or as undocumented console commands and tribal knowledge. That's a low-commitment build-vs-buy call with outsized operational payoff.

• Feature: making index schema a first-class, reviewable artifact. Index mappings are effectively database schema for search. This package lets a PM mandate that any change to how posts is indexed ships through a PR-reviewed migration file, timestamped and reversible, instead of a one-off PUT /posts/_mapping someone ran in March. That directly reduces the class of incident where "search results changed and nobody knows why."

• Roadmap sequencing: search features that depend on mapping changes. Any planned feature requiring new indexed fields, changed analyzers, or new indices (facets, filters, relevance tuning, autocomplete) is gated on being able to change mappings safely. This package unblocks that work incrementally — one migration per logical change — rather than forcing a big-bang reindex project.

• Multi-environment and multi-tenant readiness. The index_name_prefix / alias_name_prefix config (defaulting to SCOUT_PREFIX) lets one codebase target staging, production, or tenant-scoped indices purely through environment configuration. That's a product capability decision — "can we run a separate search environment per customer or per region?" — made cheap.

• Deployment pipeline standardization. Wiring opensearch:migrate immediately after php artisan migrate gives search infrastructure the same deploy discipline, ordering, and log capture as the database. PMs can commit to "search schema is in sync with every deploy" as a policy rather than an aspiration.

• Scoping the buy: what this does not solve. Critically, it does not do reindexing, alias swapping for zero-downtime cutover, query building, or search relevance. Those remain product/engineering scope. Adopting this package is buying the index definition component, not a search platform — and the roadmap must reflect that distinction.

• Risk management around vendor concentration. The package is a thin wrapper in a single-vendor chain (opensearch-migrations → opensearch-client → official opensearch/php-client), with zero dependents and an early v1.x maturity curve. The PM decision is not just "adopt" but "adopt behind an internal seam" so it can be swapped or vendored without touching application code.

When to Consider This Package

Adopt when all of the following hold:

• You are on Laravel + PHP and OpenSearch is already in production. This is not a greenfield "should we use OpenSearch?" decision; it assumes the cluster exists and the pain is keeping mappings in sync with code.
• Index mappings change more than once. If your mapping has been static since launch, the ceremony of migration files buys little. If you're adding fields monthly, it pays immediately.
• You already run Scout or a prefix scheme. The prefix defaults fall through to SCOUT_PREFIX, so existing namespacing carries over for free — no new conventions to teach.
• You have, or can build, a disciplined deploy pipeline. The package assumes one serialized migration runner. If your deploys are chaotic or heavily parallel, you must add locking or a dedicated migration job before rolling this out, not after.
• You can baseline existing indices first. The single most important adoption prerequisite: if indices already serve traffic, author a migration that reproduces the current mapping verbatim and hand-insert the ledger row before running anything. If the team can't commit to that step, adoption will produce an outage.
• You accept manual reconciliation as a runbook item. The migration ledger (a database table) and the cluster (indices) are two stateful systems with no reconciliation. A DB blip mid-migration leaves them divergent, and fixing it is a human inspecting the cluster.

Look elsewhere, or scope down, when:

• You need zero-downtime mapping changes. Aliases appear in the config, but reindex-and-swap choreography is undocumented. Treat this as the index-definition layer and build the cutover yourself — or evaluate a search platform that owns it.
• You need cross-engine support or a non-Laravel stack. The Laravel/Artisan coupling is the entire value proposition.
• Your mapping changes are rare and in-place edits are fine. Index::dropIfExists() in down() means rollback removes a live serving index; if nobody will reliably exercise the rollback path, you're carrying risk for little benefit.
• You need field type changes on live data. text → keyword requires a new index plus a reindex. This package won't do it in place, so if that's your primary need, the package is a helper, not a solution.
• Maturity risk is unacceptable. Zero dependents, a v1.0.0 in the recent past, and a v1.1.0 that changed fake-assertion callback semantics between minor versions. If you can't absorb that churn behind a seam, wait.

How to Pitch It (Stakeholders)

To executives — the one-paragraph version: Search index definitions are schema, and right now ours live in console commands and memory. This package lets us treat them like database migrations: reviewed in PRs, timestamped, reversible, and applied automatically on every deploy. It's a small Composer dependency with no new infrastructure, it's compatible with the prefix scheme we already run in Scout, and it converts a class of "search broke and nobody knows why" incidents into ordinary code review. The trade-off is discipline: we need one migration job in the pipeline, a baseline step for existing indices, and a documented runbook for the case where the migration ledger and the cluster disagree. We should adopt it behind a thin internal interface so we can swap it out if the single-vendor chain stops being maintained.

To engineering — what you're actually signing up for:

• What it gives you: opensearch:make:migration scaffolding; a fluent Mapping/Settings API; a familiar six-command set that maps 1:1 onto migrate, :rollback, :reset, :refresh, :fresh, :status; configurable ledger table, connection, storage directory, and index/alias prefixes.
• What it costs you: three must-dos before first production run — (1) baseline existing indices by authoring a verbatim-mapping migration and hand-inserting its ledger row; (2) serialize migration execution, because concurrent pods racing the same ledger row is undocumented and is the most likely source of divergence; (3) keep opensearch:migrate:fresh away from shared environments — it drops every index.
• Non-negotiables in the runbook: rollback deletes live data, since down() is typically dropIfExists; the storage directory must ship with your artifact (post-deploy assertion that it's non-empty); migration filenames are the ledger key, so renaming an applied migration orphans it forever; and at least one CI job must hit a real containerized OpenSearch, because mocks won't catch mapping rejections.
• Architectural guardrail worth one hour of effort: a thin internal service wrapping the Index facade, with a rule that application code never references it directly. That's what makes the vendor-risk answer "we can swap it" rather than "we hope."
• Where we deliberately stop: this package owns index creation and mapping evolution. Reindex orchestration, alias-swap cutovers, and query/relevance work stay in our code — and the roadmap should say so explicitly, so nobody expects zero-downtime mapping changes to come free with the dependency.