Skip to content

docs: Document the ORM upsert methods#701

Open
marcelomendoncasoares wants to merge 2 commits into
serverpod:mainfrom
marcelomendoncasoares:docs/orm-upsert
Open

docs: Document the ORM upsert methods#701
marcelomendoncasoares wants to merge 2 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
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.

1 participant