Skip to content

Refresh documentation and highlight automatic SQLite schema reconstruction #190

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jogibear9988 merged 1 commit into from
Sep 23, 2026
Merged

Refresh documentation and highlight automatic SQLite schema reconstruction #190

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 46 additions & 40 deletions README.md
View file
Open in desktop

Large diffs are not rendered by default.

6 changes: 4 additions & 2 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,9 @@ All site assets use relative URLs, so the repository subpath works without a cus

## Keep the comparison accurate

The comparison distinguishes source capabilities from guarantees about released packages or database compatibility. Update the review date and source links together when reviewing it. Avoid equating transaction rollback with reversing completed migrations, treating a provider enum as a support guarantee, or assuming scopes isolate physical tables. The v13 runner filters explicitly scoped migrations and lets unscoped migrations inherit its effective scope.
The comparison distinguishes source capabilities from guarantees about released packages or database compatibility. Update the review date and source links together when reviewing it. Avoid equating transaction rollback with reversing completed migrations, treating a provider enum as a support guarantee, or assuming scopes isolate physical tables. The runner filters explicitly scoped migrations and lets unscoped migrations inherit its effective scope.

The quick start targets the unreleased v13 source's .NET 9 API and references the source project. Check the selected NuGet release's target frameworks. The SQLite driver version matches the repository test dependency. Validate authoring and runner snippets together when changing them.
The quick start targets the current repository’s .NET 9 API and references the source project. Check the selected NuGet release's target frameworks. The SQLite driver version matches the repository test dependency. Validate authoring and runner snippets together when changing them.

## Status badges and test counts

Expand All @@ -41,3 +41,5 @@ The renderer only changes the uploaded Pages artifact; it does not commit genera

Keep the homepage, README summary and detailed comparison aligned. The fluent homepage
example replaces the imperative version-1 class and uses the same quick-start runner.

Present capabilities as ordinary features, without version-specific preview banners. Keep version numbers in the upgrade guide where they explain compatibility changes. Highlight automatic live-schema SQLite reconstruction in the homepage and README, distinguishing it from EF Core's model-based rebuilds and SQL runners' author-written scripts. Retain preservation limits and links to the operation matrix.
2 changes: 1 addition & 1 deletion docs/additional-database-qualification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ This is an implementation gate, not a claim of released provider support.

| Additional engine | Real-engine GitHub Actions route | Current disposition |
| --- | --- | --- |
| SAP HANA | Official HANA Express Linux container and SAP's .NET driver, disposable schema | Implemented in the v13 source stack with a mandatory actual-engine matrix job; require green PR checks before merge |
| SAP HANA | Official HANA Express Linux container and SAP's .NET driver, disposable schema | Implemented with a mandatory actual-engine matrix job; require green PR checks before merge |
| Amazon Redshift | AWS test warehouse/serverless endpoint with CI credentials, network access and resource cleanup | No configured test infrastructure; defer provider |
| Snowflake | Snowflake test account, warehouse, credentials and disposable database/schema | No configured test infrastructure; defer provider |
| Db2 for IBM i | IBM i endpoint on Power infrastructure and compatible .NET/ODBC driver | No configured test infrastructure; defer provider |
Expand Down
2 changes: 1 addition & 1 deletion docs/fluent-operation-coverage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ The machine-readable [inventory](fluent-operation-coverage.json) maps every name
| Drop/rename operations | `Delete` / `Rename` | SQLite schema tests, reversal tests; destructive changes need explicit reverse definitions |
| Inserts, conditional insert, update, delete | `Insert`, `Update`, `Delete.FromTable` | FluentDataChangesAndSchemaReadsPersistExpectedRows |
| Truncate, data copy, update from another table | `Execute.Truncate/CopyData/UpdateFrom` | Normal provider tests; mutable pair snapshot regression |
| SQL, files, resources | `Execute.Sql/Script/EmbeddedScript` | SQL execution/preview tests; provider-specific batch splitting is separate work |
| SQL, files, resources | `Execute.Sql/Script/EmbeddedScript` | SQL execution/preview tests; SQL Server GO batch splitting through the script APIs, with explicit rejection of unsupported client directives |
| Scalars/readers/existence/metadata | `Schema`, `Schema.Table`, `Select`, `SelectScalar` | Reader disposal and persisted-data assertions; nullable helpers are additive |
| Database administration | `Administration` | Typed operations flag transaction incompatibility; backend capabilities still apply |
| Provider conditions, commands/connections | `IfDatabase`, `Execute.WithCommand/WithConnection/WithProvider` | Inactive reversal, explicit preview rejection; callbacks execute trusted code |
Expand Down
105 changes: 82 additions & 23 deletions docs/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta
name="description"
content="DotNetProjects.Migrator: versioned database migrations in C#, independent of your ORM. Use imperative or fluent migrations and compare FluentMigrator, EF Core, DbUp and Evolve."
content="DotNetProjects.Migrator: versioned database migrations in C#, independent of your ORM. Imperative and fluent APIs, automatic SQLite schema reconstruction, and a comparison with FluentMigrator, EF Core, DbUp and Evolve."
/>
<meta name="theme-color" content="#101a2d" />
<title>Migrator.NET — Database changes, in your code.</title>
Expand Down Expand Up @@ -38,7 +38,7 @@
<h1>Database changes.<br /><span>Part of your code.</span></h1>
<p class="intro">
Write schema changes in C# with imperative or fluent APIs. Version them with your application.
Run them with the database provider and ORM you choose.
Run them with the database provider and ORM you choose. Rebuild SQLite tables automatically from their live schema, without an ORM model.
</p>
<div class="actions">
<a class="button primary" href="#quick-start"
Expand Down Expand Up @@ -134,11 +134,39 @@ <h3>Separate histories by scope</h3>
</article>
</div>
</section>
<section class="quick-section" id="version-13" aria-labelledby="v13-title">
<section class="section container" id="sqlite" aria-labelledby="sqlite-title">
<p class="eyebrow">SQLITE SCHEMA MIGRATIONS</p>
<h2 id="sqlite-title">Change existing tables. Keep your data.</h2>
<p>Migrator reads the live SQLite schema and automatically rebuilds tables for
supported column type, nullability and default changes, plus primary, foreign,
unique and check constraint changes. No ORM model is required.</p>
<div class="features-grid">
<article>
<h3>Automatic reconstruction</h3>
<p>FluentMigrator leaves general column alterations and later foreign-key changes
to manual reconstruction. DbUp and Evolve execute your scripts. EF Core also
rebuilds tables, using artifacts represented in its model.</p>
</article>
<article>
<h3>Preserve supported schema details</h3>
<p>Rebuilds retain mapped rows, named and composite keys, column collations,
supported indexes and triggers, and AUTOINCREMENT high-water state.
Foreign keys retain independent update and delete actions.</p>
</article>
<article>
<h3>Explicit preservation limits</h3>
<p>Reconstruction rejects generated columns, STRICT and WITHOUT ROWID tables,
and indexes with explicit collations. Hidden rowid values can change;
arbitrary dependent SQL requires a migration plan.</p>
</article>
</div>
<p><a href="https://github.com/dotnetprojects/Migrator.NET/blob/master/docs/migration-framework-comparison.md#sqlite-emulation-comparison">Compare SQLite operations, sources and preservation limits →</a></p>
</section>
<section class="quick-section" id="schema-api" aria-labelledby="schema-title">
<div class="container">
<div class="section-heading">
<div><p class="eyebrow">VERSION 13 · SOURCE PREVIEW</p><h2 id="v13-title">Explicit definitions, shared authoring.</h2></div>
<p>Breaking source changes. These features are not yet a released NuGet version.</p>
<div><p class="eyebrow">SCHEMA DEFINITIONS</p><h2 id="schema-title">Explicit definitions, shared authoring.</h2></div>
<p>Named constraints, explicit defaults and provider-aware collations.</p>
</div>
<p>Define primary, unique, foreign-key and check constraints as table objects.
The imperative and fluent APIs share column definitions, trusted SQL defaults and typed collation requests.</p>
Expand All @@ -149,10 +177,15 @@ <h3>Separate histories by scope</h3>
.WithColumn("Id").AsString(27)
.WithDefaultValue(RawSql.Insert("ksuid_new()"))
.WithColumn("Name").AsString(100)
.WithCollation(Collation.CaseInsensitive);</code></pre></div>
.WithCollation(Collation.AsciiIgnoreCase);</code></pre></div>
<p>The target database must supply the SQL function. Collation mappings have explicit provider limits:
SQLite ASCII folding does not satisfy a Unicode case-insensitive request.
<a href="https://github.com/dotnetprojects/Migrator.NET/blob/master/docs/migration-guide-12.1-to-13.md">Read the 12.1-to-13 migration guide ↗</a>.</p>
The SQLite example uses ASCII-only NOCASE; it does not satisfy a Unicode case-insensitive request.
<a href="https://github.com/dotnetprojects/Migrator.NET/blob/master/docs/migration-guide-12.1-to-13.md">Read the migration guide ↗</a>.</p>
<p>Use <code>TimeOnly</code> for time-of-day values and <code>TimeSpan</code> for intervals.
<a href="https://github.com/dotnetprojects/Migrator.NET/blob/master/docs/data-type-boundary-tests.md">Review type support, precision and data limits by provider</a>.</p>
<p>Runner options support tags, named profiles, ordered maintenance and consolidated history.
Integrate migration constructors and lifecycle logging with the optional Microsoft DI package.
<a href="https://github.com/dotnetprojects/Migrator.NET/blob/master/docs/runner-guide.md">Explore runner and deployment options</a>.</p>
<p>Additional databases require passing real-engine CI.
<a href="https://github.com/dotnetprojects/Migrator.NET/pull/182">SAP HANA provider qualification ↗</a>;
Redshift, Snowflake and Db2 for IBM i remain unsupported.</p>
Expand All @@ -170,14 +203,14 @@ <h3>Separate histories by scope</h3>
<h2 id="start-title">From code to schema.</h2>
</div>
<p>
A minimal SQLite example for <strong>unreleased v13 source</strong>.<br />
A minimal SQLite example using the current repository API.<br />
Use .NET 9 and a checkout of this repository.
</p>
</div>
<div class="step">
<div class="step-description">
<span class="step-index">1</span>
<h3>Reference the v13 source</h3>
<h3>Reference the library</h3>
<p>
Run these commands from your Migrator.NET checkout. This example references
the source project and passes an open SQLite connection to the provider.
Expand Down Expand Up @@ -298,7 +331,7 @@ <h3>Run pending migrations</h3>
<section class="section container" id="fluent-api" aria-labelledby="fluent-title">
<div class="section-heading">
<div>
<p class="eyebrow">FLUENT API · V13 SOURCE PREVIEW</p>
<p class="eyebrow">FLUENT API</p>
<h2 id="fluent-title">Chain operations. Keep control.</h2>
</div>
<p>Use fluent and imperative migrations in the same assembly and runner.</p>
Expand Down Expand Up @@ -384,7 +417,7 @@ <h3>Additional dialects in source</h3>
<li>Firebird</li>
<li>Ingres</li>
<li>Sybase</li>
<li>SAP HANA (v13 source)</li>
<li>SAP HANA</li>
</ul>
</div>
</div>
Expand All @@ -393,12 +426,12 @@ <h3>Additional dialects in source</h3>
server or driver version. Schema operations and transactional DDL vary
by provider. Check the
<a
href="https://github.com/dotnetprojects/Migrator.NET/blob/eabec5561c2c9c77847b9adbb7b67474e3c70a50/src/Migrator/ProviderFactory.cs"
href="https://github.com/dotnetprojects/Migrator.NET/blob/482b4d1b2a0a3672c3199c533a69cc4da330b8d6/src/Migrator/ProviderFactory.cs"
>provider factory</a
>
and
<a
href="https://github.com/dotnetprojects/Migrator.NET/tree/eabec5561c2c9c77847b9adbb7b67474e3c70a50/src/Migrator.Tests/Providers"
href="https://github.com/dotnetprojects/Migrator.NET/tree/482b4d1b2a0a3672c3199c533a69cc4da330b8d6/src/Migrator.Tests/Providers"
>provider tests</a
>
for your database.
Expand Down Expand Up @@ -427,16 +460,16 @@ <h2 id="tests-title">Evidence from CI.</h2>
<h2 id="compare-title">Choose by how you work.</h2>
</div>
<p>
Feature comparison · Reviewed 22 September 2026<br /><a
Feature comparison · Reviewed 23 September 2026<br /><a
href="#sources"
>Read the sources and qualifications ↓</a
>
</p>
</div>
<p class="comparison-intro"><strong>Version 13 source preview, not a NuGet release:</strong>
fluent operations, SQL-preview subset, runner options, native locks and source CLI.
<a href="https://github.com/dotnetprojects/Migrator.NET/blob/master/docs/runner-guide.md">Read the runner guide and limitations</a>.
<a href="https://github.com/dotnetprojects/Migrator.NET/pull/177">Read the merged runner changes</a>.
<p class="comparison-intro">
Use fluent operations, version planning, a SQL-preview subset, runner options,
native locks and the CLI.
<a href="https://github.com/dotnetprojects/Migrator.NET/blob/master/docs/runner-guide.md">Read the runner guide and provider limits</a>.
</p>
<p class="comparison-intro">
Migrator fits applications that want explicit C# migrations and
Expand Down Expand Up @@ -560,7 +593,7 @@ <h2 id="compare-title">Choose by how you work.</h2>
</tr>
<tr>
<th scope="row">Execution / deployment</th>
<td class="ours">Library + source CLI (unreleased)</td>
<td class="ours">Library + CLI</td>
<td>In-process runner + CLI</td>
<td>CLI, SQL scripts, bundles, runtime API</td>
<td>Library; host in a console app or application</td>
Expand All @@ -584,6 +617,30 @@ <h2 id="compare-title">Choose by how you work.</h2>
<td><code>RunAlways</code> scripts</td>
<td>Repeatable SQL reruns on checksum change</td>
</tr>
<tr>
<th scope="row">Automatic SQLite reconstruction</th>
<td class="ours">Live-schema rebuilds; no ORM model</td>
<td>Manual for general column and foreign-key alterations</td>
<td>Rebuilds for model-represented artifacts</td>
<td>Author scripts</td>
<td>Author scripts</td>
</tr>
<tr>
<th scope="row">Planning and SQL preview</th>
<td class="ours">Read-only version plan; connected/offline SQL subset</td>
<td>Preview/output</td>
<td>Generated SQL scripts</td>
<td>Authored SQL / pending scripts</td>
<td>Authored SQL</td>
</tr>
<tr>
<th scope="row">Deployment coordination</th>
<td class="ours">Opt-in native locks: SQL Server, PostgreSQL, MySQL/MariaDB</td>
<td>Application-lock pattern / deployment orchestration</td>
<td>Migration locking; execution-path dependent</td>
<td>Host/provider concern</td>
<td>Cluster setting; provider-dependent</td>
</tr>
</tbody>
</table>
</div>
Expand All @@ -609,7 +666,7 @@ <h2 id="compare-title">Choose by how you work.</h2>
<h3>Keep migrations in C#</h3>
<p>
<strong>Migrator:</strong> imperative and fluent schema operations, scoped
history, tags/profiles, and a source CLI or your own host.
history, tags/profiles, and the CLI or your own host.
<strong>FluentMigrator:</strong> a fluent DSL with packaged
runners, tags and profiles.
</p>
Expand All @@ -636,7 +693,7 @@ <h3>Keep SQL as the source</h3>
<p>
Our column is based on the current repository source, which
targets <code>net9.0</code>. Other columns summarize official
documentation reviewed on 22 September 2026, rather than claiming
documentation reviewed on 22 September 2026, with SQLite comparisons rechecked on 23 September, rather than claiming
parity across every released package. Check your chosen release,
provider and database version. Suitability notes are our
interpretation of these documented capabilities.
Expand Down Expand Up @@ -687,6 +744,7 @@ <h3>Keep SQL as the source</h3>
href="https://fluentmigrator.github.io/migration-types/profiles.html"
>profiles</a
>,
<a href="https://github.com/fluentmigrator/fluentmigrator/blob/2e0acdb7c375b03e50e65f34ddf50e44ee45df30/src/FluentMigrator.Runner.SQLite/Generators/SQLite/SQLiteGenerator.cs">SQLite generator</a>,
<a href="https://fluentmigrator.github.io/"
>authoring and providers</a
>.
Expand Down Expand Up @@ -716,7 +774,8 @@ <h3>Keep SQL as the source</h3>
<a
href="https://learn.microsoft.com/en-us/ef/core/modeling/data-seeding"
>seeding</a
>.
>,
<a href="https://learn.microsoft.com/en-us/ef/core/providers/sqlite/limitations">SQLite rebuilds and locking</a>.
</li>
<li id="source-dbup">
<strong>DbUp:</strong>
Expand Down
Loading
Loading