DEV Community

Cover image for 🐘 Simplified Guide to Setting Up PostgreSQL on macOS with Docker 🚢
kpndevroot
kpndevroot

Posted on

🐘 Simplified Guide to Setting Up PostgreSQL on macOS with Docker 🚢

#webdev #postgres #docker #devops

Are you struggling with PostgreSQL configuration on macOS?

If you’ve been wrestling with environment variables like these:

DATABASE_URL=postgres://myuser@host.docker.internal:5432/mydb
#OR
DATABASE_URL=postgres://myuser:myuser@127.0.0.1:5432/mydb
Enter fullscreen mode Exit fullscreen mode

You’re not alone! PostgreSQL setup on macOS can feel daunting due to:

  • ❌ Limited client tools: Unlike Linux, macOS lacks straightforward commands like createuser --interactive -P.
  • 📖 Sparse documentation: Most PostgreSQL guides cater to Linux or Windows, leaving macOS users to figure it out on their own.

But don’t worry—we’ll walk through an easy and beginner-friendly way to set up PostgreSQL on macOS using Homebrew and Docker!🎉

🏆 Why This Guide Stands Out

  • ✅ Clear step-by-step instructions.
  • 🖥️ Tailored for macOS users.
  • 📊 Real-world examples with expected outputs for verification.

Let’s dive in! 🚀

🔧 Step 1: Install PostgreSQL Using Homebrew

1️⃣ Install PostgreSQL with Homebrew:

brew install postgresql@16
Enter fullscreen mode Exit fullscreen mode

2️⃣ Start the PostgreSQL service:

brew services start postgresql@16
Enter fullscreen mode Exit fullscreen mode

3️⃣ Verify the service status:

brew services info postgresql@16
Enter fullscreen mode Exit fullscreen mode

You should see output like this:

postgresql@16 (homebrew.mxcl.postgresql@16)
Running: ✔
Loaded: ✔
Schedulable: ✘
User: root
PID: 38646
Enter fullscreen mode Exit fullscreen mode

💡 Pro Tip
If you encounter issues, restart the service:

brew services restart postgresql@16
Enter fullscreen mode Exit fullscreen mode

🏗️ Step 2: Create a PostgreSQL User and Database

1️⃣ Access the PostgreSQL interactive shell:

psql postgres
Enter fullscreen mode Exit fullscreen mode

Example output:

❯ psql postgres
psql (14.13 (Homebrew), server 16.4 (Homebrew))
WARNING: psql major version 14, server major version 16.
         Some psql features might not work.
Type "help" for help.
Enter fullscreen mode Exit fullscreen mode

2️⃣ Create a User and Database

  1. Create a user 
CREATE USER myuser WITH PASSWORD 'user';
Enter fullscreen mode Exit fullscreen mode

Expected Output:

CREATE ROLE
Enter fullscreen mode Exit fullscreen mode
  1. Create a database: 
CREATE DATABASE mydb;
Enter fullscreen mode Exit fullscreen mode

Expected Output:

CREATE DATABASE
Enter fullscreen mode Exit fullscreen mode
  1. Grant access: 
GRANT ALL PRIVILEGES ON DATABASE mydb TO myuser;
Enter fullscreen mode Exit fullscreen mode

Expected Output:

GRANT
Enter fullscreen mode Exit fullscreen mode

🔗 Step 3: Connect to Your Database

Now, let’s test the connection to ensure everything is working. Use the following command to connect:

psql -U myuser -d mydb -p 5432
Enter fullscreen mode Exit fullscreen mode

Expected Output:


❯ psql -U myuser -d mydb -p 5432

psql (14.13 (Homebrew), server 16.4 (Homebrew))
WARNING: psql major version 14, server major version 16.
         Some psql features might not work.
Type "help" for help.

mydb=>
Enter fullscreen mode Exit fullscreen mode

🛠️ Common Issues and Solutions

1️⃣ Connection Refused

  • Cause: Firewall or incorrect host.docker.internal.
  • Solution: Test with 127.0.0.1 or check your Docker network settings

2️⃣ Version Mismatch Warnings

  • Cause: Using an older psql client.
  • Solution: Update your client to match the server version.

🎯 What’s Next?

  • 🔍 Explore your database.
  • 🛠️ Start building applications.
  • ⚙️ Configure your DATABASE_URL with host.docker.internal for Docker-based projects.

Now you’re ready to handle PostgreSQL on macOS like a pro! 🚀

If you enjoyed this guide, don’t forget to share it with your fellow developers! 🧑‍💻👩‍💻

Drop a comment below if you have questions or tips to add. Let’s make PostgreSQL configuration seamless for everyone! 🌟

Top comments (0)