//! Logical diff between two schemas and per-change classification
//! (specs/implementation/schema-migrations.md#change-classification).
//!
//! Pure: no database access. Tables match by name and fields by flattened
//! name, so a rename is a removal plus an addition. The result borrows table
//! and field pointers from both schemas and must not outlive them.
const std = @import("std");
const ddl = @import("../sql/ddl.zig");
const types = @import("types.zig");
const Allocator = std.mem.Allocator;
const Constraints = types.Constraints;
const Field = types.Field;
const Schema = types.Schema;
const Table = types.Table;
pub const Bucket = enum(u8) {
auto,
checked,
migration_required,
pub fn max(a: Bucket, b: Bucket) Bucket {
return if (@intFromEnum(a) >= @intFromEnum(b)) a else b;
}
pub fn label(self: Bucket) []const u8 {
return switch (self) {
.auto => "auto",
.checked => "checked",
.migration_required => "migration required",
};
}
};
/// Physical treatment of one table in a step.
pub const TableAction = enum {
unchanged,
create,
/// Rename to `_zync_prev_
`, create the target shape, refill.
rebuild,
/// `ALTER TABLE ... ADD COLUMN` for added optional fields.
alter,
/// Rename to `_zync_prev_`; the developer moves or deletes rows.
remove,
};
pub const FieldChangeKind = enum {
added_optional,
added_required,
removed,
type_changed,
items_changed,
became_optional,
became_required,
reference_target_changed,
on_delete_changed,
indexed_changed,
constraint_tightened,
constraint_loosened,
metadata_changed,
pub fn bucket(self: FieldChangeKind) Bucket {
return switch (self) {
.removed, .type_changed, .items_changed => .migration_required,
.added_required, .became_required, .reference_target_changed, .constraint_tightened => .checked,
.added_optional, .became_optional, .on_delete_changed, .indexed_changed, .constraint_loosened, .metadata_changed => .auto,
};
}
pub fn needsRebuild(self: FieldChangeKind) bool {
return switch (self) {
.added_required,
.removed,
.type_changed,
.items_changed,
.became_optional,
.became_required,
.reference_target_changed,
.on_delete_changed,
=> true,
.added_optional, .indexed_changed, .constraint_tightened, .constraint_loosened, .metadata_changed => false,
};
}
pub fn label(self: FieldChangeKind) []const u8 {
return switch (self) {
.added_optional => "added",
.added_required => "added (required)",
.removed => "removed",
.type_changed => "type changed",
.items_changed => "array items changed",
.became_optional => "now optional",
.became_required => "now required",
.reference_target_changed => "reference target changed",
.on_delete_changed => "onDelete changed",
.indexed_changed => "indexed changed",
.constraint_tightened => "constraint tightened",
.constraint_loosened => "constraint relaxed",
.metadata_changed => "metadata changed",
};
}
};
pub const TableChangeKind = enum {
added,
removed,
namespaced_changed,
unique_tightened,
unique_loosened,
metadata_changed,
pub fn bucket(self: TableChangeKind) Bucket {
return switch (self) {
.removed, .namespaced_changed => .migration_required,
.unique_tightened => .checked,
.added, .unique_loosened, .metadata_changed => .auto,
};
}
pub fn label(self: TableChangeKind) []const u8 {
return switch (self) {
.added => "added",
.removed => "removed",
.namespaced_changed => "namespaced changed",
.unique_tightened => "unique constraint added or changed",
.unique_loosened => "unique constraint removed or reordered",
.metadata_changed => "metadata changed",
};
}
};
pub const FieldChange = struct {
kind: FieldChangeKind,
/// Flattened field name (borrowed from whichever side has the field).
name: []const u8,
from: ?*const Field,
to: ?*const Field,
};
pub const TableDiff = struct {
name: []const u8,
from: ?*const Table,
to: ?*const Table,
action: TableAction,
table_changes: []const TableChangeKind,
field_changes: []const FieldChange,
/// Managed index statements differ between the two sides.
indexes_changed: bool,
pub fn bucket(self: *const TableDiff) Bucket {
var result: Bucket = .auto;
for (self.table_changes) |c| result = result.max(c.bucket());
for (self.field_changes) |c| result = result.max(c.kind.bucket());
return result;
}
pub fn isEmpty(self: *const TableDiff) bool {
return self.action == .unchanged and !self.indexes_changed and
self.table_changes.len == 0 and self.field_changes.len == 0;
}
};
pub const SchemaDiff = struct {
allocator: Allocator,
/// Tables present in the target (target order), then removed tables (source order).
tables: []TableDiff,
pub fn deinit(self: *SchemaDiff) void {
for (self.tables) |t| {
self.allocator.free(t.table_changes);
self.allocator.free(t.field_changes);
}
self.allocator.free(self.tables);
}
pub fn bucket(self: *const SchemaDiff) Bucket {
var result: Bucket = .auto;
for (self.tables) |*t| result = result.max(t.bucket());
return result;
}
pub fn hasMigrationRequired(self: *const SchemaDiff) bool {
return self.bucket() == .migration_required;
}
/// No table-level or field-level change at all.
pub fn isEmpty(self: *const SchemaDiff) bool {
for (self.tables) |*t| {
if (!t.isEmpty()) return false;
}
return true;
}
};
/// Diffs `from` (null = empty database) against `to`.
pub fn diff(allocator: Allocator, from: ?*const Schema, to: *const Schema) !SchemaDiff {
var tables = std.ArrayListUnmanaged(TableDiff).empty;
errdefer {
for (tables.items) |t| {
allocator.free(t.table_changes);
allocator.free(t.field_changes);
}
tables.deinit(allocator);
}
for (to.tables) |*to_table| {
const from_table: ?*const Table = if (from) |f| f.table(to_table.name) else null;
var table_diff = try diffTable(allocator, from_table, to_table);
tables.append(allocator, table_diff) catch |err| {
freeTableDiff(allocator, &table_diff);
return err;
};
}
if (from) |f| {
for (f.tables) |*from_table| {
if (to.table(from_table.name) != null) continue;
const changes = try allocator.dupe(TableChangeKind, &.{.removed});
tables.append(allocator, .{
.name = from_table.name,
.from = from_table,
.to = null,
.action = .remove,
.table_changes = changes,
.field_changes = &.{},
.indexes_changed = false,
}) catch |err| {
allocator.free(changes);
return err;
};
}
}
return .{
.allocator = allocator,
.tables = try tables.toOwnedSlice(allocator),
};
}
fn freeTableDiff(allocator: Allocator, t: *TableDiff) void {
allocator.free(t.table_changes);
allocator.free(t.field_changes);
}
fn diffTable(allocator: Allocator, from: ?*const Table, to: *const Table) !TableDiff {
const source = from orelse {
return .{
.name = to.name,
.from = null,
.to = to,
.action = .create,
.table_changes = try allocator.dupe(TableChangeKind, &.{.added}),
.field_changes = &.{},
.indexes_changed = false,
};
};
var table_changes = std.ArrayListUnmanaged(TableChangeKind).empty;
defer table_changes.deinit(allocator);
var field_changes = std.ArrayListUnmanaged(FieldChange).empty;
defer field_changes.deinit(allocator);
if (source.namespaced != to.namespaced) try table_changes.append(allocator, .namespaced_changed);
switch (compareUnique(source, to)) {
.same => {},
.tightened => try table_changes.append(allocator, .unique_tightened),
.loosened => try table_changes.append(allocator, .unique_loosened),
}
if (!metadataEqual(source.metadata, to.metadata)) try table_changes.append(allocator, .metadata_changed);
for (to.userFields()) |*to_field| {
const from_field = userField(source, to_field.name) orelse {
try field_changes.append(allocator, .{
.kind = if (to_field.required) .added_required else .added_optional,
.name = to_field.name,
.from = null,
.to = to_field,
});
continue;
};
try diffField(allocator, &field_changes, from_field, to_field);
}
for (source.userFields()) |*from_field| {
if (userField(to, from_field.name) != null) continue;
try field_changes.append(allocator, .{
.kind = .removed,
.name = from_field.name,
.from = from_field,
.to = null,
});
}
var action: TableAction = .unchanged;
for (table_changes.items) |c| {
if (c == .namespaced_changed) action = .rebuild;
}
for (field_changes.items) |c| {
if (c.kind.needsRebuild()) action = .rebuild;
}
if (action == .unchanged) {
for (field_changes.items) |c| {
if (c.kind == .added_optional) action = .alter;
}
}
const indexes_changed = !try ddl.managedIndexesEqual(allocator, source, to);
const owned_table_changes = try table_changes.toOwnedSlice(allocator);
errdefer allocator.free(owned_table_changes);
return .{
.name = to.name,
.from = source,
.to = to,
.action = action,
.table_changes = owned_table_changes,
.field_changes = try field_changes.toOwnedSlice(allocator),
.indexes_changed = indexes_changed,
};
}
fn diffField(allocator: Allocator, out: *std.ArrayListUnmanaged(FieldChange), from: *const Field, to: *const Field) !void {
const change = struct {
fn make(kind: FieldChangeKind, f: *const Field, t: *const Field) FieldChange {
return .{ .kind = kind, .name = t.name, .from = f, .to = t };
}
}.make;
const same_type = from.declared_type == to.declared_type and from.storage_type == to.storage_type;
if (!same_type) {
try out.append(allocator, change(.type_changed, from, to));
} else if (from.items_type != to.items_type) {
try out.append(allocator, change(.items_changed, from, to));
}
if (from.required != to.required) {
try out.append(allocator, change(if (to.required) .became_required else .became_optional, from, to));
}
if (same_type and from.references != null and to.references != null) {
if (!std.mem.eql(u8, from.references.?, to.references.?)) {
try out.append(allocator, change(.reference_target_changed, from, to));
}
if ((from.on_delete orelse .restrict) != (to.on_delete orelse .restrict)) {
try out.append(allocator, change(.on_delete_changed, from, to));
}
}
if (from.indexed != to.indexed) try out.append(allocator, change(.indexed_changed, from, to));
if (same_type and from.items_type == to.items_type) {
switch (compareConstraints(from.constraints, to.constraints)) {
.same => {},
.tightened => try out.append(allocator, change(.constraint_tightened, from, to)),
.loosened => try out.append(allocator, change(.constraint_loosened, from, to)),
}
}
if (!metadataEqual(from.metadata, to.metadata)) try out.append(allocator, change(.metadata_changed, from, to));
}
fn userField(table: *const Table, name: []const u8) ?*const Field {
for (table.userFields()) |*f| {
if (std.mem.eql(u8, f.name, name)) return f;
}
return null;
}
// ─── Constraint comparison ───────────────────────────────────────────────────
pub const ConstraintChange = enum { same, tightened, loosened };
const Accumulator = struct {
tightened: bool = false,
loosened: bool = false,
fn note(self: *Accumulator, c: ConstraintChange) void {
switch (c) {
.same => {},
.tightened => self.tightened = true,
.loosened => self.loosened = true,
}
}
fn result(self: Accumulator) ConstraintChange {
if (self.tightened) return .tightened;
if (self.loosened) return .loosened;
return .same;
}
};
/// Classifies how the set of accepted values changed. Any tightening wins.
pub fn compareConstraints(from: ?Constraints, to: ?Constraints) ConstraintChange {
const empty = Constraints{};
const a = from orelse empty;
const b = to orelse empty;
var acc = Accumulator{};
acc.note(compareEnums(a.enum_values, b.enum_values));
acc.note(compareExactText(a.pattern_source, b.pattern_source));
acc.note(compareExactFormat(a.format, b.format));
acc.note(compareLower(u64, a.min_length, b.min_length));
acc.note(compareUpper(u64, a.max_length, b.max_length));
acc.note(compareLowerBound(a.minimum, b.minimum));
acc.note(compareUpperBound(a.maximum, b.maximum));
return acc.result();
}
fn compareEnums(from: ?[]const Constraints.EnumValue, to: ?[]const Constraints.EnumValue) ConstraintChange {
const old = from orelse return if (to == null) .same else .tightened;
const new = to orelse return .loosened;
for (old) |value| {
if (!enumContains(new, value)) return .tightened;
}
for (new) |value| {
if (!enumContains(old, value)) return .loosened;
}
return .same;
}
fn enumContains(list: []const Constraints.EnumValue, value: Constraints.EnumValue) bool {
for (list) |candidate| {
if (enumValueEql(candidate, value)) return true;
}
return false;
}
fn enumValueEql(a: Constraints.EnumValue, b: Constraints.EnumValue) bool {
return switch (a) {
.text => |at| switch (b) {
.text => |bt| std.mem.eql(u8, at, bt),
else => false,
},
.integer => |ai| switch (b) {
.integer => |bi| ai == bi,
.real => |br| @as(f64, @floatFromInt(ai)) == br,
.text => false,
},
.real => |ar| switch (b) {
.real => |br| ar == br,
.integer => |bi| ar == @as(f64, @floatFromInt(bi)),
.text => false,
},
};
}
fn compareExactText(from: ?[]const u8, to: ?[]const u8) ConstraintChange {
const old = from orelse return if (to == null) .same else .tightened;
const new = to orelse return .loosened;
return if (std.mem.eql(u8, old, new)) .same else .tightened;
}
fn compareExactFormat(from: ?Constraints.Format, to: ?Constraints.Format) ConstraintChange {
const old = from orelse return if (to == null) .same else .tightened;
const new = to orelse return .loosened;
return if (old == new) .same else .tightened;
}
/// A lower limit tightens when it appears or rises.
fn compareLower(comptime T: type, from: ?T, to: ?T) ConstraintChange {
const old = from orelse return if (to == null) .same else .tightened;
const new = to orelse return .loosened;
if (new > old) return .tightened;
if (new < old) return .loosened;
return .same;
}
/// An upper limit tightens when it appears or falls.
fn compareUpper(comptime T: type, from: ?T, to: ?T) ConstraintChange {
const old = from orelse return if (to == null) .same else .tightened;
const new = to orelse return .loosened;
if (new < old) return .tightened;
if (new > old) return .loosened;
return .same;
}
fn boundOrder(a: Constraints.Bound, b: Constraints.Bound) std.math.Order {
if (a == .integer and b == .integer) return std.math.order(a.integer, b.integer);
const af: f64 = switch (a) {
.integer => |i| @floatFromInt(i),
.real => |r| r,
};
const bf: f64 = switch (b) {
.integer => |i| @floatFromInt(i),
.real => |r| r,
};
return std.math.order(af, bf);
}
fn compareLowerBound(from: ?Constraints.Bound, to: ?Constraints.Bound) ConstraintChange {
const old = from orelse return if (to == null) .same else .tightened;
const new = to orelse return .loosened;
return switch (boundOrder(new, old)) {
.gt => .tightened,
.lt => .loosened,
.eq => .same,
};
}
fn compareUpperBound(from: ?Constraints.Bound, to: ?Constraints.Bound) ConstraintChange {
const old = from orelse return if (to == null) .same else .tightened;
const new = to orelse return .loosened;
return switch (boundOrder(new, old)) {
.lt => .tightened,
.gt => .loosened,
.eq => .same,
};
}
// ─── Unique constraints ──────────────────────────────────────────────────────
/// A target constraint whose ordered field list does not exist in the source
/// tightens; otherwise any difference (removal, reordering) loosens.
fn compareUnique(from: *const Table, to: *const Table) ConstraintChange {
for (to.unique_constraints) |constraint| {
if (!hasUnique(from, to, constraint)) return .tightened;
}
if (from.unique_constraints.len != to.unique_constraints.len) return .loosened;
for (from.unique_constraints, to.unique_constraints) |a, b| {
if (!sameUniqueFields(from, a, to, b)) return .loosened;
}
return .same;
}
fn hasUnique(haystack: *const Table, owner: *const Table, needle: types.UniqueConstraint) bool {
for (haystack.unique_constraints) |candidate| {
if (sameUniqueFields(haystack, candidate, owner, needle)) return true;
}
return false;
}
fn sameUniqueFields(a_table: *const Table, a: types.UniqueConstraint, b_table: *const Table, b: types.UniqueConstraint) bool {
if (a.field_indexes.len != b.field_indexes.len) return false;
const a_fields = a_table.userFields();
const b_fields = b_table.userFields();
for (a.field_indexes, b.field_indexes) |ai, bi| {
if (!std.mem.eql(u8, a_fields[ai].name, b_fields[bi].name)) return false;
}
return true;
}
// ─── Non-physical sections ───────────────────────────────────────────────────
fn metadataEqual(a: ?types.Metadata, b: ?types.Metadata) bool {
if (a == null or b == null) return a == null and b == null;
return std.mem.eql(u8, a.?.json, b.?.json);
}