Troubleshooting¶

Solutions to common configuration issues.

"No configuration found"¶

Symptom¶

DBWardenConfigError: No configuration found

Causes & Solutions¶

Cause 1: No dbwarden.py file

# Check if file exists
ls dbwarden.py

Solution: Create dbwarden.py:

dbwarden init

Cause 2: Wrong directory

DBWarden looks in current directory and parents.

Solution: Navigate to project root:

cd /path/to/project
dbwarden migrate

Cause 3: No database_config() calls

Solution: Add configuration:

# dbwarden.py
from dbwarden import database_config

database_config(
    database_name="primary",
    default=True,
    database_type="sqlite",
    database_url="sqlite:///./app.db",
)

Cause 4: Import error in config file

# dbwarden.py
from app.models import Base  # ← Import fails

Solution: Fix imports or use lazy loading:

# Don't import models in config file
database_config(
    database_name="primary",
    model_paths=["app.models"],  # ← Use model_paths instead
    ...
)

"Exactly one default=True required"¶

Symptom¶

ConfigurationError: Exactly one default=True required

Causes & Solutions¶

Cause 1: No default database

# ❌ Wrong
database_config(database_name="primary", default=False, ...)
database_config(database_name="analytics", default=False, ...)

Solution: Set one database as default:

# ✅ Correct
database_config(database_name="primary", default=True, ...)
database_config(database_name="analytics", default=False, ...)

Cause 2: Multiple defaults

# ❌ Wrong
database_config(database_name="primary", default=True, ...)
database_config(database_name="analytics", default=True, ...)

Solution: Only one default:

# ✅ Correct
database_config(database_name="primary", default=True, ...)
database_config(database_name="analytics", ...)  # default=False implied

"Duplicate database_name"¶

Symptom¶

ConfigurationError: Duplicate database_name 'primary'

Cause¶

Same database_name used twice:

database_config(database_name="primary", ...)
database_config(database_name="primary", ...)  # ← Duplicate

Solution¶

Use unique names:

database_config(database_name="primary", ...)
database_config(database_name="analytics", ...)  # ← Different name

"No SQLAlchemy models found"¶

Symptom¶

Warning: No SQLAlchemy models found

Causes & Solutions¶

Cause 1: Wrong model_paths

# ❌ Wrong
model_paths=["models"]  # Not on PYTHONPATH

Solution: Use correct Python path:

# ✅ Correct
model_paths=["app.models"]

Cause 2: Models not imported

# app/models/__init__.py
# ❌ Wrong - models not imported
from sqlalchemy.orm import DeclarativeBase

class Base(DeclarativeBase):
    pass

Solution: Import models:

# app/models/__init__.py
# ✅ Correct
from sqlalchemy.orm import DeclarativeBase
from app.models.user import User
from app.models.order import Order

class Base(DeclarativeBase):
    pass

Cause 3: Missing model_paths

Solution: Add model_paths:

database_config(
    database_name="primary",
    model_paths=["app.models"],  # ← Add this
    ...
)

Cause 4: Circular imports

# app/models/user.py
from app.models.order import Order  # ← Circular

# app/models/order.py
from app.models.user import User  # ← Circular

Solution: Use TYPE_CHECKING:

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from app.models.order import Order

"model_paths is required"¶

Symptom¶

ConfigurationError: model_paths is required when more than one database is configured

Cause¶

Multiple databases without model_paths:

# ❌ Wrong
database_config(database_name="primary", ...)
database_config(database_name="analytics", ...)  # No model_paths

Solution¶

Add model_paths to all databases:

# ✅ Correct
database_config(
    database_name="primary",
    model_paths=["app.models.primary"],
    ...
)
database_config(
    database_name="analytics",
    model_paths=["app.models.analytics"],
    ...
)

"model_paths overlap detected"¶

Symptom¶

ConfigurationError: model_paths overlap detected between 'primary' and 'analytics'

Cause¶

Same model paths for different databases:

# ❌ Wrong
database_config(
    database_name="primary",
    model_paths=["app.models"],
    ...
)
database_config(
    database_name="analytics",
    model_paths=["app.models"],  # ← Same path
    ...
)

Solutions¶

Solution 1: Use separate paths

# ✅ Correct
database_config(
    database_name="primary",
    model_paths=["app.models.primary"],
    ...
)
database_config(
    database_name="analytics",
    model_paths=["app.models.analytics"],
    ...
)

Solution 2: Allow overlap (if intentional)

# ✅ Correct for read replicas
database_config(
    database_name="primary",
    model_paths=["app.models"],
    overlap_models=True,
    ...
)
database_config(
    database_name="replica",
    model_paths=["app.models"],
    overlap_models=True,
    ...
)

"dev_database_url is required"¶

Symptom¶

ConfigurationError: dev_database_url is required when dev_database_type is set

Cause¶

Set dev_database_type without dev_database_url:

# ❌ Wrong
database_config(
    database_name="primary",
    dev_database_type="sqlite",
    # Missing dev_database_url
    ...
)

Solution¶

Add both dev parameters:

# ✅ Correct
database_config(
    database_name="primary",
    dev_database_type="sqlite",
    dev_database_url="sqlite:///./dev.db",  # ← Add this
    ...
)

Connection Errors¶

"could not connect to server"¶

Cause: Database server not running or unreachable.

Solutions:

Check database is running:

# PostgreSQL
sudo systemctl status postgresql

# Docker
docker ps | grep postgres

Check connection URL:

# Verify host, port, credentials
database_url="postgresql://user:pass@localhost:5432/myapp"

Test connection:

# PostgreSQL
psql -h localhost -U user -d myapp

# MySQL
mysql -h localhost -u user -p myapp

"authentication failed"¶

Cause: Wrong credentials.

Solutions:

Check credentials:

# PostgreSQL
psql -h localhost -U user -d myapp

Verify environment variable:

echo $DATABASE_URL

URL encode special characters:

from urllib.parse import quote_plus

password = "p@ss:word"
encoded = quote_plus(password)  # "p%40ss%3Aword"

"database does not exist"¶

Cause: Database not created.

Solution: Create database:

-- PostgreSQL
CREATE DATABASE myapp;

-- MySQL
CREATE DATABASE myapp CHARACTER SET utf8mb4;

Import Errors¶

"ModuleNotFoundError"¶

Cause: Python can't find module.

Solutions:

Check PYTHONPATH:

export PYTHONPATH=/path/to/project:$PYTHONPATH

Install package:

pip install -e .  # Editable install

Verify import:

python -c "import app.models"

Performance Issues¶

Slow configuration loading¶

Cause: Large codebase scan.

Solution: Specify model_paths:

# ❌ Slow - scans everything
database_config(database_name="primary", ...)

# ✅ Fast - targeted scan
database_config(
    database_name="primary",
    model_paths=["app.models"],
    ...
)

Slow imports¶

Cause: Heavy imports in config file.

Solution: Avoid imports in dbwarden.py:

# ❌ Slow
from app.models import Base
from app.services import setup

# ✅ Fast
from dbwarden import database_config

database_config(...)

Debugging Tips¶

Enable verbose output¶

dbwarden --verbose migrate

Check configuration¶

# Show all configuration
dbwarden database

# Show specific database
dbwarden database --database primary

Test imports¶

python -c "import dbwarden; print('OK')"
python -c "from dbwarden import database_config; print('OK')"

Verify database connection¶

dbwarden check-db
dbwarden check-db --database primary

Recap¶

✅ Most issues are configuration or import errors
✅ Use dbwarden database to inspect configuration
✅ Use dbwarden check-db to test connections
✅ Specify model_paths for faster loading
✅ Check Python imports with python -c
✅ Use --verbose for detailed output

What's Next?¶

Configuration API Reference - Complete parameter docs
Quick Start - Start fresh with correct setup