3.3 KiB

Raw Blame History

PostgreSQL Setup

Contractless uses PostgreSQL for transaction lookup and mempool-style records. The node creates or migrates its required tables and indexes on startup, so manual setup only needs PostgreSQL itself, a database, a login user, a password and permissions for that user.

PostgreSQL 16 is the tested version. Newer PostgreSQL versions should work, but they have not been tested for launch.

Download PostgreSQL from the official project downloads page:

https://www.postgresql.org/download/

Required Database Access

The database user configured in settings.ini must be able to:

connect to the configured database
create tables and indexes
read, insert, update and delete rows in the tables it creates
use sequences created for BIGSERIAL primary keys

The simplest way to provide the required permissions is to make the Contractless user the owner of the Contractless database.

Linux Manual Setup

Run the SQL as the PostgreSQL superuser. On many Linux installs this means using the postgres system user:

sudo -u postgres psql

Create the database user:

CREATE USER contractless WITH PASSWORD 'change_this_password';

Create the database and make the Contractless user the owner:

CREATE DATABASE contractless_db OWNER contractless;

If local password login is not already enabled, update pg_hba.conf so local TCP connections can authenticate with a password:

host all all 127.0.0.1/32 md5
host all all ::1/128 md5

Reload PostgreSQL after changing pg_hba.conf:

sudo systemctl reload postgresql

Then add the matching values to the active PostgreSQL section of settings.ini:

[Postgres-Testnet]
host = 127.0.0.1
port = 5432
user = contractless
password = change_this_password
dbname = contractless_db

Windows Manual Setup

Install PostgreSQL from the official PostgreSQL download page. PostgreSQL 16 is the tested version.

Open the PostgreSQL SQL Shell, pgAdmin query tool or another PostgreSQL client as a superuser, then run:

CREATE USER contractless WITH PASSWORD 'change_this_password';
CREATE DATABASE contractless_db OWNER contractless;

Add the matching values to the active PostgreSQL section of settings.ini:

[Postgres-Testnet]
host = 127.0.0.1
port = 5432
user = contractless
password = change_this_password
dbname = contractless_db

Existing Database

If the database already exists and is not owned by the Contractless user, either change the owner:

ALTER DATABASE contractless_db OWNER TO contractless;

or grant the user enough rights to create and manage objects in the public schema:

GRANT CONNECT ON DATABASE contractless_db TO contractless;
\c contractless_db
GRANT USAGE, CREATE ON SCHEMA public TO contractless;
ALTER SCHEMA public OWNER TO contractless;

Database ownership is preferred because Contractless creates and updates its schema automatically.

Startup Behavior

When the node starts, it connects to PostgreSQL using the values in settings.ini, then runs the mempool schema setup. This creates the required tables, applies compatible migrations, creates indexes and starts from an empty live mempool.

If PostgreSQL login succeeds but the user lacks ownership or create permissions, node startup will fail during the automatic table or index setup.

3.3 KiB Raw Blame History