---
# System prepended metadata

title: readmes/README.Macos.md
tags: [readmes/README.Macos.md]

---

# Compile and Install Cloudberry Database on macOS

This document shares how to build, compile, and install Cloudberry Database on macOS for development purposes. Follow the steps below.

According to our test, these steps work well on macOS Ventura 13.4+ with both Intel and Apple silicon processors (M1 or M2). If you have an earlier version of macOS, upgrading is recommended.

## Step 1. Install needed dependencies

Run the following command to install the needed dependencies. You will be asked to enter the `sudo` password of your macOS system.

```bash
source readmes/README.macOS.bash
```

> [!NOTE]
> This will install [Homebrew](https://brew.sh/) if missing.

## Step 2. Enable password-free SSH connection to localhost

1. Enable **Remote Login** on your macOS system by navigating to **System Preferences** \> **Sharing** \> **Remote Login**.
2. Run the following command to verify whether password-free SSH connection to localhost has been enabled on your system.

    ```bash
    ssh $(hostname)
    ```
    
    - If this command runs without error or requiring you to enter a password, run `exit` and go to [Step 3. Configure, compile, and install](#step-3-configure-compile-and-install).
    - If you are required to enter a password, take the following steps to set up password-free SSH connection.

        1. Run `ssh-keygen` and then `cat ~/.ssh/id_rsa.pub >>  ~/.ssh/authorized_keys`.
        2. Run `ssh $(hostname)` again to check whether password-free connection is ready.
        3. If ready, run `exit` and go to [Step 3. Configure, compile, and install](#step-3-configure-compile-and-install).

> [!NOTE]
>
> - If it is the first time you are using `ssh` connection to localhost, you might need to accept the trust on the first use prompt:
>
>    ```bash
>    The authenticity of host '<your hostname>' can't be established.
>    ECDSA key fingerprint is SHA256:<fingerprint here>.
>    Are you sure you want to continue connecting (yes/no)?
>   ```
>
> - If your hostname does not resolve, try adding your machine name to `/etc/hosts`:
>
>    ```bash
>      echo -e "127.0.0.1\t$HOSTNAME" | sudo tee -a /etc/hosts
>    ```

## Step 3. Configure, compile, and install

```bash
# Run the following commands under the `cloudberrydb/` dir.
# 1. Configure the build environment.

BREWPREFIX=$(brew --prefix); export PATH="$BREWPREFIX/opt/gnu-sed/libexec/gnubin:$BREWPREFIX/opt/apr/bin:$PATH"; CXXFLAGS="-I $BREWPREFIX/include" CFLAGS="-ggdb -Og -g3 -fno-omit-frame-pointer -I $BREWPREFIX/include" LDFLAGS="-L $BREWPREFIX/lib" CC=$(which gcc-13) CXX=$(which g++-13) ./configure --enable-debug --prefix=$(cd ~; pwd)/install/cbdb;

# 2. Compile and install Cloudberry Database.

make -j8
make -j8 install

# 3. Bring in Greenplum environment for Cloudberry Database into your running shell.

source $(cd ~; pwd)/install/cbdb/greenplum_path.sh

# 4. Install the Python dependencies.

pip3 install --user -r readmes/python-dependencies.txt

# 5. Start a demo cluster.

PORT_BASE=8000 make create-demo-cluster

# (gpdemo-env.sh contains __PGPORT__ and __MASTER_DATA_DIRECTORY__ values)
```
## Step 4. Verify the cluster

1. You can verify whether the cluster has started successfully by running the following command. You might see many active `postgres` processes with ports ranging from `8000` to `8007`.

    ```bash
    ps -ef | grep postgres
    ```
    
2. Connect to the Cloudberry Database and see the active segment information by querying the system table `gp_segement_configuration`. For detailed description of this table, see the Greenplum document [here](https://docs.vmware.com/en/VMware-Greenplum/6/greenplum-database/ref_guide-system_catalogs-gp_segment_configuration.html).

    ```sql
    $ psql -p 8000 postgres
    postgres=# select version();
    postgres=# select * from gp_segment_configuration;
    ```
    
    Example output:

    ```shell
    hashdatas-MacBook-Pro:cloudberrydb hashdata $ psql -p 8000 postgres
    psql (14.4, server 14.4)
    Type "help" for help.

    postgres=# select version();
                                                                                             version                                                                                         
    -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
     PostgreSQL 14.4 (Cloudberry Database 1.0.0+1c0d6e2224 build dev) on x86_64-apple-darwin22.4.0, compiled by gcc-13 (Homebrew GCC 13.2.0) 13.2.0, 64-bit compiled on Sep 22 2023 10:56:01
    (1 row)

    postgres=# select * from gp_segment_configuration;
     dbid | content | role | preferred_role | mode | status | port |          hostname           |           address           |                                                 datadir                                                  | warehouseid 
    ------+---------+------+----------------+------+--------+------+-----------------------------+-----------------------------+----------------------------------------------------------------------------------------------------------+-------------
        1 |      -1 | p    | p              | n    | u      | 8000 | hashdatas-MacBook-Pro.local | hashdatas-MacBook-Pro.local | /Users/hashdata/Documents/GitHub/upstream/cloudberrydb/gpAux/gpdemo/datadirs/qddir/demoDataDir-1         |           0
        8 |      -1 | m    | m              | s    | u      | 8001 | hashdatas-MacBook-Pro.local | hashdatas-MacBook-Pro.local | /Users/hashdata/Documents/GitHub/upstream/cloudberrydb/gpAux/gpdemo/datadirs/standby                     |           0
        3 |       1 | p    | p              | s    | u      | 8003 | hashdatas-MacBook-Pro.local | hashdatas-MacBook-Pro.local | /Users/hashdata/Documents/GitHub/upstream/cloudberrydb/gpAux/gpdemo/datadirs/dbfast2/demoDataDir1        |           0
        6 |       1 | m    | m              | s    | u      | 8006 | hashdatas-MacBook-Pro.local | hashdatas-MacBook-Pro.local | /Users/hashdata/Documents/GitHub/upstream/cloudberrydb/gpAux/gpdemo/datadirs/dbfast_mirror2/demoDataDir1 |           0
        2 |       0 | p    | p              | s    | u      | 8002 | hashdatas-MacBook-Pro.local | hashdatas-MacBook-Pro.local | /Users/hashdata/Documents/GitHub/upstream/cloudberrydb/gpAux/gpdemo/datadirs/dbfast1/demoDataDir0        |           0
        5 |       0 | m    | m              | s    | u      | 8005 | hashdatas-MacBook-Pro.local | hashdatas-MacBook-Pro.local | /Users/hashdata/Documents/GitHub/upstream/cloudberrydb/gpAux/gpdemo/datadirs/dbfast_mirror1/demoDataDir0 |           0
        4 |       2 | p    | p              | s    | u      | 8004 | hashdatas-MacBook-Pro.local | hashdatas-MacBook-Pro.local | /Users/hashdata/Documents/GitHub/upstream/cloudberrydb/gpAux/gpdemo/datadirs/dbfast3/demoDataDir2        |           0
        7 |       2 | m    | m              | s    | u      | 8007 | hashdatas-MacBook-Pro.local | hashdatas-MacBook-Pro.local | /Users/hashdata/Documents/GitHub/upstream/cloudberrydb/gpAux/gpdemo/datadirs/dbfast_mirror3/demoDataDir2 |           0
    (8 rows)

    postgres=# 
    ```

    > [!NOTE]
    > If the following problem occurs when connecting to the master:
    >
    >     
    >     psql: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed: No such file or directory
	>     Is the server running locally and accepting connections on that socket?
    >     
    >
    > You can solve it by running `export PGPORT=8000`. Run `export PGPORT=8000` every time a shell process is started. You can also write this in the `.bashrc` file by running `echo "export PGPORT=8000" >> ~/.bashrc`.

3. Now we can finally run `installcheck-world` to test everything works fine:

    ```bash
    # In the folder where your cloned the source code
    make installcheck-world
    ```

Congratulations 🎉! You've successfully installed and created a CloudberryDB cluster. Happy Hacking! 😉
