Installing PostgreSQL
On This Lesson 11 topics
Lesson Overview
In BEG-049 you designed the Library tables on paper, and in BEG-050 you wrote SQL against a ready-made database. Now you build the real thing yourself, and the first step is getting a database server running on your own computer. This lesson installs PostgreSQL, explains what exactly you have installed, and checks that it works by connecting to it.
We will use a library building as the picture for the whole module. The building is the PostgreSQL server. Inside it there are rooms (databases), shelves (schemas), staff keys (users), and rules on the door (constraints). Today we only unlock the front door and walk in.
Why this matters: every later backend module that stores data (and most real services do) assumes a PostgreSQL server that you can start, reach, and trust. A broken or half-understood installation costs hours later.
This lesson builds on BEG-005 (using a terminal) and BEG-050 (SQL statements). No other background is needed.
Learning Objectives
By the end of this lesson you will be able to:
- Explain the difference between a database server and the client programs that talk to it.
- Choose an installation route (native installer, package manager, or container) and state what each gives you.
- Name what the installer asks for: the superuser password, the port, and a data location.
- State the default port and why a database normally listens only on the local machine.
- Verify an installation with
psql --versionandSELECT version();. - Read the two most common first-connection errors and say what they mean.
Written Explanation
Server and clients
PostgreSQL is an open-source relational database management system (DBMS). It works in a client-server way:
- The server is a program that runs in the background (on Windows, usually as a service). It owns the data files and answers requests.
- A client is any program that connects to the server and sends SQL:
psqlin a terminal, a graphical tool such as pgAdmin, and later your Java application.
This split matters because "PostgreSQL is installed" can mean two different things: the server is running, or a client program is available. You need both. In the library picture: the server is the building, and a client is a visitor at the front desk who asks for things.
Where the server listens
A client reaches the server over the network, even when both are on the same laptop. It needs an address and a port. The PostgreSQL manual says the server listens on TCP port 5432 by default, and that its listen_addresses setting defaults to localhost, which allows only connections from the same machine. That is a good default for learning: nobody else on the network can knock on your door.
| Setting | Default | Meaning |
|---|---|---|
port | 5432 | Which door number clients knock on |
listen_addresses | localhost | Only this computer may connect |
If another program already uses 5432, the installer or configuration may use a different port. Always check the port rather than assuming.
Ways to install
You only need one of these. Menu names and download pages change, so treat the steps as a map, not a script.
| Route | What you get | Good for |
|---|---|---|
| Native installer (Windows, macOS) | Server, command-line tools, usually pgAdmin | Beginners on a personal computer |
| Package manager (many Linux distributions, or Homebrew on macOS) | Server and tools as packages | People comfortable with a terminal |
| Container (Docker or similar) | A disposable server in an isolated box | Developers who want to throw it away and start again |
The PostgreSQL download page for Windows points to an interactive installer built and hosted by EDB. According to that page, it includes the server, pgAdmin (a graphical tool), and StackBuilder (a helper for add-on tools). The page does not say whether psql is installed, so look at the component list the installer shows and keep the command-line tools ticked. Check postgresql.org for the current download links before you install.
This course assumes a local native install. If you prefer a container, the later lessons work the same once you can reach the server; the container route needs Docker skills that this module does not teach.
What the installer asks
Installers differ, but expect these questions:
- Which components? Keep the server and command-line tools. A graphical tool is useful for Lesson 2.
- Where do the data files go? The installer proposes a folder. Accept the default unless you have a reason.
- A password for the
postgressuperuser. When the cluster is created, PostgreSQL makes one all-powerful role. Many packaged installs name itpostgres. Choose a password you will remember and keep it in a password manager. Never put it in a file you commit to Git. - A port. Accept 5432 unless it is taken.
- A locale. The default is fine for now.
Do not tell anyone else the superuser password, and never reuse a password from another service. For this local learning install the risk is small, but the habit is the point.
Checking that it works
There are two checks, and they test different things.
Check 1: the client is installed.
psql --versionThis prints the version of the psql program. It does not contact the server. If your terminal answers "command not found" (or "not recognized" on Windows), the program is probably installed but its folder is not on your PATH. Find the installation's bin folder (its location depends on version and operating system) and either add it to PATH or run the program by its full path.
Check 2: the server answers.
psql -U postgres-U postgres means "connect as the user postgres". psql asks for the password you chose. After a successful login you see a prompt such as postgres=#. Type:
SELECT version();If a row comes back naming PostgreSQL and a version, the server is running and you can talk to it. Type \q to quit.
Two first errors
Connecting to a server fails in a few predictable ways. The wording below comes from real attempts.
FATAL: role "nobody" does not exist: the server is running and reachable, but you named a user it does not know.FATAL: database "nolib" does not exist: the user is fine, but the database name is wrong.
Both errors are good news in one sense: the server answered. If instead you see that the connection was refused or the server is not accepting connections, the server is not running or you used the wrong port. A wrong password is reported in a similar FATAL message from the server.
Examples
Example 1: checking the client (simple)
psql --versionExpected result: one line with the program name and a version number, which depends on what you installed. This proves only that the client exists. Think of it as checking that the visitor has arrived, not that the building is open.
Example 2: the first connection and SELECT version(); (practical)
$ psql -U postgres
Password for user postgres:
postgres=# SELECT version();
version
------------------------------------------------------------
PostgreSQL 18.3 on x86_64-windows, compiled by msvc-19.44.35225, 64-bit
(1 row)
postgres=# \qThe password prompt does not show what you type. The exact version text depends on your installation, operating system, and compiler: on Linux or macOS it will look different. The row proves that the server is running, accepts you, and runs SQL. The outputs in this module come from PostgreSQL 18.3 on Windows using a scratch server on port 55432, so wherever an output mentions a port, yours will show 5432 unless you changed it.
Example 3: reading a failed connection (realistic)
A teammate says "I installed Postgres but it does not work". You ask them to run the command and paste the message.
psql -U nobody -d librarypsql: error: connection to server at "localhost" (::1), port 55432 failed: FATAL: role "nobody" does not existRead it from left to right: connection to server at "localhost" and a port tell you where the client knocked; failed: FATAL: is what the server said back; role "nobody" does not exist is the cause. The server is fine. The fix is to use a real user, for example postgres. Asking for the full message first saves guessing.
Backend Insight
Real services never start with "install a database on my laptop". But your development machine mirrors production in one important way: the application is a client of a database server, found by a host, a port, a database name, a user, and a password. Those five values will appear in the configuration of your Java application later in the curriculum. Learning them now, in their plain form, makes configuration files readable.
Also note the security default: a server that listens only on localhost is invisible to the network. Production databases are usually configured to accept connections only from the application servers that need them. "Open to the whole internet" is rarely what you want.
Common Mistakes
Mistake 1: Treating psql --version as proof the server works
- Incorrect: "
psql --versionprinted a number, so Postgres is running." - Correct: that command only shows the client's version. Connect and run
SELECT version();to test the server.
Mistake 2: Forgetting or losing the superuser password
The installer asks only once. Write it in a password manager at install time. If you lose it, recovery is possible but fiddly, and reinstalling a learning server is often faster.
Mistake 3: Assuming the port is always 5432
If you already had another PostgreSQL (or a different tool) on that port, the installer may choose another. When a connection is refused, check the port before anything else.
Mistake 4: Putting the password in a command or a committed file
Typing a password into a shell command stores it in history. Let psql prompt for it. Anything you commit to Git is effectively public to the team forever.
Exercises
Try each exercise yourself before opening the solutions.
Level A: Foundation
A1. What is the default port of a PostgreSQL server, and what does the default listen_addresses setting allow?
Show solution A1
A1. The default port is 5432. The default listen_addresses is localhost, so only connections from the same computer are accepted.
A2. Name one server program and two client programs from this lesson.
Show solution A2
A2. Server: the PostgreSQL server (the installed service). Clients: psql, and pgAdmin or DBeaver (the Java application later in the curriculum is also a client).
A3. What does the installer ask you to choose that you must remember later?
Show solution A3
A3. The password of the postgres superuser. You also choose a port and a data folder, but accepting the default for these is normal.
Level B: Application
B1. After installing, psql --version prints a version but psql -U postgres says it cannot connect. Name two possible causes.
Show solution B1
B1. The server may not be running (for example the service did not start), or you are using the wrong port or host. A wrong password is also possible and would show an authentication message from the server.
B2. Write the command to connect as postgres to the database named postgres, using the explicit -d option, and say what you should see on success.
Show solution B2
B2. psql -U postgres -d postgres. After you enter the password you should see the prompt postgres=#.
B3. A message says role "admin" does not exist. Does it tell you the server is down? Explain.
Show solution B3
B3. No. The server answered and rejected the name. Only the user name is wrong, or that role has not been created.
Level C: Challenge
C1. A classmate runs a container with PostgreSQL on port 5433 on the same laptop where you have the native install on 5432. Explain how the two can run together without clashing and how each of you must connect.
Show solution C1
C1. Each server listens on its own port, so they do not clash: the native one on 5432, the container on 5433. You connect with psql -p 5433 (and the container's user) for the container, and the default port for yours. Using the wrong port connects you to the wrong server, which is a common confusion.
C2. A teammate proposes setting the server to listen on every network address "so we can all share one database". List two risks and one safer alternative.
Show solution C2
C2. Risks: anyone who can reach the network can try to log in (password guessing, exposure of all data), and a mistake in one person's script can damage everyone's data. Safer: each person runs a local server and shares a SQL script through Git, or the team uses a properly secured shared server with limited users.
Mini Challenge
Install PostgreSQL (or confirm you have it), then write a short "install log" in a text file with these lines:
- The installation route you used and the version printed by
psql --version. - The port, and where you stored the superuser password (do not write the password itself).
- The first line returned by
SELECT version();. - One error you hit, copied exactly, with what it meant. If you hit none, deliberately run
psql -U nobody -d postgresand record the error.
Check your work: step 3 came from the server, not from --version, and the log contains no password.
Summary & Next Lesson
Key takeaways
- PostgreSQL is a client-server DBMS: the server owns data, clients such as
psqlsend SQL. - By default the server listens on port 5432 and accepts only local connections.
- The installer asks for a superuser password (often
postgresis the role name); store it safely. psql --versiontests the client;SELECT version();after connecting tests the server.- Read errors word by word:
role does not existanddatabase does not existmean the server is up.
Next lesson
The next lesson, "psql and a GUI client", shows how to work in psql (listing databases and tables) and in a graphical tool such as pgAdmin or DBeaver, and when each is the better choice.
Self-check
- What is the difference between a server and a client?
- Which port does PostgreSQL use by default?
- Which command proves the server (not just the client) works?
- What does
role "x" does not existtell you about the server? - Why is "listen only on localhost" a safe default?
Show answers
- The server runs in the background and owns the data; a client connects to it and sends SQL.
- 5432.
- Connecting with
psql -U postgresand runningSELECT version();. - The server is running and reachable; you just named a user it does not have.
- No other machine on the network can connect, so only you can reach your data.
References
- PostgreSQL documentation, Connections and Authentication settings. Supports:
portdefaults to 5432 andlisten_addressesdefaults tolocalhost. - PostgreSQL, Download for Windows. Supports: the installer is provided by EDB and includes the server, pgAdmin, and StackBuilder; the page does not state whether
psqlis included or the default port, so that is hedged in the text. - PostgreSQL documentation, Database Roles. Supports: initdb creates a superuser, often named
postgresin packaged installs, and roles are cluster-wide. - PostgreSQL documentation, psql. Supports:
-U,-d,-poptions and the\qmeta-command. - The container route and package-manager steps were not checked against vendor pages, so they are described only in general terms. The
FATALmessages and the version line were run on a local PostgreSQL 18.3 test server.
Practice
Apply this lesson with the module's lab, exercises and quiz.
Marking a lesson complete is optional and you can undo it any time. Your progress stays in this browser.