From ddddcb39b82781b51bef9c90b3f71bd7143718ca Mon Sep 17 00:00:00 2001
From: ItsDrike <itsdrike@protonmail.com>
Date: Sun, 21 Jul 2024 22:22:37 +0200
Subject: [PATCH] Add example orm database classes

---
 src/db_tables/README.md | 73 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)

diff --git a/src/db_tables/README.md b/src/db_tables/README.md
index 0f6400a..39a071a 100644
--- a/src/db_tables/README.md
+++ b/src/db_tables/README.md
@@ -10,3 +10,76 @@ All of these tables must inherit from the `Base` class, that can be imported fro
 
 There is no need to register newly created classes / files anywhere, as all files in this directory (except those
 starting with `_`) will be automatically imported and picked up by SQLAlchemy.
+
+## Example database class
+
+Imagine an application that schedules appointmnets for users:
+
+`user.py`:
+
+```python
+import enum
+from typing import TYPE_CHECKING
+from sqlalchemy import Mapped, mapped_column, relationship
+
+from src.utils.database import Base
+
+
+# Prevent circular imports for relationships
+if TYPE_CHECKING:
+    from src.db_tables.appointment import Appointment
+
+
+class Role(enum.IntEnum):
+    """Enumeration of all possible user roles."""
+
+    USER = 0
+    ADMIN = 1
+
+
+class User(Base):
+    """User database table."""
+
+    __tablename__ = "user"
+
+    id: Mapped[int] = mapped_column(primary_key=True, index=True, nullable=False)
+    email: Mapped[str] = mapped_column(unique=True, nullable=False)
+    name: Mapped[str] = mapped_column(nullable=False)
+    surname: Mapped[str] = mapped_column(nullable=False)
+    user_role: Mapped[Role] = mapped_column(nullable=False, default=Role.USER)
+
+    appointments: Mapped[list["Appointment"]] = relationship(
+        lazy="selectin",
+        back_populates="user",
+        cascade="all, delete-orphan",
+    )
+```
+
+`appointment.py`:
+
+```python
+from datetime import date, time
+from typing import TYPE_CHECKING
+
+from sqlalchemy import ForeignKey
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from src.utils.database import Base
+
+# Prevent circular imports for relationships
+if TYPE_CHECKING:
+    from src.db_tables.user import User
+
+
+class Appointment(Base):
+    """Appointment database table."""
+
+    __tablename__ = "appointment"
+
+    id: Mapped[int] = mapped_column(primary_key=True, index=True, nullable=False)
+    booked_date: Mapped[date] = mapped_column(nullable=False)
+    booked_time: Mapped[time] = mapped_column(nullable=False)
+    user_id: Mapped[int] = mapped_column(ForeignKey("user.id"), nullable=False)
+
+    user: Mapped["User"] = relationship(lazy="selectin", back_populates="appointments")
+```