Postgres.app on a Mac: A Sane Local Database Setup

Postgres.app is a full PostgreSQL server packaged as a normal Mac application: download it, drag it to Applications, open it, click Initialize, and you have a database server running on port 5432.

No installer wizard, no launchd plist to write, no package manager service to babysit. It is the setup worth recommending to anyone who wants a local Postgres and does not want local Postgres to become a hobby. The parts worth knowing are the command line step almost everyone skips, how to run more than one major version, and what changes on the day the app stops talking only to your laptop.

Table of contents

• Installing it properly
• Connecting to it
• Running more than one major version
• Backups and moving data around
• Where the local setup stops being the point
• Common problems and their causes
• How this fits the rest of the stack
• FAQ

Installing it properly

Download the app, move it into Applications, open it, and click Initialize. That gives you a server on localhost port 5432, a database named after your macOS username, a superuser role with the same name, and no password.

That last detail catches people out. The default setup trusts local connections, so an empty password is correct rather than broken. It is also a good reason to keep this configuration on your laptop and not copy it anywhere else.

Then do the step the front page mentions and most people scroll past: put the binaries on your PATH.

sudo mkdir -p /etc/paths.d &&
  echo /Applications/Postgres.app/Contents/Versions/latest/bin \
  | sudo tee /etc/paths.d/postgresapp

Open a new terminal after running it. Without this, the server is running but psql, pg_dump, pg_restore and createdb are not on your PATH, and you get command not found while a perfectly healthy database sits there on 5432. It is the most common confused-user report for this app by a wide margin.

Check it worked:

which psql
psql -c 'SELECT version();'

Connecting to it

From the command line, psql with no arguments connects to the database named after your user:

psql
# or explicitly
psql -h localhost -p 5432 -U $(whoami) -d postgres

From an application, the connection string is the usual shape:

postgresql://yourusername@localhost:5432/yourdbname

No password component, because local connections are trusted. If your framework insists on a password field, any value works, or you can set a real one:

ALTER ROLE yourusername WITH PASSWORD 'something';

Creating a database per project is one command, and it is worth the habit rather than dumping every table into the default database:

createdb myproject_dev
psql myproject_dev

Running more than one major version

This is where Postgres.app quietly beats the alternatives. It ships multiple PostgreSQL major versions in the same app bundle, and the sidebar lets you run them side by side on different ports.

That matters more than it sounds. Postgres major versions are not compatible on disk, so upgrading normally means a dump and a restore. If one project is on 15 and a new one starts on 17, the usual options are to upgrade everything at once or to maintain two separate installations.

Here you add a second server in the sidebar, give it a different port, and both run. Project A talks to 5432, project B talks to 5433, and neither upgrade is urgent.

The version in the PATH snippet above is latest, which follows the newest installed version. If you want a specific one on your PATH, point the paths.d file at that version directory instead of latest.

Backups and moving data around

Because the binaries are on your PATH, the standard tools work exactly as documented. Dumping and restoring a local database:

pg_dump -Fc myproject_dev > myproject_dev.dump
createdb myproject_fresh
pg_restore -d myproject_fresh myproject_dev.dump

The custom format flag is worth the habit. It compresses, it lets pg_restore do selective restores of single tables, and it survives version differences better than a plain SQL dump.

Pulling a copy of a remote database down to work against locally is the same tool pointed somewhere else:

pg_dump -Fc 'postgresql://user:pass@host:5432/dbname' > remote.dump
createdb local_copy
pg_restore -d local_copy remote.dump

Do this with a sanitised copy rather than live customer data. A local database with no password and real personal data on it is a bad afternoon waiting to happen, and laptops get left on trains.

Where the local setup stops being the point

Everything above is about a database on your laptop, which is the correct place for a database while you are building. The transition worth planning for is the one where something other than your laptop needs to read it.

The moment a teammate needs the same data, or a deployed version of the app has to answer a request at three in the morning, the requirements change completely. The database now needs to be reachable over a network, to have real authentication, to survive a restart, to be backed up on a schedule, and to have someone paying attention to connection limits.

None of that is a criticism of Postgres.app. It is the difference between a development tool and production infrastructure, and trying to make one do the other job is how people end up running a database on a laptop under a desk with a note taped to it.

The practical version of that transition is usually short: a managed Postgres instance, a connection string in an environment variable, and a dump and restore to move the schema across. On RunxBuild that means a managed Postgres with connection limits, backups and private networking, sitting beside the service that talks to it, and a DATABASE_URL environment variable rather than a localhost default that follows the code into production.

Common problems and their causes

• psql: command not found. The PATH file was not created, or the terminal was not restarted. Run the paths.d command and open a new window.
• Could not connect to server on port 5432. Something else is already bound to that port, usually a Postgres installed by a package manager earlier. Stop the other one, or move Postgres.app to 5433.
• Database does not exist. Postgres.app creates one named after your macOS user, not one named after your project. Run createdb with the name your application config expects.
• Role does not exist. The application config specifies a user that was never created. Either change the config to your macOS username or create the role.
• Data disappeared after an upgrade. A new major version uses a new data directory. The old data is still there under the previous version; start that server in the sidebar and dump it across.

Almost every one of these is the same root cause in different clothing: the app manages the server, but it does not manage your shell, your ports, or your application config. Once you know which half owns what, the failures stop being mysterious.

How this fits the rest of the stack

A local Postgres costs nothing and a production one costs whatever the plan costs, which is easy to forget while you are building against localhost. When the project starts needing a database other things can reach, the RunxBuild hosting calculator is a quick way to see that number next to the service, the storage and the bandwidth rather than discovering it at the end. Managed MySQL and Postgres both sit on the same plan ladder, starting at the Dev plan at four dollars a month.

Useful related references:

• Show Databases in Postgres: Why SHOW DATABASES Does Not Work
• Postgres-XL: What the Distributed Fork Was, and Why It Lost to Citus
• Choosing a Vector Database for RAG: Start With Postgres
• Databases on RunxBuild

FAQ

Is Postgres.app better than installing PostgreSQL with a package manager?

For most people, yes. A package manager gives you a service to manage and a single major version at a time. Postgres.app gives you a menu bar toggle, multiple major versions running side by side on different ports, and no service management at all. A package manager is the better fit if you already script your entire machine setup.

Why does psql say command not found after installing Postgres.app?

The server runs from inside the app bundle, and so do the command line tools, which are not on your PATH by default. Create the /etc/paths.d/postgresapp file with the command in the install section above, then open a new terminal window.

What is the default password for Postgres.app?

There is not one. It configures local connections as trusted, so you connect with your macOS username and an empty password. You can set a real one with ALTER ROLE if a framework refuses to accept an empty password field.

Can I run two PostgreSQL versions at the same time?

Yes, and it is the strongest reason to pick Postgres.app. Add a second server in the sidebar, assign it a different port such as 5433, and run both. Each major version keeps its own data directory, so upgrading one project does not force the others.

How do I move my local database to a hosted one?

Dump with pg_dump in custom format, create the database on the host, then pg_restore into it using the hosted connection string. Move that connection string into an environment variable at the same time, so the application is not carrying a localhost default into production.