Connect a Django application to Neon
Set up a Neon project in seconds and connect from a Django application
To connect to Neon from a Django application:
Create a Neon project
If you do not have one already, create a Neon project. Save your connection details including your password. They are required when defining connection settings.
To create a Neon project:
- Navigate to the Projects page in the Neon Console.
- Click New Project.
- Specify your project settings and click Create Project.
Configure Django connection settings
Connecting to Neon requires configuring database connection settings in your Django project's
In your Django project, navigate to the
DATABASES section of your
settings.py file and modify the connection details as shown:
<dbname>is the name of the database. The default Neon database is
<user>is the database user.
<password>is the database user's password.
<hostname>is the hostname of the branch's compute endpoint. The hostname has an
ep-prefix and appears similar to this:
<port>is the Postgres port number. Neon uses the default port,
Neon places computes into an
Idle state and closes connections after 5 minutes of inactivity (see Compute lifecycle). To avoid connection errors, you can set the Django 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 Neon. From Django 4.1, you can use a higher
CONN_MAX_AGE setting in combination with the 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, in the Django documentation.
You can find all of the connection details listed above in the Connection Details widget on the Neon Dashboard. For more information, see Connect from any application.
For additional information about Django project settings, see Django Settings: Databases, in the Django documentation.
Running Django tests is currently not supported. The Django test runner must be able to create a database for tests, which is not yet supported by Neon.
Django uses the
psycopg2 driver as the default adapter for Postgrs. If you have an older version of that driver, you may encounter a
Endpoint ID is not specified error when connecting to Neon. This error occurs if the client library used by your driver does not support the Server Name Indication (SNI) mechanism in TLS, which Neon uses to route incoming connections. The
psycopg2 driver uses the
libpq client library, which supports SNI as of v14. You can check your
libpq versions by starting a Django shell in your Django project and running the following commands:
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.
Video course: Micro eCommerce with Django and Neon
Watch Justin Mitchel's video course, Micro eCommerce with Python, Django, Neon Serverless Postgres, Stripe, TailwindCSS and more, to learn how to connect a Django application to Neon.