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. This also applies when running and testing your dapp locally on a local node. 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

1. Docker (recommended)

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. Platform-specific installation

macOS

1. Install Homebrew (if not already installed):

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install PostgreSQL:

   brew install postgresql@16
   brew services start postgresql@16
   export PATH="$(brew --prefix postgresql@16)/bin:$PATH"
   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.

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;"

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 (Windows 11 recommended)

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 Windows PowerShell using Run as administrator 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" /M

3. Check if the environment variables are set correctly:

   echo %POSTGRESQL%

4. Open a new Windows PowerShell as normal user to make sure the environment variables are in effect. Prepare the PostgreSQL database by running the following two commands sequentially:

   psql -U postgres -c "CREATE DATABASE postchain WITH TEMPLATE = template0 LOCALE_PROVIDER icu ICU_LOCALE = 'und-u-kf-upper' LC_COLLATE = 'und-u-kf-upper' LC_CTYPE = 'und-u-kf-upper' ENCODING 'UTF-8';"
   psql -U postgres -c "CREATE ROLE postchain LOGIN ENCRYPTED PASSWORD 'postchain'; GRANT ALL ON DATABASE postchain TO postchain;"
   warning

   Windows native PostgreSQL installation is not recommended for production use. Depending on your Windows version, you may encounter issues related to permissions or Rell runtime errors. If this happens, use Docker to deploy PostgreSQL instead.