TypeORM is an open-source ORM for TypeScript and JavaScript. This guide assumes you have a TypeORM project. To create one, run npx typeorm init --name my-project --database postgres. This guide covers the following topics:
Connect to a database on Neon from TypeORM
To establish a basic connection from TypeORM to a database on Neon, perform the following steps:
-
Retrieve your database connection string. You can find the connection string for your database by clicking the Connect button in the Console nav. Select a branch, a user, and the database you want to connect to. A connection string is constructed for you.
The connection string includes the user name, password, hostname, and database name. -
Install the
pgdriver, which TypeORM uses for Postgres, anddotenvto load your.envfile.npx typeorm initdoesn't installpg.npm install pg dotenv -
Update the TypeORM
DataSourceinitialization in your application (src/data-source.tsin a project created withtypeorm init) to the following. Replace thehost,port,username,password, anddatabaseoptions withurl, and keep your other options, such asentitiesandmigrations.import 'dotenv/config'; import 'reflect-metadata'; import { DataSource } from 'typeorm'; export const AppDataSource = new DataSource({ type: 'postgres', url: process.env.DATABASE_URL, ssl: true, entities: [ /*list of entities*/ ], });The
import 'dotenv/config'line loads.envbefore theDataSourcereadsprocess.env.DATABASE_URL. Without it,DATABASE_URLis undefined and TypeORM tries to connect tolocalhost. -
Create a
.envfile in your project root, add aDATABASE_URLvariable, and set it to the connection string you copied in the first step. Add.envto your.gitignoreso you don't commit the password.DATABASE_URL="postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require&channel_binding=require"pg8.23 and later print aSECURITY WARNINGwhen a connection string usessslmode=require. Changesslmode=requiretosslmode=verify-fullto keep the current behavior and remove the warning. For more about SSL modes, see Connect securely. -
Run your application. In a project created with
typeorm init, runnpm start. The sample app inserts a user and prints the users it loads from your database.
tip
TypeORM uses a node-postgres Pool to connect to your Postgres database. Installing pg-native and setting the NODE_PG_FORCE_NATIVE environment variable to true switches the pg driver to pg-native, which uses the libpq C library.
Use connection pooling with TypeORM
Serverless functions can require a large number of database connections as demand increases. If you use serverless functions in your application, we recommend that you use a pooled Neon connection string, as shown:
# Pooled Neon connection string
DATABASE_URL="postgresql://alex:AbC123dEf@ep-cool-darkness-123456-pooler.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require"A pooled Neon connection string adds -pooler to the endpoint ID, which tells Neon to use a pooled connection. You can add -pooler to your connection string manually or copy a pooled connection string from the Connect to your branch modal, which you can access by clicking Connect in the Console nav. Enable the Connection pooling toggle to add the -pooler suffix.
important
Use a pooled connection string for your application at runtime, but use a direct (non-pooled) connection string when running TypeORM migrations. Neon's pooled connection uses PgBouncer in transaction mode, which doesn't support all session-level operations that migration tools rely on, so running migrations over a pooled connection can lead to errors. See Connection pooling.
Connection timeouts
If your compute has been suspended after a period of inactivity, the first connection starts it again. This usually takes a few hundred milliseconds. See Scale to zero.
By default, TypeORM waits for a connection with no timeout. If you set a timeout with TypeORM's connectTimeoutMS option, give it enough time for the compute to start:
export const AppDataSource = new DataSource({
type: 'postgres',
url: process.env.DATABASE_URL,
ssl: true,
connectTimeoutMS: 10000,
entities: [
/*list of entities*/
],
});When the timeout is reached, pg throws Error: Connection terminated due to connection timeout.
note
TypeORM ignores the connect_timeout parameter in the connection string. Use connectTimeoutMS instead.
Next steps
- Set up Managed Better Auth: Add managed authentication that branches with your database
- Add Object Storage: S3-compatible file storage that branches with your database
- Deploy a Function: Run backend compute next to your database, no separate hosting needed
- Call an LLM with AI Gateway: Access foundation models from Anthropic, OpenAI, Google, and more with one credential
Need help?
Join our Discord Server to ask questions or see what others are doing with Neon. For paid plan support options, see Support.








