Skip to main content

Database Connection Issues

Database connectivity problems are among the most common issues when deploying applications. This guide covers diagnosing and fixing connection errors for databases provisioned through Appliku.

Common Issues​

"Connection Refused"​

Your application logs show Connection refused when trying to connect to the database.

Common causes:

  • The database container is not running
  • The connection URL is wrong (wrong host, port, or database name)
  • The application is trying to connect before the database has started

Solutions:

  1. Check database status in the dashboard: Application > Databases > Manage
  2. Verify the DATABASE_URL environment variable is set correctly
  3. If the database was just created, give it a minute to initialize
  4. SSH into the server and check: docker ps | grep postgres (or mysql, redis, etc.)

Public vs Private Connection URL​

Appliku provides two connection URLs for each database:

  • connection_url (public) -- Uses the server's public IP. Use this when connecting from outside the server (e.g., from your local machine for debugging).
  • private_connection_url (private/internal) -- Uses Docker's internal network. Use this for your application containers running on the same server.
tip

Always use private_connection_url in your application's environment variables for best performance and security. The private URL routes traffic through Docker's internal network, avoiding the public internet entirely.

If your DATABASE_URL uses localhost or 127.0.0.1, it will not work inside a container. Docker containers have their own network namespace. Use the connection URL provided by Appliku instead.

Connection Timeout​

The application hangs when trying to connect to the database, eventually timing out.

Common causes:

  • Firewall blocking the connection port
  • Wrong port number in the connection URL
  • Database is on a different server and network routing is incorrect

Solutions:

  1. Verify the port in your connection URL matches the database's exposed port
  2. If connecting from outside the server, ensure the database port is open in the firewall
  3. Use the private connection URL for same-server connections

"Too Many Connections"​

The database refuses new connections because the maximum connection limit has been reached.

Symptoms:

  • FATAL: too many connections for role (PostgreSQL)
  • Too many connections (MySQL)
  • Application intermittently fails to connect

Solutions:

  • Use connection pooling in your application:
    • Django: Use django-db-connections or set CONN_MAX_AGE in database settings
    • Node.js: Configure pool size in your database client (e.g., pg pool options)
    • Rails: Set pool size in database.yml
  • Reduce the number of worker processes if each opens its own connection
  • For PostgreSQL, consider using PgBouncer as a connection pooler

How to Check Database Status​

  1. Dashboard: Go to Application > Databases > Manage and click on the database to see its status
  2. SSH: Connect to the server and run: 
    docker ps | grep postgres  # or mysql, redis, etc.
    docker logs <container-name> --tail 50
  3. Test connection: From the server, use the database client: 
    # PostgreSQL
    docker exec -it <postgres-container> psql -U <user> -d <database>

    # MySQL
    docker exec -it <mysql-container> mysql -u <user> -p

    # Redis
    docker exec -it <redis-container> redis-cli ping