Best Practices¶

To get the most out of sqlatypemodel, follow these guidelines.

Performance¶

Choose the Right Mixin: * Use LazyMutableMixin for large documents where you only access a few fields. It’s significantly faster to load from the DB (5.1x faster initialization). * Use MutableMixin for small documents or when you iterate over the entire object graph anyway.
Use Uniform Collections: * Avoid lists with mixed types (e.g., [1, "a", Model()]). While supported, it forces the lazy loader to inspect every item individually, slowing down access. * Prefer typed Pydantic fields: tags: list[str].
Batch Mutations: * If adding many items to a list in a loop, use batch_changes() to avoid notifying SQLAlchemy on every iteration.
```
with model.batch_changes():
    for i in range(1000):
        model.items.append(i)
```
Leverage orjson: * Always install with pip install sqlatypemodel[fast] for maximum performance. * orjson is significantly faster than standard json for serialization/deserialization.

Use Safe Wrappers for Dataclasses: * Standard dataclasses on Python 3.12+ can have initialization issues with mutable defaults. * Use sqlatypemodel.util.dataclasses.dataclass instead.
Avoid Shared References: * Don’t share the same mutable list object between two different models. * The library’s tracking graph assumes a tree structure (parent -> child). * Shared children (“diamond dependencies”) are supported via multiple parents logic, but can be confusing.
Concurrency: * While the library handles internal state thread-safety, SQLAlchemy Sessions are not thread-safe. * Keep session scope local to the thread/task.
Pre-commit Hooks: * Always run pre-commit before pushing: pre-commit run --all-files * This ensures code quality and prevents CI failures.

Use `orjson`: * Install with pip install sqlatypemodel[fast]. It handles serialization much faster than the standard library. * ~40% performance improvement over standard json.
Watch Integer Limits: * If your application deals with integers larger than 64-bit (e.g., crypto IDs), be aware that orjson might fail. * The library handles this by falling back to standard json, but it’s a performance hit.
Pickle Support: * Full pickle compatibility for Celery/Redis caching. * Mutation tracking is automatically restored upon deserialization.

Run Local Tests: * Always run tests locally before pushing: poetry run pytest -v * Coverage should stay at 100%: poetry run pytest --cov=sqlatypemodel
Use Database Tests: * Set up local PostgreSQL/MySQL for database integration tests. * Tests automatically skip if databases unavailable.
CI/CD Coverage: * The GitHub Actions workflow tests on Python 3.10-3.14 automatically. * All tests must pass before merge to master.

Type Hints: * Always include type hints in new code. * MyPy strict mode is enforced: poetry run mypy src/sqlatypemodel
Follow Code Style: * Black + Ruff are enforced: poetry run ruff check --fix && poetry run black * Line length: 79 characters * No bare excepts, unused imports, or undefined names
Documentation: * Docstrings for all public APIs * Include examples for complex functions * Update RST docs for major features
Logging: * Use Python’s standard logging module * Include context for debugging * Avoid excessive logging in performance-critical paths

Automated Releases: * Releases are automated via GitHub Actions (see .github/WORKFLOWS.md). * Just tag a release and it publishes to PyPI automatically.
Version Bumping: * Update pyproject.toml and CHANGELOG.md * Use semantic versioning (MAJOR.MINOR.PATCH) * Tag with git tag v1.2.3
Monitoring: * Check CI/CD status: https://github.com/GrehBan/sqlatypemodel/actions * Security scans run weekly * Coverage tracked automatically