If you’re working on a Node.js project and run into errors like ECONNREFUSED ::1:5432, chances are PostgreSQL isn’t running — or it isn’t even installed. Here’s a quick guide to install postgres on macOS using Homebrew, the most reliable and straightforward method.

Before installing PostgreSQL, make sure you already have Homebrew installed on your Mac. Homebrew is the package manager we’ll be using to install and manage PostgreSQL.

Don’t have Homebrew yet? No worries, we got you covered. Check out our guide: How to Install Homebrew on macOS.

Once you’ve got Homebrew set up, you’re ready to continue.

Step 1: Install PostgreSQL via Homebrew#

With Homebrew installed, adding PostgreSQL is easy:

brew install postgresql

If you want to install a specific version of postgres, e.g, version 17 type:

brew install postgresql@17

Do the versioned one. postgresql is just an alias that Homebrew points at whatever the current major release is, so the command you run today and the command a teammate runs in six months can install different databases. And PostgreSQL major versions store their data in incompatible formats — 17 cannot read a cluster that 18 created. Pinning the version now saves you a genuinely annoying afternoon later.

If you’re not sure which one you ended up with:

brew list --versions | grep postgresql

Step 2: Start the PostgreSQL Service#

Once installed, start PostgreSQL as a background service. Use the same name you installed — if you took the versioned advice above, that’s postgresql@17, not plain postgresql:

brew services start postgresql@17

Get this wrong and Homebrew tells you Formula postgresql not found, which is a confusing error when you just watched PostgreSQL install successfully. It only means the service name doesn’t match the formula name.

To confirm it’s running:

brew services list

You should see something like:

Name        Status   User       File
postgresql  started  your-name  Library/LaunchAgents/[email protected]

Step 3: Confirm the Installation#

Check that PostgreSQL is installed correctly:

psql --version

psql is the interactive command-line tool when working with Postgres

Expected output:

psql (PostgreSQL) 17.5 (Homebrew)

In case you are getting a command not found: psql error you have to explicitly link it. For my example, in which i installed version 17, I just had to type

brew link postgresql@17 --force

By typing psql --version you should now see the postgreSQL you just installed.

Why does this happen at all? 🧐#

Because the versioned formulas are keg-only. Homebrew installed everything correctly and then deliberately did not add it to your PATH — that’s how it lets postgresql@17 and postgresql@18 sit on the same machine without each one claiming the name psql.

So zsh: command not found: psql isn’t a failed install. It’s Homebrew waiting for you to say which version you meant.

brew link --force is one answer. The other, which I prefer because it doesn’t touch Homebrew’s symlinks, is to put that one version on your PATH yourself:

echo 'export PATH="/opt/homebrew/opt/postgresql@17/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

That path is for Apple Silicon Macs. On an Intel Mac, Homebrew lives in /usr/local instead — run brew --prefix if you’re not sure which you have.

Step 4: Connect to PostgreSQL#

You can now open a PostgreSQL shell:

psql postgres

Or create your own database:

createdb mydb
psql mydb

Step 5 (Optional): Choosing a GUI#

If you prefer a graphical interface over the terminal, consider installing

These tools make managing your databases even easier.

The error everyone hits: role "postgres" does not exist 😤#

You install Postgres, you follow a tutorial written for Linux, you run something like psql -U postgres, and you get:

psql: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed:
FATAL:  role "postgres" does not exist

Nothing is broken. There simply is no user called postgres on your Mac.

Here’s why. When Homebrew installs PostgreSQL it runs initdb for you, and initdb creates the superuser named after whoever ran it — which is your macOS account, not postgres. On a Linux server the install runs as a system user called postgres, so every tutorial written on Linux assumes that name exists. On your Mac, the superuser is you.

Which is exactly why psql postgres from Step 4 works: postgres there is the name of a database that ships with every cluster, and you’re connecting to it as yourself.

If some tool insists on the postgres role — plenty of Docker-flavoured tutorials and ORM configs do — just create it:

createuser -s postgres

-s makes it a superuser. Now both worlds are happy.

When brew services says it started but nothing is listening#

ECONNREFUSED ::1:5432 after brew services start usually means the service died a second after launching. brew services list will show error rather than started.

Work through these in order:

brew services restart postgresql@17
ls $(brew --prefix)/var/log

The second command shows you Homebrew’s log folder — there’s a postgresql log in there, and unlike brew services, it tells you the actual reason. The two you’ll most likely find:

  • A stale postmaster.pid. The Mac was force-restarted while Postgres was running and the lock file outlived the process. The log names the file; delete it and start the service again.
  • A data directory built by a different major version. You installed postgresql@18 over a cluster initdb-ed by 17. The log says so plainly, in the form of a version mismatch complaint.

One more thing worth knowing about ECONNREFUSED ::1:5432 specifically: ::1 is IPv6 localhost. If Postgres is definitely running and your app still can’t reach it, point your connection string at 127.0.0.1 instead of localhost and see if that fixes it. If it does, the problem was never the database — your app resolved localhost to IPv6 and Postgres was only listening on IPv4.

Useful things to type once you’re inside psql#

The shell is fantastic once you know four commands, and completely opaque until then:

Command What it does
\l List every database
\c mydb Connect to a different database
\dt List tables in the current database
\d users Describe the users table
\du List roles (useful right after the error above)
\q Quit

And yes — SQL statements need a semicolon. If you press return and get a prompt that ends in -# instead of =#, Postgres is still waiting for you to finish the statement.

Frequently asked questions#

How do I stop PostgreSQL on macOS?#

brew services stop postgresql@17

Use brew services list to confirm it’s stopped. If you don’t want it launching every time you log in, this is the command you want rather than uninstalling.

What is the default username and password for Postgres on a Mac?#

The default user is your macOS username, and there is no password prompt for local connections on a fresh Homebrew cluster. You can set one from inside psql with \password. Nothing here is exposed to the internet by default, but the moment you do anything real with it, keep the credentials out of your code — see our guide to environment variables with dotenv.

What port does PostgreSQL use?#

5432, unless you changed it. If you also run Postgres in Docker, both will fight over that port and the loser is whichever one started second — that’s another common source of ECONNREFUSED.

How do I upgrade to a newer major version?#

Carefully, and not by accident. A new major cannot open the old version’s data directory, so installing postgresql@18 next to your postgresql@17 cluster does not migrate anything. The dependable route is to dump your databases with pg_dump (or pg_dumpall) before you switch, install the new version, and restore into it. Do the dump first — it’s the step people skip and then regret. If you’d rather not rely on remembering, a cron job can run that dump on a schedule for you.

Do I need Postgres installed locally if my app uses a hosted database?#

No, and it can be simpler not to. If your app connects to a managed database, all you need locally is a connection string. Installing Postgres locally is worth it when you want to break things without breaking a deployed environment — which, when you’re learning, is most of the time.

Keep reading#