How to Integrate Replit with PostgreSQL

Open your Replit project and look at the left sidebar. You will see a database cylinder icon labeled 'Database.' Click it to open the Database panel. If your project does not yet have a database, you will see a button labeled 'Create a database' or 'Enable PostgreSQL.' Click it. Replit provisions a PostgreSQL database in approximately 10–30 seconds. Once provisioned, the panel shows two tabs: one for the development database (used while coding in the editor) and one for the production database (used by deployed apps). You will also see a connection string and individual credential fields displayed. These credentials are automatically injected as environment variables — you do not need to copy them anywhere. The six auto-injected variables are: DATABASE_URL (full connection string), PGHOST, PGPORT, PGDATABASE, PGUSER, and PGPASSWORD. These are available immediately in all your code via os.environ in Python and process.env in Node.js, with no additional configuration needed.

With the database provisioned and credentials auto-injected, connecting your app requires only installing a database driver and writing a few lines of connection code. For Node.js apps, the most common options are the pg library (raw SQL), Prisma (type-safe ORM), or Drizzle (lightweight ORM). For Python apps, the standard choices are psycopg2 (raw SQL) or SQLAlchemy (ORM). In all cases, the connection string is the same: read DATABASE_URL from the environment. There is no need to construct a connection string manually or configure SSL separately — Replit's built-in database uses a local network connection that does not require SSL. For production resilience, use connection pooling rather than creating a new connection on every request. The pg library's Pool class and SQLAlchemy's engine both handle pooling automatically. The most important pattern for Replit's database: implement reconnect logic because the database sleeps after 5 minutes of inactivity, and a sleeping database causes the first query after idle to fail with a connection error before the database wakes up.

1// Node.js — using pg with connection pooling
2const { Pool } = require('pg');
3
4const pool = new Pool({
5  connectionString: process.env.DATABASE_URL,
6  // No SSL needed for Replit's built-in database
7  // For external PostgreSQL providers, add: ssl: { rejectUnauthorized: false }
8  max: 10,               // max pool size
9  idleTimeoutMillis: 60000,  // close idle connections after 60s
10  connectionTimeoutMillis: 5000  // fail fast if can't connect in 5s
11});
12
13// Test connection on startup
14pool.query('SELECT NOW()', (err, res) => {
15  if (err) {
16    console.error('Database connection failed:', err.message);
17  } else {
18    console.log('Database connected at:', res.rows[0].now);
19  }
20});
21
22module.exports = pool;
23
24---
25
26# Python — using psycopg2 with connection pool
27import os
28import psycopg2
29from psycopg2 import pool
30
31connection_pool = psycopg2.pool.SimpleConnectionPool(
32    minconn=1,
33    maxconn=10,
34    dsn=os.environ['DATABASE_URL']
35)
36
37def get_connection():
38    return connection_pool.getconn()
39
40def release_connection(conn):
41    connection_pool.putconn(conn)
42
43# Test connection
44conn = get_connection()
45with conn.cursor() as cur:
46    cur.execute('SELECT NOW()')
47    print('Connected at:', cur.fetchone()[0])
48release_connection(conn)

With the connection established, create your database schema. You can do this in three ways on Replit: using the SQL runner in the Database panel sidebar (good for quick schema setup), using the Replit Agent (good for generating and running migrations from a description), or by writing migration code in your application (good for production apps that need version-controlled schema changes). The Agent approach is the fastest for getting started: describe your data model in plain English and the Agent generates both the CREATE TABLE statements and the corresponding application code. For a more structured approach, use Drizzle's schema definition and migration system or Prisma's schema file. Both ORM tools generate type-safe client code from your schema definition, which catches column name typos and type mismatches at compile time. When seeding initial data for development, use INSERT statements or your ORM's seed script. Remember that seed data inserted in development mode stays in the development database — it will not appear in production. If you need the same initial data in production, run the seed against the production database explicitly after deploying.

1// Drizzle ORM schema — schema.js
2const { pgTable, serial, text, timestamp, varchar, integer } = require('drizzle-orm/pg-core');
3
4exports.users = pgTable('users', {
5  id: serial('id').primaryKey(),
6  email: varchar('email', { length: 255 }).notNull().unique(),
7  passwordHash: text('password_hash').notNull(),
8  createdAt: timestamp('created_at').defaultNow().notNull()
9});
10
11exports.projects = pgTable('projects', {
12  id: serial('id').primaryKey(),
13  userId: integer('user_id').references(() => exports.users.id).notNull(),
14  name: varchar('name', { length: 255 }).notNull(),
15  description: text('description').default(''),
16  status: varchar('status', { length: 50 }).default('active').notNull(),
17  updatedAt: timestamp('updated_at').defaultNow().notNull()
18});
19
20// Run migration: drizzle-kit push (or use the SQL runner in Replit Database panel)

Replit includes Drizzle Studio, a visual database browser, directly in the editor. To open it, click the Database icon in the sidebar, then click the 'Open Drizzle Studio' button in the Database panel. Drizzle Studio opens as an embedded tab showing all your tables in a spreadsheet-style interface. You can browse rows, edit values inline, add new rows, and run raw SQL queries — all without writing any code. This is the fastest way to verify that your application is inserting data correctly, inspect foreign key relationships, or quickly fix a bad row in development. Drizzle Studio connects to your development database by default. When you deploy your app and need to inspect production data, you can connect Drizzle Studio to the production database by switching the database connection in the panel (click the database name dropdown in the sidebar). Be careful when editing production data directly — there is no undo for manual edits made outside your application code.

Replit's built-in PostgreSQL database sleeps after approximately 5 minutes without any queries. This is a cost-saving measure that works well for development but requires special handling for production web apps. When the database is asleep and your app tries to connect, the first query will fail with a connection error (typically 'Connection refused' or 'ECONNREFUSED'), and the database will start waking up. Subsequent queries — usually within 1–3 seconds — will succeed. The solution is to implement retry logic in your database layer so that a single failed query triggers a brief wait and retry rather than returning an error to your user. In practice, for apps deployed on Autoscale Deployment (which itself scales to zero), both the app and the database may be asleep simultaneously when a user first visits. The combined cold start can take 3–5 seconds. For apps where this latency is unacceptable, use a Reserved VM Deployment (which keeps your app always running) and ensure your database connection pool sends a keepalive query (e.g., SELECT 1) every few minutes to prevent the database from sleeping. The pg library's keepAlive option and connection heartbeat interval settings handle this automatically.

1// Node.js — pg Pool with keepalive and retry wrapper
2const { Pool } = require('pg');
3
4const pool = new Pool({
5  connectionString: process.env.DATABASE_URL,
6  max: 10,
7  idleTimeoutMillis: 60000,
8  connectionTimeoutMillis: 5000,
9  // Send keepalive to prevent database sleep during idle periods
10  keepAlive: true,
11  keepAliveInitialDelayMillis: 200000  // start keepalive after ~3 min idle
12});
13
14// Retry wrapper for transient connection failures
15async function queryWithRetry(text, params, retries = 3) {
16  for (let i = 0; i < retries; i++) {
17    try {
18      return await pool.query(text, params);
19    } catch (err) {
20      if (i === retries - 1) throw err;
21      if (err.code === 'ECONNREFUSED' || err.message.includes('Connection')) {
22        console.log(`DB connection attempt ${i + 1} failed, retrying in 2s...`);
23        await new Promise(r => setTimeout(r, 2000));
24      } else {
25        throw err; // Non-connection errors should not be retried
26      }
27    }
28  }
29}
30
31module.exports = { pool, queryWithRetry };