Using aioflureedb from the commandline

The aioflureedb library is an asyncio python library for communicating with the FlureeDB blockchain-based graph database. Have a look at the other posts to get more info on how aioflureedb is used from Python.

In this post we are going to look at a convenience feature of aioflureedb that allows you to use the library as a commandline tool instead of a library.

It is important to note that as this functionality isn't the core functionality of aioflureedb, the implementation is a bit minimal. Eventhough the useage as a commandline tool can be really usefull for testing, manual database patching, or CICD pipleine integration.

Currently the following FlureeDB API endpoints are supported by this feature:

Server (fluree) level API endpoints:

• health : Check server health
• version : Check server software version
• new_keys : Have the server create a new ECDSA keypair
• dbs : List the currently excisting databases on the ledger
• new_db : Breate a new database on the ledger.

Database (database) level API endpoints:

• ledger_stats : Ledger stats for specifivc database
• flureeql : Queries in the Fluree Query Language (FlureeQL)
• command : Transactions
• history : The FlureeDB history API
• block : The FlureeDB block API

So how does this work from the command line. Well to use aioflureedb at all, first thing we need to do is install aioflureedb. We are going to do this in a way similar to how we will use aioflureedb on the commandline in order to illustrate that this type of usage is available for different libraries.

python3 -m pip install aioflureedb

This command is basically the same as:

pip3 install aioflureedb

The -m flag tells python to load the library and run it at a special entry point as an executable script.

Now let's assume you have a FlureeDB instance running on the default port on localhost. Let's check the health of the FlureeDB server:

python3 -m aioflureedb fluree --endpoint health

The result looks something like this:

{
  "ready": true,
  "status": "leader",
  "utilization": 0.5
}

Notice we use the level fluree as subcommand to show we are doing a server level command. The --endpoint parameter sets the endpoint to use to health. Health takes no input data, requires no ECDSA signing, and we are using a FlureeDB server on the default localhost.

Let's look how the command would look in a little more compex setting. Imagine that FlureeDB runs on the network behind a HTTPS gateway. Imagine the gateway uses a self signed certificate, what is bad in operation, but maybe its just a system integration test environment and we are running things from within a CICD pipeline. Now our call could end up looking something like this:

python3 -m aioflureedb fluree --endpoint health --host fluree.sit.local --port 443 --https true --sslverify false

Most of the other commands at the fluree level work exactly the same as health. But lets look at an other one. dbs.

The base command looks something like this:

python3 -m aioflureedb fluree --endpoint dbs

This should work perfectly if the sever runs in open API mode. But what is the server is closed up because it is running in production. In that case we need to supplu the ECDSA signing key in order to access the API:

python3 -m aioflureedb fluree --endpoint dbs --masterkey e9e42ded56a7687f6ab55abc28c3e24f2d9f09013326af4b980b37acb4dc1e5b

On to the database level commands. The simplest API endpoint we have there is the ledger_stats endpoint:

python -m aioflureedb database --endpoint ledger_stats --db test/mydb

All database level endpoints need you to specify --db, the database.

The result could look something like this.

{
  "status": 200,
  "data": {
    "indexes": {
      "1": 1658915950196
    },
    "block": 5,
    "index": 1,
    "status": "ready",
    "flakes": 482,
    "size": 53170,
    "indexed": 1
  }
}

All of the other database command need an input JSON. This JSON can either be written out on the command line, or it can be supplied in a designated file.

Let's do a query using flureeql

python -m aioflureedb database --endpoint flureeql --db test/mydb --data '{"select": ["*"], "from": "_auth"}'

The result could look something like this:

[
  {
    "_id": 105553116266496,
    "_auth/id": "TfEvvqHzWyr5u3k7gMY8sdo48pcCqxHNPhH",
    "_auth/roles": [
      {
        "_id": 123145302310912
      }
    ]
  }
]

Typing a more complex query on the commandline might be a problem, so we have an alternative where we put the query in a JSON file and invoke it like this:

python -m aioflureedb database --endpoint flureeql --db test/mydb --datafile all_auths.json

The block and history endpoints work basically the same. Transactions do too:

python -m aioflureedb database --endpoint command --db test/mydb --datafile create_foo.json

{
  "_id": -9,
  "_tx/hash": "d2d707ea0af08b484acb4b0b2b3aa8ef5b752a25b1b9dadb5284f3d54a5700a0",
  "_tx/id": "a0703b6be48a4e030cfbf72162c5c3ed99d76b1ef081c50ae0b589ab647c930d",
  "_tx/auth": {
    "_id": 105553116266496
  },
  "_tx/nonce": 5964671092524222
}

This is basically is, the rest works basically the same. It is a crude commandline tool for doing very basic operations with FlureeDB.