From 7c6405cf5ffdb7f712a9fd4adb37dcdfa0e5b40d Mon Sep 17 00:00:00 2001
From: Righteousness Akinbola <righteousnessakinbola@gmail.com>
Date: Thu, 25 Sep 2025 09:38:24 +0100
Subject: [PATCH] docs: update PostgreSQL installation instructions for macOS
 (#14710)

This pull request improves the local development setup instructions for
PostgreSQL on macOS, especially for users installing via Homebrew. It
clarifies how to ensure the PostgreSQL server is running and addresses
potential issues with the default user role.
This pull request solves issue #14637
I personally faced this issues today while trying to setup the project
on my M1 Macbook Air.

PostgreSQL setup enhancements:

* Added instructions to start the PostgreSQL service using Homebrew and
verify its status with `brew services list`.
* Provided guidance on checking for the existence of the `postgres` role
and steps to manually create it if missing, to avoid permission issues
during development.

---------

Co-authored-by: Charles Bochet <charles@twenty.com>
---
 .../src/content/developers/local-setup.mdx    | 36 +++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/packages/twenty-website/src/content/developers/local-setup.mdx b/packages/twenty-website/src/content/developers/local-setup.mdx
index cb551e37ec..e217987ef1 100644
--- a/packages/twenty-website/src/content/developers/local-setup.mdx
+++ b/packages/twenty-website/src/content/developers/local-setup.mdx
@@ -124,9 +124,45 @@ You should run all commands in the following steps from the root of the project.
     ```bash
       brew install postgresql@16
       export PATH="/opt/homebrew/opt/postgresql@16/bin:$PATH"
+      brew services start postgresql@16
       psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;"
     ```
 
+    You can verify if the PostgreSQL server is running by executing:
+    ```bash
+      brew services list
+    ```
+
+    The installer might not create the `postgres` user by default when installing 
+    via Homebrew on MacOS. Instead, it creates a PostgreSQL role that matches your macOS
+    username (e.g., "john").
+    To check and create the `postgres` user if necessary, follow these steps:
+    ```bash
+      # Connect to PostgreSQL
+      psql postgres
+      or
+      psql -U $(whoami) -d postgres
+    ```
+
+    Once at the psql prompt (postgres=#), run:
+     ```bash
+      # List existing PostgreSQL roles
+      \du
+    ```
+    You'll see output similar to:
+     ```bash
+      Role name | Attributes  | Member of 
+      -----------+-------------+-----------
+      john      | Superuser   | {}
+    ```
+
+    If you do not see a `postgres` role listed, proceed to the next step.
+    Create the `postgres` role manually:
+     ```bash
+      CREATE ROLE postgres WITH SUPERUSER LOGIN;
+    ```
+    This creates a superuser role named `postgres` with login access.
+
     <b>Option 2:</b> If you have docker installed:
     ```bash
       make postgres-on-docker