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.
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.
To connect to PostgreSQL database
uplink on localhost port 5432:
To connect to PostgreSQL database
uplink on localhost port 5432 with user
test and password
To connect to a leveldb database in directory
Initializing a Database¶
Currently, initializing a new database before running a node and running a node using an existing database are separate commands.
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
(designated by the
$ 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 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
host all all 127.0.0.1/32 md5
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.
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
command line flag.