feat!(db): initial work towards #9

.pre-commit-config.yaml

@@ -131,7 +131,10 @@ repos:
             typing-extensions,
             "uvicorn[standard]",
             uvloop>=0.18.0,
-            litestar,
+            asyncpg,
+            "litestar[cli,structlog,standard]",
+            types-click,
+            asyncpg-stubs,
             polyfactory,
             discord-py,
           ]

Makefile

@@ -96,6 +96,19 @@ docs: docs-clean 									## Dump the existing built docs and rebuild them
 	@echo "=> Building documentation"
 	@$(PDM_RUN_BIN) sphinx-build -M html docs docs/_build/ -E -a -j auto --keep-going
 
+# =============================================================================
+# Database
+# =============================================================================
+migrations:       ## Generate database migrations
+	@echo "ATTENTION: This operation will create a new database migration for any defined models changes."
+	@while [ -z "$$MIGRATION_MESSAGE" ]; do read -r -p "Migration message: " MIGRATION_MESSAGE; done ;
+	@$(ENV_PREFIX)app database make-migrations --autogenerate -m "$${MIGRATION_MESSAGE}"
+
+.PHONY: migrate
+migrate:          ## Apply database migrations
+	@echo "ATTENTION: Will apply all database migrations."
+	@$(ENV_PREFIX)app database upgrade
+
 # =============================================================================
 # Main
 # =============================================================================

docker-compose.infra.yml

@@ -0,0 +1,35 @@
+version: "3.9"
+
+services:
+  db:
+    image: postgres:latest
+    ports:
+      - "5432:5432"
+    hostname: db
+    environment:
+      POSTGRES_USER: "byte"
+      POSTGRES_PASSWORD: "bot"
+      POSTGRES_DB: "byte"
+
+    volumes:
+      - db-data:/var/lib/postgresql/data
+    restart: unless-stopped
+
+    logging:
+      options:
+        max-size: 10m
+        max-file: "3"
+
+    healthcheck:
+      test:
+        - CMD
+        - pg_isready
+        - -U
+        - app
+      interval: 2s
+      timeout: 3s
+      retries: 40
+
+volumes:
+  db-data: {}
+  cache-data: {}

docs/web/api/domain/db/index.rst

@@ -0,0 +1,13 @@
+========
+Database
+========
+
+This is the database layer serving all domains in the application.
+
+.. toctree::
+    :titlesonly:
+    :caption: Database Domain API Reference
+    :glob:
+    :hidden:
+
+    *

docs/web/api/domain/db/models.rst

@@ -0,0 +1,16 @@
+======
+models
+======
+
+Model definition for the domain.
+
+API Reference
+-------------
+
+.. automodule:: src.server.domain.db.models
+    :members:
+
+Mermaid Diagram
+---------------
+
+.. autoclasstree:: src.server.domain.db.models

docs/web/api/index.rst

@@ -22,6 +22,7 @@ API Reference
     domain/*
     domain/web/index
     domain/system/index
+    domain/db/index
 
 .. toctree::
     :titlesonly:
@@ -31,3 +32,4 @@ API Reference
 
     lib/*
     lib/log/index
+    lib/db/index

docs/web/api/lib/db/base.rst

@@ -0,0 +1,9 @@
+====
+base
+====
+
+API Reference
+-------------
+
+.. automodule:: src.server.lib.db.base
+     :members:

docs/web/api/lib/db/index.rst

@@ -0,0 +1,13 @@
+================
+Database Library
+================
+
+Documentation for the Database library.
+
+
+.. toctree::
+    :titlesonly:
+
+    base
+    utils
+    orm

docs/web/api/lib/db/orm.rst

@@ -0,0 +1,9 @@
+===
+orm
+===
+
+API Reference
+-------------
+
+.. automodule:: src.server.lib.db.orm
+     :members:

docs/web/api/lib/db/utils.rst

@@ -0,0 +1,9 @@
+=====
+utils
+=====
+
+API Reference
+-------------
+
+.. automodule:: src.server.lib.db.utils
+     :members:

pyproject.toml

@@ -12,8 +12,9 @@ dependencies = [
     "litestar[jwt,opentelemetry,prometheus,standard,structlog]>=2.0.0b4",
     "pydantic-settings>=2.1.0",
     "anyio>=3.7.1",
-    "advanced-alchemy>=0.5.4",
+    "advanced-alchemy>=0.5.5",
     "certifi>=2023.11.17",
+    "asyncpg>=0.29.0",
 ]
 requires-python = ">=3.11,<4.0"
 readme = "README.md"
@@ -97,7 +98,7 @@ lint = [
 ]
 
 [project.scripts]
-app = "litestar.__main__:run_cli"
+app = "src.__main__:run_cli"
 
 [project.entry-points."litestar.commands"]
 run-bot = "src.cli:run_bot"

src/__main__.py

@@ -0,0 +1,30 @@
+"""Application Entrypoint."""
+from __future__ import annotations
+
+__all__ = ("run_cli",)
+
+
+def run_cli() -> None:
+    """Application Entrypoint."""
+    import os
+    import sys
+    from pathlib import Path
+
+    current_path = Path(__file__).parent.parent.resolve()
+    sys.path.append(str(current_path))
+    os.environ.setdefault("LITESTAR_APP", "src.app:app")
+    try:
+        from litestar.__main__ import run_cli as run_litestar_cli
+
+    except ImportError as exc:
+        print(  # noqa: T201
+            "Could not load required libraries.  ",
+            "Please check your installation and make sure you activated any necessary virtual environment",
+        )
+        print(exc)  # noqa: T201
+        sys.exit(1)
+    run_litestar_cli()
+
+
+if __name__ == "__main__":
+    run_cli()

src/app.py

@@ -3,6 +3,8 @@
 
 from typing import TYPE_CHECKING
 
+from src.server.lib import db
+
 if TYPE_CHECKING:
     from litestar import Litestar
 
@@ -15,6 +17,7 @@ def create_app() -> Litestar:
     Returns:
         Litestar: The Litestar application.
     """
+    from advanced_alchemy.exceptions import RepositoryError
     from litestar import Litestar
     from pydantic import SecretStr
 
@@ -33,6 +36,7 @@ def create_app() -> Litestar:
         # Handlers
         exception_handlers={
             exceptions.ApplicationError: exceptions.exception_to_http_response,
+            RepositoryError: exceptions.exception_to_http_response,
         },
         route_handlers=[*domain.routes],
         # Configs
@@ -51,10 +55,13 @@ def create_app() -> Litestar:
         middleware=[log.controller.middleware_factory],
         signature_namespace=domain.signature_namespace,
         type_encoders={SecretStr: str},
-        plugins=[],
+        plugins=[db.plugin],
     )
 
 
 def create_bot() -> None:
-    """Application factory to instantiate a Discord bot."""
+    """Application factory to instantiate a Discord bot.
+
+    .. todo:: Move into this file.
+    """
     ...

src/server/domain/db/__init__.py

@@ -0,0 +1,4 @@
+"""Domain for database models."""
+from src.server.domain.db import models
+
+__all__ = ["models"]