Skip to main content
POST/migrations/apply

Apply Migrations

Applies all pending migration files to the project's schema, executing each atomically in a Postgres transaction.

Corresponds to the k9o migration apply CLI command and uses a time-bounded _admin DB credential revoked after the run completes.

Concurrent apply calls are serialised via a Postgres advisory lock.

A second call that cannot acquire the lock within 60 seconds returns K9O_MIGRATION_CONFLICT (409).

Schema changes that introduce undefined-policy state are rejected with K9O_MIGRATION_POLICY_VALIDATION_FAILED (400) unless the migration declares noPolicy: true.

Requires PROJECT_ADMIN.

Parameters
projectSlug *path

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

It is unique within the org.

Responses
HTTPK9O CodeDescription
200Success
400K9O_INVALID_FIELD_VALUEThe migrations body is malformed, a column uses the platform-reserved _k9o_ prefix, or a migration op fails to apply; fix the request and retry.
403K9O_ACCESS_DENIEDApplying migrations requires the PROJECT_ADMIN role.
Response body (200)
data *object

Which of the submitted migrations ran and which were skipped.

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.apply()

Showing example in TypeScript

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

More in Storage & Schema