Skip to content

docs: Document the ORM upsert methods#701

Merged
developerjamiu merged 5 commits into
serverpod:mainfrom
marcelomendoncasoares:docs/orm-upsert
Jul 22, 2026
Merged

docs: Document the ORM upsert methods#701
developerjamiu merged 5 commits into
serverpod:mainfrom
marcelomendoncasoares:docs/orm-upsert

Conversation

@marcelomendoncasoares

@marcelomendoncasoares marcelomendoncasoares commented Jul 21, 2026

Copy link
Copy Markdown
Collaborator

Summary

upsertRow and the batch upsert are generated on every table model but were missing from the CRUD page, so there was no documented way to insert-or-update a row.

Changes

  • Add an "Upsert" section to the CRUD page, right after Create and its conflict handling.
  • Extend the shared Company example model with a unique name, address, employeeCount, and isActive, so the conflict examples have something to conflict on. The address field was already used by an existing example on the page but missing from the model.
  • Show upsertRow with conflictColumns, and explain the default update set.
  • State that the primary id column can be a conflict target.
  • Document updateColumns and updateWhere, and explain why upsertRow returns a nullable value.
  • Document the batch upsert: atomicity, transaction support, a result that can be shorter than the input, and noReturn.
  • Explain how non-persistent fields behave.

Reference

Use a single-word heading in line with Create, Read, Update, and Delete,
give the single-row case its own subsection so it mirrors the Create
section, switch to gerund subheadings, and link the transactions and
filtering pages instead of naming the concepts in passing.
@marcelomendoncasoares
marcelomendoncasoares marked this pull request as ready for review July 21, 2026 18:40
@marcelomendoncasoares
marcelomendoncasoares requested a review from a team July 21, 2026 18:40
@marcelomendoncasoares
marcelomendoncasoares marked this pull request as draft July 21, 2026 18:52
@marcelomendoncasoares
marcelomendoncasoares marked this pull request as ready for review July 21, 2026 18:58

@developerjamiu developerjamiu left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

LGTM

@developerjamiu
developerjamiu enabled auto-merge (squash) July 22, 2026 17:37
@developerjamiu
developerjamiu merged commit 41c7b33 into serverpod:main Jul 22, 2026
4 checks passed
@marcelomendoncasoares
marcelomendoncasoares deleted the docs/orm-upsert branch July 22, 2026 17:41
@developerjamiu developerjamiu added the documentation Improvements or additions to documentation label Jul 22, 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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants