Webinar: Managing Macs with Intune: security, scale, & the modern enterprise fleet
Register to attend
Developer Productivity
Guide

How to configure PostgreSQL for local development

Petros Amoiridis

After Workbrew is deployed, brew services runs PostgreSQL as the workbrew system user. When initdb runs under this user, the default superuser role it creates is workbrew rather than the developer's OS username. Any application or tool that connects to PostgreSQL without an explicit username will default to the current OS user, which results in:

FATAL: role "yourname" does not exist

This guide covers three approaches to resolve this, depending on what works best for your team. The examples below use Rails, but the same principle applies to any framework or tool that connects to PostgreSQL (Django, Phoenix, psql, etc.): configure an explicit username instead of relying on the OS default.

Option 1: Use workbrew as the connection role

The simplest approach. The workbrew role already exists on every Workbrew-managed PostgreSQL installation.

For example, in a Rails application, set the username in config/database.yml:

development:
  username: workbrew

Or set it in the shell environment:

export PGUSER=workbrew

Option 2: Use a shared application role

Instead of depending on OS usernames, create a shared role that every developer on the team uses. This keeps the database configuration consistent across machines, with or without Workbrew.

Create the role (once per Device):

psql -U workbrew -d postgres -c "CREATE ROLE dev WITH LOGIN SUPERUSER CREATEDB;"

Then configure the application to use it. For example, in Rails:

development:
  username: dev

To automate this, add role creation to your project's setup script (e.g. script/bootstrap):

psql -U workbrew -d postgres -c "CREATE ROLE dev WITH LOGIN SUPERUSER CREATEDB;" 2>/dev/null || true

The || true ensures the script doesn't fail if the role already exists.

Option 3: Create a role matching the OS username

If you prefer each developer to connect as their own OS username, create a matching PostgreSQL role:

psql -U workbrew -d postgres -c "CREATE ROLE \"$(whoami)\" WITH LOGIN SUPERUSER CREATEDB;"

This needs to be run once per user on each Device where Workbrew manages PostgreSQL.

Running multiple PostgreSQL versions

If multiple PostgreSQL versions are installed (e.g. postgresql@14 and postgresql@18), only one can run on port 5432 at a time. Starting both will cause the second to fail with exit code 1.

To run both simultaneously, configure the second version to use a different port. Stop the service first:

brew services stop postgresql@14

Edit the configuration file at /opt/homebrew/var/postgresql@14/postgresql.conf, find the port setting (usually commented out), and change it:

port = 5433

Then start the service again:

brew services start postgresql@14

Applications connecting to the non-default version will need to specify the port explicitly.

Note on existing installations

If PostgreSQL was already installed via Homebrew before Workbrew was deployed, the existing database and its roles are preserved. Workbrew changes ownership of the data directory but does not re-initialize the database. The CREATE ROLE steps above are only needed for PostgreSQL versions installed fresh through Workbrew.

psql not found

PostgreSQL installed via Homebrew is keg-only, so psql is not on the PATH by default. Use the full path:

/opt/homebrew/opt/postgresql@18/bin/psql -d postgres

Adjust the version number to match your installation.