Skip to content

docs: Document database interceptors#702

Merged
developerjamiu merged 5 commits into
serverpod:mainfrom
marcelomendoncasoares:docs/database-interceptor
Jul 23, 2026
Merged

docs: Document database interceptors#702
developerjamiu merged 5 commits into
serverpod:mainfrom
marcelomendoncasoares:docs/database-interceptor

Conversation

@marcelomendoncasoares

@marcelomendoncasoares marcelomendoncasoares commented Jul 21, 2026

Copy link
Copy Markdown
Collaborator

Summary

The Serverpod constructor and the withServerpod test helper accept a databaseInterceptor callback that decides what Session.db returns. Nothing in the docs covered it.

Changes

  • Add a "Database interceptors" page at the end of the database section, so it does not interrupt the normal CRUD path.
  • Show the callback signature, that it receives the session and the framework database, and that it is called once per session.
  • Show returning a custom Database implementation and list what it is useful for: tracing, metrics, tenant scoping, policy checks, and safety guards.
  • Note that a policy layer has to cover raw access and transactions to be effective.
  • Carry over the API stability warning from the implementation: custom layers depend on serverpod_database, which can change in a breaking way in a minor release.
  • Show the same callback in a withServerpod test and add databaseInterceptor to the test helper configuration table.
  • Cross-link from the raw access page.

Reference

marcelomendoncasoares and others added 5 commits July 21, 2026 15:35
Give the page a noun-shaped title like its sibling database pages, drop
the counter from the introductory example, link the related database
pages instead of listing concepts in prose, correct the argument order in
the withServerpod example, and add databaseInterceptor to the test helper
configuration table.
…ptor

# Conflicts:
#	docs/06-concepts/03-data-and-the-database/02-database/12-raw-access.md
@developerjamiu
developerjamiu marked this pull request as ready for review July 23, 2026 11:26
@developerjamiu developerjamiu added the documentation Improvements or additions to documentation label Jul 23, 2026

@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 merged commit 965c842 into serverpod:main Jul 23, 2026
4 checks passed
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