Files

Samir Boulahtit 3c7af0ccdf refactor: standardize markdown file naming to kebab-case convention

Renamed all documentation files to follow kebab-case naming standard:
- UPPERCASE files → lowercase (e.g., RBAC.md → rbac.md)
- snake_case files → kebab-case (e.g., icons_guide.md → icons-guide.md)
- SCREAMING_SNAKE_CASE → kebab-case (e.g., DATABASE_SETUP_GUIDE.md → database-setup-guide.md)

Files renamed (15 total):
API Documentation:
  - api/RBAC.md → api/rbac.md

Architecture:
  - architecture/API_CONSOLIDATION_PROPOSAL.md → api-consolidation-proposal.md
  - architecture/API_MIGRATION_STATUS.md → api-migration-status.md

Development:
  - development/AUTH_DEPENDENCIES_GUIDE.md → auth-dependencies-guide.md
  - development/CUSTOMER_AUTHENTICATION_IMPLEMENTATION.md → customer-authentication-implementation.md
  - development/CUSTOMER_AUTH_SUMMARY.md → customer-auth-summary.md
  - development/icons_guide.md → icons-guide.md

Database Seeder:
  - database-seeder/DATABASE_INIT_GUIDE.md → database-init-guide.md
  - database-seeder/DATABASE_QUICK_REFERENCE_GUIDE.md → database-quick-reference-guide.md
  - database-seeder/DATABASE_SEEDER_DOCUMENTATION.md → database-seeder-documentation.md
  - database-seeder/MAKEFILE_DATABASE_SEEDER.md → makefile-database-seeder.md

Error Rendering:
  - error-rendering/ERROR_RENDERING_DEVELOPER_DOCUMENTATION.md → error-rendering-developer-documentation.md
  - error-rendering/HTML_ERROR_RENDERING_FLOW_DIAGRAM.md → html-error-rendering-flow-diagram.md

Getting Started:
  - getting-started/DATABASE_QUICK_REFERENCE.md → database-quick-reference.md
  - getting-started/DATABASE_SETUP_GUIDE.md → database-setup-guide.md

Updates:
- Updated all references in mkdocs.yml
- Updated all cross-references in markdown files
- Verified mkdocs builds without warnings or errors

Standard: Use kebab-case (lowercase-with-hyphens) for all markdown files

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-11-28 07:58:33 +01:00

4.4 KiB

Raw Blame History

Database Quick Reference Card

Quick reference for common database operations. See DATABASE_SETUP_GUIDE.md for detailed instructions.

🚀 Quick Start (New Developer)

# 1. Clone and setup
git clone <wizamart-repo>
cd wizamart-repo
python -m venv venv
venv\Scripts\activate  # Windows
pip install -r requirements.txt

# 2. Initialize database
alembic upgrade head
python scripts/seed_database.py

# 3. Start server
python -m uvicorn app.main:app --reload

# 4. Login
# http://localhost:8000/admin/login
# Username: admin | Password: admin123

🔄 Reset Database (Clean Slate)

Windows:

.\scripts\reset_database.ps1

Linux/Mac:

./scripts/reset_database.sh

Manual:

# 1. Delete migrations
Remove-Item alembic\versions\*.py -Exclude __init__.py

# 2. Delete database
Remove-Item wizamart.db

# 3. Regenerate
alembic revision --autogenerate -m "Initial migration"
alembic upgrade head
python scripts/seed_database.py

📝 Creating Migrations

# After modifying models in models/database/

# 1. Generate migration
alembic revision --autogenerate -m "Add field to vendor_themes"

# 2. Review the file
# Check: alembic/versions/<id>_add_field_to_vendor_themes.py

# 3. Apply migration
alembic upgrade head

🔍 Checking Status

# Current migration version
alembic current

# Migration history
alembic history --verbose

# List all tables
python -c "import sqlite3; conn = sqlite3.connect('wizamart.db'); cursor = conn.cursor(); cursor.execute('SELECT name FROM sqlite_master WHERE type=\"table\" ORDER BY name;'); [print(t[0]) for t in cursor.fetchall()]"

# Check specific table
python -c "import sqlite3; conn = sqlite3.connect('wizamart.db'); cursor = conn.cursor(); cursor.execute('PRAGMA table_info(vendor_themes)'); [print(col) for col in cursor.fetchall()]"

⬆️ Upgrading Database

# Upgrade to latest
alembic upgrade head

# Upgrade one version
alembic upgrade +1

# Upgrade to specific revision
alembic upgrade <revision_id>

⬇️ Rolling Back

# Downgrade one version
alembic downgrade -1

# Downgrade to specific revision
alembic downgrade <revision_id>

# Downgrade to empty database
alembic downgrade base

🌱 Seeding Data

# Seed development data
python scripts/seed_database.py

# Manual seed (Python shell)
python
>>> from scripts.seed_database import seed_database
>>> seed_database()

🐛 Common Fixes

"No such table" Error

# Check model imported in alembic/env.py
# Then regenerate:
alembic revision --autogenerate -m "Add missing table"
alembic upgrade head

"Database locked"

# Stop server
taskkill /F /IM python.exe  # Windows
pkill python                # Linux/Mac

# Try again
alembic upgrade head

"Target database not up to date"

alembic stamp head
alembic upgrade head

"Multiple head revisions"

alembic merge heads -m "Merge migrations"
alembic upgrade head

📦 Adding New Models

Checklist:

# 1. Create model file
# models/database/my_model.py

# 2. Import in alembic/env.py
# from models.database.my_model import MyModel

# 3. Generate migration
alembic revision --autogenerate -m "Add MyModel table"

# 4. Review migration file
# alembic/versions/<id>_add_mymodel_table.py

# 5. Apply migration
alembic upgrade head

# 6. Test
python -c "from models.database.my_model import MyModel; print('✓ Import works')"

🔗 Important Files

├── alembic/
│   ├── env.py              ← Import ALL models here!
│   └── versions/           ← Migration files
├── app/core/
│   └── database.py         ← Database connection
├── models/database/        ← SQLAlchemy models
├── scripts/
│   ├── seed_database.py    ← Seed script
│   └── reset_database.ps1  ← Reset script
├── alembic.ini             ← Alembic config
└── wizamart.db            ← SQLite database

🆘 Getting Help

Check full guide: docs/DATABASE_SETUP_GUIDE.md
Check Alembic docs: https://alembic.sqlalchemy.org/
Ask team lead

⚠️ Important Notes

✅ Always review migrations before applying
✅ Test on local database first
✅ Keep migrations in version control
✅ Backup before destructive operations
❌ Never edit applied migrations
❌ Never delete migration files

Last Updated: 2025-10-27

4.4 KiB Raw Blame History