PostgreSQL on Arch Linux is a pacman-managed database server, but it will not start until you initialize its data directory with initdb. The official postgresql package installs the server, uses the postgresql.service systemd unit, and pulls in client tools such as psql through postgresql-libs.
Use this setup when you need an Arch host to run PostgreSQL with a dedicated application role; it initializes /var/lib/postgres/data with safer authentication defaults and verifies local or remote access before exposing the service to other hosts.
Update Arch Linux
Synchronize package databases and apply pending upgrades before installing PostgreSQL. Arch expects packages and dependencies to move together on the rolling release branch.
sudo pacman -SyuThese commands use
sudofor tasks that need root privileges. If your user is not in the sudoers file yet, run the commands as root or follow the guide on how to add and manage sudo users on Arch Linux.
Install PostgreSQL on Arch Linux
Install the PostgreSQL server from Arch’s official repositories. The package page for PostgreSQL in Arch Linux lists the current repository package, while pacman handles the matching dependencies.
sudo pacman -S postgresqlVerify that the server package and client-library package are installed:
pacman -Qq postgresql postgresql-libspostgresql postgresql-libs
The package split matters for common search terms such as install psql Arch. The postgresql package owns the server binaries such as postgres, initdb, and pg_ctl; postgresql-libs owns client tools such as psql, pg_dump, createdb, and pg_isready.
command -v psql
pacman -Qo /usr/bin/psql/usr/bin/psql /usr/bin/psql is owned by postgresql-libs 18.3-2
The exact package version changes with Arch repository updates. If you only need the PostgreSQL client tools on another Arch machine, install postgresql-libs there instead of the full server package.
PostgreSQL Package Names on Arch Linux
| Package | Role | Install When |
|---|---|---|
postgresql | Server daemon, initdb, pg_ctl, pg_upgrade | You want this Arch system to host PostgreSQL databases |
postgresql-libs | Client tools and libpq, including psql and pg_dump | You only need PostgreSQL client commands or libraries |
php-pgsql | PHP PostgreSQL extensions, including pgsql and pdo_pgsql | A PHP application needs to connect to PostgreSQL |
postgresql-old-upgrade | Previous-major PostgreSQL binaries for pg_upgrade | Arch moves PostgreSQL to a new major branch and you need in-place migration |
The Arch package name for PHP PostgreSQL support is php-pgsql. Install it only on PHP application hosts; if PHP is not set up yet, use the Arch Linux PHP installation guide first.
sudo pacman -S php-pgsqlInitialize the PostgreSQL Data Directory
Arch packages do not initialize the database cluster automatically. Create the data directory as the postgres system user, using C.UTF-8 and password-capable host authentication from the start:
sudo -iu postgres initdb -D /var/lib/postgres/data --locale=C.UTF-8 --encoding=UTF8 --auth-local=peer --auth-host=scram-sha-256The database cluster will be initialized with locale "C.UTF-8".
The default database encoding has accordingly been set to "UTF8".
Data page checksums are enabled.
Success. You can now start the database server using:
pg_ctl -D /var/lib/postgres/data -l logfile start
The Arch Wiki PostgreSQL page uses the same package-managed data path. A plain initdb -D /var/lib/postgres/data currently creates trust rules for local and localhost connections; the command above creates peer authentication for local sockets and SCRAM-SHA-256 for host connections.
sudo -iu postgres grep -E '^(local|host)' /var/lib/postgres/data/pg_hba.conflocal all all peer host all all 127.0.0.1/32 scram-sha-256 host all all ::1/128 scram-sha-256 local replication all peer host replication all 127.0.0.1/32 scram-sha-256 host replication all ::1/128 scram-sha-256
If your database directory resides on a Btrfs filesystem, the Arch PostgreSQL package handles the data directory through systemd-tmpfiles. For ZFS, tune the dataset for database storage before placing the cluster there; the Arch Wiki PostgreSQL page covers filesystem-specific notes.
Start the PostgreSQL Service
Start PostgreSQL and enable the packaged systemd unit for future boots. The service name on Arch Linux is postgresql.service.
sudo systemctl enable postgresql --nowConfirm that the unit is both active and enabled:
systemctl is-active postgresql
systemctl is-enabled postgresqlactive enabled
Check the installed PostgreSQL client version. The exact minor version follows Arch’s current repository state, so your output may show a newer point release.
psql --versionpsql (PostgreSQL) 18.3
Verify that the server accepts a local superuser connection through the Unix socket:
sudo -iu postgres psql -tAc 'SELECT current_user, current_database();'postgres|postgres
Configure PostgreSQL Authentication
PostgreSQL reads connection rules from /var/lib/postgres/data/pg_hba.conf. Rule order matters: keep the postgres superuser on peer authentication first, then add a password rule for normal application users.
sudo nano /var/lib/postgres/data/pg_hba.confUse these local socket rules for a typical application server:
# Unix socket connections
local all postgres peer
local all all scram-sha-256Peer authentication lets only the Linux postgres account connect as the database superuser without a password. The second rule requires SCRAM-SHA-256 passwords for application roles that connect over local sockets.
Reload PostgreSQL after editing pg_hba.conf:
sudo systemctl reload postgresqlConfirm PostgreSQL is reading the expected authentication file:
sudo -iu postgres psql -tAc 'SHOW hba_file;'/var/lib/postgres/data/pg_hba.conf
Connect to PostgreSQL
Open the PostgreSQL shell as the database superuser through the postgres Linux account:
sudo -iu postgres psqlThe version line changes with Arch repository updates, but the prompt confirms the superuser connection:
psql (18.3) Type "help" for help. postgres=#
Exit with \q or press Ctrl+D. Common psql meta-commands include:
| Command | Purpose |
|---|---|
\l | List databases |
\c dbname | Connect to another database |
\dt | List tables in the current database |
\du | List roles and attributes |
\d tablename | Describe a table |
\? | Show all psql meta-commands |
\q | Quit psql |
Create a PostgreSQL Database and User
Applications should use dedicated database roles instead of the postgres superuser. Open psql as the superuser:
sudo -iu postgres psqlCreate a login role and a database owned by that role:
CREATE ROLE myapp_user WITH LOGIN;
CREATE DATABASE myapp_db OWNER myapp_user;Set the role password interactively so the password does not appear in shell history or process arguments:
\password myapp_user
\qTest the new role over localhost, which uses the SCRAM-SHA-256 host rule created during initialization:
psql -h 127.0.0.1 -U myapp_user -d myapp_dbThe version line varies, but the prompt should switch to the application database name:
Password for user myapp_user: psql (18.3) Type "help" for help. myapp_db=>
Configure Remote PostgreSQL Access
Leave PostgreSQL on local sockets and localhost when the database only serves applications on the same machine. Remote clients need three separate pieces: a network listener, a matching pg_hba.conf rule, and a firewall rule if your Arch host filters inbound traffic.
Enable Network Listening
Edit postgresql.conf and set the addresses PostgreSQL should bind to:
sudo nano /var/lib/postgres/data/postgresql.confUse a specific server address when possible. The wildcard form is useful for testing but exposes PostgreSQL on every interface unless firewall policy restricts it.
listen_addresses = 'localhost,192.168.1.100'For a lab system that intentionally listens on all interfaces, use:
listen_addresses = '*'Allow Remote Client Authentication
Add a pg_hba.conf host rule for the client subnet or a single trusted client IP:
sudo nano /var/lib/postgres/data/pg_hba.conf# IPv4 remote connections from a trusted subnet
host all all 192.168.1.0/24 scram-sha-256Use a single-client /32 rule when only one host should connect. Restart PostgreSQL after changing listen_addresses because that setting changes the server listener:
sudo systemctl restart postgresqlVerify the TCP listener. A localhost-only configuration shows 127.0.0.1:5432 and [::1]:5432; a wildcard listener shows 0.0.0.0:5432 and [::]:5432.
ss -H -ltn 'sport = :5432'LISTEN 0 200 0.0.0.0:5432 0.0.0.0:* LISTEN 0 200 [::]:5432 [::]:*
If you manage the host firewall with UFW, allow PostgreSQL only for the clients that need it. The UFW guide for Arch Linux covers UFW setup; Firewalld users can use the Firewalld guide for Arch Linux instead.
sudo ufw allow from 192.168.1.0/24 to any port 5432 proto tcpDo not open TCP port 5432 for local-only databases. Unix socket and localhost connections do not need an inbound firewall exception.
Manage PostgreSQL on Arch Linux
Use systemd for routine service control. Reload after authentication or logging changes; restart after listener or shared-memory settings change. Run only the action you need.
sudo systemctl stop postgresqlsudo systemctl start postgresqlsudo systemctl restart postgresqlsudo systemctl reload postgresqlsystemctl status postgresql --no-pagerControl boot startup separately when needed. Use the command that matches the desired boot behavior:
sudo systemctl disable postgresqlsudo systemctl enable postgresqlUpgrade PostgreSQL on Arch Linux
Minor PostgreSQL updates arrive through normal sudo pacman -Syu upgrades. Major upgrades, such as PostgreSQL 17 to PostgreSQL 18, require a database migration because the on-disk storage format changes.
Create a logical backup before any major migration:
sudo -iu postgres pg_dumpall > postgresql-backup.sqlArch provides postgresql-old-upgrade for in-place pg_upgrade migrations from the previous major branch. Install it only during a major upgrade window, then follow the Arch Wiki PostgreSQL upgrade procedure for the full migration sequence.
sudo pacman -S postgresql-old-upgradeUse
IgnorePkgonly as a short-term hold while you schedule backups and migration. Leaving core database packages pinned indefinitely can create partial-upgrade risk on Arch.
If you need a short migration hold, add PostgreSQL packages to IgnorePkg in /etc/pacman.conf:
IgnorePkg = postgresql postgresql-libsTroubleshoot PostgreSQL on Arch Linux
Start troubleshooting with package state, the service unit, and the local listener. These checks catch the most common Arch-specific failures before you edit authentication or firewall rules.
postgresql.service Not Found
If systemctl start postgresql returns Unit postgresql.service not found, the server package is not installed or systemd has not reloaded package units yet.
pacman -Q postgresql
systemctl list-unit-files 'postgresql.service'A healthy install lists the package and unit; the package version follows your current mirror state:
postgresql 18.3-2 UNIT FILE STATE PRESET postgresql.service disabled disabled
Install postgresql if the package query fails. If the package is installed but the unit is still missing, refresh systemd’s unit cache:
sudo systemctl daemon-reloadService Fails Before Startup
A fresh install usually fails before startup when the data directory has not been initialized or is owned by the wrong user.
journalctl -xeu postgresql
ls -ld /var/lib/postgres /var/lib/postgres/dataIf /var/lib/postgres/data is missing, run the initdb command from the installation section. If ownership was changed manually, restore it:
sudo chown -R postgres:postgres /var/lib/postgresAuthentication Failed
Peer authentication failed means the Linux account does not match the database role for the selected rule. Use sudo -iu postgres psql for superuser administration, or use a password-capable rule such as scram-sha-256 for application roles.
Inspect the active authentication file:
sudo -iu postgres grep -E '^(local|host)' /var/lib/postgres/data/pg_hba.confReload PostgreSQL after editing pg_hba.conf:
sudo systemctl reload postgresqlCollation Version Mismatch Warning
glibc or ICU updates can change locale collation behavior on a rolling-release system. If PostgreSQL reports a collation version mismatch, reindex affected databases and refresh their recorded collation version.
WARNING: database "postgres" has a collation version mismatch
sudo -iu postgres psql -c 'REINDEX DATABASE postgres'
sudo -iu postgres psql -c 'ALTER DATABASE postgres REFRESH COLLATION VERSION'Repeat the commands for each database named in the warning. New clusters initialized with C.UTF-8 avoid most locale-dependent collation changes.
Connection Refused on Port 5432
A connection refused error means the server is not listening where the client is connecting, or a firewall or network layer is blocking the request.
systemctl is-active postgresql
ss -H -ltn 'sport = :5432'
sudo -iu postgres grep -E '^(local|host)' /var/lib/postgres/data/pg_hba.confIf local checks pass but remote clients still fail, confirm the client IP matches a pg_hba.conf host rule, the server is bound to a reachable address, and the firewall allows TCP traffic to port 5432 from that client.
Remove PostgreSQL from Arch Linux
Stop and disable the service before removing the server package:
sudo systemctl disable postgresql --nowRemove the PostgreSQL server and dependencies installed only for it:
sudo pacman -Rns postgresqlIf you installed optional packages from this article, run only the matching removal command for the package you no longer need. These package-specific removals avoid broad dependency cleanup for shared packages such as php or postgresql-libs.
sudo pacman -R php-pgsqlsudo pacman -R postgresql-old-upgradePacman preserves PostgreSQL data under
/var/lib/postgres/to prevent accidental database loss. Do not delete that directory until backups have been verified.
After backups are confirmed, remove the data directory manually:
sudo rm -rf /var/lib/postgresVerify the server package is no longer installed:
pacman -Q postgresqlerror: package 'postgresql' was not found
Conclusion
PostgreSQL on Arch is ready once /var/lib/postgres/data is initialized, postgresql.service is active, and authentication rules match your application model. Keep major upgrades planned around backups and postgresql-old-upgrade. For adjacent database choices, compare the MariaDB guide or the SQLite guide.
Formatting tips for your comment
You can use basic HTML to format your comment. Useful tags currently allowed in published comments:
<code>command</code>command<strong>bold</strong><em>italic</em><blockquote>quote</blockquote>