Troubleshooting: Database

Fix common database connection and query issues.

Connection Refused

Error: ECONNREFUSED 127.0.0.1:5432 or connect ECONNREFUSED 127.0.0.1:27017

This error means 1DevTool reached out to the host and port in your connection string, but nothing was listening there. The database server is either not running or is listening on a different port.

Fixes:

  • Check if the database is running. For PostgreSQL: run pg_ctl status in the terminal. For MySQL: mysqladmin status. For Redis: redis-cli ping (you should get PONG). Start the service if it is stopped.
  • Check the port. The default ports are 5432 (PostgreSQL), 3306 (MySQL/MariaDB), 27017 (MongoDB), and 6379 (Redis). Compare the port in your DATABASE_URL to the port your database is actually using.
  • Docker containers. If your database is running inside Docker, check that the container is running with docker ps. If it is not listed, start it with docker start <container-name>. Also confirm that the container's port is published to your host (look for 0.0.0.0:5432->5432/tcp in docker ps output).

Authentication Failed

Error: password authentication failed for user "postgres" or Access denied for user 'root'@'localhost'

The username or password in your connection string does not match what the database server expects.

Fixes:

  • Double-check the username and password in your DATABASE_URL or connection settings. It is easy to confuse your Supabase account password with the database password — they are different. Use the password shown in the Supabase dashboard under Settings → Database.
  • Special characters in passwords. If your password contains @, #, /, or :, these characters must be URL-encoded in the connection string. For example, @ becomes %40 and # becomes %23. A password like p@ss#word would be written as p%40ss%23word in the URL.

SSL/TLS Required

Error: SSL connection has been closed unexpectedly or server requires SSL but client does not support it

Many cloud database providers (Supabase, Neon, Railway, Render) require encrypted connections.

Fix: Add ?sslmode=require to the end of your PostgreSQL connection string:

postgresql://user:pass@host:5432/db?sslmode=require

For MongoDB Atlas, use the mongodb+srv:// scheme in your connection string — it enables TLS automatically and does not need an extra parameter.

Query Times Out

Cause: the query is scanning too much data, or the network connection between 1DevTool and the database dropped mid-query.

Fixes:

  • Add a LIMIT clause to your query while exploring data. For example: SELECT * FROM orders LIMIT 100.
  • If a specific query is always slow, check whether the columns in your WHERE clause have indexes. Running EXPLAIN ANALYZE <your query> in the SQL editor will show you the query plan.
  • If timeouts happen intermittently, check your network. VPN connections in particular can cause flaky database connectivity.

MongoDB: Special Characters in Password

If your MongoDB password contains @, /, :, or #, you must URL-encode those characters in the connection string. These characters have special meaning in a URL and will break parsing if used literally.

Common encodings: @ → %40, # → %23, / → %2F, : → %3A.

Example: a password of my@secret#pass becomes my%40secret%23pass in the connection string.

Cannot Connect to Docker Container

If your database is running inside a Docker container and you are trying to connect from 1DevTool (which runs on your host machine), do not use localhost in your connection string. From the host, localhost refers to the host machine itself — not the container.

Use host.docker.internal instead:

postgresql://user:[email protected]:5432/db

This special hostname always resolves to your host machine from inside Docker, and to the correct loopback interface from the host side.