database does not exist

What it means

A PostgreSQL server holds several databases, and every connection is to one of them. This message says the server accepted who you are (and your password, if it asked for one), then found no database with the exact name you asked for. Names are compared exactly, so MyApp and myapp are different databases.

The SQLSTATE is 3D000 (invalid_catalog_name). Statements that name a missing database, such as DROP DATABASE or ALTER DATABASE, fail with the same code as an ERROR.

Common causes

1. No database name was given, so the client used your user name. Connect as app without -d and libpq asks for a database called app.
2. A typo, or a capital letter. A database created as "MyApp" in quotes keeps its capitals. Connection settings, psql -d and psql’s \c take the name as typed, but an unquoted name in SQL is folded to lower case: DROP DATABASE MyApp looks for myapp.
3. It was never created. The app or its migration tool expects the database to exist, and nobody ran the step that creates it.
4. The Docker settings changed after the first start. The official image creates POSTGRES_DB only when it starts with an empty data directory; changing it later on an existing volume creates nothing.
5. A different server. The database exists on another install, container or port than the one you reached.

How to fix it

Name the database

psql -h <host> -U <user> -d <database>

In a URL, the database is the path: postgresql://<user>@<host>:5432/<database>. With no path, the user name is used.

List what’s there

Every new server has a database called postgres for this kind of maintenance. Connect to it and look:

SELECT datname FROM pg_database WHERE NOT datistemplate ORDER BY datname;

psql -l prints the same list, with owners and encodings, and exits. It connects to postgres when you don’t give a database, so it works even when the one named after you doesn’t exist.

Create it

As a superuser or a role with CREATEDB:

CREATE DATABASE app OWNER app;

createdb -O app app does the same from the shell. CREATE DATABASE can’t run inside a transaction block, so run it on its own.

Quote names with capitals

DROP DATABASE "MyApp";

Better still, use lower-case names, so nobody has to remember the quotes.

Check which server you reached

On a connection that works, these say where you are:

SELECT inet_server_addr(), inet_server_port(), version();

If a local Homebrew server and a Docker container both run on your Mac, they listen on different ports, and each has its own databases.

Reproduce it

On PostgreSQL 18.6, asking for a database that isn’t there:

psql -h localhost -p 54318 -U inlet -d seo_pgconn_missing -c 'select 1'

psql: error: connection to server at "localhost" (::1), port 54318 failed: FATAL:  database "seo_pgconn_missing" does not exist

The password is checked first: the same command with a wrong password gets password authentication failed instead.

With no -d, the database name is the user name. Connecting as a role called seo_pgconn_login (inside the container, over the trusted local socket):

docker exec inlet-test-pg18-1 psql -U seo_pgconn_login -c 'select 1'

psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: FATAL:  database "seo_pgconn_login" does not exist

Capitals: after CREATE DATABASE "Seo_pgconn_Case", \c Seo_pgconn_Case connects. The lower-case name doesn’t, and neither does an unquoted name in SQL:

\c seo_pgconn_case
DROP DATABASE Seo_pgconn_Case;

\connect: connection to server at "localhost" (::1), port 54318 failed: FATAL:  database "seo_pgconn_case" does not exist
ERROR:  database "seo_pgconn_case" does not exist

DROP DATABASE seo_pgconn_missing;, with \set VERBOSITY verbose to show the code:

ERROR:  3D000: database "seo_pgconn_missing" does not exist
LOCATION:  dropdb, dbcommands.c:1702

A temporary server’s log, set to print the SQLSTATE, shows the same 3D000 for the connection error:

2026-10-09 10:07:06.898 UTC [99] 3D000 FATAL:  database "appdb" does not exist

In Inlet

The connection window shows the server’s message with a hint for common causes; check the database field. If you paste a connection URL, Inlet fills the form from it, so you can see which database name it carries before you connect.