Connect an SQLAlchemy application to Neon
Set up a Neon project in seconds and connect from an SQLAlchemy application
SQLAlchemy is a Python SQL toolkit and Object Relational Mapper (ORM) that provides application developers with the full power and flexibility of SQL. This guide describes how to create a Neon project and connect to it from SQLAlchemy.
Prerequisites:
To complete the steps in this topic, ensure that you have an SQLAlchemy installation with a Postgres driver. The following instructions use psycopg2
, the default driver for Postgres in SQLAlchemy. For SQLAlchemy installation instructions, refer to the SQLAlchemy Installation Guide. psycopg2
installation instructions are provided below.
To connect to Neon from SQLAlchemy:
- Create a Neon project
- Install psycopg2
- Create the "hello neon" program
- Create an SQLAlchemy engine for your Neon project
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.
- Navigate to the Projects page in the Neon Console.
- Click New Project.
- Specify your project settings and click Create Project.
Install psycopg2
Psycopg2 is a popular python library for running raw Postgres queries.
For most operating systems, the quickest installation method is using the PIP package manager. For example:
For additional information about installing psycopg2
, refer to the psycopg2 installation documentation.
Create the "hello neon" program
You can find all of the connection details mentioned above in the Connection Details widget on the Neon Dashboard. For more information, see Connect from any application.
note
This example was tested with Python 3 and psycopg2 version 2.9.3.
Create an SQLAlchemy engine for your Neon project
SQLAlchemy uses engine abstraction to manage database connections and exposes a create_engine
function as the primary endpoint for engine initialization.
The following example creates an SQLAlchemy engine that points to your Neon branch:
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 connecting from SQLAlchemy, refer to the following topics in the SQLAlchemy documentation:
SQLAlchemy connection errors
-
SQLAlchemy versions prior to 2.0.33 may reuse idle connections, leading to connection errors. If this occurs, you could encounter an
SSL connection has been closed unexpectedly
error. To resolve this, upgrade to SQLAlchemy 2.0.33 or later. For more details, see the SQLAlchemy 2.0.33 changelog. -
If you encounter an
SSL SYSCALL error: EOF detected
when connecting to the database, this typically happens because the application is trying to reuse a connection after the Neon compute has been suspended due to inactivity. To resolve this issue, try one of the following options:- Set the SQLAlchemy
pool_recycle
parameter to a value less than or equal to the autosuspend setting configured for your compute. - Set the SQLAlchemy
pool_pre_ping
parameter totrue
. This ensures that your engine checks if the connection is alive before executing a query.
For more details on the
pool_recycle
andpool_pre_ping
parameters, refer to SQLAlchemy: Connection Pool Configuration and Dealing with Disconnects. For information on configuring Neon's autosuspend setting, see Configuring Autosuspend for Neon computes. - Set the SQLAlchemy
Schema migration with SQLAlchemy
For schema migration with SQLAlchemy, see our guide:
Need help?
Join our Discord Server to ask questions or see what others are doing with Neon. Users on paid plans can open a support ticket from the console. For more detail, see Getting Support.