qubu 0.7.0 → 0.7.1

package/dist/diff.mjs

@@ -518,7 +518,7 @@ function addInternalObject(records, kind, value, path, namespace, parent, snapsh
 function operationForMatch(match, diagnostics) {
 	const before = match.before.object;
 	const after = match.after.object;
-	const changedProperties = propertyChangesBetween(before.value, after.value);
+	const changedProperties = propertyChangesBetween(before.value, after.value).filter((change) => !(before.kind === "column" && change.path.length === 1 && change.path[0] === "ordinalPosition"));
 	const physicalRename = before.physicalName !== void 0 && after.physicalName !== void 0 && before.physicalName !== after.physicalName;
 	const blockedRename = match.before.lossy || match.after.lossy;
 	const effectiveChanges = physicalRename && blockedRename && changedProperties.length === 0 ? freeze([{

package/docs/migrations/index.md

@@ -91,3 +91,34 @@ import { emitMigrationPlan } from "@qubu/migrate/ddl/postgres"
 
 const preview = emitMigrationPlan(plan)
 ```
+
+## Column order
+
+Migration generation defaults to declaration order. PostgreSQL can opt in to
+alignment ordering for new tables:
+
+```ts
+import { compileMigrationProgram } from "@qubu/migrate/artifact/postgres"
+
+const compiled = compileMigrationProgram(plan, { columnOrder: "alignment" })
+```
+
+For the CLI, add `columnOrder: "alignment"` to your existing `qubu.config.js`.
+Both generation commands also accept an override:
+
+```sh
+qubu migrate create add-users --column-order alignment
+qubu schema bootstrap --column-order alignment --dry-run
+```
+
+The flag overrides configuration; omitting both selects `"declaration"`. Use
+`--column-order declaration` to override an alignment setting. MySQL and SQLite
+reject alignment ordering. `qubu migrate apply` executes the sealed program;
+changing configuration does not change an existing artifact.
+
+Alignment ordering is a conservative PostgreSQL storage heuristic, not a guarantee
+of smaller rows. Known fixed-width columns come first, sorted by descending
+alignment with stable ties. Variable-length and unknown types follow in declaration
+order. Existing tables are never automatically repacked, and column-order-only
+snapshot differences do not generate migrations. Sealing retains existing physical
+column ordinals and records the selected order for new tables.

package/docs/schema/ddl-emission.md

@@ -89,3 +89,23 @@ For execution, compile the plan with `compileMigrationProgram()` from
 `@qubu/migrate/artifact`. The versioned program—not the aggregate `sql`
 string—is authoritative. See [Artifacts and approval
 policy](../migrations/artifacts-and-policy.md).
+
+CREATE TABLE statements follow column `ordinalPosition` values, preserving schema
+declaration order across PostgreSQL, MySQL, and SQLite. Snapshot arrays remain
+sorted by ID for deterministic serialization; array order does not determine DDL
+column order.
+
+For new PostgreSQL tables, opt in to alignment ordering:
+
+```ts
+import { emitMigrationPlan } from "@qubu/migrate/ddl/postgres"
+
+const preview = emitMigrationPlan(plan, { columnOrder: "alignment" })
+```
+
+The default is `"declaration"`. Alignment ordering places known fixed-width types
+first, in descending alignment order, preserving declaration order for ties.
+Variable-length and unknown types retain their relative order after that group.
+This is a conservative heuristic: nulls and variable-length values affect actual
+savings. It does not rebuild or reorder existing tables or change index key order.
+MySQL and SQLite reject `"alignment"`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qubu",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/aleclarson/qubu"