Migration Order Planner

Overview

You send the migrations you hold — an id, a version, and whichever prerequisites each one has — and we return the order they may be applied in, the waves that can run together, and every migration we could not place with the reason. On top of the ordering we check what a dependency sort cannot see: a hole in the version series, two migrations claiming one version, two migrations forking one chain, a prerequisite that ships later than the migration needing it, and a prerequisite nothing declares. We read no migration body, open no connection, and apply nothing: the answer is about the set you described.

Every migration runner orders pending changes slightly differently, and most of them stay quiet about the ones they could not place — a duplicate version or a forked chain then surfaces halfway through a release. You get one order, and every objection named up front.

When to use it

Scope

Non-goals

• Does not connect to a database or read a live catalog
• Does not read, parse or rewrite a migration body
• Does not apply, roll back or schedule anything
• Does not accept a connection string, user name or password
• Does not order generic tasks — dependency ordering with no version series is what workflow.topological_sort is for
• Does not read a clock, so a migration set has no notion of now

Properties

Capabilities

Cost & billing

Flat rate per invocation

File handling

How we handle your data

Input schema

Output schema

API contract

curl -sS -X POST "$BASE/v1/execute" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{"skillKey":"database.migration_order_plan","input":{"migrations":[{"id":"0001_create_accounts","version":"1"},{"id":"0002_add_email","version":"2","dependsOn":["0001_create_accounts"]}]}}'

import { Squillify } from "@squillify/sdk";

const sq = new Squillify({ apiKey: process.env.SQUILLIFY_API_KEY });

const { output } = await sq.execute("database.migration_order_plan", {"migrations":[{"id":"0001_create_accounts","version":"1"},{"id":"0002_add_email","version":"2","dependsOn":["0001_create_accounts"]},{"id":"0003_backfill_email","version":"3","dependsOn":["0002_add_email"]},{"id":"0004_add_email_index","version":"4","dependsOn":["0003_backfill_email"]}]});

Errors

Other limits

Limitations

• Does not connect to a database or read a live catalog
• Does not read, parse or rewrite a migration body
• Does not apply, roll back or schedule anything
• Does not accept a connection string, user name or password
• Does not order generic tasks — dependency ordering with no version series is what workflow.topological_sort is for
• Does not read a clock, so a migration set has no notion of now
• Applying migrations or checking whether they already ran
• Ordering tasks that carry no version, where a plain dependency sort fits better
• Deciding whether a migration is safe for the data already stored

How to call

POST /v1/execute (requires authentication)

{
  "skillKey": "database.migration_order_plan",
  "input": {
    "migrations": [
      {
        "id": "0001_create_accounts",
        "version": "1"
      },
      {
        "id": "0002_add_email",
        "version": "2",
        "dependsOn": [
          "0001_create_accounts"
        ]
      },
      {
        "id": "0003_backfill_email",
        "version": "3",
        "dependsOn": [
          "0002_add_email"
        ]
      },
      {
        "id": "0004_add_email_index",
        "version": "4",
        "dependsOn": [
          "0003_backfill_email"
        ]
      }
    ]
  }
}

Examples

{
  "migrations": [
    {
      "id": "0001_create_accounts",
      "version": "1"
    },
    {
      "id": "0002_add_email",
      "version": "2",
      "dependsOn": [
        "0001_create_accounts"
      ]
    },
    {
      "id": "0003_backfill_email",
      "version": "3",
      "dependsOn": [
        "0002_add_email"
      ]
    },
    {
      "id": "0004_add_email_index",
      "version": "4",
      "dependsOn": [
        "0003_backfill_email"
      ]
    }
  ]
}

{
  "ordered": [
    "0001_create_accounts",
    "0002_add_email",
    "0003_backfill_email",
    "0004_add_email_index"
  ],
  "summary": {
    "migrationCount": 4,
    "orderedCount": 4,
    "blockedCount": 0,
    "levelCount": 4,
    "edgeCount": 3,
    "declaredEdgeCount": 3,
    "versionScheme": "NUMERIC",
    "chainModel": "LINEAR_CHAIN",
    "gapDetection": "CONTIGUOUS_INTEGER",
    "tieBreaker": "VERSION_THEN_ID",
    "conflictCount": 0,
    "truncated": false
  },
  "levels": [
    [
      "0001_create_accounts"
    ],
    [
      "0002_add_email"
    ],
    [
      "0003_backfill_email"
    ],
    [
      "0004_add_email_index"
    ]
  ],
  "applicable": true,
  "blocked": [],
  "conflicts": []
}

{
  "chainModel": "DAG",
  "migrations": [
    {
      "id": "0001_create_orders",
      "version": "1"
    },
    {
      "id": "0002_add_status",
      "version": "2",
      "dependsOn": [
        "0005_split_totals"
      ]
    },
    {
      "id": "0005_split_totals",
      "version": "5",
      "dependsOn": [
        "0001_create_orders"
      ]
    }
  ]
}

{
  "ordered": [
    "0001_create_orders",
    "0005_split_totals",
    "0002_add_status"
  ],
  "summary": {
    "migrationCount": 3,
    "orderedCount": 3,
    "blockedCount": 0,
    "levelCount": 3,
    "edgeCount": 2,
    "declaredEdgeCount": 2,
    "versionScheme": "NUMERIC",
    "chainModel": "DAG",
    "gapDetection": "CONTIGUOUS_INTEGER",
    "tieBreaker": "VERSION_THEN_ID",
    "conflictCount": 2,
    "truncated": false
  },
  "levels": [
    [
      "0001_create_orders"
    ],
    [
      "0005_split_totals"
    ],
    [
      "0002_add_status"
    ]
  ],
  "applicable": false,
  "blocked": [],
  "conflicts": [
    {
      "code": "VERSION_GAP",
      "severity": "warning",
      "migrationIds": [
        "0002_add_status"
      ],
      "relatedIds": [
        "0005_split_totals"
      ],
      "detail": "version 2 is followed by version 5, which skips 2 value(s)"
    },
    {
      "code": "DEPENDS_ON_LATER_VERSION",
      "severity": "error",
      "migrationIds": [
        "0002_add_status"
      ],
      "relatedIds": [
        "0005_split_totals"
      ],
      "detail": "prerequisite version 5 is greater than dependent version 2"
    }
  ]
}

Recommended use cases

• Decide the order a pending migration set may be applied in
• Catch a duplicate version or a forked chain before a release goes out
• Show which migrations a missing prerequisite or a loop has stranded

Avoid for

• Applying migrations or checking whether they already ran
• Ordering tasks that carry no version, where a plain dependency sort fits better
• Deciding whether a migration is safe for the data already stored

Related skills

Composable with

Safety & privacy

• Runs without calling any external service.
• Your payloads are never stored permanently.
• Telemetry captures metadata only — never your payload contents.
• We never train models on your payloads.
• No human reviews your payloads.

Tags