Databases

The Uplink Distributed Ledger is essentially a distributed consensus layer on top of a traditional database. Users can choose between several traditional databases to use as the persistence layer. In other words, an Uplink node is backend agnostic and the normal operation of a node is abstracted over the database layer such that the node will operate exactly the same way whether the data is persisted to disk using a LevelDB, PostgreSQL, or Oracle database.

Users can both initialize new databases and run Uplink nodes using existing databases by specifying the URI of the database the node should connect to. Nodes running on the same network need not use the same database, as the database layer of a node is for persisting ledger data to disk; Ledger data is converted to the relative database schema– depending on the database in use– and subsequently converted back into the in-memory representation that the Uplink node uses when necessary.

Configuration

The database that Uplink uses can be configured in the config file (default node.config) by editing the storage.backend field. This field should contain a valid URI. URI fields are nullable such that missing fields fallback to using default values depending on the resource.

PostgreSQL URI:

postgresql://<user>:<password>@<host>:<port>/<database>

LevelDB URI:

leveldb:///<database>

Example URIs:

To connect to PostgreSQL database uplink on localhost port 5432:

postgresql://localhost:5432/uplink

To connect to PostgreSQL database uplink on localhost port 5432 with user test and password test:

postgresql://test:test@localhost:5432/uplink

To connect to a leveldb database in directory ./uplink:

leveldb:///uplink

Initializing a Database

Currently, initializing a new database before running a node and running a node using an existing database are separate commands.

PostgreSQL

Before an Uplink node can connect to a postgres database server, you must configure a postgres user with a password and use this user and password in your connection string (URI) when booting an uplink node:

The postgres user must have CREATEDB permissions. This can be accomplished by executing a SQL command using a postgres user with SUPERUSER privileges (e.g. the postgres account.):

$ sudo -u postgres psql
postgres=# CREATE USER uplink_test WITH CREATEDB PASSWORD 'uplink_test';

After the uplink database user has been created, the following command will successfully run an Uplink node by initializing a new database named uplink. The database will be owned by the uplink_test user, attempt connect to the local postgres server running on port 5432 (designated by the -b flag). It will also store database agnostic node data in directory uplink_node_data (designated by the -d flag):

$ uplink chain init -b "postgresql://uplink_test:uplink_test@localhost:5432/uplink" -d uplink_node_data

Note: This command will fail if a database already exists.

The following command will run an Uplink node using an existing database named uplink, using the user issuing the command to communicate with the local postgres server running on port 5432, and store node data in directory uplink_node_data:

$ uplink chain -b "postgresql://localhost:5432/uplink" -d uplink_node_data

Depending on the configuration of your postgresql server (and the contents of file pg_hba.conf), an Uplink node’s attempt at communicating with the postgres server may fail because it is expecting a password due to Uplink issuing a request for a TCP connection to connect to the database, and md5 being the default authorization rule. If your pg_hba.conf file does not contain an authorization rule for local TCP connections, add the following line to the file:

host    all             all             127.0.0.1/32            md5

to your pg_hba.conf file if it doesn’t already exist, and then supplying a password in the URI used to connect to the postgresql uplink database.

LevelDB

To initialize a leveldb database or run an Uplink node using an existing leveldb database, you can run the commands as described in the PostgreSQL section above, simply altering the URI following the -b command line flag.