Database Conventions

This document outlines the naming conventions, import ordering, and typing standards for database modules.

File and Directory Naming

Directories

• snake_case for all directories: core_engine, knowledge_base
• Plural for collections: users/, products/, services/
• Singular for single-purpose: utils/, config/

Python Files

• snake_case for all Python files: models.py, schemas.py
• Descriptive names that match their purpose
• Avoid abbreviations unless very common (e.g., crud.py, apis.py)

Class Naming

• PascalCase for class names
• Descriptive names
• Pydantic schemas end with purpose: Create, Update, Response, Base

# Good
class UserProfile(Base):
    pass

class AppConfigCreate(BaseModel):
    pass

class EntityResponse(BaseModel):
    pass

# Avoid
class userProfile(Base):
    pass

class AppData(BaseModel):  # Too generic
    pass

Variable and Function Naming

• snake_case for all variables and functions
• Descriptive names that convey purpose
• Boolean variables start with is_, has_, should_, or can_

# Good
user_id = "abc123"
is_authenticated = True
app_config = await get_app_config(db, config_id)

# Avoid
uid = "abc123"
auth = True
cfg = await get_cfg(db, cid)

Database Tables

• snake_case for table names
• Plural form for entity collections
• Singular for configuration/settings

# Good
__tablename__ = "app_config"  # Singular - one config per app/tenant
__tablename__ = "users"       # Plural - collection
__tablename__ = "items"       # Plural

API Endpoints

These standards are defined centrally in API Standards:

• docs/backend/08_api/api_standards.md

Import Ordering

Group imports in this order:

1. Standard library
2. Third-party packages
3. Local application imports

# Standard library
import os
from datetime import datetime
from typing import Optional, List

# Third-party
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy import Column, String
from pydantic import BaseModel, Field

# Local
from database.database import Base
from database.dependencies import get_db, get_current_user

Type Hints

Always use type hints for function parameters and return values:

async def get_user_by_id(
    db: AsyncSession,
    user_id: str
) -> Optional[User]:
    """Get user by ID."""
    # Implementation

Docstrings

Use concise docstrings for functions:

async def create_item(
    db: AsyncSession,
    item_data: ItemCreate,
    user_id: str
) -> Item:
    """
    Create a new item in the database.
    
    Args:
        db: Database session
        item_data: Item creation data
        user_id: User ID
        
    Returns:
        Created item object
    """
    # Implementation