feat: database imrovements

Author: tmgbedu

CLAUDE.md

@@ -0,0 +1,186 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a **monorepo** for the FastAPI Startkit ecosystem — a Laravel/Masonite-inspired framework for building Python applications with FastAPI. It contains four main components:
+
+| Directory | Purpose | Published as |
+|---|---|---|
+| `fastapi_startkit/` | Core framework package | [`fastapi-startkit`](https://pypi.org/project/fastapi-startkit/) on PyPI |
+| `fastapi_startkit.github.io.git/` | Documentation site | GitHub Pages (VitePress) |
+| `example/` | Standalone example apps | Not published — reference only |
+| `application/` | Starter application template | Not published — clone/scaffold target |
+
+### `fastapi_startkit/` — Core Package
+
+The PyPI package (`fastapi-startkit`, currently v0.13.6). Source lives under `src/fastapi_startkit/`. This is the foundational framework all other components depend on.
+
+**Do not modify framework code unless explicitly necessary.** Changes to core abstractions (Container, Application, Model, Provider, Facades) can have broad breaking effects on downstream applications.
+
+Optional extras are installed with pip/uv extras:
+
+```
+fastapi-startkit[fastapi]    # FastAPI + Starlette
+fastapi-startkit[database]   # SQLAlchemy async ORM
+fastapi-startkit[postgres]   # asyncpg driver
+fastapi-startkit[sqlite]     # aiosqlite driver
+fastapi-startkit[mysql]      # aiomysql driver
+fastapi-startkit[vite]       # Jinja2 for Vite integration
+```
+
+### `fastapi_startkit.github.io.git/` — Documentation
+
+VitePress site. Docs cover getting started, configuration, console, database, logging, FastAPI integration, frontend, and exception handling. Edit `.md` files under `docs/` and the home page at `index.md`.
+
+### `example/` — Example Applications
+
+Self-contained apps demonstrating specific features. Each subdirectory is an independent uv workspace member:
+
+| App | What it shows |
+|---|---|
+| `config-app/` | Configuration system |
+| `console-app/` | CLI / Cleo commands |
+| `database-app/` | ORM, migrations, seeders |
+| `fastapi-app/` | Minimal FastAPI setup |
+| `inertia-pingcrm-app/` | Full Inertia.js + PingCRM clone |
+| `onefile-app/` | Single-file application |
+| `vite-app/` | Vite + Jinja2 frontend |
+
+### `application/` — Starter Application
+
+The template users clone when starting a new project. Contains the minimal scaffolding: `artisan` entrypoint, `bootstrap/`, `config/`, `providers/`, `routes/`, and `storage/`. It mirrors a typical project layout and is a uv workspace member of this monorepo.
+
+## Commands
+
+```bash
+# Install all workspace dependencies
+uv sync
+
+# Build the core package
+cd fastapi_startkit && uv build
+
+# Run framework tests
+uv run pytest fastapi_startkit/src/fastapi_startkit/tests/ -v
+
+# Run a single test file
+uv run pytest fastapi_startkit/src/fastapi_startkit/tests/configurations/test_config_merge.py -v
+
+# Serve the docs locally
+cd fastapi_startkit.github.io.git && npm run dev
+```
+
+Tests run with `asyncio_mode = "auto"` (configured in `pyproject.toml`), so all tests are async-capable by default.
+
+## Architecture (Core Package)
+
+### Application Lifecycle
+
+1. `Application(base_path)` initializes the service container and singleton
+2. `.load_environment()` loads `.env` + `.env.{APP_ENV}` (auto-detects `.env.testing` under pytest)
+3. `.configure_paths()` sets config/storage paths
+4. `.register_providers()` → `.load_providers()` (two-phase boot)
+5. `app.fastapi` is lazy-loaded; HTTP routes delegate to the FastAPI instance
+
+### Service Container (`container/container.py`)
+
+Central IoC container. Core API:
+- `bind(key, value)` — register a binding
+- `make(key)` — resolve a binding
+- `resolve(obj)` — auto-wire a callable by inspecting its type-hinted parameters
+
+Hooks (`on_bind`, `on_make`, `on_resolve`) allow intercepting container operations. `collect('Auth*')` returns all bindings matching a wildcard.
+
+### Configuration (`configuration/`)
+
+Define config as a dataclass with fields sourced from environment variables via `env()`:
+
+```python
+from dataclasses import dataclass, field
+from fastapi_startkit.environment import env
+
+@dataclass
+class RedisConfig:
+    host: str = field(default_factory=lambda: env('REDIS_HOST'))
+    port: int = field(default_factory=lambda: env('REDIS_PORT'))
+```
+
+`app.load_environment()` applies a two-step merge: `.env` as base, then `.env.{APP_ENV}` on top.
+
+Register in the container for dotted-key access:
+
+```python
+config = app.make('config')
+config.set('redis', RedisConfig())
+
+Config.get('redis.host')   # via facade
+```
+
+### Provider Pattern (`providers/`)
+
+Providers are the standard way to register services. Each provider has two phases:
+- `register()` — bind things into the container
+- `boot()` — run after all providers are registered (safe to resolve dependencies here)
+
+### FastAPI Routing (`fastapi/routers/router.py`)
+
+`Router` wraps FastAPI's `APIRouter` and adds a `resource()` shortcut.
+
+```python
+from fastapi_startkit.fastapi import Router
+
+router = Router()
+router.get("/path", endpoint)
+router.post("/path", endpoint)
+router.put("/path", endpoint)
+router.patch("/path", endpoint)
+router.delete("/path", endpoint)
+```
+
+`router.resource(name, controller)` registers standard CRUD routes (index, create, store, show, edit, update, destroy). Use `only=`, `excepts=`, `names=`, `parameters=` to customise.
+
+Group routes by access level using separate `Router` instances:
+
+```python
+# routes/web.py
+from fastapi import Depends
+from fastapi_startkit.fastapi import Router
+
+guest = Router()
+guest.get("/login", auth_controller.create)
+guest.post("/login", auth_controller.store)
+
+auth = Router(dependencies=[Depends(auth_middleware)])
+auth.get("/", dashboard_controller.index)
+auth.resource("users", users_controller)
+```
+
+### ORM (`masoniteorm/`)
+
+Async-first fork of Masonite ORM built on SQLAlchemy async:
+- All DB operations are `async`/`await`
+- `Model` auto-pluralizes table names via `inflection`
+- `created_at`/`updated_at` managed as `pendulum` Carbon objects
+- Relationships: `HasOne`, `HasMany`, `BelongsTo`, `BelongsToMany`, `HasOneThrough`
+- `AsyncQueryBuilder` provides the chainable query interface
+
+### Facades (`facades/`)
+
+Static-like access to container-resolved services (`Config.get()`, `Auth.user()`, etc.). Each facade has a `.pyi` stub for IDE type support. Requires a booted Application singleton.
+
+### Console (`commands/`, `masoniteorm/commands/`)
+
+CLI built on [Cleo](https://github.com/python-poetry/cleo). Database commands (migrate, seed, make:model, etc.) live in `masoniteorm/commands/`. Run via `uv run artisan`.
+
+## Key Dependencies
+
+| Package | Purpose |
+|---|---|
+| `fastapi[standard]` | HTTP framework (lazily imported) |
+| `sqlalchemy[asyncio]` | Async ORM backend |
+| `pendulum` | Datetime/timezone (used as Carbon) |
+| `cleo` | CLI commands |
+| `dotty-dict` | Nested dict access via dotted keys |
+| `inflection` | Table name pluralization |
+| `asyncpg` / `aiomysql` / `aiosqlite` | DB drivers |

fastapi_startkit/src/fastapi_startkit/application.py

@@ -1,9 +1,9 @@
 import os
+from fastapi_startkit.providers.app_provider import AppProvider
 from pathlib import Path
 from typing import TYPE_CHECKING, Optional
 from typing import Type, Callable, Any, List, TypeVar, Generic
 
-from fastapi_startkit.providers.app_provider import AppProvider
 from .config import AppConfig
 from .configuration.providers import ConfigurationProvider
 from .container import Container
@@ -30,12 +30,12 @@ class Application(Container, Generic[TConfig]):
     ]
 
     def __init__(
-        self,
-        base_path: str | Path = None,
-        env=None,
-        providers=None,
-        config: Type[TConfig] | None = None,
-        exception_handler: Type[ExceptionHandler] | None = None,
+            self,
+            base_path: str | Path = None,
+            env=None,
+            providers=None,
+            config: Type[TConfig] | None = None,
+            exception_handler: Type[ExceptionHandler] | None = None,
     ):
         super().__init__()
 
@@ -83,6 +83,9 @@ def register_providers(self):
             config = {}
             if isinstance(provider_data, tuple):
                 provider_class, config = provider_data
+
+                if callable(config):
+                    config = config()
             else:
                 provider_class = provider_data
 
@@ -151,7 +154,7 @@ def mount(self, path: str, app_instance: "FastAPI", **kwargs):
 
     # Add custom exception handlers
     def add_exception_handler(
-        self, exc_class_or_status_code: Any, handler: Callable[..., Any]
+            self, exc_class_or_status_code: Any, handler: Callable[..., Any]
     ):
         self._fastapi.add_exception_handler(exc_class_or_status_code, handler)
         return self
@@ -178,9 +181,9 @@ def load_environment(self):
 
     def is_debug(self) -> bool:
         return (
-            hasattr(self, "_config_instance")
-            and self._config_instance is not None
-            and getattr(self._config_instance, "debug", False)
+                hasattr(self, "_config_instance")
+                and self._config_instance is not None
+                and getattr(self._config_instance, "debug", False)
         )
 
     def configure_config(self):

fastapi_startkit/src/fastapi_startkit/config/__init__.py

@@ -1,2 +1 @@
 from .app import AppConfig
-from .facades import Config

fastapi_startkit/src/fastapi_startkit/exceptions/handler.py

@@ -62,10 +62,13 @@ def report(self, exception: Exception):
         self.report_exception(exception)
 
     def report_exception(self, exception: Exception):
+        context = self._build_context(exception)
         if self.app and self.app.has("logger"):
             from fastapi_startkit.logging.logger import Logger
 
-            Logger.error(self._build_context(exception))
+            Logger.error(context)
+        else:
+            print(context, file=sys.stderr)
 
     def _build_context(self, exception: Exception) -> str:
         import traceback

fastapi_startkit/src/fastapi_startkit/helpers/string.py

@@ -14,6 +14,12 @@ def trim(self, suffix: str) -> "Stringable":
     def slugify(self) -> "Stringable":
         return Stringable(Str.slugify(self.text))
 
+    def camel_case(self) -> "Stringable":
+        return Stringable(Str.camel_case(self.text))
+
+    def snake_case(self) -> "Stringable":
+        return Stringable(Str.snake_case(self.text))
+
 
 class Str:
     @classmethod
@@ -29,3 +35,17 @@ def slugify(cls, text: str) -> str:
     def trim(cls, text: str, word: str) -> str:
         """Remove all occurrences of a word from the string (case-insensitive)."""
         return re.sub(re.escape(word), "", text, flags=re.IGNORECASE).strip("_").strip()
+
+    @classmethod
+    def camel_case(cls, text: str) -> str:
+        """Convert a string to camelCase."""
+        words = re.split(r"[-_\s]+", text)
+        return words[0].lower() + "".join(word.capitalize() for word in words[1:])
+
+    @classmethod
+    def snake_case(cls, text: str) -> str:
+        """Convert a string to snake_case."""
+        text = re.sub(r"[-\s]+", "_", text)
+        text = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1_\2", text)
+        text = re.sub(r"([a-z\d])([A-Z])", r"\1_\2", text)
+        return text.lower()

fastapi_startkit/src/fastapi_startkit/masoniteorm/commands/MakeMigrationCommand.py

@@ -1,8 +1,9 @@
 import datetime
 import os
 import pathlib
-from inflection import camelize, tableize
+from inflection import tableize
 from cleo.helpers import argument, option
+from fastapi_startkit.helpers.string import Str
 from .Command import Command
 
 
@@ -29,7 +30,7 @@ class MakeMigrationCommand(Command):
     ]
 
     def handle(self):
-        name = self.argument("name")
+        name = self.argument("name").replace("-", "_")
         now = datetime.datetime.today()
 
         if self.option("create") != "None":
@@ -52,7 +53,9 @@ def handle(self):
             )
         ) as fp:
             output = fp.read()
-            output = output.replace("__MIGRATION_NAME__", camelize(name))
+            camel = Str.camel_case(name)
+            class_name = camel[0].upper() + camel[1:]
+            output = output.replace("__MIGRATION_NAME__", class_name)
             output = output.replace("__TABLE_NAME__", table)
 
         file_name = f"{now.strftime('%Y_%m_%d_%H%M%S')}_{name}.py"

fastapi_startkit/src/fastapi_startkit/masoniteorm/commands/MigrateFreshCommand.py

@@ -22,7 +22,7 @@ class MigrateFreshCommand(Command):
             description="The location of the migration directory",
         ),
         option(
-            "ignore-fk", "i", flag=True, description="Ignore foreign key constraints"
+            "no-fk", None, flag=True, description="Re-enable foreign key constraints during drop"
         ),
         option(
             "seed",
@@ -54,7 +54,7 @@ async def handle_async(self):
             migration_directory=self.option("directory"),
         )
 
-        await migration.fresh(ignore_fk=self.option("ignore-fk"))
+        await migration.fresh(ignore_fk=not self.option("no-fk"))
 
         if self.option("seed") == "null":
             self.call(

fastapi_startkit/src/fastapi_startkit/masoniteorm/commands/stubs/create_migration.stub

@@ -1,20 +1,20 @@
 """__MIGRATION_NAME__ Migration."""
 
-from masoniteorm.migrations import Migration
+from fastapi_startkit.masoniteorm.migrations import Migration
 
 
 class __MIGRATION_NAME__(Migration):
-    def up(self):
+    async def up(self):
         """
         Run the migrations.
         """
-        with self.schema.create("__TABLE_NAME__") as table:
+        async with await self.schema.create("__TABLE_NAME__") as table:
             table.increments("id")
 
             table.timestamps()
 
-    def down(self):
+    async def down(self):
         """
         Revert the migrations.
         """
-        self.schema.drop("__TABLE_NAME__")
+        await self.schema.drop("__TABLE_NAME__")

fastapi_startkit/src/fastapi_startkit/masoniteorm/commands/stubs/table_migration.stub

@@ -1,19 +1,19 @@
 """__MIGRATION_NAME__ Migration."""
 
-from masoniteorm.migrations import Migration
+from fastapi_startkit.masoniteorm.migrations import Migration
 
 
 class __MIGRATION_NAME__(Migration):
-    def up(self):
+    async def up(self):
         """
         Run the migrations.
         """
-        with self.schema.table("__TABLE_NAME__") as table:
+        async with await self.schema.table("__TABLE_NAME__") as table:
             pass
 
-    def down(self):
+    async def down(self):
         """
         Revert the migrations.
         """
-        with self.schema.table("__TABLE_NAME__") as table:
+        async with await self.schema.table("__TABLE_NAME__") as table:
             pass