112 lines
3.3 KiB
Markdown
112 lines
3.3 KiB
Markdown
# 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:
|
|
|
|
```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.
|