How to Check if PostgreSQL Server Is Running on macOS

To find out whether PostgreSQL is ready for clients, start with pg_isready; a process check alone only shows that a process exists. The commands below focus on the macOS shell. PostgreSQL packages use different installation layouts, so command locations and cluster paths vary by distribution and setup.

Check PostgreSQL Process and Connection Readiness on macOS

Choose a check based on the question you need to answer. pg_isready tests whether a PostgreSQL server responds to connection attempts. pg_ctl status checks a particular cluster when you know its data directory. Process inspection with ps can help locate server processes, but it cannot establish that a client can connect. These signals are related, but they do not mean the same thing.

The examples are command patterns, not captured output from a local database. A PostgreSQL installation, server, credentials, and paths are environment-dependent; adapt the host, port, user, and data directory to your setup.

Use pg_isready to Check Connection Readiness

Run pg_isready for the default connection target, or supply options such as -h localhost and -p 5432 to check a specific host and port. Its exit status is useful in scripts:

• 0: the server is accepting connections.
• 1: the server is rejecting connections, for example during startup.
• 2: no response was received.
• 3: no connection attempt was made, such as when the parameters are not valid.

The PostgreSQL pg_isready documentation describes these exit statuses and the command’s connection options.

A successful status means the server accepts connection attempts at that target. It does not verify that a particular database, role, password, schema, or query is usable, so treat it as a readiness signal rather than a complete health check.

A small shell branch can handle the documented success status. Here the variable is set directly, so the example does not contact a database:

status=0
case "$status" in
  0) printf '%s\n' 'accepting connections' ;;
esac

accepting connections

For a real check, capture the status immediately after running pg_isready and branch on that value; a later command can replace the shell’s most recent exit status.

Use pg_ctl status to Check a Known Data Directory

Use pg_ctl -D "$PGDATA" status when PGDATA names the cluster’s data directory. You can also pass the directory explicitly, for example pg_ctl -D /path/to/cluster status. If the data directory cannot be inferred from the environment, pg_ctl needs the correct one. A path to the postgres executable is not a cluster directory.

The PostgreSQL pg_ctl documentation documents the status and start actions and the -D and -l options used here.

This check reports whether the postmaster process for that data directory is running. A running process does not by itself prove that PostgreSQL accepts client connections; use pg_isready for that question. If you set PGDATA in a shell startup file, confirm the value points to the initialized cluster directory before relying on it.

Inspect PostgreSQL Processes with ps

To inspect processes, use ps aux | grep '[p]ostgres' or, where available, pgrep -fl postgres. The bracket pattern prevents grep from matching its own command line. Process names and arguments can help identify a server launch and its -D directory, but a matching process is only a secondary signal: it may be starting, shutting down, or unable to accept connections.

psql answers a different question. A command such as psql -h localhost -p 5432 -U myuser -d mydb -c 'SELECT 1' attempts an authenticated connection and query. A failure can reflect credentials, database selection, network configuration, or server availability, so it is not a process-only test.

Troubleshoot Connection and Data Directory Errors

“Connection refused” means the requested endpoint did not accept the connection at that moment. Check that the host and port are the intended ones, then compare the result with pg_isready and inspect the relevant server logs. The message alone does not prove that every PostgreSQL instance on the machine is stopped; the service may be listening on another address or port.

A pg_ctl message about a missing or unusable postmaster.pid often points to a wrong data-directory path, permissions, or a cluster that is not running. Verify the directory used when the cluster was initialized and the value of PGDATA. Do not use the output of which postgres as -D: it identifies the executable, while -D expects the cluster data directory. Avoid deleting PID files unless you have confirmed which cluster owns the file and that its server is stopped.

Start PostgreSQL with pg_ctl When It Is Stopped

If the relevant cluster is stopped and you have identified its data directory, start it with pg_ctl -D "$PGDATA" -l "$PGDATA/server.log" start, replacing PGDATA with the correct directory if it is not set. The -D option takes the cluster directory; -l selects a log file. Ensure the account running the command has access to that cluster and log location. Package-managed installations may instead expect you to start the service through their own management tool.

After startup, run pg_isready against the intended host and port to check connection readiness. Use pg_ctl ... status when you specifically need to confirm the state of a known data directory. In short, use process inspection to locate a process, pg_ctl status for a known cluster, and pg_isready when the question is whether clients can connect.