How does Django connect to external database?

Pythoneo

Django’s built-in ORM supports connecting to external relational databases—such as PostgreSQL, MySQL, SQLite, Oracle, and others—via the DATABASES setting in settings.py. Proper configuration ensures secure, performant access for development and production environments.

1. Configure DATABASES in settings.py

Define connection parameters under the DATABASES dictionary. For PostgreSQL:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'mydb',
        'USER': 'dbuser',
        'PASSWORD': 's3cr3t',
        'HOST': 'db.example.com',
        'PORT': '5432',
        'OPTIONS': {
            'sslmode': 'require',
        },
    }
}

Supported ENGINE values:
django.db.backends.postgresql,
django.db.backends.mysql,
django.db.backends.oracle,
django.db.backends.sqlite3 (file),
plus third-party backends (e.g., Microsoft SQL Server).

See also  How to add to manytomany field in Django

2. Manage Credentials Securely

Avoid hard-coding credentials. Leverage environment variables or a secrets manager:

import os

DATABASES = {
    'default': {
        'ENGINE': os.getenv('DB_ENGINE', 'django.db.backends.postgresql'),
        'NAME': os.getenv('DB_NAME'),
        'USER': os.getenv('DB_USER'),
        'PASSWORD': os.getenv('DB_PASS'),
        'HOST': os.getenv('DB_HOST'),
        'PORT': os.getenv('DB_PORT'),
    }
}

Use Django-environ or dynaconf for structured settings and 12-factor compliance.

3. Enable SSL/TLS for Secure Connections

Configure SSL options to encrypt traffic:

'OPTIONS': {
    'sslmode': 'verify-full',
    'sslrootcert': '/path/to/ca.crt',
},

MySQL uses OPTIONS: {'ssl': {'ca': '/path/ca.pem'}}. Verify your database’s SSL support in PDF driver documentation.

4. Use Connection Pooling for Performance

Django opens a new connection per request by default. For high traffic, integrate pooling via:

  • django-db-geventpool: gevent-based pool
  • django-postgrespool2: psycopg2 pool support
  • SQLAlchemy as an alternative ORM with built-in pooling
See also  How to Use django-adaptors

Example with django-postgrespool2:

DATABASES['default']['ENGINE'] = 'django_postgrespool2'

5. Migrate and Test the Connection

Apply migrations and verify connectivity:

python manage.py migrate
python manage.py dbshell
Use dbshell to open a SQL shell with your configured database driver.

6. Troubleshooting Common Issues

  1. Authentication errors: Check credentials and host reachability.
  2. SSL failures: Validate certificates and sslmode settings.
  3. Driver not installed: Install psycopg2 for PostgreSQL, mysqlclient for MySQL, or cx_Oracle for Oracle.
  4. Timeouts: Increase CONN_MAX_AGE or database-side timeout settings.
See also  How to reset secret key in Django

7. Summary Checklist

  1. Define DATABASES with appropriate ENGINE and connection parameters.
  2. Secure credentials via environment variables or secret managers.
  3. Enable SSL/TLS using OPTIONS and valid certificates.[PDF Driver SSL Guide]
  4. Integrate connection pooling for high-throughput applications.
  5. Run migrate and dbshell to verify connectivity.
  6. Install and configure database drivers per PDF-backed documentation.