Skip to main content
POST/migrations/pending/{pendingId}/apply

Apply Pending Migration

Approves and executes a queued pending migration, transitioning it from queued to applied and running its DDL atomically against the project's schema.

Returns data: { pendingId, applied[], skipped[] } where applied and skipped list the migration slugs disposed by the underlying apply run.

Attempting this on a row that is not in queued state returns K9O_INVALID_FIELD_VALUE (400).

Emits a migration.applied_from_pending audit event on successful DDL execution.

Requires PROJECT_ADMIN.

Parameters
pendingId *path

The pending migration's id (pmig_...).

projectSlug *path

The project's slug: the path segment after @.

It is unique within the org.

Responses
HTTPK9O CodeDescription
200Success
403K9O_ACCESS_DENIEDApplying a pending migration requires the PROJECT_ADMIN role, or the caller is not a project member.
403K9O_RBAC_DENYA session is required to apply a pending migration: a personal access token alone is refused with `context.reason` `session_required`, and a service, workload or extension token with `human_only`.
Response body (200)
data *object

The pending migration that was applied, and what ran.

pendingId *string

The pending migration's id (pmig_...).

applied *object[]

The migrations applied by this call, in the order they ran.

version *integer

The migration's version, an integer from 1 to 2147483647.

Versions apply in ascending order.

slug *string

The migration's slug, as given when it was submitted.

checksum *string

SHA-256 (hex) of the migration's canonical JSON (version, slug, up, down, policy).

Re-applying a version with a different checksum is refused.

skipped *object[]

The migrations skipped because they were already applied with the same checksum.

version *integer

The migration's version, an integer from 1 to 2147483647.

Versions apply in ascending order.

slug *string

The migration's slug, as given when it was submitted.

reason *"already_applied"

Why the migration was skipped. already_applied: this version is already in the project with the same checksum.

meta *any

Request metadata: cost, timing and correlation ids.

TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.migrations.applyPending('pmig_4Fh2kQ9xLm7a')

Showing example in TypeScript

Response example (200)
{
  "data": {
    "pendingId": "string",
    "applied": [
      {
        "version": 0,
        "slug": "string",
        "checksum": "string"
      }
    ],
    "skipped": [
      {
        "version": 0,
        "slug": "string",
        "reason": "already_applied"
      }
    ]
  }
}

More in Storage & Schema