# orca.migrations

> A module of morca's API.

The schema's migrations (`State.migrate` applies them): each version's statements, which versions raise the floor an older binary needs, and the check that an older binary may run on a newer schema. AGENTS.md says how to keep a migration additive.

## Functions

### `data_version_sql`

```mojo
def data_version_sql(describe: String) -> String
```

SQL for the data version of the `describe` JSON `describe` (a jsonb expression): its steps' `version=` as `<step>=<version>`, by step name, comma-separated; empty when no step sets one (#297). The fill takes a partition done under another code as done only when this matches (`orca.fill`).

### `migration_floor`

```mojo
def migration_floor(version: Int) -> Int
```

The fewest migrations a binary must know to run on a database at schema version `version`: the newest floor-raising migration up to it.

### `known_migrations`

```mojo
def known_migrations() -> Int
```

How many migrations this binary knows: all of `_migrations`, or fewer under `ORCA_TEST_MIGRATIONS=N`, which the tests use to act as an older binary on a database a newer one migrated.

### `schema_ahead`

```mojo
def schema_ahead(have: Int, floor: Int, known: Int) -> Bool
```

Whether a binary that knows `known` migrations runs on a database at schema version `have` without migrating it: False when the database isn't ahead (the binary applies what it lacks), True when it's ahead with only additive migrations since (`floor`, the fewest migrations the database says a binary must know, is at most `known`). Raises when the database needs a newer binary, or doesn't say (`floor` < 0).