Modeling
Execution Workflow
-
Choose a base class around key shape and audit needs: BigIntBase , BigIntAuditBase , UUIDBase , UUIDv7Base , or related variants.
-
Add mixins intentionally: SlugKey for URL slugs, audit columns when timestamps are required, and UniqueMixin when get-or-create semantics matter.
-
Model relationships with explicit loading strategy such as selectin or joined instead of relying on defaults.
-
Use UniqueMixin to collapse duplicate creation logic for tags, lookup tables, and many-to-many helper models.
-
Customize the declarative base only when the built-in bases do not fit an existing schema or database-specific requirement.
Implementation Rules
-
Pick one primary-key strategy per bounded context and keep it consistent.
-
Let mixins own their concern; do not duplicate slug or audit columns by hand.
-
Implement both unique_hash() and unique_filter() whenever UniqueMixin is used.
-
Keep model classes transport-agnostic and leave request or response shaping to services or framework layers.
Example Pattern
from advanced_alchemy.base import BigIntAuditBase from advanced_alchemy.mixins import SlugKey, UniqueMixin
class Tag(BigIntAuditBase, SlugKey, UniqueMixin): tablename = "tag"
Validation Checklist
-
Confirm the base class matches the database key and migration strategy.
-
Confirm relationship loading avoids obvious N+1 behavior in hot paths.
-
Confirm UniqueMixin criteria match actual uniqueness guarantees.
-
Confirm timestamps, slugs, and indexes align with the expected query patterns.
Cross-Skill Handoffs
-
Use advanced-alchemy-types for custom column types on model fields.
-
Use advanced-alchemy-repositories for CRUD and filtering over these models.
-
Use advanced-alchemy-services when the model requires schema conversion or business rules.
Advanced Alchemy References