2.3.0

• Put Noora behind a new RichTerminal package trait, on by default with CLI and Migrations. With only CLI enabled, the spectro command prints plain text: alerts with their takeaways, progress steps, a [y/N] confirmation, and aligned tables. Roost enables only CLI, so roost spectro keeps working without fetching Noora.
• CI builds the spectro command without Noora.
• Report 2.3.0 from spectro --version and pin the Mint installation examples and the Mintfile to 2.3.0.

Full comparison with 2.2.0

2.2.0

• Put the spectro command's dependencies (ArgumentParser and Noora) behind the CLI package trait, and SpectroMigrations' ArgumentParser dependency behind the Migrations trait. Both are on by default. A package that only uses SpectroKit, such as a framework built on Spectro, can depend on it with traits: []; SwiftPM then skips fetching those tools' dependencies.
• Require Swift 6.1 (swift-tools-version 6.1), the first version with package traits. Swift 6.0 projects keep resolving Spectro 2.1.x.
• Report 2.2.0 from spectro --version and pin the Mint installation examples and the Mintfile to 2.2.0.

Full comparison with 2.1.1

2.1.1

• Depend on swift-syntax through its canonical swiftlang/swift-syntax URL. Packages that also depend on ESW no longer get SwiftPM's conflicting-identity warning, which future SwiftPM versions turn into an error.
• Report 2.1.1 from spectro --version and pin the Mint installation examples and the Mintfile to 2.1.1.

Full comparison with 2.1.0

2.1.0

Spectro 2.1.0 adds Swift migrations and browsable DocC documentation. This is an additive update from 2.0: existing SpectroKit consumers and SQL migration directories keep their APIs and workflow.

Swift migrations

• The optional SpectroMigrations product provides a declarative Swift DSL for tables, columns, indexes, references, and checks, with automatic rollback for reversible operations and explicit SQL or irreversible branches.
• Applications own their migration registry and compiled executable. Preview SQL offline, bundle existing SQL history, and deploy the executable with its resources without shipping SwiftPM or a compiler.
• spectro migrate init scaffolds the target. Generation, planning, migration, status, and rollback commands forward to the configured project executable and preserve its exit status and signals.
• Swift and SQL migrations share the same session lock and transactional execution engine. Rollback validates missing and irreversible history before changing the database.
• PostgreSQL statement splitting now handles quoted identifiers, escape strings, bind parameters, and nested comments correctly.
• Package discovery stops at the filesystem root, including on macOS, so SQL commands work in directories without a Swift package.

Documentation and CLI

The merged DocC site includes guides and API navigation for Spectro, SpectroMigrations, and SpectroCommon. CLI help now explains setup, configuration, previews, rollback defaults, and deployment with examples.

• Swift migration guide
• CLI reference
• Build and browse the DocC documentation
• Upgrade from 2.0

Validation

All 414 tests passed on macOS and Linux. Release CI also passed copied migration artifact checks on both platforms, deployment in a Linux container without a compiler or source checkout, HTTP application acceptance, and strict DocC validation. CI verification.

Install

.package(url: "https://github.com/Spectro-ORM/Spectro.git", from: "2.1.0")

mint install Spectro-ORM/Spectro@2.1.0
spectro --version

Full changelog · Changes since 2.0.0

2.0.0

Spectro 2.0 focuses on PostgreSQL correctness and application-level validation. It also includes the changeset, pagination, and soft-delete APIs added since 1.2.0.

Breaking changes

• Custom Repo conformers must implement insert(_ changeset:) and update(_ changeset:). Spectro's built-in repositories already implement both requirements, including inside transactions.
• Model-returning right joins now throw because their result types cannot represent an absent main model. Reverse the query and use a left join. Typed self joins and repeated tables are rejected until table aliases are supported; typed left joins require a nonnullable primary key on the joined schema.
• Typed joined reads now throw when a present row cannot be decoded, instead of substituting default values or silently omitting it.
• Migration runners require a direct or session-pooled connection and transaction-compatible SQL. Use the 2.0 runner consistently when multiple processes can migrate the same database.

See the upgrade guide for migration examples and operational changes.

Added

• Changesets with permitted-field casting, validators, serializable errors, uniqueness checks, and repository insert/update support.
• Query.page(size:page:) with total counts and navigation metadata.
• Opt-in soft deletes with @SoftDelete and .withDeleted().
• A public-API IssueTracker HTTP application and repeatable acceptance command covering transactions, joined reads, competing writes, populated migrations, rollback/reapply, and restart persistence.

Fixed

• @Schema recognizes @SoftDelete, generates filtering metadata, and preserves deletion timestamps in decoded models and JSON.
• Migration SQL and status recording now use the same transaction. Competing migration commands serialize through a PostgreSQL advisory lock, with bounded lock waiting and cancellation cleanup.
• Joined models decode from separate projections, preserving IDs, timestamps, custom column mappings, and nullable fields without column collisions. An unmatched left-joined model is nil.
• Query parameters follow SQL order across joins, filters, and HAVING clauses; soft-delete filters are qualified in joined queries.
• Changeset casting rejects invalid field types and non-finite numbers before persistence. Both repositories honor custom column names.
• Recursive error formatting no longer crashes when reporting SpectroError; transaction failures preserve the original error after successful rollback.
• Database connections honor configured TLS settings and reject invalid settings before allocating event-loop threads.
• Fresh-database migration commands initialize their tracking state, while migration status remains read-only.
• CI propagates test failures. Acceptance build artifacts use a local cache to avoid macOS signing failures caused by Finder metadata in cloud-synced folders.

Compatibility and validation

• Spectro requires Swift 6.0+ and supports macOS 13+ and Linux with PostgreSQL.
• All 368 PostgreSQL-backed tests passed on macOS and Linux with Swift 6.0.3, including concurrent migration processes, cancellation, and macro-defined soft deletes. HTTP acceptance passed with Swift 6.3.3 and Xcode 26.3. CI verification.
• Building the IssueTracker acceptance application requires Swift 6.3+ and an Xcode 26.3+ SDK on a compatible host (macOS 15.6+ for Xcode 26.3); its package deployment target is macOS 14. Its pinned Peregrine 1.2.0 dependency currently prevents that example from building on Linux; Spectro's core Linux support is unaffected.

Full comparison with 1.2.0

1.2.0

Encodable Schema Conformance

The @Schema macro now auto-generates Encodable conformance, so schema types can be passed directly to JSONEncoder without manually constructing dictionaries.

// Before — manual mapping
return try conn.json(value: donuts.map { d in
    ["id": "\(d.id)", "name": d.name, "price": "\(d.price)"]
})

// After — direct encoding
return try conn.json(encodable: donuts)

What's new

• Auto-generated Encodable — CodingKeys enum and encode(to:) method generated at compile time for all @Schema types
• Snake_case JSON keys — createdAt → "created_at", matching database column convention
• @Column("custom") overrides — custom column names are used as JSON keys
• Smart relationship encoding — @HasMany, @HasOne, @BelongsTo, @ManyToMany fields are included only when loaded; omitted entirely when .notLoaded
• Opt-out — @Schema("secrets", encodable: false) skips Encodable generation

Fixes

• Fixed CLI tests for Noora styled output in non-interactive environments
• Fixed CI false positives from skipped tests being reported as failures
• Disabled two transaction tests that trigger Swift 6 SIGBUS (runtime bug, not Spectro bug)

1.1.1

Full Changelog: https://github.com/Spectro-ORM/Spectro/commits/1.1.1