How do I connect to PostgreSQL without specifying a database name?
When attempting to list available databases or perform administrative tasks on a PostgreSQL server, a common stumbling block is the pg_connect() function in PHP. The error message FATAL: database "testuser" does not exist immediately tells you that the connection string requires a specific database name, even if your intention is merely to authenticate and access the template1 system database or list schemas.
The core misunderstanding often lies in how the PostgreSQL server interprets the connection string versus how it behaves with a missing target. When you call pg_connect("host=localhost user=testuser password=123"), the client library attempts to connect to the default database for that user. By default, this is usually the same as the username (testuser). If that database does not exist, the connection fails immediately because the server cannot assign a session context without a target database.
To list databases or interact with system catalogs without creating a specific application database first, you must explicitly connect to the template1 database. This is the standard approach used by tools like phpPgAdmin and is consistent with PostgreSQL architecture. The template1 database acts as the "template" from which new user databases are created; it contains the standard system objects and procedural languages that should be available in every new database.
You can modify your connection string to target this specific database:
$connection = pg_connect("host=localhost user=testuser password=123 dbname=template1");
Alternatively, if you are using a PostgreSQL version that supports the OPTIONS keyword for specifying default search path or other session attributes without needing a separate database name in older syntax, you might be tempted to leave it blank. However, leaving the dbname parameter empty or omitting it entirely will still default to the user's namesake database if one exists, or fail with the exact error you encountered if it does not.
If you need to connect as a superuser (like postgres) to list all databases without creating a specific project database, connecting to template1 is the correct path. Once connected to template1, you can run queries against the pg_database system catalog to retrieve the list of available databases.
$result = pg_query($connection, 'SELECT datname FROM pg_database WHERE datistemplate = false ORDER BY datname');
while ($row = pg_fetch_assoc($result)) {
echo $row['datname'] . "\n";
}
It is crucial to understand that connecting to template1 does not grant you unrestricted access to user databases unless you have the necessary privileges. You are technically in a system database, but your ability to run specific queries depends on your role and permissions within that system context. If you require full access to list all databases including those marked as templates, ensure your connection string includes the appropriate superuser credentials or grant CONNECT and CREATEDB roles appropriately.
In modern application stacks using frameworks like Laravel, this concept translates directly into database configuration. While you typically configure a specific database for your application, administrative scripts should explicitly target system databases. If you are maintaining legacy code or building utility scripts that need to scan the server state, always ensure the dbname parameter is set to template1 or the specific user-created database you intend to inspect, avoiding the implicit default behavior that leads to connection failures when the user's default database is missing.