Skip to content

Redesign fluent API with explicit table selection - #193

Merged
jogibear9988 merged 1 commit into
masterfrom
codex/fluent-api-explicit-tables
Sep 23, 2026
Merged

jogibear9988 merged 1 commit into
masterfrom
codex/fluent-api-explicit-tables

Conversation

@jogibear9988

Copy link
Copy Markdown
Member

The unreleased fluent API mixes object names and table names in positional arguments, making migrations hard to read and easy to misconfigure. Replace those overloads with staged expressions that make the target table and the next supported step explicit.

migration.Create.Column("Email").OnTable("Users").AsString(320);
migration.Alter.Column("Name").OnTable("Users").AsString(200);
migration.Rename.Column("Name").OnTable("Users").To("DisplayName");
migration.Delete.Column("Email").FromTable("Users");

migration.Create.Index("IX_Users_Email")
    .OnTable("Users").WithColumns("Email").Unique();
migration.Create.ForeignKey("FK_Orders_Users")
    .FromTable("Orders").WithColumns("UserId")
    .ToTable("Users").WithColumns("Id")
    .OnDelete(ForeignKeyConstraintType.Cascade);

API changes

  • Apply explicit table selection to columns, indexes, constraints, foreign keys, views, renames, removals, data transfers, and schema reads. Remove the old positional fluent overloads.
  • Share column type/options methods across table definitions, additions, and alterations. Each column handle stays bound to its own column; named fluent columns require an explicit type.
  • Split insert, update, and delete into distinct builders exposing only valid steps. Each insert describes one row. Updates and deletes must finish with a predicate or explicit AllRows().
  • Register expressions in authoring order and reject incomplete chains during Build, Apply, or Preview, before any queued operation executes. Reject duplicate completion and retain independent snapshots of mutable definitions.
  • Rename IfDatabase to IfProvider; move table selections to Schema.Table(table).Select(...) / .SelectScalar(...).
  • Make AsDateTime() map to DbType.DateTime; add AsDateTime2() for the former mapping.

Execution fixes and documentation

Correct provider overload selection for unfiltered updates and scalar reads, and quote table names for scalar reads and unfiltered deletion. Add regression coverage for incomplete chains, provider dispatch, column handles, snapshots, composite foreign keys, quoted names, and SQLite schema/data changes.

Update the README, manual sources, generated website and search index, capability inventory, breaking-change guide, and runnable fluent quick start. The quick start now previews, applies, and automatically reverses an added column and index.

This intentionally breaks the unreleased fluent API. The migration guide documents the replacement syntax and behavior changes. This PR is based directly on master and contains only the fluent API work.

Validation

  • Solution build passed.
  • Unit suite: 584 passed, zero skipped.
  • SQLite suite: 306 passed, zero skipped.
  • 106 published C# samples compiled, with 8 Classic/Fluent SQLite parity checks passing.
  • Generated documentation, local links, anchors, search entries, and paired examples verified, including after rebasing onto master.
  • Fluent quick-start preview, migration, and automatic rollback passed.
  • External database suites were not run locally.

Replace ambiguous positional table arguments in the unreleased fluent API
with staged expressions: Create/Alter.Column(name).OnTable(table),
Delete.Column(name).FromTable(table), and Rename.Column(name).OnTable(table)
.To(newName). Apply the same explicit table selection to indexes, named
constraints, foreign keys, views, data transfers, and schema reads.

- Share column type/options methods across table, create, and alter builders.
  Keep each column handle bound to its own column and snapshot mutable input.
- Split insert/update/delete into builders exposing only supported operations.
  Require Where, WhereSql, or explicit AllRows for updates and deletes.
- Reject unfinished expressions at Build, Apply, and Preview before execution,
  preserve expression ordering, and reject duplicate completion.
- Rename IfDatabase to IfProvider and map AsDateTime to DbType.DateTime,
  with a distinct AsDateTime2 helper for DbType.DateTime2.
- Fix unfiltered updates and scalar reads to select the correct provider
  overloads; quote table names for scalar reads and unfiltered deletion.
- Update README, manual source, generated website/search index, capability
  inventory, breaking-change guide, and the runnable fluent quick start.
- Add regressions for incomplete chains, dispatch, column handles, snapshots,
  composite foreign keys, quoted names, and SQLite schema/data execution.

Validation:
- Solution build passed.
- Unit suite: 584 passed, zero skipped.
- SQLite suite: 306 passed, zero skipped.
- Documentation: 106 C# samples compiled and 8 SQLite parity checks passed.
- Generated docs, links, anchors, and paired examples verified.
- Fluent quick-start preview, migration, and automatic rollback passed.
- External database suites were not run locally.

BREAKING CHANGE: Remove the old positional fluent overloads and shared data
builder. Named fluent columns now require an explicit type; unfiltered
update/delete requires AllRows. Existing fluent consumers must adopt the
staged methods documented in the migration guide. This API is unreleased.
Copilot AI lite review requested due to automatic review settings September 23, 2026 09:32

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@jogibear9988
jogibear9988 merged commit 496c035 into master Sep 23, 2026
13 of 14 checks passed
@jogibear9988
jogibear9988 deleted the codex/fluent-api-explicit-tables branch September 23, 2026 09:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants