Contractless/docs/POSTGRES.md

# 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.

## PostgreSQL Must Not Be Public

**Do not expose PostgreSQL to the public Internet. The PostgreSQL port should not be publicly accessible.**

Contractless nodes need a public RPC port for peer connections, but PostgreSQL is an internal database dependency and should normally listen only on `127.0.0.1` or another private interface. Do not open PostgreSQL port `5432` to the public Internet in your router, cloud firewall, VPS firewall, or host firewall.

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:

```bash
sudo -u postgres psql
```

Create the database user:

```sql
CREATE USER contractless WITH PASSWORD 'change_this_password';
```

Create the database and make the Contractless user the owner:

```sql
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:

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

Reload PostgreSQL after changing `pg_hba.conf`:

```bash
sudo systemctl reload postgresql
```

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

```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:

```sql
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`:

```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:

```sql
ALTER DATABASE contractless_db OWNER TO contractless;
```

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

```sql
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.