Managing buckets with Reduct Storage CLI Client
Tags: database, tutorial, reducstorage
Published: 2022-11-06 14:22:50

A bucket is a top-level data container of [Reduct Storage](https://reduct-storage.dev). You can consider it as a folder of a file system. If you delete it, you delete all files inside the bucket. Also, it has common [settings](https://docs.reduct-storage.dev/how-does-it-work#bucket) for all entries, like the quota or maximal block size.

You can create, remove or browse a bucket by using:
1. [HTTP API](https://docs.reduct-storage.dev/http-api) with CURL
2. [Python](https://github.com/reduct-storage/reduct-py), [JavaScript](https://github.com/reduct-storage/reduct-js), or [C++](https://github.com/reduct-storage/reduct-cpp) SDKs
3. [Web Console](https://github.com/reduct-storage/web-console)
4. [CLI Client](https://github.com/reduct-storage/reduct-cli)

In this post, I'll show you how we can use the CLI client for typical operations with bucket.

## Installing

The CLI client is cross-platform and written in pure Python. The easiest way to install it, is `pip`:

```
pip install reduct-cli
```

After installation, check the version:

```
rcli --version
```

This tutorial was written and tested for version 0.2.0 and Reduct Storage 1.0.1.


## Aliasing

To avoid entering credentials and server URL for each command, the CLI client uses aliases. So, we should setup one before to start. Let's run a [Reduct Storage](https://docs.reduct-storage.dev/) instance locally and add an alias to it:

```
rcli alias add local
  URL: http://127.0.0.1:8383
  API Token []: # leav token empty if you don't use it
```

Check:

```
rcli server status local
Status:     Ok
Version:    1.0.1
Uptime:     39 second(s)
```

If you don't have any errors, you create a correct alias.

## Bucket Management

Now, we can create a bucket:

```
rcli bucket create --quota-type FIFO --quota-size 30Mb local/my-data
Bucket 'my-data' created
```

Here we created a bucket called `my-data` and FIFO quota of 30MB. We choose this type of the bucket quota to remove old data when the bucket size reaches 30MB. 

You can check the whole settings:

```
rcli bucket show local/my-data --full

╭───────────────────── Info ─────────────────────╮╭───────── Settings ─────────╮
│ Entry count:         0                         ││ Quota Type:         FIFO   │
│ Size:                0 B                       ││ Quota Size:         30 MB  │
│ Oldest Record (UTC): ---                       ││ Max. Block Size:    64 MB  │
│ Latest Record (UTC): ---                       ││ Max. Block Records: 1024   │
│ History Interval:    ---                       ││                            │
│                                                ││                            │
│                                                ││                            │
│                                                ││                            │
│                                                ││                            │
│                                                ││                            │
╰────────────────────────────────────────────────╯╰────────────────────────────╯
                                    Entries                                     
┏━━━━━━┳━━━━━━━━━┳━━━━━━━━┳━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
┃      ┃         ┃        ┃      ┃ Oldest Record   ┃ Latest Record   ┃         ┃
┃ Name ┃ Records ┃ Blocks ┃ Size ┃ (UTC)           ┃ (UTC)           ┃ History ┃
┡━━━━━━╇━━━━━━━━━╇━━━━━━━━╇━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩
└──────┴─────────┴────────┴──────┴─────────────────┴─────────────────┴─────────┘
```

You may also notice that the bucket is empty. We can write some data there with CURL:

```
curl -X POST -d "Hey, I'm a blob string"  http://127.0.0.1:8383/api/v1/b/my-data/entry?ts=1667741359000000
```

If we repeat the previous `bucket show` command, we should see that the bucket has some data now:

```
rcli bucket show local/my-data --full
```

The CLI client also provides the ` bucket ls` command to print a list of buckets:

```
rcli bucket ls local
my-data
```

You also can add `--full` flag to show more detail:

```
rcli bucket ls local --full

┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
┃                  ┃             ┃      ┃ Oldest Record     ┃ Latest Record    ┃
┃             Name ┃ Entry Count ┃ Size ┃ (UTC)             ┃ (UTC)            ┃
┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
│          my-data │ 1           │ 22 B │ 2022-11-06T13:29… │ 2022-11-06T13:2… │
├──────────────────┼─────────────┼──────┼───────────────────┼──────────────────┤
│      Total for 1 │ 1           │ 22 B │ 2022-11-06T13:29… │ 2022-11-06T13:2… │
│          buckets │             │      │                   │                  │
└──────────────────┴─────────────┴──────┴───────────────────┴──────────────────┘
```

In the end, you may want to remove your bucket and all its data. You should use the `bucket rm` command for this:

```
rcli bucket rm local/my-data
All data in bucket 'my-data' will be REMOVED.
Do you want to continue? [y/N]: y
Bucket 'my-data' was removed
```

I hope it was helpful. The Reduct Storage project is open-source software. You can find the source code of the storage engine and all its libraries and tools on our [GitHub organization](https://github.com/reduct-storage). Please create an issue or discussion there, if you need help.