--- title: "Release Notes v0.4.3" description: "Release notes for RoomSharp 0.4.3" canonical: "https://roomsharp.dev/docs/v0.5.3/release-notes-0-4-3" source: "src/content/v0.5.3/release-notes-0-4-3.mdx" --- # RoomSharp 0.4.3 – Release Notes ## Highlights - Migration engine overhaul: strict pathing, transaction-bound execution, durable journaling, dirty-state protection, and cross-process provider locks. - Concurrency overhaul: safe-by-default serialized execution, with opt-in true parallel DB I/O using connection-per-operation sessions. - Mapper cache moved to runtime (owned by `RoomDatabase`): smaller generated output while preserving allocation-free hit path. - **New packages released:** - **RoomSharp.Cli** – command-line tool for scaffolding, migrations, schema export/validation, inspection, and safe diagnostics. - **RoomSharp.QueryExtensions** – high-performance raw SQL helpers for ad-hoc queries without DAOs. --- ## New Features ### Migrations (Runtime Engine) - New metadata tables: - `__room_state` (single-row state) - `__room_migrations` (append-only journal) - New migration API: - `IRoomMigration` + `MigrationContext` (transaction-safe command creation) - Strict pathing enforcement: migrations apply only when `StartVersion == currentVersion` (no gaps / no branching). - Journaling: records identity, checksum, timing, success/failure, and error details. - Dirty-state safety: blocks re-entry when `dirty=1` with deterministic recovery behavior. - Cross-process provider locks: - PostgreSQL: `pg_advisory_lock` - SQL Server: `sp_getapplock` - MySQL: `GET_LOCK` - SQLite: early write lock + busy timeout - Backward-compatible legacy support via `LegacyMigrationAdapter` (transaction-bound execution). ### Threading & Concurrency (Runtime) - Added `ConcurrencyMode`: - `Serialized` (default): a DB gate ensures safe execution in multi-threaded apps. - `Parallel` (opt-in): true parallel DB execution via multiple connections (provider pooling). - Added session-based execution primitives: `IRoomDatabaseFactory`, `DbSession`, `PooledRoomDatabaseFactory`. - Added Unit-of-Work support for explicit transactional scopes on a single session/connection. ### Mapper Cache (Runtime) - Introduced `MapperCache` + `TypeMapperCache` owned by `RoomDatabase` (replaces per-DAO static caches). - Preserved two-level keying (fast hash key + exact key fallback) with bounded eviction via queue (no dictionary enumeration). - Dialect safety preserved by including `DatabaseType` in layout keys. ### New Package: RoomSharp.Cli - CLI and runtime share the same migration engine (CLI loads the compiled application assembly and executes the same pipeline). - Migration workflow: - `migrate:plan` – prints the exact migration chain that would be applied (strict pathing enforced). - `migrate:up` – applies migrations using the runtime migration pipeline. - `migrate:verify` – verifies applied migrations against recorded checksums in `__room_migrations`. - `migrate:set-version --to=N --force` (DANGEROUS) – edits `__room_state` only; does not revert schema (recovery-only). - Safety defaults: - `-b/--build` auto-builds before runtime commands; `-r/--release` forces Release build - scaffolding supports `--dry-run` and requires `--force` to overwrite - `query` blocks write operations by default; requires `--allow-writes` ### Dependency Injection (RoomSharp.DependencyInjection) - Added `ServiceLifetime` parameter to all `AddRoomSharpDatabase(...)` overloads. - Added `AddRoomSharpScopedDatabase()` shorthand for scoped registration. - Added `AddRoomSharpDatabaseFactory()` with `IRoomDatabaseFactory` for background services and Blazor Server. - Added provider shortcuts in builder context: `UseSqlServer()`, `UsePostgres()`, `UseMySql()`. ### New Package: RoomSharp.QueryExtensions - Introduced `RoomSharp.QueryExtensions` for ad-hoc / high-performance SQL without DAOs. - Provides direct raw SQL helpers integrated with RoomSharp (querying, executing, streaming, and transaction helpers). --- ## Improvements ### Migrations - Guaranteed transaction-bound execution for migration steps (no commands executed outside the started transaction). - Safer upgrade path from legacy `__room_metadata` to the new tables. - Optional fields in `__room_state`: `app_id`, `roomsharp_version`, `schema_hash` (with backfill support). ### Concurrency - Default multi-thread safety: concurrent DAO calls on the same `RoomDatabase` instance are serialized safely. - Parallel mode uses independent connections per operation (no parallel commands on a single connection). ### Performance - Allocation-free mapper cache hit path preserved (no `string.Join`, no `string[]` per row, no exact-key builds on hits). - Reduced generated code size by relocating cache infrastructure to runtime. - Native bulk insert engines for major providers with automatic fallback. - Batch inserts are fully asynchronous and cancellation-aware. - Streaming support in `[Query]` via `IAsyncEnumerable`. ### Provider Updates - MySQL provider: switched internal driver from `MySql.Data` to **MySqlConnector** (performance and licensing considerations). No application-level changes are required. ### Developer Experience - Improved conflict resolution handling for `Replace` and `Ignore`. - Improved diagnostics and compile-time validation. --- ## Fixes ### Migrations - Fixed commands sometimes executing outside the started transaction (now reliably bound to `DbTransaction`). - Fixed selection applying non-sequential ranges; strict chain enforcement prevents gaps/branching. - Fixed auto-migration dialect detection when using transaction-bound legacy connection wrappers. ### Concurrency - Fixed hazards from shared `DbConnection`/`DbCommand` reuse by introducing serialized execution by default. - Implemented true parallel execution via multiple connections (opt-in), instead of parallel commands on a single connection. ### General - Fixed silent failure of native bulk insert on unsupported providers. - Fixed incorrect `Id = 0` behavior in `OnConflict.Replace` inserts. - Fixed incorrect upsert behavior on auto-generated primary keys. - Fixed duplicated diagnostics in the source generator. - Fixed async methods generated without `await`. --- ## Breaking / Behavioral Changes - `__room_metadata` is deprecated; new installs use `__room_state` + `__room_migrations`. - Existing databases are upgraded automatically when possible. - `QueryExecutor` and `[RawQuery]` have been removed. - Use the **new** `RoomSharp.QueryExtensions` package instead. --- ## Upgrade Notes (Recommended) - Preview the exact migration chain: - `room migrate:plan -b` - Apply and verify: - `room migrate:up -b` - `room migrate:verify -b` - If you previously used `[RawQuery]`: - migrate to the **new** `RoomSharp.QueryExtensions` package. - For dirty-state recovery: - prefer restoring from a backup in production; use `migrate:set-version --force` only when you fully understand the consequences.