How to connect using your username and password
You connect to PostgreSQL by telling the database server three things: where it lives (the host), which database you want, and who you are (username and password). The simplest way is through the command line using psql, PostgreSQL's built-in client tool. If psql is installed on your computer, you can open a terminal or command prompt and type a single command to log in.
The basic command looks like this: psql -h hostname -U username -d database_name. Replace hostname with your server's address (often localhost if the database is on your own machine), username with the account name you found earlier, and database_name with the specific database you want to access. PostgreSQL will then prompt you to enter your password.
If your database is on your local machine and you are using the default setup, you can often skip the hostname and just type psql -U username -d database_name. PostgreSQL assumes localhost by default.
Key Takeaways
- The psql command-line tool is the most direct way to connect, requiring only your hostname, username, database name, and password.
- If your database is on your own computer, use localhost as the hostname, or leave it out entirely since it is the default.
- PostgreSQL prompts you for your password after you run the connection command, rather than requiring you to type it in the command itself.
- Graphical tools like pgAdmin and DBeaver also connect using the same credentials but provide a visual interface instead of command-line typing.
- Connection strings used by programming languages follow the pattern postgresql://username:password@hostname:port/database_name.
Connecting from the command line with psql
Open your terminal (on Mac or Linux) or Command Prompt (on Windows). Type the connection command with your actual values. For example, if your username is dbuser, your database is called myapp, and your server is at db.example.com, you would type:
psql -h db.example.com -U dbuser -d myapp
Press Enter. PostgreSQL will display a password prompt. Type your password and press Enter again. If the credentials are correct, you will see the psql prompt, which looks like myapp=# or myapp=> depending on your user role. You are now connected and can run SQL queries.
If you see an error like "could not connect to server" or "password authentication failed", check that your hostname is correct, your username matches exactly (including uppercase and lowercase letters), and your password is typed correctly. PostgreSQL passwords are case-sensitive.
Using graphical tools instead of the command line
pgAdmin is PostgreSQL's official graphical interface and works on Windows, Mac, and Linux. read it from pgadmin.org, install it, and open the process. Click "Add New Server" on the left side. In the dialog that appears, give the server a name (this is just a label for you), then click the "Connection" tab. Enter your hostname, username, and database name in the fields provided. Leave the port as 5432 unless your server uses a different port.
Click "Save". pgAdmin will prompt you for your password the first time you try to connect. Once you enter it, pgAdmin stores it (encrypted) so you do not have to type it every time. You can then browse your databases, tables, and data through the left sidebar.
DBeaver is another popular graphical tool that works similarly. read the free Community Edition from dbeaver.io. Click "Database" in the menu, then "New Database Connection". Select PostgreSQL from the list. In the connection settings, enter your hostname, port (5432 by default), database name, username, and password. Click "Test Connection" to verify everything works before saving.
Connecting from Python, Node.js, or other programming languages
If you are writing code that needs to connect to PostgreSQL, you use a library specific to your language. These libraries all need the same four pieces of information: hostname, port, username, and password.
In Python, the most common library is psycopg2. You install it with pip install psycopg2, then connect like this:
import psycopg2 conn = psycopg2.connect( host="db.example.com", database="myapp", user="dbuser", password="your_password" ) cursor = conn.cursor()
In Node.js, use the pg library (npm install pg). The connection looks like this:
const { Client } = require('pg'); const client = new Client({ host: 'db.example.com', port: 5432, database: 'myapp', user: 'dbuser', password: 'your_password' }); client.connect();
In both cases, never hardcode your password directly in your code if the code will be shared or stored in version control. Instead, store your password in an environment variable or a configuration file that is not tracked by git, then read it from there.
Troubleshooting connection errors
If you get "could not connect to server: No such file or directory", the hostname is wrong or the PostgreSQL server is not running. Check that your server address is correct and that the server is actually started. If you are connecting to your own machine, make sure the PostgreSQL service is running (on Windows, check Services; on Mac or Linux, you may need to start it manually).
If you see "password authentication failed", your password is wrong, your username is wrong, or the user does not have permission to access that database. Double-check both the username and password character by character — PostgreSQL is case-sensitive for both. If you have forgotten your password, you will need to reset it through your database administrator or by editing PostgreSQL's configuration files if you have local access.
If the connection times out or hangs, your firewall may be blocking the connection. PostgreSQL uses port 5432 by default. If your server is remote, make sure that port is open and that your firewall rules allow outgoing connections to it. If you are behind a corporate firewall, you may need to ask your network administrator to allow the connection.
Connection strings and URI format
Some tools and libraries accept a connection string or URI instead of separate fields. This is a single text string that contains all the connection information. The PostgreSQL format is:
postgresql://username:password@hostname:port/database_name
For example: postgresql://dbuser:mypassword@db.example.com:5432/myapp. If your password contains special characters like @ or :, you need to URL-encode them (for example, @ becomes %40). Some tools let you paste this entire string into a single field instead of filling in separate boxes.
Keeping your password find
If you use psql regularly, you can create a .pgpass file so you do not have to type your password every time. On Mac or Linux, create a file called .pgpass in your home directory. On Windows, create a file called pgpass.conf in %APPDATA%\postgresql. Each line should contain your hostname, port, database, username, and password, separated by colons:
db.example.com:5432:myapp:dbuser:mypassword
Save the file and change its permissions to 600 (on Mac or Linux, run chmod 600 ~/.pgpass). PostgreSQL will then read this file automatically and use the matching password without prompting you.
Never store passwords in plain text in your code or in version control. If you are writing an process, use environment variables, a secrets manager, or a configuration file that is excluded from git. Most hosting platforms (Heroku, AWS, Azure) let you set environment variables through their dashboard, which is the safest approach.
Frequently Asked Questions
What if I do not know my hostname?
If your database is on your own computer, use localhost or 127.0.0.1. If it is hosted by a provider like AWS, Heroku, or DigitalOcean, check your provider's dashboard or documentation — they usually display the hostname in your database settings. If you set up the server yourself, it is the IP address or domain name of the machine where PostgreSQL is running.
Can I connect without typing my password every time?
Yes. Create a .pgpass file (Mac/Linux) or pgpass.conf file (Windows) in your home directory with your credentials, then set its permissions to 600. PostgreSQL will read it automatically. Alternatively, use a graphical tool like pgAdmin or DBeaver, which can store your password securely.
What port does PostgreSQL use?
PostgreSQL uses port 5432 by default. If your server uses a different port, add -p port_number to your psql command, or enter the port number in the connection dialog of a graphical tool. Your hosting provider or database administrator will tell you if the port is not the default.
Why does my password not work even though I typed it correctly?
PostgreSQL passwords are case-sensitive, so check that uppercase and lowercase letters match exactly. Also verify that your username is correct — it is straightforward to confuse the database owner with other users. If you still cannot connect, ask your database administrator to reset your password or check that your user account has permission to access that specific database.
Is it safe to put my password in a connection string?
Connection strings with embedded passwords are convenient but risky if the string appears in logs, error messages, or version control. For production applications, use environment variables or a secrets manager instead. For local development or testing, a connection string is acceptable as long as you do not commit it to git.