Fix the “NestJS cannot connect to PostgreSQL on Shared VPS” Error Before Your Next Deployment Deadline

You’ve spent hours polishing a NestJS micro‑service, pushed it to your shared VPS, and then—bam—“cannot connect to PostgreSQL” pops up. Your heart races, the deployment deadline looms, and the client’s patience is wearing thin. Don’t let a mis‑configured database ruin the rollout. In this guide we’ll walk through the exact steps to diagnose, fix, and future‑proof your NestJS‑PostgreSQL connection on a shared VPS—so you can hit Deploy with confidence.

Why This Matters

A broken DB connection isn’t just a technical hiccup; it translates to lost revenue, angry users, and wasted developer hours. On a shared VPS you also share limited resources, making every second of downtime count even more. Fixing the issue quickly not only saves money but also builds trust with stakeholders who expect “it just works” every time you push code.

Step‑by‑Step Tutorial

1. Verify VPS Network Settings

   Log into your VPS via SSH and run:

   sudo netstat -plnt | grep 5432

   If you don’t see PostgreSQL listening on 0.0.0.0:5432 (or the custom port you configured), edit postgresql.conf:

   sudo nano /etc/postgresql/12/main/postgresql.conf
   # Find the line:
   #listen_addresses = 'localhost'
   # Change to:
   listen_addresses = '*'

   Restart PostgreSQL:

   sudo systemctl restart postgresql

2. Configure pg_hba.conf for Remote Auth

   Open the host‑based authentication file and add an entry for your app’s IP range (or use 0.0.0.0/0 for testing only):

   sudo nano /etc/postgresql/12/main/pg_hba.conf
   # Add:
   host    all             all             0.0.0.0/0               md5

   Reload the rules:

   sudo systemctl reload postgresql

3. Create a Dedicated Database User

   Never use postgres for your app. From the psql prompt:

   CREATE USER nest_user WITH PASSWORD 'SuperSecret123!';
   CREATE DATABASE nest_db OWNER nest_user;
   GRANT ALL PRIVILEGES ON DATABASE nest_db TO nest_user;

4. Open the VPS Firewall (ufw)

   Shared VPS often have ufw enabled. Allow traffic on the PostgreSQL port:

   sudo ufw allow 5432/tcp
   sudo ufw reload

5. Update NestJS TypeOrmModule Config

   In app.module.ts (or a dedicated DB module), replace the connection options with the exact values you set on the VPS:

   import { TypeOrmModule } from '@nestjs/typeorm';
   
   @Module({
     imports: [
       TypeOrmModule.forRoot({
         type: 'postgres',
         host: 'YOUR_VPS_IP',        // e.g., 203.0.113.42
         port: 5432,
         username: 'nest_user',
         password: 'SuperSecret123!',
         database: 'nest_db',
         entities: [__dirname + '/**/*.entity{.ts,.js}'],
         synchronize: true,
       }),
       // …other modules
     ],
   })
   export class AppModule {}

   Tip: Keep synchronize: true only in dev. Switch to migrations for production to avoid accidental schema changes.

6. Test the Connection Locally

   Run the NestJS app on the VPS (or locally with the remote DB settings) and watch the logs:

   npm run start:prod
   # Expected output:
   #   [Nest] 12345   - 2026-05-04 12:00:00   LOG [NestApplication] NestJS application successfully started
   #   [Nest] 12345   - 2026-05-04 12:00:01   LOG [TypeOrmModule] Connected to PostgreSQL at 203.0.113.42:5432

7. Deploy with PM2 (Optional but Recommended)

   PM2 keeps your app alive across crashes and reboots—critical on shared hosting.

   npm install -g pm2
   pm2 start dist/main.js --name nest-app
   pm2 save
   pm2 startup

Real‑World Use Case: E‑Commerce API on a $5 Shared VPS

Imagine you run a small online store that needs a fast API for inventory and checkout. You chose NestJS for its modularity and TypeORM for rapid development. After the first deployment you hit the “cannot connect to PostgreSQL” wall because the default localhost binding only allowed local connections. By applying the steps above you:

• Opened port 5432 to the internet (secured with a strong password).
• Created a limited‑privilege DB user, reducing the blast radius of any future breach.
• Automated process management with PM2, guaranteeing 99.9% uptime on a cheap VPS.

The result? Your API handled 1,200 requests per minute during a flash sale, and you avoided a $200 downtime cost.

Results / Outcome

After completing the checklist you’ll see:

• Clear, error‑free logs confirming a successful DB handshake.
• A hardened PostgreSQL configuration that still works on a shared environment.
• Reduced deployment time from hours to minutes—giving you more room to add features.

Bonus Tip: Enable log_connections = on in postgresql.conf and watch /var/log/postgresql/postgresql-12-main.log to verify each incoming connection. This is a quick sanity check before you push to production.

Bonus Tips for Long‑Term Stability

• Use Environment Variables: Store DB credentials in .env and load with @nestjs/config to keep secrets out of source control.
• Enable SSL: Even on a shared VPS, enable ssl: true in the TypeORM config if your provider supports it.
• Automated Backups: Set up a daily pg_dump cron job and ship the dump to an S3 bucket.
• Connection Pooling: Tweak extra: { max: 20 } in TypeORM to match the VPS’s RAM limits.

Warning: Never expose PostgreSQL to the public internet without a strong password and limited IP ranges. If possible, restrict access to the VPS’s internal network only.

Monetization (Optional)

If you found this guide useful, consider offering a premium “One‑Click VPS Setup Script” on Gumroad for $9.99. It bundles all the ufw, postgresql.conf, and pg_hba.conf tweaks into a single setup.sh file—perfect for busy devs who want to automate the entire process.

© 2026 Your Developer Hub – All rights reserved.