# `Milvex.Schema.Migration`

Boot-time schema migration for Milvus collections.

Provides functionality to:
- Create collections from DSL definitions when missing
- Verify existing schemas against expected definitions
- Ensure indexes declared on the DSL are created when missing

This is the conservative, additive-only path invoked from your application's
supervision tree. It will never drop or recreate indexes, fields, or the
collection itself. Operators wanting destructive migrations (drops, index
recreations) should run `mix milvex.migrate --apply --allow-drop`, which
exposes the full plan and requires explicit confirmation.

## Options

- `:strict` - When `true`, raises on schema mismatches instead of logging warnings.
  Useful for CI/CD pipelines. Default: `false`

## Examples

    # Basic migration
    Milvex.Schema.Migration.migrate!(conn, MyApp.Movies, [])

    # Strict mode (fails on schema mismatch)
    Milvex.Schema.Migration.migrate!(conn, MyApp.Movies, strict: true)

# `schema_diff`

```elixir
@type schema_diff() :: %{
  missing: [String.t()],
  extra: [String.t()],
  mismatches: [{String.t(), map(), map()}]
}
```

# `migrate!`

```elixir
@spec migrate!(GenServer.server(), module(), keyword()) :: :ok
```

Migrates a collection module to Milvus.

If the collection exists, verifies the schema matches and ensures any indexes
declared on the DSL but missing in Milvus are created. If the collection does
not exist, it is created together with its declared indexes.

Destructive operations (dropping fields, dropping or recreating indexes) are
intentionally not performed here. Use `mix milvex.migrate --apply --allow-drop`
for those.

## Options

- `:strict` - Raise on schema mismatch instead of warning. Default: `false`
- Any additional options are passed to Milvus API calls.

## Returns

- `:ok` on success
- Raises `Milvex.Error` on failure

# `verify_schema!`

```elixir
@spec verify_schema!(GenServer.server(), module(), String.t(), keyword()) ::
  {:ok, :match} | {:ok, {:mismatch, schema_diff()}}
```

Verifies that the existing collection schema matches the expected schema.

## Options

- `:strict` - Raise on mismatch instead of warning. Default: `false`

## Returns

- `{:ok, :match}` - Schemas match
- `{:ok, {:mismatch, diff}}` - Schemas differ (only in non-strict mode)
- Raises in strict mode when schemas don't match

---

*Consult [api-reference.md](api-reference.md) for complete listing*