PostgreSQL Quickstart

postgres/postgres

B Clarity
8 Steps
15 min Time
macOS, Linux, Windows Tested On
100% Copy-Paste Ready
0 Issues

Get PostgreSQL running on your machine and create your first database in under 15 minutes. This guide covers installation, basic SQL operations, and essential database management.

Prerequisites

  • 💻
    Operating System macOS 12+, Ubuntu 20.04+, or Windows 10/11
  • 💾
    Disk Space At least 500MB free
  • 🔑
    Admin Access sudo/administrator privileges required for installation

Install PostgreSQL

1

Install PostgreSQL

~3 min

Download and install PostgreSQL for your platform:

macOS (using Homebrew):

bash 
brew install postgresql@16

💡 After installation, follow the instructions to add PostgreSQL to your PATH.

Linux (Ubuntu/Debian):

bash 
# Add PostgreSQL APT repository
sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'

Import repository signing key


wget –quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -


Update and install


sudo apt-get update
sudo apt-get install postgresql-16

Windows:

powershell 
winget install PostgreSQL.PostgreSQL

⚠️ The Windows installer will prompt you to set a password for the postgres user. Remember this password!

Start the Server

2

Start the Server

~1 min

Start the PostgreSQL server:

macOS:

bash 
brew services start postgresql@16
Expected output: 
==> Successfully started `postgresql@16` (label: homebrew.mxcl.postgresql@16)

Linux:

bash 
sudo systemctl start postgresql
sudo systemctl enable postgresql

Windows:

powershell 
net start postgresql-x64-16

💡 On Windows, the service usually starts automatically after installation.

Create a Database

3

Create a Database

~1 min

Create a new database for your project:

macOS/Linux:

bash 
createdb myapp

Windows (or if you need to specify a user):

bash 
createdb -U postgres myapp

📝 On Linux, you may need to run as the postgres user: sudo -u postgres createdb myapp

Verify the database was created:

bash 
psql -l
Expected output: 
                             List of databases
   Name    |  Owner   | Encoding | Collate | Ctype | Access privileges
-----------+----------+----------+---------+-------+-------------------
 myapp     | youruser | UTF8     | C       | C     |
 postgres  | youruser | UTF8     | C       | C     |
 template0 | youruser | UTF8     | C       | C     | =c/youruser
 template1 | youruser | UTF8     | C       | C     | =c/youruser

Connect with psql

4

Connect with psql

~1 min

Connect to your new database using the psql command-line client:

bash 
psql myapp
Expected output: 
psql (16.2)
Type "help" for help.

myapp=#

🎉
Connected to PostgreSQL!

You're now in the psql interactive terminal. The # prompt indicates superuser access.

💡 Useful psql commands: \q to quit, \dt to list tables, \d tablename to describe a table.

Create a Table

5

Create a Table

~2 min

Create a users table to store some data:

sql 
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
Expected output: 
CREATE TABLE

Verify the table was created:

sql 
\d users
Expected output: 
                                       Table "public.users"
   Column   |            Type             | Collation | Nullable |              Default
------------+-----------------------------+-----------+----------+-----------------------------------
 id         | integer                     |           | not null | nextval('users_id_seq'::regclass)
 name       | character varying(100)      |           | not null |
 email      | character varying(255)      |           | not null |
 created_at | timestamp without time zone |           |          | CURRENT_TIMESTAMP
Indexes:
    "users_pkey" PRIMARY KEY, btree (id)
    "users_email_key" UNIQUE CONSTRAINT, btree (email)

📝 SERIAL creates an auto-incrementing integer. PostgreSQL automatically creates a sequence for this.

Insert Data

6

Insert Data

~2 min

Insert some sample data into the users table:

sql 
INSERT INTO users (name, email) VALUES
    ('Alice Johnson', '[email protected]'),
    ('Bob Smith', '[email protected]'),
    ('Carol Williams', '[email protected]');
Expected output: 
INSERT 0 3

Insert a single row and return the generated ID:

sql 
INSERT INTO users (name, email)
VALUES ('David Brown', '[email protected]')
RETURNING id, name;
Expected output: 
 id |    name
----+-------------
  4 | David Brown
(1 row)

INSERT 0 1

💡 RETURNING is a PostgreSQL-specific feature that returns data from inserted rows.

Query Data

7

Query Data

~2 min

Retrieve all users from the table:

sql 
SELECT * FROM users;
Expected output: 
 id |      name      |       email        |         created_at
----+----------------+--------------------+----------------------------
  1 | Alice Johnson  | [email protected]  | 2026-02-03 10:30:00.123456
  2 | Bob Smith      | [email protected]    | 2026-02-03 10:30:00.123456
  3 | Carol Williams | [email protected]  | 2026-02-03 10:30:00.123456
  4 | David Brown    | [email protected]  | 2026-02-03 10:31:15.654321
(4 rows)

Query with conditions and ordering:

sql 
SELECT id, name, email
FROM users
WHERE name LIKE '%Smith%'
ORDER BY created_at DESC;
Expected output: 
 id |   name    |      email
----+-----------+-----------------
  2 | Bob Smith | [email protected]
(1 row)
🎉
You're querying data!

You've successfully created a table, inserted data, and run queries.

Basic Operations (UPDATE, DELETE)

8

Basic Operations (UPDATE, DELETE)

~3 min

Update a user’s email address:

sql 
UPDATE users
SET email = '[email protected]'
WHERE id = 1
RETURNING *;
Expected output: 
 id |     name      |           email           |         created_at
----+---------------+---------------------------+----------------------------
  1 | Alice Johnson | [email protected] | 2026-02-03 10:30:00.123456
(1 row)

UPDATE 1

Delete a user:

sql 
DELETE FROM users WHERE id = 4;
Expected output: 
DELETE 1

⚠️ Always use a WHERE clause with UPDATE and DELETE to avoid modifying all rows!

Count remaining users:

sql 
SELECT COUNT(*) FROM users;
Expected output: 
 count
-------
     3
(1 row)

Exit psql when you’re done:

sql 
\q
🚀
PostgreSQL quickstart complete!

You've installed PostgreSQL, created a database and table, and performed CRUD operations. You're ready to build applications!

Next Steps

📚

PostgreSQL Documentation

Explore the official PostgreSQL docs

 🖥️

pgAdmin

Use a GUI to manage your databases

 ⚡

Performance Tuning

Optimize your PostgreSQL server