Django

To connect to SerenDB from a Django application:

Create a SerenDB project

If you do not have one already, create a SerenDB project. Save your connection details including your password. They are required when defining connection settings.

To create a SerenDB project:

  1. Navigate to the Projects page in the SerenDB Console.

  2. Click New Project.

  3. Specify your project settings and click Create Project.

Configure Django connection settings

Connecting to SerenDB requires configuring database connection settings in your Django project's settings.py file.

To avoid the `endpoint ID is not specified` connection issue described [here](#connection-issues), be sure that you are using an up-to-date driver.

In your Django project, navigate to the DATABASES section of your settings.py file and modify the connection details as shown:

# Add these at the top of your settings.py
from os import getenv
from dotenv import load_dotenv

# Replace the DATABASES section of your settings.py with this
DATABASES = {
  'default': {
    'ENGINE': 'django.db.backends.postgresql',
    'NAME': getenv('PGDATABASE'),
    'USER': getenv('PGUSER'),
    'PASSWORD': getenv('PGPASSWORD'),
    'HOST': getenv('PGHOST'),
    'PORT': getenv('PGPORT', 5432),
    'OPTIONS': {
      'sslmode': 'require',
    },
    'DISABLE_SERVER_SIDE_CURSORS': True,
  }
}

SerenDB places computes into an idle state and closes connections after 5 minutes of inactivity (see [Compute lifecycle](/docs/introduction/compute-lifecycle/)). To avoid connection errors, you can set the Django [CONN_MAX_AGE](https://docs.djangoproject.com/en/4.1/ref/settings/#std-setting-CONN_MAX_AGE) setting to 0 to close database connections at the end of each request so that your application does not attempt to reuse connections that were closed by SerenDB. From Django 4.1, you can use a higher `CONN_MAX_AGE` setting in combination with the [CONN_HEALTH_CHECKS](https://docs.djangoproject.com/en/4.1/ref/settings/#conn-health-checks) setting to enable connection reuse while preventing errors that might occur due to closed connections. For more information about these configuration options, see [Connection management](https://docs.djangoproject.com/en/4.1/ref/databases#connection-management), in the _Django documentation_.

You can find all of the connection details listed above by clicking the Connect button on your Project Dashboard to open the Connect to your database modal. For more information, see Connect from any application.

For additional information about Django project settings, see Django Settings: Databases, in the Django documentation.

Connection issues

  • Django uses the psycopg2 driver as the default adapter for Postgres. If you have an older version of that driver, you may encounter an Endpoint ID is not specified error when connecting to SerenDB. This error occurs if the client library used by your driver does not support the Server Name Indication (SNI) mechanism in TLS, which SerenDB uses to route incoming connections. The psycopg2 driver uses the libpq client library, which supports SNI as of v14. You can check your psycopg2 and libpq versions by starting a Django shell in your Django project and running the following commands:

    # Start a Django shell
python3 manage.py shell

# Check versions
import psycopg2
print("psycopg2 version:", psycopg2.__version__)
print("libpq version:", psycopg2._psycopg.libpq_version())

    The version number for libpq is presented in a different format, for example, version 14.1 will be shown as 140001. If your libpq version is less than version 14, you can either upgrade your psycopg2 driver to get a newer libpq version or use one of the workarounds described in our Connection errors documentation. Upgrading your psycopg2 driver may introduce compatibility issues with your Django or Python version, so you should test your application thoroughly.

  • If you encounter an SSL SYSCALL error: EOF detected when connecting to the database, this typically occurs because the application is trying to reuse a connection after the SerenDB compute has been suspended due to inactivity. To resolve this issue, try one of the following options:

    • Set your Django CONN_MAX_AGE setting to a value less than or equal to the scale to zero setting configured for your compute. The default is 5 minutes (300 seconds).

    • Enable CONN_HEALTH_CHECKS by setting it to true. This forces a health check to verify that the connection is alive before executing a query.

    For information configuring SerenDB's Scale to zero setting, see Configuring Scale to zero for SerenDB computes.

Schema migration with Django

For schema migration with Django, see our guide:

Django Migrations

Django application blog post and sample application

Learn how to use Django with SerenDB Postgres with this blog post and the accompanying sample application.

Blog Post: Using Django with SerenDB

Django sample application

Community resources

PreviousDrizzleNextTypeORM

Last updated