Run manage.py commands from the krill/ directory (or use the make targets). For production deployment see the deployment guide.
This guide explains how to set up and switch between SQLite (local development) and PostgreSQL (production) databases in the Krill project.
The project is configured to support both database engines:
- SQLite: Default for local development (easiest setup)
- PostgreSQL: Recommended for production deployments (better performance, features)
-
Clone and setup the project:
git clone <repository> cd krill uv sync source .venv/bin/activate # On Windows: .venv\Scripts\activate
-
Run with SQLite (default):
python manage.py migrate python manage.py createsuperuser python manage.py runserver
-
Set environment variables:
export DATABASE_ENGINE=postgresql export DB_NAME=krill_production export DB_USER=krill_user export DB_PASSWORD=your_secure_password export DB_HOST=localhost export DB_PORT=5432
-
Run with PostgreSQL:
python manage.py migrate python manage.py createsuperuser python manage.py runserver
The project includes several environment file templates:
env.example- Basic configuration for local developmentenv.production.example- Production configuration with PostgreSQL.env- Your actual environment file (create this)
| Variable | Description | Default | Required |
|---|---|---|---|
DATABASE_ENGINE |
Database engine (sqlite or postgresql) |
sqlite |
No |
DB_NAME |
Database name | krill |
Yes (PostgreSQL) |
DB_USER |
Database user | krill_user |
Yes (PostgreSQL) |
DB_PASSWORD |
Database password | - | Yes (PostgreSQL) |
DB_HOST |
Database host | localhost |
Yes (PostgreSQL) |
DB_PORT |
Database port | 5432 |
Yes (PostgreSQL) |
DB_SSLMODE |
SSL mode for PostgreSQL | prefer |
No |
-
Start PostgreSQL:
docker-compose up -d postgres
-
Set environment variables:
export DATABASE_ENGINE=postgresql export DB_NAME=krill export DB_USER=krill_user export DB_PASSWORD=krill_password export DB_HOST=localhost export DB_PORT=5432
-
Run migrations:
python manage.py migrate
-
Install PostgreSQL:
# Ubuntu/Debian sudo apt-get install postgresql postgresql-contrib # macOS brew install postgresql # Windows # Download from https://www.postgresql.org/download/windows/
-
Create database and user:
CREATE USER krill_user WITH PASSWORD 'your_password'; CREATE DATABASE krill OWNER krill_user; GRANT ALL PRIVILEGES ON DATABASE krill TO krill_user;
The project includes a custom management command for database operations:
# Check current database configuration
python manage.py setup_db --check
# Switch to PostgreSQL
python manage.py setup_db --engine=postgresql
# Switch to SQLite
python manage.py setup_db --engine=sqlite
# Create PostgreSQL user (requires superuser privileges)
python manage.py setup_db --create-user# Create new migrations
python manage.py makemigrations
# Apply migrations
python manage.py migrate
# Show migration status
python manage.py showmigrations
# Reset database (WARNING: destroys all data)
python manage.py flush-
Backup your data:
cp krill/db.sqlite3 krill/db.sqlite3.backup
-
Set PostgreSQL environment:
export DATABASE_ENGINE=postgresql # ... other DB variables
-
Run migrations:
python manage.py migrate
-
Load fixtures (if available):
python manage.py loaddata tests/fixtures/sample_fixtures.json
A helper script is provided for easy migration:
python scripts/migrate_to_postgresql.pyThe project uses multiple settings files:
krill/settings.py- Base settings with environment-based configurationkrill/settings_local.py- Local development overrideskrill/settings_production.py- Production settings
# Use local settings (SQLite)
export DJANGO_SETTINGS_MODULE=krill.settings_local
# Use production settings (PostgreSQL)
export DJANGO_SETTINGS_MODULE=krill.settings_production
# Use base settings (environment-based)
export DJANGO_SETTINGS_MODULE=krill.settings-
PostgreSQL Connection Failed:
- Check if PostgreSQL is running
- Verify environment variables
- Check firewall settings
- Ensure database and user exist
-
Permission Denied:
- Verify database user permissions
- Check SSL mode settings
- Ensure proper authentication method
-
Migration Errors:
- Check database connection
- Verify Django version compatibility
- Check for conflicting migrations
# Test database connection
python manage.py dbshell
# Check Django settings
python manage.py check
# Show database info
python manage.py setup_db --check-
Connection Pooling:
DATABASES = { 'default': { # ... other settings 'CONN_MAX_AGE': 60, 'OPTIONS': { 'sslmode': 'require', 'connect_timeout': 10, }, } }
-
Indexing:
- Use
db_index=Trueon frequently queried fields - Consider composite indexes for complex queries
- Monitor query performance with
django-debug-toolbar
- Use
-
Caching:
- Use
select_related()andprefetch_related()for queries - Implement database query optimization
- Use
# Create backup
pg_dump -h localhost -U krill_user krill > backup.sql
# Restore backup
psql -h localhost -U krill_user krill < backup.sql
# Automated backups (add to crontab)
0 2 * * * pg_dump -h localhost -U krill_user krill > /backups/krill_$(date +\%Y\%m\%d).sql# Simple copy
cp krill/db.sqlite3 krill/db.sqlite3.backup
# Using sqlite3
sqlite3 krill/db.sqlite3 ".backup 'krill/db.sqlite3.backup'"-
Environment Variables:
- Never commit
.envfiles - Use strong, unique passwords
- Rotate credentials regularly
- Never commit
-
Database Security:
- Use SSL connections
- Limit database user permissions
- Regular security updates
- Network access restrictions
-
Application Security:
- Enable HTTPS
- Use secure cookies
- Implement rate limiting
- Regular security audits
For issues or questions:
- Check the troubleshooting section above
- Review Django and PostgreSQL documentation
- Check project issues and discussions
- Contact the development team