How to use piladb?

Now that you know how to install piladb and what do you need to start using it, let's do real things with it. We will start a pilad server and play with it. You don't need to understand all of the steps, copy-pasting them in your terminal and checking the output will be enough for now.

Start the server

If you followed correctly the Installation instructions as an admin, you should have access to the pilad binary:

pilad -h

Do you see the Usage of pilad as an output? Then you are fine. pilad provides some configuration flags, but we'll stick with the defauls for now. Let's start the server for real:

pilad

This will show you the logs in your terminal. Something like this:

2014/05/12 23:24:03 
2014/05/12 23:24:03          d8b 888               888 888      
2014/05/12 23:24:03          Y8P 888               888 888      
2014/05/12 23:24:03              888               888 888      
2014/05/12 23:24:03 88888b.  888 888  8888b.   .d88888 88888b.  
2014/05/12 23:24:03 888 "88b 888 888    "88b  d88" 888 888 "88b 
2014/05/12 23:24:03 888  888 888 888 .d888888 888  888 888  888 
2014/05/12 23:24:03 888 d88P 888 888 888  888 Y88b 888 888 d88P 
2014/05/12 23:24:03 88888P"  888 888 "Y888888  "Y88888 88888P"  
2014/05/12 23:24:03 888
2014/05/12 23:24:03 888
2014/05/12 23:24:03 888
2014/05/12 23:24:03 
2014/05/12 23:24:03 Version: 1b8b3972367f6f1c5ea439e0236c84ff5ac3f16c
2014/05/12 23:24:03 Host:    linux_amd64
2014/05/12 23:24:03 Port:    1205
2014/05/12 23:24:03 PID:     572
2014/05/12 23:24:03

Keep an eye on this output, as it will log all activities processed by pilad.

🔝 Protip! You can log into a file with pilad &> pilad.log &

Play with piladb

We will use curl for this walkthrough. You can use your favorite HTTP client, considering that some options might change.

So now pilad is running on localhost:1205. If we access the root page will be redirected to the official pilad REST API documentation:

curl -L localhost:1205
# -L follow redirects

We can also check the current status of piladb:

curl localhost:1205/_status

Or the current configuration values:

curl localhost:1205/_config

🔝 Protip! Install jq to pretty print and process the JSON responses.

Create a Database

To start working with piladb, we need to create a new Database, which will contain the Stacks we will work with:

curl -XPUT "localhost:1205/databases?name=MY_DATABASE"

We will see the new Database as an output in JSON format. We can have access to this content everytime by requesting the new Database itself:

curl localhost:1205/databases/MY_DATABASE
{
  "number_of_stacks": 0,
  "name": "MY_DATABASE",
  "id": "da5bf1684cdb20bd0be0b767007b9e82"
}

Also, we can list all existing databases:

curl localhost:1205/databases
{
  "databases": [
    {
      "number_of_stacks": 0,
      "name": "MY_DATABASE",
      "id": "da5bf1684cdb20bd0be0b767007b9e82"
    }
  ],
  "number_of_databases": 1
}

Create a Stack

We created a Database, this means we can start creating Stacks. The process is very similar to the one of creating Databases. We just need to provide the Database and the name of the Stack.

For this example, we'll create a Stack called BOOKSHELF that will contain books:

curl -XPUT "localhost:1205/databases/MY_DATABASE/stacks?name=BOOKSHELF"
{
  "size": 0,
  "peek": null,
  "name": "BOOKSHELF",
  "id": "682fdfca692a0ad5d46ac6ea35fc4f28,
  "created_at": "2016-12-08T17:45:50.668575679+01:00",
  "updated_at": "2016-12-08T17:45:50.668575679+01:00",
  "read_at": "2016-12-08T17:45:50.668575679+01:00"
}

As an output we get the Stack in JSON format. The bookshelf if empty and there's no book on top that we can pick-up.

PUSH, PEEK, POP and SIZE on a Stack

Let's add a book into the bookshelf by doing a PUSH operation.

curl -XPOST localhost:1205/databases/MY_DATABASE/stacks/BOOKSHELF \
  -d '{"element":{"title":"1984","author":"George Orwell","ISBN":"1595404325","comments":[]}}'

This will return the pushed Element:

{
  "element": {
    "title": "1984",
    "comments": [],
    "author": "George Orwell",
    "ISBN": "1595404325"
  }
}

We can get the status of the stack anytime by requesting our Stack:

curl localhost:1205/databases/MY_DATABASE/stacks/BOOKSHELF
{
  "size": 1,
  "peek": {
    "title": "1984",
    "comments": [],
    "author": "George Orwell",
    "ISBN": "1595404325"
  },
  "name": "BOOKSHELF",
  "id": "682fdfca692a0ad5d46ac6ea35fc4f28",
  "created_at": "2016-12-08T17:45:50.668575679+01:00",
  "updated_at": "2016-12-08T17:46:50.668575679+01:00",
  "read_at": "2016-12-08T17:47:50.668575679+01:00"
}

We want to read 1984, but in the meantime we come up with another book that we'd like to read before. So we add it with another PUSH operation:

curl -XPOST localhost:1205/databases/MY_DATABASE/stacks/BOOKSHELF \     
  -d '{"element":{"title":"The Metamorphosis","author":"Franz Kafka","ISBN":"9780486290300","comments":["🐞"]}}'

Now we have two books, and we have to start reading them from top to bottom. To find out which Element is on top, we use the PEEK operation:

curl "localhost:1205/databases/MY_DATABASE/stacks/BOOKSHELF?peek"
{
  "element": {
    "title": "The Metamorphosis",
    "comments": [
      "🐞"
    ],
    "author": "Franz Kafka",
    "ISBN": "9780486290300"
  }
}

Seems like we start reading The Metamorphosis in order to empty our bookshelf. To consume an Element from a Stack, we use the POP operation:

curl -XDELETE localhost:1205/databases/MY_DATABASE/stacks/BOOKSHELF

We get The Metaphorphosis as a response, but if we fetch the status of the Stack we'll only find 1984 as a pending book in the bookshelf:

curl localhost:1205/databases/MY_DATABASE/stacks/BOOKSHELF
{
  "size": 1,
  "peek": {
    "title": "1984",
    "comments": [],
    "author": "George Orwell",
    "ISBN": "1595404325"
  },
  "name": "BOOKSHELF",
  "id": "682fdfca692a0ad5d46ac6ea35fc4f28"
}

We finally read the pending book by doing a POP operation on the Stack:

curl -XDELETE localhost:1205/databases/MY_DATABASE/stacks/BOOKSHELF

And we make sure the bookshelf is empty by running a SIZE operation on the Stack:

curl "localhost:1205/databases/MY_DATABASE/stacks/BOOKSHELF?size"

The result is 0, so we read all pending books!

Cleanup

  • FLUSH a Stack so all Elements are deleted on it:

    curl -XDELETE "localhost:1205/databases/MY_DATABASE/stacks/BOOKSHELF?flush"
    
  • Delete a Stack:

    curl -XDELETE "localhost:1205/databases/MY_DATABASE/stacks/BOOKSHELF?full"
    
  • Delete a Database:

    curl -XDELETE localhost:1205/databases/MY_DATABASE
    

Recap

In this page we have started a pilad server, we learnt how to create a Database and a Stack, and how to handle the latter and Elements by using an idea of a bookshelf where we can pile books, and only read the one on top. Finally, we have applied a cleanup, deleting all existing resources.

results matching ""

    No results matching ""