test_db Command
A Django management command for managing test databases. Useful when tests leave orphaned databases or when you need to inspect extension state.
Actions
| Action | Description |
|---|---|
info | Show test database info (name, size, status, extensions) |
cleanup | Drop test databases |
reset | Drop and recreate from scratch |
check-extensions | List installed and missing PostgreSQL extensions |
Common Options
| Option | Description |
|---|---|
--database DATABASE | Database alias (default: default) |
--all | Apply to all configured databases |
--force | Skip confirmation prompt |
--json | Output in JSON format |
info
python manage.py test_db info
python manage.py test_db info --all
python manage.py test_db info --jsonOutput:
======================================================================
TEST DATABASE INFORMATION
======================================================================
Database Alias: default
Test DB Name: test_myapp
Status: EXISTS
Size: 11 MB
Extensions: pgvector, pg_trgm
Engine: django.db.backends.postgresql
======================================================================JSON output:
[
{
"alias": "default",
"test_db_name": "test_myapp",
"exists": true,
"engine": "django.db.backends.postgresql",
"size": "11 MB",
"extensions": ["pgvector", "pg_trgm"]
}
]cleanup
Removes test databases. Use this when tests fail and leave orphaned databases behind.
python manage.py test_db cleanup # with confirmation
python manage.py test_db cleanup --force # no confirmation
python manage.py test_db cleanup --all # all databases
python manage.py test_db cleanup --all --forceOutput:
Found 2 test database(s):
• test_myapp (alias: default)
• test_analytics (alias: analytics)
Remove these databases? [y/N]: y
Removed: test_myapp
Removed: test_analytics
Cleanup complete: 2/2 databases removedSmartTestRunner runs cleanup automatically before each test run. Use this command only for manual cleanup or CI pre-steps.
reset
Drops and recreates the test database from scratch — including extension installation.
python manage.py test_db reset # with confirmation
python manage.py test_db reset --force # no confirmation
python manage.py test_db reset --database=analytics # specific aliasOutput:
Database: test_myapp (alias: default)
Status: EXISTS
This will DROP and recreate the test database. Continue? [y/N]: y
Dropped: test_myapp
Created: test_myapp
Installed extensions
Test database reset completeUse this when migrations are inconsistent and you want a guaranteed clean state before running tests.
check-extensions
Lists which PostgreSQL extensions are installed and which are required but missing.
python manage.py test_db check-extensions
python manage.py test_db check-extensions --database=analytics
python manage.py test_db check-extensions --jsonOutput:
======================================================================
TEST DATABASE EXTENSIONS
======================================================================
Database: test_myapp
Installed Extensions:
(none)
Required Extensions:
❌ vector (missing)
❌ pg_trgm (missing)
❌ unaccent (missing)
======================================================================JSON output:
{
"test_db_name": "test_myapp",
"installed_extensions": [],
"needs_pgvector": true
}If extensions are missing, run your tests — SmartTestRunner will install them:
python manage.py testTypical Workflows
After a failed test run
# Remove orphaned databases
python manage.py test_db cleanup --all --force
# Run tests again
python manage.py testFresh start before debugging
python manage.py test_db reset --force
python manage.py testInspect before a CI run
python manage.py test_db info --json
python manage.py test_db check-extensions --jsonMulti-database project
python manage.py test_db info --all
python manage.py test_db cleanup --all --force
python manage.py test_db reset --database=analyticsFull debug sequence
python manage.py test_db info
python manage.py test_db check-extensions
python manage.py test_db reset --force
python manage.py testCI/CD Integration
# GitHub Actions
- name: Cleanup stale test databases
run: poetry run python manage.py test_db cleanup --all --force
- name: Run tests
run: poetry run python manage.py test
# SmartTestRunner handles the rest automaticallyAlways use --force in CI/CD. Without it the command will wait for stdin and block the pipeline.
See Also
- Overview — what’s automatic vs manual
- Test Runners —
SmartTestRunnerandMigrationManager
TAGS: test_db, management command, test database, cleanup, CI/CD DEPENDS_ON: [overview, test-runners]
Django-CFG