We’ve become sooo used to having a graphical user interface with swipy user-friendly experiences that we’ve become remarkably complacent about the shadowy figures that lurk in the background, able to unleash their power at will1. I am, of course, describing command line interfaces whose ability to perform simple and complex actions quickly is unrivalled.

Attack chickens

Just be careful out there, with great power comes great responsibility; just ask anyone who has typed ‘rm -rf /’ on a Unix based computer. 2

Syntax Error: When Words Betray You

Let us move out of the cold, chilly, dark depths that my words have taken us to and into the lighter, warmer shallows with an eye on an appealing beach bar.

There are times when a CLI gets you what you need without needing to push a pointer around a screen and click on things - it’s way faster and more convenient.

Consider using the Aura provisioning API 3, Aura being a cloud based service for Neo4j graph databases. You can read more on about Aura provisioning API in the documentation.

The API allows programmatic management of provisioning Aura instances - you can create, update and then, when you’re done, delete them.

You can use the API in code, an application like Postman or with a CLI - like curl. For example , use curl to list all of the Aura instances in your account

curl -s -X 'GET' \
 'https://api.neo4j.io/v1/instances' \
 -H 'accept: application/json' \
 -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImFKbWhtUTlYeExsQmFLdHNuZnJIcCJ9eyJ1c3IiOiJkNzI2MzE1My03MWZmLTUxMjQtOWVjYy1lOGFlM2FjNjNjZWUiLCJpc3MiOiJodHRwczovL2F1cmEtYXBpLmV1LmF1dGgwLmNvbS8iLCJzdWIiOiJvVXI4WkN5SjhyNmhwUU9CSmFDTVJGSVFrTVo3RktLVEBjbGllbnRzIiwiYXVkIjoiaoijojHR0cHM6Ly9jb25zb2xlLm5lbzRqLmlvIiwiaWF0IjoxNzAxMTAxMzY2LCJleHAiOjE3MDExMDQ5NjYsImF6cCI6Im9VcjhaQ3lKOHI2aHBRT0JKYUNNUkZJUWtNWjdGS0tUIiwiZ3R5IjoiY2xpZW50LWNyZWRlbnRpYWxzIn0.7MtrY2HKjTRJonE9fHAt97peeLqniGm03m7rq5J9Imy8Liem3-kF0Cvi_SmKe-sut943RHQ47Q_RjyYCZ3Y58a7IYH27;lkj;iojREX6hI6Tz3bI8E2WlpSHDg4OJ0i9z6XMFrbOpKsu6uWYQyLLleVCOtpzqg1ManZnotsI5Krw9rKPBJAoV_EUMFYeMmbVbH7UMKry_ogi15zrhmSZTHYeU1YBkPC_vYmhWc6fBj7flt04A4SyzyG5ITYuzCFuNiECsA6T3acCQRAUbFLngMszYu1RFg'

Which will return JSON like this

{
 "data": [
   {
     "cloud_provider": "gcp",
     "id": "4980872a",
     "name": "Instance01",
     "tenant_id": "6e6bbbe2-1234-5f8a-a25f-b1f62f08b98f"
   },
   {
     "cloud_provider": "gcp",
     "id": "601d53a3",
     "name": "Instance02",
     "tenant_id": "6e6bbbe2-1234-5f8a-a25f-b1f62f08b98f"
   },
   {
     "cloud_provider": "gcp",
     "id": "713adeb0",
     "name": "Instance03",
     "tenant_id": "6e6bbbe2-2345-5f8a-a25f-b1f62f

Curl is a great tool with many strengths but it is not focused on provisioning activities in Aura; this results in a user experience that is not as good as it could be.

If only someone could wave a magic wand and take us to a place where CLIs for Aura danced and gambled amongst the rippling waves of flowers in the fields soaked in the rays of summer 4

Efficiency Unleashed

Why hello there Aura API, a CLI for use with , err, Aura. It brings the ability to provision Aura instances and manage their lifecycle programmatically. If you’re comfortable at the command line or want to include Aura in cloud formation templates or terraform scripts, then this is for you.

Aura CLI is currently a Neo4j Labs project written in Python. This means that you can wave your own magic wand and suggest code improvements - ‘Codify’ as Harry P would say whilst waving his wood around.

We’re going to see how it goes for the next few months before we take any decision but, based on feedback so far, there’s a fair to good chance that Aura CLI will become an official Neo4j product 5.

Let us take a quick peek into what it can do

Learn by Doing

Install the Aura CLI with

pip install aura-cli

Once that’s done, and it only takes a few moments, you’re then able to confirm that the installation was successful

aura --version

API commands are divided into 3 resources: instances, tenants and snapshots. Use the –help flag to get more information about each subcommand, e.g.

aura instances --help
Usage: aura instances [OPTIONS] COMMAND [ARGS]...

  Manage your Aura instances

Options:
  --help  Show this message and exit.

Commands:
  create     Create a new instance
  delete     Delete an instance
  get        Get details for an instance
  list       List all instances in a tenant
  overwrite  Overwrite an instance
  pause      Pause an instance
  resume     Resume an instance
  update     Update an instance

I should have mentioned this a bit earlier but you will need a client id and client secret which you obtain from the Aura console by clicking on your account and following the UX

Nip off, do that and come back. I’ll wait.

With the client id and client secret use them like this

aura credentials add --name <NAME> --client-id <YOUR_CLIENT_ID> --client-secret <YOUR_CLIENT_SECRET> --use

This tells the Aura CLI what credentials to use with the Aura API

Now you can use the various commands. For example, show the Aura instances in a table

aura instances list --output table

cloud_provider | id       | name                        | tenant_id                           
----------------------------------------------------------------------------------------------
aws            | aab68676 | Instance01                  | cdd08005-1f34-57e0-abc6-9f1d813f7301
gcp            | bbe0632f | Instance02                  | cdd08005-1f34-57e0-abc6-9f1d813f7301
aws            | 3djfi676 | Instance03                  | cdd08005-1f34-57e0-abc6-9f1d813f7301

How about creating a new instance?

First, you’ll need to know what configurations are available. These can be different to each tenant you belong to in Aura. This will be a two step process - get the list of tenants and then get the configurations for the tenant where you want to create an instance.

Get the tenants

aura tenants list --output table
id                                   | name          
-----------------------------------------------------
a4dd8fc3-a16d-5734-a5e3-1f2e465ddd2b | Tenant1
cdd08005-1234-57e0-abc6-9f1d813f7301 | Tenant2

Now the configurations for Tenant1 using its tenant id

Caution - this will be a long list and I’ve only shown a snip in the example

aura tenants get -id a4dd8fc3-a16d-5734-a5e3-1f2e465ddd2b
{
  "id": "a4dd8fc3-a16d-5734-a5e3-1f2e465ddd2b",
  "instance_configurations": [
    {
      "cloud_provider": "gcp",
      "memory": "2GB",
      "region": "europe-west1",
      "region_name": "Belgium (europe-west1)",
      "type": "enterprise-db",
      "version": "4"
    },

You can then use this information to create an instance.

aura instances create -tid a4dd8fc3-a16d-5734-a5e3-1f2e465ddd2b -cp gcp -t enterprise-db -r europe-west1 -m 4 -v 5 -n Instance10
{
  "cloud_provider": "gcp",
  "connection_url": "neo4j+s://5c45c43b.databases.neo4j.io",
  "id": "5c45c43b",
  "name": "Instance10",
  "password": "PWP6UZHNEGkaZEBj5c9N1PYqfNRMf0jsCBKWgCt874U",
  "region": "europe-west1",
  "tenant_id": "a4dd8fc3-a16d-5734-a5e3-1f2e465ddd2b",
  "type": "enterprise-db",
  "username": "neo4j"
}

It will take a few moments to create the new instance. You can check progress like so

aura instances get -id 5c45c43b
{
  "cloud_provider": "gcp",
  "connection_url": "neo4j+s://5c45c43b.databases.neo4j.io",
  "id": "5c45c43b",
  "memory": "4GB",
  "name": "Instance01",
  "region": "europe-west1",
  "status": "running",
  "storage": "8GB",
  "tenant_id": "a4dd8fc3-a16d-5734-a5e3-1f2e465ddd2b",
  "type": "enterprise-db"
}

When status changes to running , the instance is available

The sun rays warms our skin

The default JSON output can be consumed by other applications for subsequent processing so you can start to sequence operations together. Or, if you’re just lazy like me, place it into scripts to spin up and down Aura instances without having to move a mouse around the screen.

Enjoy

Until the next time, laters

  1. Sucks to be Will or whomever that is. ↩

  2. rm lurks in the swadows of the bass bin in sticky floored night club trying lure people into the endless darkness of despare with it’s siren call. Approach with care and preferably at the other end of a 10 foot pole. ↩

  3. Full disclosure - I advised on this API as part of my Product Management responsibiliies for APIs at Neo4j. It goes without saying that I’m rather proud of what the team created here and I’m looking forward to see where we go next with it. ↩

  4. I maybe over correcting for the earlier trip into barren , bleak lands. ↩

  5. I’d take that bet - I’m the PM for it. ↩

<
Previous Post
Episode 3: Like what you’re done with that rabbit hole
>
Next Post
Starting out with the Aura API