Skip to content

docs: Rework the Data & the database section for 4.0#696

Open
developerjamiu wants to merge 1 commit into
mainfrom
concepts-phase3-section3-data-database
Open

docs: Rework the Data & the database section for 4.0#696
developerjamiu wants to merge 1 commit into
mainfrom
concepts-phase3-section3-data-database

Conversation

@developerjamiu

@developerjamiu developerjamiu commented Jul 21, 2026

Copy link
Copy Markdown
Contributor

Section-by-section deep rework of the Concepts area, part 3 of the series (after Server fundamentals in #687 and Endpoints & APIs in #693). This pass covers the Data & the database section: 22 pages across the models and database subgroups, plus the pages they touch.

Structure

  • Vector & geography fields moved from the models subgroup into the database subgroup, next to the query pages that use it.
  • Backward compatibility moved to Endpoints & APIs, where its rules (endpoint signatures, future calls) belong.
  • Database pages renumbered essentials-first: tables → CRUD → filtering → sorting → pagination → relations → relation queries → vector & geography → indexing → transactions → row locking → raw access → migrations → connection → runtime parameters → client-side database → exceptions.
  • New Relations landing page: the category label now opens a short orientation page with a "which shape when" table.
  • All inbound links updated; URL redirects for the two moved pages are queued for the 4.0 GA cutover (the old URLs only ever existed under /next).

Content highlights

  • New coverage for 4.0 surface: upsert (upsertRow/upsert with conflictColumns, updateColumns, updateWhere, noReturn), dynamic model fields, DatabaseResult, databaseInterceptor, Transaction.cancel(), the tail keyword, Uri/BigInt default values, the client-migrations pipeline, and a wire-format table for the built-in types.
  • Corrections: the --force/--empty conflation on migrations, the repair-migration directory name, a non-compiling filtering example (Dart operator precedence), the comparison-operator type list (String and UuidValue were missing), the inheritance table rule (only an ancestor with a table blocks a child; sibling branches may each define one), future-call compatibility rules rewritten around the real API, and the modules relation page rebuilt on serverpod_auth_core.
  • SQLite behavior documented where it diverges: like/ilike case rules, ignored isolation levels, row locking, vector/geography limits, and the simple-query methods.
  • Client-side database page rebuilt: enabling the database keyword, session lifecycle with close(), on-device migrations with runMigrations/isDebugMode, and a gathered list of SQLite differences.
  • Model reference gained rows for database, serializationDataType, column, operatorClass, and tail, and corrected the immutable, sealed, default, defaultModel, and unique rows against the CLI validators.

Every new technical claim was verified against the framework at 4.0.0-beta.0, and the upsert, cursor-pagination, and raw-access examples were run against a real project (12/12 tests green). Build passes with no broken links or anchors.

Advances #504.

@developerjamiu
developerjamiu requested a review from Zfinix July 21, 2026 09:07
@developerjamiu developerjamiu self-assigned this Jul 21, 2026
@developerjamiu developerjamiu added documentation Improvements or additions to documentation enhancement New feature or request labels Jul 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant