From 51d39174211c5bacaa5ec3a120ea4e0e8eeca9fb Mon Sep 17 00:00:00 2001 From: d3vyce Date: Mon, 30 Mar 2026 14:23:27 -0400 Subject: [PATCH] docs: update v3 migration guide --- docs/migration/v3.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/migration/v3.md b/docs/migration/v3.md index 56ea99c..2d5b236 100644 --- a/docs/migration/v3.md +++ b/docs/migration/v3.md @@ -4,6 +4,30 @@ This page covers every breaking change introduced in **v3.0** and the steps requ --- +## CRUD + +### Facet keys now always use the full relationship chain + +In `v2`, relationship facet fields used only the terminal column key (e.g. `"name"` for `Role.name`) and only prepended the relationship name when two facet fields shared the same column key. In `v3`, facet keys **always** include the full relationship chain joined by `__`, regardless of collisions. + +=== "Before (`v2`)" + + ``` + User.status -> status + (User.role, Role.name) -> name + (User.role, Role.permission, Permission.name) -> name + ``` + +=== "Now (`v3`)" + + ``` + User.status -> status + (User.role, Role.name) -> role__name + (User.role, Role.permission, Permission.name) -> role__permission__name + ``` + +--- + ## Models The lifecycle event system has been rewritten. Callbacks are now registered with a module-level [`listens_for`](../reference/models.md#fastapi_toolsets.models.listens_for) decorator and dispatched by [`EventSession`](../reference/models.md#fastapi_toolsets.models.EventSession), replacing the mixin-based approach from `v2`.