DEV Community

Cover image for PostgreSQL on Arch Linux: From Zero to Running in 5 Minutes
Zil Norvilis
Zil Norvilis

Posted on

PostgreSQL on Arch Linux: From Zero to Running in 5 Minutes

#postgres #archlinux #linux #tutorial

Why This Guide Exists

Most PostgreSQL installation guides are either outdated or don't cover the gotchas specific to Arch Linux. This guide will get you from zero to a working PostgreSQL installation in under 5 minutes, with proper systemd integration and best practices baked in.

Prerequisites

  • Arch Linux (obviously)
  • Sudo access
  • Basic terminal knowledge

That's it. Let's go.

Step 1: Install PostgreSQL

Arch makes this stupidly simple:

sudo pacman -S postgresql
Enter fullscreen mode Exit fullscreen mode

This installs the latest PostgreSQL version available in the official repositories. As of writing, that's PostgreSQL 16.x, but Arch keeps this current.

Step 2: Initialize the Database Cluster

Before you can start PostgreSQL, you need to initialize the data directory:

sudo -iu postgres initdb -D /var/lib/postgres/data
Enter fullscreen mode Exit fullscreen mode

What's happening here:

  • sudo -iu postgres - switches to the postgres user with a login shell
  • initdb - creates a new PostgreSQL database cluster
  • -D /var/lib/postgres/data - specifies the data directory location

You should see output like:

The files belonging to this database system will be owned by user "postgres".
This user must also own the server process.

The database cluster will be initialized with locale "en_US.UTF-8".
The default database encoding has accordingly been set to "UTF8".
...
Success. You can now start the database server using:
    pg_ctl -D /var/lib/postgres/data -l logfile start
Enter fullscreen mode Exit fullscreen mode

Step 3: Start and Enable PostgreSQL

Use systemd to manage PostgreSQL:

sudo systemctl start postgresql
sudo systemctl enable postgresql
Enter fullscreen mode Exit fullscreen mode

What each command does:

  • start postgresql - starts the service immediately
  • enable postgresql - ensures it starts automatically on boot

Step 4: Verify Installation

Check that PostgreSQL is running:

sudo systemctl status postgresql
Enter fullscreen mode Exit fullscreen mode

You should see:

● postgresql.service - PostgreSQL database server
     Loaded: loaded (/usr/lib/systemd/system/postgresql.service; enabled)
     Active: active (running) since...
Enter fullscreen mode Exit fullscreen mode

Check the version:

psql --version
Enter fullscreen mode Exit fullscreen mode

Step 5: Create Your First Database and User

Switch to the postgres user and access the PostgreSQL prompt:

sudo -iu postgres
psql
Enter fullscreen mode Exit fullscreen mode

Now you're in the PostgreSQL shell. Create a user with your system username:

CREATE USER your_username WITH PASSWORD 'your_secure_password';
CREATE DATABASE your_database OWNER your_username;
GRANT ALL PRIVILEGES ON DATABASE your_database TO your_username;
Enter fullscreen mode Exit fullscreen mode

Exit the PostgreSQL prompt:

\q
Enter fullscreen mode Exit fullscreen mode

Then exit back to your normal user:

exit
Enter fullscreen mode Exit fullscreen mode

Step 6: Configure Local Access (Optional)

By default, PostgreSQL on Arch is configured for local socket connections. If you want to connect via TCP/IP on localhost, you may need to adjust the configuration.

Edit the PostgreSQL configuration:

sudo -u postgres nano /var/lib/postgres/data/postgresql.conf
Enter fullscreen mode Exit fullscreen mode

Find and uncomment this line (it should already be set correctly):

listen_addresses = 'localhost'
Enter fullscreen mode Exit fullscreen mode

Edit the authentication file:

sudo -u postgres nano /var/lib/postgres/data/pg_hba.conf
Enter fullscreen mode Exit fullscreen mode

Add or modify this line for local password authentication:

# IPv4 local connections:
host    all             all             127.0.0.1/32            scram-sha-256
Enter fullscreen mode Exit fullscreen mode

Restart PostgreSQL:

sudo systemctl restart postgresql
Enter fullscreen mode Exit fullscreen mode

Common Issues and Fixes

Issue 1: "Directory exists but is not empty"

If you see this error during initdb:

# Remove the existing data directory
sudo rm -rf /var/lib/postgres/data

# Reinitialize
sudo -iu postgres initdb -D /var/lib/postgres/data
Enter fullscreen mode Exit fullscreen mode

Issue 2: "Could not bind to address" or Service Fails to Start

Check if another PostgreSQL instance is running:

ps aux | grep postgres
sudo lsof -i :5432
Enter fullscreen mode Exit fullscreen mode

If you have a Snap PostgreSQL installation:

sudo snap stop postgresql
sudo snap remove postgresql
sudo systemctl start postgresql
Enter fullscreen mode Exit fullscreen mode

Issue 3: Permission Errors

Fix ownership and permissions:

sudo chown -R postgres:postgres /var/lib/postgres/data
sudo chmod 700 /var/lib/postgres/data
sudo systemctl restart postgresql
Enter fullscreen mode Exit fullscreen mode

Issue 4: "Peer authentication failed"

This means you're trying to connect as a user that doesn't exist in PostgreSQL. Either:

  1. Create the PostgreSQL user matching your system username
  2. Specify a different user: psql -U postgres

Connecting to Your Database

From the command line: 

# As your user (if you created a matching PostgreSQL user)
psql -d your_database

# As a specific user
psql -U your_username -d your_database

# Remote connection (if configured)
psql -h localhost -p 5432 -U your_username -d your_database
Enter fullscreen mode Exit fullscreen mode

From your application:

Connection string format:

postgresql://username:password@localhost:5432/database_name
Enter fullscreen mode Exit fullscreen mode

Example in Ruby:

require 'pg'

conn = PG.connect(
  host: 'localhost',
  dbname: 'your_database',
  user: 'your_username',
  password: 'your_password'
)
Enter fullscreen mode Exit fullscreen mode

Example in Python:

import psycopg2

conn = psycopg2.connect(
    host="localhost",
    database="your_database",
    user="your_username",
    password="your_password"
)
Enter fullscreen mode Exit fullscreen mode

Useful PostgreSQL Commands

Once you're in the psql shell:

\l              -- List all databases
\c dbname       -- Connect to a database
\dt             -- List all tables in current database
\du             -- List all users/roles
\q              -- Quit psql
\?              -- Show all psql commands
\h              -- Show SQL command help
Enter fullscreen mode Exit fullscreen mode

Security Best Practices

  1. Use strong passwords: Don't use 'password' or '123456'
  2. Don't expose to the internet: Keep listen_addresses = 'localhost' unless you know what you're doing
  3. Use least privilege: Create separate users for each application with only the permissions they need
  4. Keep PostgreSQL updated: Run sudo pacman -Syu regularly
  5. Back up your databases: Use pg_dump regularly

Backup and Restore

Backup a database: 

pg_dump -U your_username your_database > backup.sql
Enter fullscreen mode Exit fullscreen mode

Restore a database: 

psql -U your_username your_database < backup.sql
Enter fullscreen mode Exit fullscreen mode

Backup all databases: 

sudo -u postgres pg_dumpall > all_databases.sql
Enter fullscreen mode Exit fullscreen mode

Uninstalling PostgreSQL

If you need to completely remove PostgreSQL:

# Stop the service
sudo systemctl stop postgresql
sudo systemctl disable postgresql

# Remove the package
sudo pacman -R postgresql

# Remove data (WARNING: This deletes all your databases)
sudo rm -rf /var/lib/postgres
Enter fullscreen mode Exit fullscreen mode

Why Arch + PostgreSQL is Great

  • Always up-to-date: Arch's rolling release means you get the latest PostgreSQL features
  • Clean integration: Systemd management works flawlessly
  • Minimal bloat: No unnecessary packages or configurations
  • AUR availability: Easy access to PostgreSQL extensions and tools
  • Performance: Arch's optimizations benefit database workloads

Next Steps

Now that you have PostgreSQL running, consider:

  1. Learning SQL: PostgreSQL has excellent documentation at postgresql.org
  2. Installing pgAdmin: A GUI tool for managing PostgreSQL
  3. Exploring extensions: PostGIS for spatial data, pg_stat_statements for query analysis
  4. Setting up automated backups: Use cron and pg_dump
  5. Tuning performance: Adjust postgresql.conf for your workload

Conclusion

Installing PostgreSQL on Arch is straightforward when you know the steps. The combination of Arch's simplicity and PostgreSQL's power makes for an excellent development environment.

The key takeaways:

  • Use pacman for installation
  • Initialize with initdb before starting
  • Manage with systemd
  • Create users and databases through psql
  • Keep it updated and backed up

Got questions or run into issues? Drop them in the comments below!

Top comments (0)