How to Connect NocoDB to PostgreSQL Using Docker (Fix Host Not Found Error)

If you’re connecting NocoDB to PostgreSQL in Docker and hitting “Host not found” — this guide fixes it in under 5 minutes.

You’ll get a working Docker Compose setup, the exact cause of every connection error, and a production-ready self-hosted Airtable alternative you can deploy on any VPS — DigitalOcean, AWS EC2, or your own server.

By the end, your NocoDB dashboard will be live and connected to PostgreSQL — no repeated errors.

What Is NocoDB and Why Use It With PostgreSQL?

NocoDB is a free, open-source no-code database tool and the most popular self-hosted Airtable alternative. It turns PostgreSQL, MySQL, and SQLite into a collaborative spreadsheet interface — complete with auto-generated REST and GraphQL APIs, role-based access control, and a no-code app builder.

When combined with PostgreSQL in Docker, you get:

• A fully self-hosted no-code platform
• Full control over your data
• No subscription costs or row limits
• Auto-generated REST and GraphQL APIs for backend use
• Role-based access control for your team

Quick Fix Checklist (Fix Connection Errors Fast)

Before setting up anything, check these common issues:

• Both containers must be on the same Docker network
• Use container name instead of localhost
• Avoid host.docker.internal on Linux
• Ensure PostgreSQL is running and accessible
• Verify username, password, and database name

This quick checklist alone fixes most connection errors instantly.

NocoDB PostgreSQL Connection String Example

Understanding the connection format helps avoid mistakes.

Method 1: Connect NocoDB Using Docker Run

This is the fastest way to get started for testing.

docker run -d --name nocodb-postgres \
  -v "$(pwd)"/nocodb:/usr/app/data/ \
  -p 8080:8080 \
  -e NC_DB="pg://host.docker.internal:5432?u=root&p=password&d=d1" \
  -e NC_AUTH_JWT_SECRET="your-secret-key-here" \
  nocodb/nocodb:latest

Replace credentials with your PostgreSQL details.

What each flag does:

• -v → Persists NocoDB data to your local folder so it survives container restarts
• -p 8080:8080 → Exposes NocoDB on port 8080 of your host machine
• NC_DB → Your PostgreSQL connection string
• NC_AUTH_JWT_SECRET → Secures your NocoDB login session

Note: host.docker.internal works on Mac and Windows only. On Linux, use your PostgreSQL container name instead (see Method 2).

Then open:

http://localhost:8080

Method 2: Connect Using Docker Compose (Recommended)

This is the best approach for production and stable setups.

Create docker-compose.yml:

services:
  postgres:
    image: postgres:17.2
    container_name: nocodb-postgres
    environment:
      POSTGRES_DB: nocodb
      POSTGRES_PASSWORD: mysecretpassword
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - nocodb-net
    restart: unless-stopped

  nocodb:
    image: nocodb/nocodb:latest
    container_name: nocodb
    depends_on:
      - postgres
    environment:
      NC_DB: "pg://postgres:5432?u=postgres&p=mysecretpassword&d=nocodb"
      NC_AUTH_JWT_SECRET: "your-jwt-secret"
    ports:
      - "8080:8080"
    volumes:
      - nocodb_data:/usr/app/data
    networks:
      - nocodb-net
    restart: unless-stopped

volumes:
  postgres_data:
  nocodb_data:

networks:
  nocodb-net:

Run:

docker-compose up -d

Pro tip: Add a healthcheck to your postgres service so NocoDB waits until PostgreSQL is truly ready — not just started. This prevents race condition errors on first boot.

When to Use Docker Run vs Docker Compose

Choosing the right method saves time and avoids future issues.

• Use Docker Run: Quick testing or temporary setup
• Use Docker Compose: Production or long-term projects
• Use external database: Existing apps (Prisma, backend systems)

Fix Host Not Found Error in NocoDB

This is the most common issue when connecting NocoDB to PostgreSQL.

Cause 1: Containers Not on Same Network

If containers are not on the same network, they cannot communicate.

Fix: Use a shared Docker network (as shown in Docker Compose above with nocodb-net).

Cause 2: Wrong Hostname

Using localhost inside Docker is incorrect. Docker containers are isolated — localhost inside NocoDB refers to the NocoDB container itself, not your PostgreSQL container.

Correct:

pg://postgres:5432

Wrong:

pg://localhost:5432

Cause 3: Using host.docker.internal on Linux

This works only on Mac and Windows Docker Desktop.

Fix (Linux only): Add this to your NocoDB service in docker-compose.yml:

yaml

extra_hosts:
  - "host.docker.internal:host-gateway"

Cause 4: PostgreSQL Not Accepting Connections

Sometimes PostgreSQL blocks external connections.

Fix: Test PostgreSQL is running and accessible:

bash

docker exec -it nocodb-postgres psql -U postgres -c "\l"

If this returns your database list, PostgreSQL is working. The issue is in your NocoDB connection string.

Connect NocoDB to Existing PostgreSQL (Prisma Setup)

If you already use PostgreSQL with Prisma or another backend:

1. Ensure both containers are on the same Docker network
2. Use container name as host in your NC_DB string
3. Connect via NocoDB UI → Team & Settings → External database

This allows NocoDB to act as a visual no-code layer on top of your existing database — without affecting Prisma migrations, schemas, or your existing backend.

One-Command Auto Setup (Production)

For production VPS deployments on DigitalOcean, AWS EC2, or Hetzner, use NocoDB’s auto-install script:

bash

bash <(curl -sSL http://install.nocodb.com/noco.sh) <(mktemp)

This automatically sets up a complete open-source no-code database stack:

• PostgreSQL — your primary database
• Redis — for caching and performance
• Minio — S3-compatible file storage for attachments
• Traefik — reverse proxy with automatic SSL/HTTPS

Best for: teams who want a fully managed self-hosted Airtable alternative without manual Docker configuration.

Why NocoDB + PostgreSQL Is Worth Using

This setup is powerful for modern teams and developers.

• No row limits beyond PostgreSQL’s own capacity
• No vendor lock-in — your data stays in your database
• Free and open-source forever (AGPL license)
• Role-based access control for teams
• REST and GraphQL APIs auto-generated from your tables
• Works alongside existing tools like Prisma, Hasura, or Supabase

FAQs

Why is NocoDB not connecting to PostgreSQL?

It usually happens due to wrong hostname (using localhost instead of container name), network mismatch between containers, or incorrect credentials.

Can I use localhost in Docker for PostgreSQL?

No. Inside Docker, localhost refers to the container itself. You must use the PostgreSQL container name (e.g. postgres) as the hostname.

Does host.docker.internal work on Linux?

No, it works only on Mac and Windows unless you manually add host.docker.internal:host-gateway to your extra_hosts config.

Is Docker Compose required for NocoDB?

No, but it is strongly recommended for production or any setup beyond quick local testing.

Can NocoDB connect to an existing PostgreSQL database?

Yes, NocoDB connects as a read/write layer on top of your existing database. It does not interfere with Prisma migrations or your existing schema.

Is NocoDB free for commercial use?

Yes. NocoDB is open-source under the AGPL license and free to self-host for commercial use.

Can I use NocoDB with Prisma on the same PostgreSQL database?

Yes — NocoDB and Prisma can share the same PostgreSQL instance. NocoDB reads and writes through its own connection and does not affect Prisma’s migrations or schema management.

Once you understand Docker networking, connecting NocoDB to PostgreSQL is straightforward. The “Host not found” error almost always comes from incorrect hostnames or missing network config — never the database itself.

NocoDB is one of the best free Airtable alternatives available in 2026 — and running it on your own PostgreSQL instance means zero row limits, zero subscription fees, and full data ownership.