Skip to main content

Set up PostgreSQL database

Rell requires PostgreSQL 16.3 to run a node. While the Rell IDE can function without a database, executing a node or a remote Postchain app necessitates PostgreSQL. For a seamless development experience, we recommend using Docker to simplify the setup process.

Default database configuration for Rell​

  • Database name: postchain
  • User: postchain
  • Password: postchain

Installation options​

Using Docker is the simplest and most reliable way to set up PostgreSQL. It avoids platform-specific issues and ensures a consistent environment.

  1. Install Docker Desktop for your operating system.

  2. Run the following command to pull and start a PostgreSQL container:

    docker run --name postgres -e POSTGRES_USER=postchain -e POSTGRES_PASSWORD=postchain -p 5432:5432 -d postgres:16.3-alpine3.20
    note

    We use the Alpine version of PostgreSQL because it provides the correct collation settings by default. The POSTGRES_INITDB_ARGS environment variable explicitly sets these options.

    POSTGRES_INITDB_ARGS="--lc-collate=C.UTF-8 --lc-ctype=C.UTF-8 --encoding=UTF-8"

  3. Verify that the container is running:

    docker ps

2. Installation on macOS​

  1. Install Homebrew: Homebrew installation guide

  2. Install PostgreSQL:

    brew install postgresql@16
    brew services start postgresql@16
    createuser -s postgres

  3. Prepare the PostgreSQL database:

    psql -U postgres -c "CREATE DATABASE postchain WITH TEMPLATE = template0 LC_COLLATE = 'C.UTF-8' LC_CTYPE = 'C.UTF-8' ENCODING 'UTF-8';" -c "CREATE ROLE postchain LOGIN ENCRYPTED PASSWORD 'postchain'; GRANT ALL ON DATABASE postchain TO postchain;"
    info

    If you get an error saying peer authentication failed, change the authentication method from peer to md5 in the pg_hba.conf file.

3. Installation on Linux​

  1. Update your package manager and install PostgreSQL:

    sudo apt update
    sudo apt install postgresql-16

  2. Start PostgreSQL and set up the database:

    sudo service postgresql start
    sudo -u postgres psql -c "CREATE DATABASE postchain WITH TEMPLATE = template0 LC_COLLATE = 'C.UTF-8' LC_CTYPE = 'C.UTF-8' ENCODING 'UTF-8';" -c "CREATE ROLE postchain LOGIN ENCRYPTED PASSWORD 'postchain'; GRANT ALL ON DATABASE postchain TO postchain;"

4. Installation on Windows​

Option 1: Using WSL (Windows Subsystem for Linux) within Windows​

  1. Install WSL and a Linux distribution (e.g., Ubuntu) from the Microsoft Store.

  2. Open the WSL terminal and install PostgreSQL:

    sudo apt update
    sudo apt install postgresql-16

  3. Start PostgreSQL and set up the database:

    sudo service postgresql start
    sudo -u postgres psql -c "CREATE DATABASE postchain WITH TEMPLATE = template0 LC_COLLATE = 'C.UTF-8' LC_CTYPE = 'C.UTF-8' ENCODING 'UTF-8';"
    sudo -u postgres psql -c "CREATE ROLE postchain LOGIN ENCRYPTED PASSWORD 'postchain'; GRANT ALL ON DATABASE postchain TO postchain;"

Option 2: Using native installer​

  1. Download the PostgreSQL installer from the official website.

  2. Install the executable and add the PostgreSQL folder containing the binaries to your environment variables. Open the Command Prompt (CMD) and run the following command, ensuring that you set the path to your binaries correctly and replace the <version> placeholder with the actual version number:

    setx POSTGRESQL "C:\Program Files\PostgreSQL\<version>\bin"

  3. Reopen the Command Prompt (CMD) to update the environment variables. Prepare the PostgreSQL database by running the following two commands sequentially:

    psql -U postgres -c "CREATE DATABASE postchain WITH TEMPLATE = template0 LC_COLLATE = 'en_US.UTF-8' LC_CTYPE = 'en_US.UTF-8' ENCODING 'UTF-8';"
    psql -U postgres -c "CREATE ROLE postchain LOGIN ENCRYPTED PASSWORD 'postchain'; GRANT ALL ON DATABASE postchain TO postchain;"
    info

    Depending on your Windows version, you may encounter errors related to permissions or incorrect PostgreSQL installations. If this happens, use Docker to deploy PostgreSQL instead.