Skip to content

Commit 90cfd80

Browse files
ohsayanohsayan
committed
Add 0.6.3 docs
1 parent 32b39bf commit 90cfd80

37 files changed

+1009
-0
lines changed

‎versioned_docs/version-0.6.3/1.index.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
id: index
3+
title: Introduction
4+
sidebar_label: Home
5+
slug: /
6+
---
7+
Welcome to Skytable's docs! You will find information about how you can get started with Skytable, installation options, configuration and clients.
8+
9+
## Users
10+
11+
We have an easy-to-follow guide for [Getting Started](getting-started). Once you've got everything up and running, you can take a look at the available actions [here](actions-overview) and [configuration files](config-files).
12+
Once you've learned the basics, start using a [client driver](clients)!
13+
14+
## Developers
15+
16+
You can find information on how to build your own clients [here](protocol/skyhash). The primary idea is to implement the Skyhash Protocol.
17+
18+
## Contributing
19+
20+
If you find any typos, mistakes or any other scope of improvement - please don't hesitate to bring it up [here](https://github.com/skytable/docs/issues). Thank you ❤️!
21+
22+
## License
23+
24+
The documentation is licensed under the [CC-BY-SA-4.0 License](https://github.com/skytable/docs/tree/master/LICENSE)

‎versioned_docs/version-0.6.3/2.getting-started.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
id: getting-started
3+
title: Getting Started
4+
---
5+
Getting started with Skytable is easy 😊 (and fun!). You can get started with [native binaries (recommended)](#get-started-with-bundles) or by using the [docker image](#get-started-with-docker).
6+
7+
## Get started with bundles
8+
9+
### Step 1: Download a bundle
10+
11+
Head over to this [page](https://github.com/skytable/skytable/releases/v0.6.2) and download a version for your platform.
12+
13+
### Step 2: Make the files runnable
14+
15+
Unzip the `zip` file that you just downloaded. If you're on a *nix system, run `chmod +x skyd skysh` to make the files executable. If you're on Windows, right-click the files and then check the `UNBLOCK` checkbox and click on the `APPLY` button.
16+
17+
### Step 3: Start the database server
18+
19+
In the directory where you extracted the files, run `./skyd` on *nix systems or simply `skyd` on Windows systems. That's all there is to starting the database server!
20+
21+
### Step 4: Run the shell `skysh`
22+
23+
`skysh` is the shell that is shipped with the bundle. Run it, just like you did with the database server. Now enter commands in the shell, and have fun! First run `HEYA` to check if everything is fine - the server should reply with _HEY!_.
24+
See all the available actions [here](actions-overview).
25+
26+
You're done with setting up `skyd` 🎉!
27+
28+
## Get started with Docker
29+
30+
First of all, you need to have Docker installed and available on your `PATH` ; you can read the official guide [here](https://docs.docker.com/get-docker/). Once you've got Docker up and running, follow the steps!
31+
32+
### Step 0: Create a container
33+
34+
Open up a terminal and run:
35+
36+
```
37+
docker create skytable/sdb:v0.6.2 --name skyvm
38+
```
39+
40+
:::note
41+
You may need superuser privileges
42+
:::
43+
At the same time, you'll need to set up the bundle by following [Step 1](#step-1-download-a-bundle) and [Step 2](#step-2-make-the-files-runnable) from the previous section.
44+
45+
### Step 1: Start the container
46+
47+
Now run:
48+
49+
```
50+
docker start skyvm
51+
```
52+
53+
:::note
54+
You may need superuser privileges
55+
:::
56+
57+
### Step 2: Find the IP address of the container
58+
59+
In order to connect to the container (which, to `skysh` is nothing but a remote server), you'll have to run:
60+
61+
``` shell
62+
docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' skyvm
63+
```
64+
65+
:::note
66+
You may need superuser privileges
67+
:::
68+
And you'll get a result like:
69+
70+
``` text
71+
172.17.0.1
72+
```
73+
74+
### Step 3: Start the command line client
75+
76+
Open up a terminal in the directory where you downloaded the command line client and run:
77+
78+
``` shell
79+
skysh -h 172.17.0.1
80+
```
81+
82+
And you're done!

‎versioned_docs/version-0.6.3/3.building-from-source.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
id: building-from-source
3+
title: Building from source
4+
---
5+
Of course you can build it from source — but with quite a bit of hassle. The database server is a bit fussy with its builds, so you'll need quite a few tools before you can actually start using it.
6+
7+
### Step 1: Install pre-requisites
8+
As Skytable is written in Rust, you'll have to install the Rust toolchain to build it (a little messy, but not too messy). Go to [this page](https://rustup.rs/) to set up Rust on your local machine.
9+
10+
Besides, the TLS/SSL components are written in C (OpenSSL) — so you'll need to install:
11+
* A C compiler for your platform
12+
* GNU Make (`make`)
13+
* Perl
14+
15+
### Step 2: Clone the tag
16+
Run this from your terminal:
17+
```
18+
git clone --branch v0.6.2 https://github.com/skytable/skytable.git
19+
```
20+
:::tip Bonus tip
21+
If you want to avoid downloading all the version history, run this instead:
22+
```
23+
git clone --depth 1 --branch v0.6.2 https://github.com/skytable/skytable.git
24+
```
25+
:::
26+
### Step 3: Build it!
27+
Expecting that you're still in the same directory, run:
28+
```
29+
cd skybase && cargo build --release
30+
```
31+
:::note
32+
This will take **crazy long** at times, so hold on until Cargo finishes building things
33+
:::
34+
35+
### Step 4: Get the binaries
36+
You'll need to copy `skyd` and `skysh` (or `skyd.exe` and `skysh.exe` if on Windows) from the `skybase/target/release` folder. Be sure to copy these **exact files** and not something else!
37+
### Step 5: Run it!
38+
Now start the database server by running `./skyd` and then start the interactive shell by running `./skysh`. You're ready to use the [actions](actions-overview)!

‎versioned_docs/version-0.6.3/4.persistence.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
---
2+
id: persistence
3+
title: Persistence
4+
---
5+
6+
Skytable supports the persistent storage of data, which is an inherently obvious need for any database. In this document we explore how Skytable's persistence works.
7+
8+
## Data directory structure
9+
10+
Whenever you start Skytable, it will create a number of directories under a root 'data' directory. This is what the
11+
data directory structure looks like:
12+
13+
```
14+
|__user-files (your other files)
15+
|__data
16+
|__data.bin
17+
|__snapshots
18+
|__<YYYYMMDD>-<HHMMSS>.snapshot (many)
19+
|__remote
20+
|___<snapshotname>.snapshot (many)
21+
```
22+
23+
The `data.bin` file is primarily used for persistence while the snapshots folder contains automatically created
24+
snapshots and remotely created snapshots.
25+
26+
## How Skytable stores data
27+
28+
As soon as you start Skytable, it will look for a `data.bin` file in the data directory;
29+
if the data file is found and successfully read, then the previous data is moved into the in-memory table. If no
30+
file was found, then the database server will create one. Once you terminate the daemon, it will flush all data
31+
to this file. All writes are `fsync`ed by the time they complete.
32+
33+
### Save failure during termination
34+
35+
The server would attempt to do a _final_ save operation before it terminates and if this fails, the
36+
server would enter into a retry loop. It will try the save operation after every 10 seconds.
37+
Exponential backoff was not chosen because it could increase to extremely large values that may hurt
38+
a sysadmin's time and productivity.
39+
40+
You might be interested in more features like [BGSAVE](#automated-background-saving) and [snapshots](/snapshots) that
41+
can be configured and used by users.
42+
43+
## Automated background saving
44+
45+
Skytable supports automated saving of data in the background, via `BGSAVE`. `BGSAVE`, runs every two minutes to flush all the data in the in-memory table onto disk, unless customized through the [configuration file](config-files/#an-example-configuration). BGSAVE is enabled by default and we don't recommend disabling it until you're sure that
46+
your hardware will never fail; it is likely that this will never be the case. First BGSAVE will create a temporary
47+
file and then flush the current in-memory table onto disk. It will then replace the old `data.bin` file. The daemon automatically `fsync`s after every successful write (whether to the buffers or
48+
to the actual disk).
49+
50+
### Reliability of BGSAVE
51+
52+
It can happen that BGSAVE fails to flush data to the disk due to some unforeseen system issues (such as lack of
53+
empty disk space, permission errors, etc). But if we continue to accept modifications to the data, it is a bad idea
54+
because this data may never get updated! This is why if BGSAVE fails, it will automatically _poison_ the in-memory
55+
table preventing it from accepting any write/update operations. Poisioning is nothing but a global flag set in the
56+
database that indicates that the DB shouldn't accept any more updates/writes to data and in such a poisoned state,
57+
only reads are permitted.
58+
59+
### BGSAVE Recovery
60+
61+
BGSAVE will automatically try to recover on every 120s (or whatever duration was set). If the problem
62+
was corrected (say it was a permissions issue), then the database server will automatically resume
63+
writes and _unpoison_ the database.

‎versioned_docs/version-0.6.3/5.benchmarking.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
id: benchmarking
3+
title: Benchmarking
4+
---
5+
Who doesn't like speed and as a consequence, benchmarks? So here's a guide on benchmarking Skytable with our tool `sky-bench` .
6+
7+
## Step 0: Getting the benchmarking tool
8+
9+
You'll need to download a bundle from the [releases page](https://github.com/skytable/skytable/releases/v0.6.2) and unzip it. In the following steps we'll assume that you have unzipped the archive and you're in that directory.
10+
11+
## Step 1: Starting the database server
12+
13+
Open a terminal in the current directory and [set executable permissions](getting-started#step-2-make-the-files-runnable). Now start the server by running `./skyd` (or just `skyd` on Windows).
14+
15+
## Step 2: Run the benchmark tool
16+
17+
Open another terminal in the current directory and then run `sky-bench` with no arguments if you want to use the default options, or run `sky-bench --help` to see available configuration options. Hold tight, you'll know when it happens 🚀.
18+
19+
:::tip Tip
20+
**JSON Output**
21+
If you're a bit nerdy, we know it — you'll like some structured data. Well, all you need to do is: run `sky-bench --json` for JSON output!
22+
:::

‎versioned_docs/version-0.6.3/5.cfg-files.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
id: config-files
3+
title: Configuration Files
4+
---
5+
6+
Skytable supports custom configuration files to let users customize the functioning of Sky. Arguably, Sky has one of the simplest configuration files around. Skytable also allows configuration via [command line arguments](config-cmd).
7+
8+
## An example configuration
9+
10+
A configuration file is a TOML file, which has the following basic structure:
11+
12+
```toml
13+
[server]
14+
host = "127.0.0.1"
15+
port = 2003
16+
noart = false # optional
17+
maxcon = 50000 # optional
18+
19+
[bgsave]
20+
enabled = true
21+
every = 120 # Every 120 seconds
22+
```
23+
24+
This is the default configuration used by Sky when you don't specify a configuration file. Let's understand what each of the keys mean along with some other keys that can be used for more
25+
advanced configuration:
26+
27+
- `server` :
28+
- `host` : This is the IP address to which you want the database server to bind to. It can be any valid IPv4 _or_ IPv6 address, as a quoted string
29+
- `port` : This is the port to which you want Sky to bind to
30+
- `noart`: This is **an optional argument** and is recommended for secure environments where displaying terminal artwork might cause problems
31+
- `maxcon` : Set the maximum number of clients that can query concurrently
32+
- `bgsave`:
33+
- `enabled`: This is an optional key, which is to be set to true to enable BGSAVE or false to disable it. If this key is not specified, Sky will enable BGSAVE by default
34+
- `every` : Run BGSAVE `every` seconds. So, for example, if you set this to 120, BGSAVE will run every two minutes. This is also an optional key, and if you don't provide it, the default BGSAVE duration of 120 seconds is used
35+
- `snapshot` (OPTIONAL): This key can be used to configure snapshots and is not enabled by default. See [this](snapshots) for more information.
36+
- `ssl`: This key can be used to configure SSL/TLS options. See [this](ssl) for more information.
37+
38+
## Using a configuration file
39+
40+
To use a configuration file:
41+
42+
1. Create it! We recommend you to name it as `skyd.toml` for easy identification
43+
2. Start the database server with: `skyd -c /path/to/your/file.toml`
44+
3. Done 🎉
45+
46+
If you're confused about creating a configuration file, we always recommend you to download a sample file from [this link](https://github.com/skytable/skytable/blob/next/examples/config-files/template.toml). Do note that this file is bleeding-edge and as a result will have new keys as they're created upstream.
47+
48+
That's all that's there for using configuration files!
49+
:::tip Bonus tip
50+
If you're using a custom host/port, then you can bind `skysh` to a custom host/port by starting `skysh` like:
51+
52+
```shell
53+
skysh -h [HOST] -p [PORT]
54+
```
55+
56+
You can do the same for `sky-bench`:
57+
58+
```shell
59+
sky-bench -h [HOST] -p [PORT]
60+
```
61+
62+
:::

‎versioned_docs/version-0.6.3/actions.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
id: actions-overview
3+
title: Actions overview
4+
---
5+
Actions are like shell commands: they take arguments and do something! Skytable currently supports the following actions:
6+
7+
* [DBSIZE](actions/DBSIZE.md)
8+
* [DEL](actions/DEL.md)
9+
* [EXISTS](actions/EXISTS.md)
10+
* [FLUSHDB](actions/FLUSHDB.md)
11+
* [GET](actions/GET.md)
12+
* [KEYLEN](actions/KEYLEN.md)
13+
* [LSKEYS](actions/LSKEYS.md)
14+
* [MGET](actions/MGET.md)
15+
* [MKSNAP](actions/MKSNAP.md)
16+
* [MSET](actions/MSET.md)
17+
* [MUPDATE](actions/MUPDATE.md)
18+
* [POP](actions/POP.md)
19+
* [SDEL](actions/SDEL.md)
20+
* [SET](actions/SET.md)
21+
* [SSET](actions/SSET.md)
22+
* [SUPDATE](actions/SUPDATE.md)
23+
* [UPDATE](actions/UPDATE.md)
24+
* [USET](actions/USET.md)

‎versioned_docs/version-0.6.3/actions/DBSIZE.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
id: dbsize
3+
title: DBSIZE
4+
---
5+
:::note About
6+
**Time complexity**: O(1)
7+
**Arguments**: `DBSIZE`
8+
**Returns**: Number of keys that exist in the database as an unsigned int
9+
:::
10+
Number of key/value pairs stored in the database

‎versioned_docs/version-0.6.3/actions/DEL.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
id: del
3+
title: DEL
4+
---
5+
:::note About
6+
**Time complexity**: O(n)
7+
**Arguments**: `DEL <key1> <key2> ...`
8+
**Returns**: Number of keys that were deleted as an unsigned int
9+
:::
10+
Delete 'n' keys

‎versioned_docs/version-0.6.3/actions/EXISTS.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
id: exists
3+
title: EXISTS
4+
---
5+
:::note About
6+
**Time complexity**: O(n)
7+
**Arguments**: `EXISTS <key1> <key2> ...`
8+
**Returns**: Number of keys that exist as an unsigned int
9+
:::
10+
Check if 'n' keys exist

0 commit comments

Comments
 (0)