From 4cd96d9353d16c95aa8968d57b1ddc9ce9b0c473 Mon Sep 17 00:00:00 2001 From: Sayan Nandan Date: Tue, 15 Feb 2022 18:30:43 +0530 Subject: [PATCH] Bump docs for 0.7.3 --- versioned_docs/version-0.7.3/1.index.md | 25 ++ versioned_docs/version-0.7.3/10.snapshots.md | 56 ++++ versioned_docs/version-0.7.3/11.ssl.md | 57 ++++ versioned_docs/version-0.7.3/12.clients.md | 19 ++ versioned_docs/version-0.7.3/13.perf-guide.md | 25 ++ .../version-0.7.3/14.benchmarking.md | 23 ++ .../version-0.7.3/15.deployment-notes.md | 20 ++ .../version-0.7.3/16.building-from-source.md | 53 ++++ .../version-0.7.3/2.getting-started.md | 71 +++++ .../version-0.7.3/3.actions-overview.md | 98 +++++++ versioned_docs/version-0.7.3/4.containers.md | 141 +++++++++ versioned_docs/version-0.7.3/5.ddl.md | 150 ++++++++++ versioned_docs/version-0.7.3/5b.examples.md | 167 +++++++++++ versioned_docs/version-0.7.3/6.all-actions.md | 51 ++++ versioned_docs/version-0.7.3/7.cfg-files.md | 88 ++++++ versioned_docs/version-0.7.3/7.cfg.md | 32 ++ versioned_docs/version-0.7.3/7a.env-config.md | 44 +++ .../version-0.7.3/8.config-cmdline.md | 23 ++ versioned_docs/version-0.7.3/9.persistence.md | 54 ++++ .../version-0.7.3/actions/DBSIZE.md | 24 ++ versioned_docs/version-0.7.3/actions/DEL.md | 26 ++ .../version-0.7.3/actions/EXISTS.md | 25 ++ .../version-0.7.3/actions/FLUSHDB.md | 25 ++ versioned_docs/version-0.7.3/actions/GET.md | 25 ++ versioned_docs/version-0.7.3/actions/HEYA.md | 25 ++ .../version-0.7.3/actions/KEYLEN.md | 24 ++ versioned_docs/version-0.7.3/actions/LGET.md | 158 ++++++++++ versioned_docs/version-0.7.3/actions/LMOD.md | 123 ++++++++ versioned_docs/version-0.7.3/actions/LSET.md | 29 ++ .../version-0.7.3/actions/LSKEYS.md | 28 ++ versioned_docs/version-0.7.3/actions/MGET.md | 23 ++ .../version-0.7.3/actions/MKSNAP.md | 32 ++ versioned_docs/version-0.7.3/actions/MPOP.md | 26 ++ versioned_docs/version-0.7.3/actions/MSET.md | 26 ++ .../version-0.7.3/actions/MUPDATE.md | 26 ++ versioned_docs/version-0.7.3/actions/POP.md | 27 ++ versioned_docs/version-0.7.3/actions/SDEL.md | 27 ++ versioned_docs/version-0.7.3/actions/SET.md | 25 ++ versioned_docs/version-0.7.3/actions/SSET.md | 25 ++ .../version-0.7.3/actions/SUPDATE.md | 27 ++ .../version-0.7.3/actions/UPDATE.md | 25 ++ versioned_docs/version-0.7.3/actions/USET.md | 24 ++ .../version-0.7.3/actions/WHEREAMI.md | 25 ++ .../version-0.7.3/protocol/data-types.md | 197 +++++++++++++ .../version-0.7.3/protocol/errors.md | 34 +++ .../version-0.7.3/protocol/response-codes.md | 20 ++ .../version-0.7.3/protocol/skyhash.md | 277 ++++++++++++++++++ .../version-0.7.3-sidebars.json | 69 +++++ versions.json | 1 + 49 files changed, 2645 insertions(+) create mode 100644 versioned_docs/version-0.7.3/1.index.md create mode 100644 versioned_docs/version-0.7.3/10.snapshots.md create mode 100644 versioned_docs/version-0.7.3/11.ssl.md create mode 100644 versioned_docs/version-0.7.3/12.clients.md create mode 100644 versioned_docs/version-0.7.3/13.perf-guide.md create mode 100644 versioned_docs/version-0.7.3/14.benchmarking.md create mode 100644 versioned_docs/version-0.7.3/15.deployment-notes.md create mode 100644 versioned_docs/version-0.7.3/16.building-from-source.md create mode 100644 versioned_docs/version-0.7.3/2.getting-started.md create mode 100644 versioned_docs/version-0.7.3/3.actions-overview.md create mode 100644 versioned_docs/version-0.7.3/4.containers.md create mode 100644 versioned_docs/version-0.7.3/5.ddl.md create mode 100644 versioned_docs/version-0.7.3/5b.examples.md create mode 100644 versioned_docs/version-0.7.3/6.all-actions.md create mode 100644 versioned_docs/version-0.7.3/7.cfg-files.md create mode 100644 versioned_docs/version-0.7.3/7.cfg.md create mode 100644 versioned_docs/version-0.7.3/7a.env-config.md create mode 100644 versioned_docs/version-0.7.3/8.config-cmdline.md create mode 100644 versioned_docs/version-0.7.3/9.persistence.md create mode 100644 versioned_docs/version-0.7.3/actions/DBSIZE.md create mode 100644 versioned_docs/version-0.7.3/actions/DEL.md create mode 100644 versioned_docs/version-0.7.3/actions/EXISTS.md create mode 100644 versioned_docs/version-0.7.3/actions/FLUSHDB.md create mode 100644 versioned_docs/version-0.7.3/actions/GET.md create mode 100644 versioned_docs/version-0.7.3/actions/HEYA.md create mode 100644 versioned_docs/version-0.7.3/actions/KEYLEN.md create mode 100644 versioned_docs/version-0.7.3/actions/LGET.md create mode 100644 versioned_docs/version-0.7.3/actions/LMOD.md create mode 100644 versioned_docs/version-0.7.3/actions/LSET.md create mode 100644 versioned_docs/version-0.7.3/actions/LSKEYS.md create mode 100644 versioned_docs/version-0.7.3/actions/MGET.md create mode 100644 versioned_docs/version-0.7.3/actions/MKSNAP.md create mode 100644 versioned_docs/version-0.7.3/actions/MPOP.md create mode 100644 versioned_docs/version-0.7.3/actions/MSET.md create mode 100644 versioned_docs/version-0.7.3/actions/MUPDATE.md create mode 100644 versioned_docs/version-0.7.3/actions/POP.md create mode 100644 versioned_docs/version-0.7.3/actions/SDEL.md create mode 100644 versioned_docs/version-0.7.3/actions/SET.md create mode 100644 versioned_docs/version-0.7.3/actions/SSET.md create mode 100644 versioned_docs/version-0.7.3/actions/SUPDATE.md create mode 100644 versioned_docs/version-0.7.3/actions/UPDATE.md create mode 100644 versioned_docs/version-0.7.3/actions/USET.md create mode 100644 versioned_docs/version-0.7.3/actions/WHEREAMI.md create mode 100644 versioned_docs/version-0.7.3/protocol/data-types.md create mode 100644 versioned_docs/version-0.7.3/protocol/errors.md create mode 100644 versioned_docs/version-0.7.3/protocol/response-codes.md create mode 100644 versioned_docs/version-0.7.3/protocol/skyhash.md create mode 100644 versioned_sidebars/version-0.7.3-sidebars.json diff --git a/versioned_docs/version-0.7.3/1.index.md b/versioned_docs/version-0.7.3/1.index.md new file mode 100644 index 000000000..150cd093c --- /dev/null +++ b/versioned_docs/version-0.7.3/1.index.md @@ -0,0 +1,25 @@ +--- +id: index +title: Introduction +sidebar_label: Home +slug: / +--- + +Welcome to Skytable's docs! You will find information about how you can get started with Skytable, installation options, configuration and clients. + +## Users + +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](all-actions) and [configuration](config). +Once you've learned the basics, start using a [client driver](clients)! + +## Developers + +You can find information on how to build your own clients [here](protocol/skyhash). The primary idea is to implement the Skyhash Protocol. + +## Contributing + +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 ❤️! + +## License + +The documentation is licensed under the [CC-BY-SA-4.0 License](https://github.com/skytable/docs/tree/master/LICENSE) diff --git a/versioned_docs/version-0.7.3/10.snapshots.md b/versioned_docs/version-0.7.3/10.snapshots.md new file mode 100644 index 000000000..5486cc737 --- /dev/null +++ b/versioned_docs/version-0.7.3/10.snapshots.md @@ -0,0 +1,56 @@ +--- +id: snapshots +title: Snapshots +--- + +Skytable supports automated snapshots that can be used for periodic backups. +Skytable's snapshotting system is dead simple and works in a similar way to [BGSAVE](persistence). + +## Enabling snapshots + +Snapshots aren't enabled by default — you have to enable them by using the configuration file or [command line arguments](config-cmd). To your existing configuration file, just add the following block: + +```toml +[snapshot] +every = 3600 +atmost = 4 +failsafe = true # optional +``` + +Here's what these values mean: + +- `every` - Number of seconds to wait before creating another snapshot +- `atmost` - The maximum number of snapshots to keep +- `failsafe` - This indicates whether the database should stop accepting write operations if + snapshotting fails + +## Storage of snapshots + +All the created snapshots are stored in a `data/snaps` folder in the current directory. +The snapshot folders are named in the format: `YYYYMMDD-HHMMSS`. On the other hand, +[remote snapshots](#remote-snapshots) are stored in the `data/rsnap` folder. + +## How snapshots work + +As mentioned earlier, snapshots work just like `BGSAVE`. A task is spawned that starts encoding +(and writing data) to a folder (which appears to be a copy of the ks folder); once all the data is successfully flushed to disk, the task exits. + +## Methods of creating snapshots + +Snapshots can be created automatically by using the configuration file. However, if you want to create snapshots remotely, you can use the [ `MKSNAP` ](actions/mksnap) action. This will only +create snapshots if it is enabled on the server-side, unless you use +[truly remote snapshots](#remote-snapshots). + +## Remote snapshots + +Irrespective of whether snapshots are enabled on the server side, you can use _truly remote snapshots_. +Such snapshots can be created by using the [`MKSNAP`](actions/mksnap) action. To do this, +pass a second argument to `MKSNAP` with the desired name of your snapshot. This will create +a snapshot in the `data/rsnap` directory. + +:::tip +Since snapshots are intended for data backups — you can do a little _trick_ to make these +backups offsite-backups: mount a network file system or a different drive and create a folder +for storing your snapshots in it. Now, symlink the `data/snaps` directory to your +_remotely mounted directory_. You now have offsite backups! +::: diff --git a/versioned_docs/version-0.7.3/11.ssl.md b/versioned_docs/version-0.7.3/11.ssl.md new file mode 100644 index 000000000..d245cc93d --- /dev/null +++ b/versioned_docs/version-0.7.3/11.ssl.md @@ -0,0 +1,57 @@ +--- +id: ssl +title: TLS configuration +--- + +Skytable lets you secure connections with TLS. This feature is built into Sky with OpenSSL and doesn't require you to have OpenSSL installed. You can enable TLS by using your [preferred mode of configuration](config). + +### Step 1: Create a self-signed certificate and private key + +This is outside the scope of this document, but you can read [this guide on Stackoverflow](https://stackoverflow.com/a/10176685) to get a brief idea of creating one. + +### Step 2: Add it to your configuration and launch + +#### With config files + +Add the following block: + +```toml +[ssl] +key = "/path/to/keyfile.pem" +chain = "/path/to/chain.pem" +port = 2004 +only = true +``` + +The above block is self-explanatory; you just have to add the paths to the private key and certificate files and add the port (if required). + +By setting `only` to `true`, the server will only accept accept secure connections. In other cases, +the server listens to two ports: `2003` and `2004`, a non-TLS port and a TLS port (similar to port +80 and port 443 in HTTP/HTTPS). As expected, you can configure this port number to suit your needs. + +:::note +We use the terms `SSL` and `TLS` interchangeably, when what we really mean is TLS. +::: + +#### With command-line arguments + +Simply start `skyd` with: + +```shell +skyd -z cert.pem -k key.pem +``` + +:::tip Tip +You can pass the `--sslonly` flag to force the server to only accept secure connections, disabling the non-SSL interface. When this flag is not passed, and other SSL options are given — the server listens to both SSL and non-SSL requests +::: + +:::info Note +To use TLS with the Skytable shell (`skysh`) just run: + +``` +skysh -C /path/to/cert.pem --port [SSLPORT] +``` + +and you'll be on a secure connection. Don't forget the SSL port! The skytable daemon binds the secure +listener on a different port when in multi-socket mode. +::: diff --git a/versioned_docs/version-0.7.3/12.clients.md b/versioned_docs/version-0.7.3/12.clients.md new file mode 100644 index 000000000..3eebd3155 --- /dev/null +++ b/versioned_docs/version-0.7.3/12.clients.md @@ -0,0 +1,19 @@ +--- +id: clients +title: Client drivers +--- + +We officially maintain the following drivers: + +- [Rust driver](https://github.com/skytable/client-rust) [Apache-2.0] - Always up to date and is used by the core project itself + +Community powered drivers: + +- [C# driver](https://www.nuget.org/packages/Skytable.Client/) [Apache-2.0] - Source code can be found [here on GitHub](https://github.com/martinmolin/skytable-dotnet) +- [JavaScript/TypeScript driver (node)](https://www.npmjs.com/package/skytable.js) [MIT-License] - Source code can be found [here on GitHub](https://github.com/zhangyuannie/skytable.js) + +:::info More lanugages +The team is always looking to support more languages and we wish we could ship more drivers. But due to limited +resources we haven't been able to. If you're willing to write a driver (it's super easy to), jump into the +[Skytable discord server](https://discord.gg/QptWFdx) and a maintainer/moderator will help you out! +::: diff --git a/versioned_docs/version-0.7.3/13.perf-guide.md b/versioned_docs/version-0.7.3/13.perf-guide.md new file mode 100644 index 000000000..d8e12c7be --- /dev/null +++ b/versioned_docs/version-0.7.3/13.perf-guide.md @@ -0,0 +1,25 @@ +--- +id: perf-guide +title: Performance Guide +--- + +We have put in our best efforts to make Skytable really fast — but usage patterns can greatly +affect how well Skytable performs for you, and how well you are able to exploit the _on metal_ +performance that Skytable can provide. Here are some quick pointers to get maximum performance: + +- **Try to have a lesser number of tables** + + The number of tables you can create is virtually + unlimited, but however, creating a huge number of tables (say over 60,000) _can_ hurt performance. + +- **Try to use default connection level containers** + + Although you are free to run actions by + specifying the table to use, it has a runtime cost because the table has to be looked up and errors + need to be handled. Instead, try using default containers wherever possible. For example, if you + have a table `cakes` in a keyspace `birthday` and your application will be using this table for + the most part, it's a good idea to run `use birthday:cakes` after connecting and then using the + actions without specifying a table (or keyspace). This avoids the lookup and error handling cost. + +- If you know your data in keymap tables has valid unicode, try using the `binstr` type instead. + This is because unicode validation adds a _very small_ runtime cost diff --git a/versioned_docs/version-0.7.3/14.benchmarking.md b/versioned_docs/version-0.7.3/14.benchmarking.md new file mode 100644 index 000000000..1700265e2 --- /dev/null +++ b/versioned_docs/version-0.7.3/14.benchmarking.md @@ -0,0 +1,23 @@ +--- +id: benchmarking +title: Benchmarking +--- + +Who doesn't like speed and as a consequence, benchmarks? So here's a guide on benchmarking Skytable with our tool `sky-bench` . + +## Step 0: Getting the benchmarking tool + +You'll need to download a bundle from the [releases page](https://github.com/skytable/skytable/releases/v0.6.3) and unzip it. In the following steps we'll assume that you have unzipped the archive and you're in that directory. + +## Step 1: Starting the database server + +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). + +## Step 2: Run the benchmark tool + +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 🚀. + +:::tip Tip +**JSON Output** +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! +::: diff --git a/versioned_docs/version-0.7.3/15.deployment-notes.md b/versioned_docs/version-0.7.3/15.deployment-notes.md new file mode 100644 index 000000000..d34b8731c --- /dev/null +++ b/versioned_docs/version-0.7.3/15.deployment-notes.md @@ -0,0 +1,20 @@ +--- +id: deployment-notes +title: Deployment notes +--- + +Here are some _good to know_ things about deploying Skytable: + +- Skytable is under active development. If you do find any rough edges, [please open an issue](https://github.com/skytable/skytable/issues) +- The daemon will create a `.sky_pid` file in its working directory which functions as a PID file + and indicates other processes to not use the data directory. If the daemon is somehow forcefully + stopped, the file may not be removed. In that case, you should manually remove the file +- Skytable currently has a default limit of 50000 connections on a single daemon instance. This limit + can be modified [in your configuration](config). + :::note + Make sure you change the maximum number of connections according to the available system resources to avoid DoS + like attacks that may cause your system to crash + ::: +- Skytable is inherently multithreaded. As of now, there is no way to stop Skytable from using + multiple threads +- The best way to deploy Skytable is as a service (and disabling terminal artwork) diff --git a/versioned_docs/version-0.7.3/16.building-from-source.md b/versioned_docs/version-0.7.3/16.building-from-source.md new file mode 100644 index 000000000..894608940 --- /dev/null +++ b/versioned_docs/version-0.7.3/16.building-from-source.md @@ -0,0 +1,53 @@ +--- +id: building-from-source +title: Building from source +--- + +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. + +### Step 1: Install pre-requisites + +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. + +Besides, the TLS/SSL components are written in C (OpenSSL) — so you'll need to install: + +- A C compiler for your platform +- GNU Make (`make`) +- Perl + +### Step 2: Clone the tag + +Run this from your terminal: + +``` +git clone --branch v0.7.3 https://github.com/skytable/skytable.git +``` + +:::tip Bonus tip +If you want to avoid downloading all the version history, run this instead: + +``` +git clone --depth 1 --branch v0.7.3 https://github.com/skytable/skytable.git +``` + +::: + +### Step 3: Build it! + +Expecting that you're still in the same directory, run: + +``` +cd skybase && cargo build --release +``` + +:::note +This will take **crazy long** at times, so hold on until Cargo finishes building things +::: + +### Step 4: Get the binaries + +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! + +### Step 5: Run it! + +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)! diff --git a/versioned_docs/version-0.7.3/2.getting-started.md b/versioned_docs/version-0.7.3/2.getting-started.md new file mode 100644 index 000000000..592036bc1 --- /dev/null +++ b/versioned_docs/version-0.7.3/2.getting-started.md @@ -0,0 +1,71 @@ +--- +id: getting-started +title: Getting Started +--- + +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). + +## Get started with bundles + +### Step 1: Download a bundle + +Head over to this [page](https://github.com/skytable/skytable/releases/v0.7.3) and download a version for your platform. + +:::tip Tip +If you're on Debian, consider downloading an appropriate `.deb` (Debian Package) file for your machine. +The package will install `skyd`, `skysh`, `sky-bench` and `sky-migrate` on your system while also +configuring a `systemd` service unit. +::: + +### Step 2: Make the files runnable + +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. + +### Step 3: Start the database server + +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! + +### Step 4: Run the shell `skysh` + +`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!_. + +You're done with setting up `skyd` 🎉! + +## Get started with Docker + +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! + +:::note +You may need superuser privileges for installation and running the commands below +::: + +### Step 0: Create and start the container + +We'll create a container where: + +1. We'll call our container `mysky` +2. We'll expose port 2003 of the container +3. We'll save all our data on the host in a folder called `skytable` relative to the current directory. To achieve this, we'll make use of Docker volumes. + +Open up a terminal and run: + +```sh +docker run --name mysky \ + -v ./skytable:/var/lib/skytable \ + -p 2003:2003 \ + skytable/sdb:v0.7.3 +``` + +### Step 1: Download and setup the bundle + +Follow the [instructions above](#get-started-with-bundles) so that you're ready to run `skysh` + +### Step 2: Connect to the instance + +Simply run: + +```sh +skysh -h 127.0.0.1 -p 2003 +``` + +Now, you're all set! diff --git a/versioned_docs/version-0.7.3/3.actions-overview.md b/versioned_docs/version-0.7.3/3.actions-overview.md new file mode 100644 index 000000000..e9e77876a --- /dev/null +++ b/versioned_docs/version-0.7.3/3.actions-overview.md @@ -0,0 +1,98 @@ +--- +id: actions-overview +title: Actions and Querying +--- + +Actions are exactly what they say — they do something! You can think of actions to be like +shell commands: you run a command with arguments and you get some corresponding output. +In this document we'll explore actions, or what you may +call queries. We'll also explore the different kinds of queries that you can use with Skytable. + +Remember the `HEYA` you ran in the earlier document? Yup, that's an action. All kind of _quering_ in Skytable is done through actions. Actions are classified into two kinds: + +- DDL (Data definition language) Actions: These actions enable us to interact with the structures + that store our data +- DML (Data manipulation language) Actions: These actions enable us to access and manipulate the data stored in our database + +## Taking _action_ + +If you're coming from a SQL background, you might be used to the _DML_ way of things. That's right, DML actions are _similar_. +Let us try out a few basic DML actions (don't worry — you'll learn about DDL in the next few documents). + +### SET + +The `SET` action lets us assign a key to a value (in a key/value table). For example: + +```sql +SET x 100 +``` + +will assign the key `x` to `100`. But how do we get it? + +### GET + +The `GET` action lets us fetch keys. For example: + +```sql +GET x +``` + +will return the `100` that we set in the last step. + +### UPDATE + +The `UPDATE` action lets us update the values of keys. For example: + +```sql +UPDATE x 200 +``` + +will update the value of `x` to `200` + +### DEL + +The `DEL` action lets us remove keys from the database. For example: + +```sql +DEL x +``` + +will remove the key `x` from the database. + +Didn't we just do a **C**reate-**R**ead-**U**pdate-**D**elete? The infamous CRUD! Now that you know +some basic actions, you can take a look at the [full index of actions](all-actions). + +## Types of queries + +### Simple queries + +Simple queries are, well simple! You run a single action and there — you ran a simple query. + +### Pipelined queries + +Pipelined queries or simply pipelines enable clients to send multiple queries to the database server +at once. Responses for every query is returned in the order they query was sent. For example if you sent four queries like: +```sql +heya once +heya twice +heya thrice +heya finally +``` +Then you'd get the echos in the following order: +```sql +"once" +"twice" +"thrice" +"finally" +``` + +Hence, the responses are returned in the order queries were issued. + +:::note Limitations +Pipelines provide no transactional guarantees and hence shouldn't be relied on for the same. +::: + +### Batches + +Batches are currently in the _decision phase_ but aim to provide a way to overcome the limitations imposed by pipelines, hence providing stronger +guarantees. If you have any ideas, drop an [issue here](https://github.com/skytable/skytable/issues/new) and we'll be happy to consider it! diff --git a/versioned_docs/version-0.7.3/4.containers.md b/versioned_docs/version-0.7.3/4.containers.md new file mode 100644 index 000000000..3d81881dd --- /dev/null +++ b/versioned_docs/version-0.7.3/4.containers.md @@ -0,0 +1,141 @@ +--- +id: containers +title: Containers +--- + +Containers are _objects_ that hold other objects. In Skytable, we have two kinds of containers: + +- **Keyspaces**: Keyspaces are containers that hold tables. The basic idea is to keep all the related tables for a given _application_ in one logical collection. +- **Tables**: Tables are **not tables**. Funny, isn't it? Instead, tables are structures that contain the actual data. Be it key/value or the future data models — it's all in a table + +To interact with containers, we need to use DDL actions like `CREATE`, `DROP` and `INSPECT`. + +## Entities + +Every container is an entity. A keyspace being a top-level entity and a table being a low-level +entity. Hence a keyspace name or a table name can be called an _entity_ or _entity name_. + +**Naming rules** + +All entity names have the following naming rules: + +- Names are case sensitive +- Names must begin with an ASCII alphabet (A-Z or a-z) or an underscore (`_`) +- Names must be lesser than or equal to 64 characters long +- Names must **not** begin with a digit (0-9) +- Names can contain digits anywhere else (except for the first character) + +**Entity groups** + +The most important thing is an _Entity Group_ which is also known as _Fully Qualified +Entity_ Syntax (FQE Syntax). FQE syntax is used to describe the full _path_ to a table. For example, +if you have a keyspace `supercyan` and you have a table `cyan` within it, then the FQE syntax will +be: + +``` +supercyan:cyan +``` + +This can be extremely helpful when running DDL queries. + +:::note Important note +When you connect to Skytable, you are connected to the `default` keyspace which has a `default` +table. The `default` table or the `default` keyspace **cannot be dropped**. +There is another keyspace called the `system` keyspace which is not user-accessible and hence +**cannot be modified or dropped**. +::: + +## Keyspaces + +Like we noted above, keyspaces are logical collections of tables and is known as a top level container. Creating a keyspace is as simple as: + +```sql +CREATE KEYSPACE +``` + +while you can drop keyspaces by running: + +```sql +DROP KEYSPACE +``` + +> **Note:** Keyspaces can only be dropped if no other client is connected to it and if it contains no tables. This can be evaded by forcing removal through other DDL actions. + +## Tables + +Tables contain your actual data: be it key/value, or anything else. Tables reside within keyspaces. To create a table, you'll need to run: + +```sql +CREATE TABLE (modelargs) +``` + +### Properties + +A table, apart from the data model's own properties, has some model-indpendent properties. Supplying these are optional. +The user-accessible property that you should know about is the `volatile` property. + +#### The volatile property + +Adding the `volatile` property after your model arguments makes your table volatile. This means that the table itself will exist, but none of its data will persist after a restart. This makes volatile tables extremely useful for caching. + +Don't worry too much about the _model_ and _modelargs_ now — the next section will tell you about models. + +### Table models + +Just jump to [the models section](#models) + +## Models + +A model defines what kind of data is stored in a table. You can think of it to be a _type_ in a +programming language. + +### The `keymap` model + +A keymap model is the one you just interacted with in the earlier documents. A keymap is like an +associated array: it maps a key to a value. More importantly, it maps a specific _key type_ to a specific _value type_. + +> **Warning:** Everything after `CREATE TABLE` is case sensitive! + +This is how you create keymap tables: + +```sql +CREATE TABLE keymap(,) +``` + +Here: + +- ``: is your table name (or the FQE syntax for your table) +- ``: is the [data type](#data-types) +- ``: are the optional properties [discussed earlier](#properties) + +#### Data types + +The keymap model supports the following types: + +- `str`: A valid unicode string +- `binstr`: A binary string +- `list`: A collection type similar to a _resizeable_ array + +(more types are expected to be shipped in future editions) + +#### Example + +1. Let's create a keymap table with an `str` type key and `binstr` type value. We'll assume you'll + be creating it in the default keyspace with the name "mytbl", so there's no need to specify an [FQE](#entities). + + ```sql + CREATE TABLE mytbl keymap(str,binstr) + ``` + +2. Let's create a keymap table with an `str` type key and a list of binary strings as the value type. + Again, we'll assume you're in the default keyspace, and we'll call this table `mylist`. + + ```sql + CREATE TABLE mylist keymap(str,list) + ``` + +### Models in the future + +With our goal to build a native multi-model database — we're working on several data models! All you need to do is hang around in our communities to know what is brewing! + +Check out the [DDL examples here](examples#ddl) diff --git a/versioned_docs/version-0.7.3/5.ddl.md b/versioned_docs/version-0.7.3/5.ddl.md new file mode 100644 index 000000000..f6a2c88ee --- /dev/null +++ b/versioned_docs/version-0.7.3/5.ddl.md @@ -0,0 +1,150 @@ +--- +id: ddl +title: DDL +--- + +DDL or _Data Definition Language_ is a way to interact with [containers](containers). Skytable lets you interact with containers with the following DDL actions: + +- [`CREATE`](#create) to create containers +- [`USE`](#use) to switch to containers and run actions in them +- [`INSPECT`](#inspect) to inspect containers +- [`DROP`](#drop) to delete containers + +## CREATE + +### Keyspaces + +- **Time complexity**: O(1) +- **Transactional**: Not yet +- **Syntax**: + ```sql + CREATE KEYSPACE + ``` +- **Returns**: + - Okay if the keyspace was created + - `err-already-exists` if it already existed + - server error if something unpredictable has happened on the server side + +### Tables + +- **Time complexity**: O(1) +- **Transactional**: Not yet +- **Syntax**: + ```sql + CREATE TABLE (modelargs) + ``` +- **Returns**: + - Okay if the table was created + - `err-already-exists` if it already existed + - `default-container-unset` if the connection level default keyspace has not been set + - server error if something unpredictable has happened on the server side +- Refer to the [model section](containers#models) to know what to pass for `` and `modelargs` +- Refer to the [table properties section](containers#properties) to know what to pass for `properties` +- Refer to the [entity section](containers#entities) to know what to pass for `entity`. It is + simply your `tablename` or `yourkeyspacename:yourtablename` + +## DROP + +### Keyspaces + +- **Time complexity**: O(1) +- **Transactional**: Not yet +- **Syntax**: + ```sql + DROP KEYSPACE + ``` +- **Returns**: + - Okay if the keyspace was deleted + - `container-not-found` if the keyspace wasn't found + - `still-in-use` if clients are still connected to the keyspace or the keyspace is not empty + - server error if something unpredictable has happened on the server side + +### Tables + +- **Time complexity**: O(1) +- **Transactional**: Not yet +- **Syntax**: + ```sql + DROP TABLE + ``` +- **Returns**: + + - Okay if the table was deleted + - `container-not-found` if the keyspace wasn't found + - `still-in-use` if clients are still connected to the table + - `default-container-unset` if the connection level default keyspace has not been set + - server error if something unpredictable has happened on the server side + +- Refer to the [entity section](containers#entities) to know what to pass for `entity`. It is + simply your `tablename` or `yourkeyspacename:yourtablename` + +## INSPECT + +### Entire database + +To inspect the entire database, run: + +```sql +INSPECT KEYSPACES +``` + +This will return a flat array with all the keyspace names + +### Keyspaces + +To inspect a keyspace, run: + +```sql +INSPECT KEYSPACE +``` + +This will return a flat array with all the table names + +### Tables + +To inspect a table, run: + +```sql +INSPECT TABLE +``` + +This will return a string with the table's _syntactical description_. For example, the keymap model +_can_ return: + +```js +Keymap { data: (binstr,binstr), volatile: true } +``` + +- Refer to the [entity section](containers#entities) to know what to pass for `entity`. It is + simply your `tablename` or `yourkeyspacename:yourtablename` + +## USE + +### Keyspaces + +- **Time complexity**: O(1) +- **Transactional**: Not applicable +- **Syntax**: + ```sql + USE + ``` +- **Returns**: + - Okay if the keyspace was switched + - `container-not-found` if the keyspace wasn't found + +### Tables + +- **Time complexity**: O(1) +- **Transactional**: Not applicable +- **Syntax**: + ```sql + USE + ``` +- **Returns**: + + - Okay if the table was switched + - `container-not-found` if the keyspace wasn't found + - `default-container-unset` if the connection level default keyspace has not been set + +- Refer to the [entity section](containers#entities) to know what to pass for `entity`. It is + simply your `tablename` or `yourkeyspacename:yourtablename` diff --git a/versioned_docs/version-0.7.3/5b.examples.md b/versioned_docs/version-0.7.3/5b.examples.md new file mode 100644 index 000000000..9bdddf823 --- /dev/null +++ b/versioned_docs/version-0.7.3/5b.examples.md @@ -0,0 +1,167 @@ +--- +id: examples +title: Examples +--- + +## DDL + +1. Create a keymap table called 'cats' in a keyspace 'animals'. The cat's name will be the key + which as an `str` value while the value would be the cat's image in a binary format, so it'll be + of the `binstr` type. + + a. Let's create the keyspace + + ```sql + CREATE KEYSPACE animals + ``` + + b. Let's create the table: + + ```sql + CREATE TABLE animals:cat keymap(str,binstr) + ``` + + c. Let's switch to the table: + + ```sql + USE animals:cat + ``` + + d. Let's inspect it: + + ```sql + INSPECT TABLE animals:cat + ``` + + e. Let's drop the table: + + ```sql + DROP TABLE animals:cat + ``` + + f. Let's drop the keyspace + + ```sql + DROP KEYSPACE animals + ``` + +2. Create a keymap table called 'favorites' in the 'default' keyspace. This will store a favorite + name, an `str` and an URL, also an `str`: + + ```sql + CREATE TABLE favorites keymap(str,str) + ``` + +3. Create a keymap table called 'cache' in the 'default' keyspace that is volatile. Our cache key is an `str` while the value would be some binary data, so `binstr`: + + ```sql + CREATE TABLE cache keymap(str,binstr) volatile + ``` + +## Lists + +1. Create a table called 'notes' in the default keyspace. We'll have usernames linked to a collection + of notes made by them. Since the names are unicode values, we'll use the `str` type for the key. + For the data type, we'll use the `list` type, with the inner type as `str` since the notes will also + have unicode characters (like emojis, for example). If we needed to store binary data within the + lists, we'd simply use the `binstr` data type instead. + + ```sql + CREATE TABLE notes keymap(str,list) + ``` + +2. Now let's switch to the table + + ```sql + use default:notes + ``` + +3. Let's add some notes made by our theoretical user `joe`. This is how it goes (`#` signs were simply + added for explanations, simply ignore them): + + ```sql + # create an empty list + LSET sayan + # now append some notes + LMOD sayan PUSH "Just woke up. Jotting down today's first note!" + LMOD sayan PUSH "Heading to the subway; gotta get to work fast!" + LMOD sayan PUSH "Funny that someone broke my chair! Just called someone to get it fixed!" + LMOD sayan PUSH "Brrr...on my work machine. See you later!" + LMOD sayan PUSH "Done with work, now heading home!" + LMOD sayan PUSH "Woot, I'm home. What a hectic day!" + ``` + +4. Let's read all the notes: + + ```sql + LGET sayan + ``` + + This would have printed out all the notes if we were using the command-line client, like this: + + ```sql + (1) "Just woke up. Jotting down today's first note!" + (2) "Heading to the subway; gotta get to work fast!" + (3) "Funny that someone broke my chair! Just called someone to get it fixed!" + (4) "Brrr...on my work machine. See you later!" + (5) "Done with work, now heading home!" + (6) "Woot, I'm home. What a hectic day!" + ``` + +5. Let's read a maximum of 5 notes: + + ```sql + LGET sayan LIMIT 5 + ``` + + This would output: + + ```sql + (1) "Just woke up. Jotting down today's first note!" + (2) "Heading to the subway; gotta get to work fast!" + (3) "Funny that someone broke my chair! Just called someone to get it fixed!" + (4) "Brrr...on my work machine. See you later!" + (5) "Done with work, now heading home!" + ``` + +6. Now let's remove the "broken chair" note because it turns out that I actually had the wrong chair! + + ```sql + LMOD sayan REMOVE 2 + ``` + + > Remember that array indexes start at 0? Duh! + + Let's see what we have with `LGET sayan`: + + ```sql + (1) "Just woke up. Jotting down today's first note!" + (2) "Heading to the subway; gotta get to work fast!" + (3) "Brrr...on my work machine. See you later!" + (4) "Done with work, now heading home!" + (5) "Woot, I'm home. What a hectic day!" + ``` + +7. Wait, I forgot about something! Someone left a mysterious letter on my desk. I discovered it as soon + as I entered my workplace. Let's insert that: + + ```sql + LMOD sayan INSERT 2 "Just discovered a mysterious letter on my desk! How cool!" + ``` + +8. Let's get our entire bunch of notes now: + + ```sql + LGET sayan + ``` + + This would output: + + ```sql + (1) "Just woke up. Jotting down today's first note!" + (2) "Heading to the subway; gotta get to work fast!" + (3) "Just discovered a mysterious letter on my desk! How cool!" + (4) "Brrr...on my work machine. See you later!" + (5) "Done with work, now heading home!" + (6) "Woot, I'm home. What a hectic day!" + ``` diff --git a/versioned_docs/version-0.7.3/6.all-actions.md b/versioned_docs/version-0.7.3/6.all-actions.md new file mode 100644 index 000000000..25601ec3f --- /dev/null +++ b/versioned_docs/version-0.7.3/6.all-actions.md @@ -0,0 +1,51 @@ +--- +id: all-actions +title: Index of actions +--- + +Skytable currently supports the actions listed in this document. You can find all the actions +classified by scope, model and type below. Do note that this list doesn't include DDL actions. +For DDL, see [this document](ddl). + +## Global Actions + +These actions can be used globally irrespective of the underlying keyspace or table properties: +- [DBSIZE](actions/DBSIZE.md) +- [FLUSHDB](actions/FLUSHDB.md) +- [HEYA](actions/HEYA.md) +- [MKSNAP](actions/MKSNAP.md) +- [WHEREAMI](actions/WHEREAMI.md) +## Key-value actions + +These actions can be used on Keymap model tables which is essentially an extensible key/value store. + +### Generic actions + +These actions can be used on all Keymap tables irrespective of the key/value type in the table +definition: +- [DEL](actions/DEL.md) +- [EXISTS](actions/EXISTS.md) +- [LSKEYS](actions/LSKEYS.md) +### String actions + +These actions can be used on keymap tables that have string types (such as `str` and `binstr`) in +both the key and value: +- [GET](actions/GET.md) +- [KEYLEN](actions/KEYLEN.md) +- [MGET](actions/MGET.md) +- [MPOP](actions/MPOP.md) +- [MSET](actions/MSET.md) +- [MUPDATE](actions/MUPDATE.md) +- [POP](actions/POP.md) +- [SDEL](actions/SDEL.md) +- [SET](actions/SET.md) +- [SSET](actions/SSET.md) +- [SUPDATE](actions/SUPDATE.md) +- [UPDATE](actions/UPDATE.md) +- [USET](actions/USET.md) +### List actions + +These actions can be used on keymap tables that have list types (`list`) as their value type: +- [LGET](actions/LGET.md) +- [LMOD](actions/LMOD.md) +- [LSET](actions/LSET.md) diff --git a/versioned_docs/version-0.7.3/7.cfg-files.md b/versioned_docs/version-0.7.3/7.cfg-files.md new file mode 100644 index 000000000..233d3970a --- /dev/null +++ b/versioned_docs/version-0.7.3/7.cfg-files.md @@ -0,0 +1,88 @@ +--- +id: config-files +title: Configuration Files +--- + +By using configuration files, you can customize the behavior of Skytable. + +## An example configuration + +A configuration file is a TOML file, which has the following basic structure: + +```toml +[server] +host = "127.0.0.1" +port = 2003 +noart = false +maxcon = 50000 +mode = "prod" + +[bgsave] +enabled = true +every = 120 + +[snapshot] +every = 3600 +atmost = 4 +failsafe = true + +[ssl] +key = "/path/to/keyfile.pem" +chain = "/path/to/chain.pem" +port = 2004 +only = true +``` + +Let's understand what each of the keys mean along with some other keys that can be used for more +advanced configuration: + +- **`server` (required)**: + - **`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 + - **`port`**: This is the port to which you want Sky to bind to + - **`noart` (optional)**: This is recommended for secure environments where displaying terminal artwork might cause problems + - **`maxcon` (optional)**: Set the maximum number of clients that can query concurrently + - **`mode` (optional)**: Should be set to `prod` for production deployments and `dev` during development +- **`bgsave` (optional)**: + - **`enabled` (optional)**: 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 + - **`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 +- **`snapshot` (optional)**: This key can be used to configure snapshots and is not enabled by default. + See [this](snapshots) for more information. +- **`ssl` (optional)**: This key can be used to configure SSL/TLS options. See [this](ssl) for more + information. + +## Using a configuration file + +To use a configuration file: + +1. Create it! We recommend you to name it as `skyd.toml`for easy identification +2. Start the database server with: `skyd -c /path/to/your/file.toml` +3. Done 🎉 + +If you're confused about creating a configuration file, we always recommend you to download the template configuration from [this link](https://raw.githubusercontent.com/skytable/skytable/v0.7.3/examples/config-files/template.toml). + +That's all that's there to using configuration files! + +:::tip Bonus tip +If you're using a custom host/port, then you can bind `skysh`to a custom host/port by starting `skysh`like: + +```shell +skysh -h [HOST] -p [PORT] +``` + +You can do the same for `sky-bench`: + +```shell +sky-bench -h [HOST] -p [PORT] +``` + +::: + +## Using a configuration file with Docker containers + +The official Docker image will look for a configuration file at `/etc/skytable/skyd.toml` within the container. To use a file on the host as the configuration file in the container, we'll make use of Docker volumes. Simply follow the [steps above](#using-a-configuration-file) and then start your docker image like this: + +```sh +docker run --name skyd \ + -v /path/to/your/file.toml:/etc/skytable/skyd.toml \ + skytable/sdb:v0.7.3 +``` diff --git a/versioned_docs/version-0.7.3/7.cfg.md b/versioned_docs/version-0.7.3/7.cfg.md new file mode 100644 index 000000000..6cc00d966 --- /dev/null +++ b/versioned_docs/version-0.7.3/7.cfg.md @@ -0,0 +1,32 @@ +--- +id: config +title: Configuration basics +--- + +Skytable can be configured to a great degree, depending on your requirements. You can configure Skytable using: +* [Configuration files](config-files): A simple TOML file to tune your settings +* [Command-line arguments](config-cmd): Use command-line parameters to configure the database +* [Environment variables](config-env): Use environment variables for configuration + +## Deployment mode + +Skytable uses the idea of a `dev` and `prod` mode to make configuration during deployment easier. The `dev`/`prod` +mode setting can be changed by using your preferred mode of configuration, as listed above. + +### `dev` mode + +The `dev` mode allows you to use any configuration without any hard checks. This is suitable for use +during development + +### `prod` mode + +In this mode, you are required to use the settings that we recommend for production usage. This includes +strict requirements on BGSAVE, TLS and snapshot settings. Here's what's required for production: + +| Setting | Requirement | +| ------------------- | ---------------------------------------------------------------------------------- | +| Maximum connections | Must be lesser than or equal to the resource limits set for that process (on Unix) | +| Terminal artwork | Disabled | +| BGSAVE | Enabled | +| Snapshot failsafe | Set to `true | +| TLS | Atleast insecure TCP+TLS multi-socket mode or TLS-only mode must be enabled | diff --git a/versioned_docs/version-0.7.3/7a.env-config.md b/versioned_docs/version-0.7.3/7a.env-config.md new file mode 100644 index 000000000..1dbb558c4 --- /dev/null +++ b/versioned_docs/version-0.7.3/7a.env-config.md @@ -0,0 +1,44 @@ +--- +title: Environment Variables +id: config-env +--- + +If you don't want to use configuration files or use command-line arguments, you can choose to use +environment variables for configuration. The environment variables are divided into sections +for convenience, per the [configuration file](config-files). + +## System + +| Variable | Setting | Expected value | +| ------------------- | ---------------------------- | ------------------------------------------------------------- | +| SKY_SYSTEM_HOST | Sets the host | A valid IPv4/IPv6 address | +| SKY_SYSTEM_PORT | Sets the port | 16-bit positive integer | +| SKY_SYSTEM_NOART | Disables terminal artwork | `true`/`false` | +| SKY_SYSTEM_MAXCON | Sets the maximum connections | 64/32 bit positive integer, depending on system | +| SKY_DEPLOYMENT_MODE | Sets the deployment mode | Should be set to `dev` or `prod` depending on deployment mode | + +## BGSAVE + +| Variable | Setting | Expected value | +| ------------------- | ------------------------ | -------------------------------- | +| SKY_BGSAVE_ENABLED | Enables/disables BGSAVE | `true`/`false` | +| SKY_BGSAVE_DURATION | Sets the BGSAVE interval | Non-zero 64-bit positive integer | + +## Snapshots + +| Variable | Setting | Expected value | +| --------------------- | ----------------------------------------------------- | ----------------------------------------------------- | +| SKY_SNAPSHOT_ENABLED | Enables/disables snapshots | `true`/`false` | +| SKY_SNAPSHOT_DURATION | Sets the snapshot interval | Non-zero 64-bit positive integer | +| SKY_SNAPSHOT_KEEP | Sets the maximum number of snapshots to keep | `0` for keeping all or any positive 32/64 bit integer | +| SKY_SNAPSHOT_FAILSAFE | Sets if writes should be disabled on snapshot failure | `true`/`false` | + +## TLS + +| Variable | Setting | Expected value | +| -------------- | ------------------------------------------------- | ----------------------- | +| SKY_TLS_PORT | Sets the TLS port | 16-bit positive integer | +| SKY_TLS_ONLY | Enables/disables TLS only mode | `true`/`false` | +| SKY_TLS_CERT | Sets the location of the TLS cert | String | +| SKY_TLS_KEY | Sets the location of the TLS private key | String | +| SKY_TLS_PASSIN | Sets the location of the TLS private key password | String | diff --git a/versioned_docs/version-0.7.3/8.config-cmdline.md b/versioned_docs/version-0.7.3/8.config-cmdline.md new file mode 100644 index 000000000..a66b0ee99 --- /dev/null +++ b/versioned_docs/version-0.7.3/8.config-cmdline.md @@ -0,0 +1,23 @@ +--- +id: config-cmd +title: Command-line configuration +--- + +You can use command line arguments alone for configuration in place of configuration files. Every binary ( `skyd` , `skysh` and `sky-bench` ) that you get with a bundle have extremely helpful help menus. Whatever you can configure with the configuration file can be configured through command line +arguments. + +- `skyd --help` : Brings up the help menu for `skyd` +- `skysh --help` : Brings up the help menu for `skysh` +- `sky-bench --help` : Brings up the help menu for `sky-bench` + +:::tip +There is no specific _advantage_ in using command-line arguments over configuration files or +vice versa. When any kind of configuration is specified: either a configuration file or command +line arguments, it is parsed once at startup and then the same configuration is used throughout. +It is really a matter of choice (or convenience). +::: + +:::caution +You must specify either a configuration file **or** command-line arguments. If you provide both — +the database will shut down with an error that asks you to provide either one mode of configuration +::: diff --git a/versioned_docs/version-0.7.3/9.persistence.md b/versioned_docs/version-0.7.3/9.persistence.md new file mode 100644 index 000000000..1ba4abce2 --- /dev/null +++ b/versioned_docs/version-0.7.3/9.persistence.md @@ -0,0 +1,54 @@ +--- +id: persistence +title: Persistence +--- + +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. + +## How Skytable stores data + +As soon as you start Skytable, it will look for a `PRELOAD` file in the data directory. If it +isn't found — the server would expect this to be a new instance and will create the +required files for you. Skytable uses a disk storage format called **Cyanstore** (version `1A`) +for storing your data and all files are encoded/decoded in compliance with this format. + +Once you terminate the daemon, it will flush all data to disk. All writes are `fsync`ed by the time +they complete. + +### Save failure during termination + +The server would attempt to do a _final_ save operation before it terminates and if this fails, the +server would enter into a retry loop. It will try the save operation after every 10 seconds. +Exponential backoff was not chosen because it could increase to extremely large values that may hurt +a sysadmin's time and productivity. + +You might be interested in more features like [BGSAVE](#automated-background-saving) and [snapshots](/snapshots) that +can be configured and used by users. + +## Automated background saving + +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](config). BGSAVE is enabled by default and we don't recommend disabling it until you're sure that +your hardware will never fail; it is likely that this will never be the case. First BGSAVE will create a temporary +file and then flush the current in-memory table onto disk. The daemon automatically `fsync`s after every successful write (whether to the buffers or +to the actual disk). + +### Reliability of BGSAVE + +It can happen that BGSAVE fails to flush data to the disk due to some unforeseen system issues (such as lack of +empty disk space, permission errors, etc). But if we continue to accept modifications to the data, it is a bad idea +because this data may never get updated! This is why if BGSAVE fails, it will automatically _poison_ the in-memory +table preventing it from accepting any write/update operations. Poisioning is nothing but a global flag set in the +database that indicates that the DB shouldn't accept any more updates/writes to data and in such a poisoned state, +only reads are permitted. + +### BGSAVE Recovery + +BGSAVE will automatically try to recover on every 120s (or whatever duration was set). If the problem +was corrected (say it was a permissions issue), then the database server will automatically resume +writes and _unpoison_ the database. + +:::warning +Avoid editing/changing/removing files from the data directory by hand. All files stored in the data +directory are critical to the server and your data. If you end up corrupting any file due to a bad +edit — you might end up losing access to your data! +::: diff --git a/versioned_docs/version-0.7.3/actions/DBSIZE.md b/versioned_docs/version-0.7.3/actions/DBSIZE.md new file mode 100644 index 000000000..9adddd6f3 --- /dev/null +++ b/versioned_docs/version-0.7.3/actions/DBSIZE.md @@ -0,0 +1,24 @@ +--- +id: dbsize +title: DBSIZE +--- + + +:::note About +**Time complexity**: O(1) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [Integer](../protocol/skyhash.md#unsigned-integers-) + +**Syntax**: + +- `DBSIZE` +- `DBSIZE ` + +::: + +Check the number of entries stored in the current table or in the provided entity diff --git a/versioned_docs/version-0.7.3/actions/DEL.md b/versioned_docs/version-0.7.3/actions/DEL.md new file mode 100644 index 000000000..f2013031b --- /dev/null +++ b/versioned_docs/version-0.7.3/actions/DEL.md @@ -0,0 +1,26 @@ +--- +id: del +title: DEL +--- + + +:::note About +**Time complexity**: O(n) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [Integer](../protocol/skyhash.md#unsigned-integers-) +- [Rcode 5](../protocol/response-codes.md) + +**Syntax**: + +- `DEL ...` + +::: + +Delete 'n' keys from the current table. This will return the number of keys that were deleted +as an unsigned integer + diff --git a/versioned_docs/version-0.7.3/actions/EXISTS.md b/versioned_docs/version-0.7.3/actions/EXISTS.md new file mode 100644 index 000000000..d3d31aec9 --- /dev/null +++ b/versioned_docs/version-0.7.3/actions/EXISTS.md @@ -0,0 +1,25 @@ +--- +id: exists +title: EXISTS +--- + + +:::note About +**Time complexity**: O(n) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [Integer](../protocol/skyhash.md#unsigned-integers-) + +**Syntax**: + +- `EXISTS ...` + +::: + +Check if 'n' keys exist in the current table. This will return the number of keys that exist +as an unsigned integer. + diff --git a/versioned_docs/version-0.7.3/actions/FLUSHDB.md b/versioned_docs/version-0.7.3/actions/FLUSHDB.md new file mode 100644 index 000000000..54eeea742 --- /dev/null +++ b/versioned_docs/version-0.7.3/actions/FLUSHDB.md @@ -0,0 +1,25 @@ +--- +id: flushdb +title: FLUSHDB +--- + + +:::note About +**Time complexity**: O(n) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [Rcode 0](../protocol/response-codes.md) +- [Rcode 5](../protocol/response-codes.md) + +**Syntax**: + +- `FLUSHDB` +- `FLUSHDB ` + +::: + +Removes all entries stored in the current table or in the provided entity diff --git a/versioned_docs/version-0.7.3/actions/GET.md b/versioned_docs/version-0.7.3/actions/GET.md new file mode 100644 index 000000000..cd0cd8cec --- /dev/null +++ b/versioned_docs/version-0.7.3/actions/GET.md @@ -0,0 +1,25 @@ +--- +id: get +title: GET +--- + + +:::note About +**Time complexity**: O(1) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [Rcode 1](../protocol/response-codes.md) +- [String](../protocol/skyhash.md#strings-) +- [Binstr](../protocol/skyhash.md#strings-) + +**Syntax**: + +- `GET ` + +::: + +Get the value of a key from the current table, if it exists diff --git a/versioned_docs/version-0.7.3/actions/HEYA.md b/versioned_docs/version-0.7.3/actions/HEYA.md new file mode 100644 index 000000000..ae42d367c --- /dev/null +++ b/versioned_docs/version-0.7.3/actions/HEYA.md @@ -0,0 +1,25 @@ +--- +id: heya +title: HEYA +--- + + +:::note About +**Time complexity**: O(1) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [String](../protocol/skyhash.md#strings-) + +**Syntax**: + +- `HEYA` +- `HEYA ` + +::: + +Either returns a "HEY!" or returns the provided argument as an `str` + diff --git a/versioned_docs/version-0.7.3/actions/KEYLEN.md b/versioned_docs/version-0.7.3/actions/KEYLEN.md new file mode 100644 index 000000000..e1db59f15 --- /dev/null +++ b/versioned_docs/version-0.7.3/actions/KEYLEN.md @@ -0,0 +1,24 @@ +--- +id: keylen +title: KEYLEN +--- + + +:::note About +**Time complexity**: O(1) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [Integer](../protocol/skyhash.md#unsigned-integers-) +- [Rcode 1](../protocol/response-codes.md) + +**Syntax**: + +- `KEYLEN ` + +::: + +Returns the length of the UTF-8 string, if it exists in the current table diff --git a/versioned_docs/version-0.7.3/actions/LGET.md b/versioned_docs/version-0.7.3/actions/LGET.md new file mode 100644 index 000000000..d7f2ce165 --- /dev/null +++ b/versioned_docs/version-0.7.3/actions/LGET.md @@ -0,0 +1,158 @@ +--- +id: lget +title: LGET +--- +`LGET` can be used to access the items in a list. Through the sub-actions provided by `lget`, + you can access multiple or individual elements in lists. +### `LGET` +:::note About +**Time complexity**: O(n) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [Typed Array](../protocol/data-types.md#typed-array) +- [Rcode 1](../protocol/response-codes.md) + +**Syntax**: + +- `LGET ` + +::: + +Returns all the values contained in a the provided list, if it exists in the current +table. + + +### `limit` +:::note About +**Time complexity**: O(n) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [Typed Array](../protocol/data-types.md#typed-array) +- [Rcode 1](../protocol/response-codes.md) + +**Syntax**: + +- `LGET limit ` + +::: + +Returns a maximum of `limit` values from the provided list, if it exists in the current table + +### `len` +:::note About +**Time complexity**: O(1) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [Integer](../protocol/skyhash.md#unsigned-integers-) +- [Rcode 1](../protocol/response-codes.md) + +**Syntax**: + +- `LGET len` + +::: + +Returns the length of the list + +### `valueat` +:::note About +**Time complexity**: O(1) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [String](../protocol/skyhash.md#strings-) +- [binstr](../protocol/skyhash.md#strings-) +- [Rcode 1](../protocol/response-codes.md) +- [bad-list-index](../protocol/errors.md#table-of-errors) + +**Syntax**: + +- `LGET valueat ` + +::: + +Returns the element present at the provided `index`, if it exists in the given list. + +### `first` +:::note About +**Time complexity**: O(1) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [String](../protocol/skyhash.md#strings-) +- [binstr](../protocol/skyhash.md#strings-) +- [Rcode 1](../protocol/response-codes.md) +- [list-is-empty](../protocol/errors.md#table-of-errors) + +**Syntax**: + +- `LGET first` + +::: + +Returns the first element present in the list, if it exists. + +### `last` +:::note About +**Time complexity**: O(1) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [String](../protocol/skyhash.md#strings-) +- [binstr](../protocol/skyhash.md#strings-) +- [Rcode 1](../protocol/response-codes.md) +- [list-is-empty](../protocol/errors.md#table-of-errors) + +**Syntax**: + +- `LGET last` + +::: + +Returns the last element present in the list, if it exists. + +### `range` +:::note About +**Time complexity**: O(n) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [Typed Array](../protocol/data-types.md#typed-array) +- [Rcode 1](../protocol/response-codes.md) +- [bad-list-index](../protocol/errors.md#table-of-errors) + +**Syntax**: + +- `LGET range ` +- `LGET range ` + +::: + +Returns items in the given range. If no value for `stop` is provided, all the elements from that +index are returned. If a value for `stop` is provided, then a subarray is returned + + diff --git a/versioned_docs/version-0.7.3/actions/LMOD.md b/versioned_docs/version-0.7.3/actions/LMOD.md new file mode 100644 index 000000000..ee42c82ea --- /dev/null +++ b/versioned_docs/version-0.7.3/actions/LMOD.md @@ -0,0 +1,123 @@ +--- +id: lmod +title: LMOD +--- +`LMOD` can be used to mutate the elements in a list +### `push` +:::note About +**Time complexity**: O(1) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [Rcode 0](../protocol/response-codes.md) +- [Rcode 1](../protocol/response-codes.md) +- [Rcode 5](../protocol/response-codes.md) + +**Syntax**: + +- `LMOD push ` + +::: + +Appends the element to the end of the provided list + +### `insert` +:::note About +**Time complexity**: O(1) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [Rcode 0](../protocol/response-codes.md) +- [Rcode 1](../protocol/response-codes.md) +- [Rcode 5](../protocol/response-codes.md) +- [bad-list-index](../protocol/errors.md#table-of-errors) + +**Syntax**: + +- `LMOD insert ` + +::: + +Inserts the element to the provided index, if it is valid while shifting elements +to the right if required + + +### `pop` +:::note About +**Time complexity**: O(1) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [String](../protocol/skyhash.md#strings-) +- [Binstr](../protocol/skyhash.md#strings-) +- [Rcode 0](../protocol/response-codes.md) +- [Rcode 1](../protocol/response-codes.md) +- [Rcode 5](../protocol/response-codes.md) +- [bad-list-index](../protocol/errors.md#table-of-errors) + +**Syntax**: + +- `LMOD pop` +- `LMOD pop ` + +::: + +Removes the element from the end of the list if no index is provided or from the provided +index while shifting elements to the right if required. + + +### `remove` +:::note About +**Time complexity**: O(1) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [Rcode 0](../protocol/response-codes.md) +- [Rcode 1](../protocol/response-codes.md) +- [Rcode 5](../protocol/response-codes.md) +- [bad-list-index](../protocol/errors.md#table-of-errors) + +**Syntax**: + +- `LMOD remove ` + +::: + +Removes the element at the provided index from the list, shifting elements to the right +if required. + + +### `clear` +:::note About +**Time complexity**: O(n) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [Rcode 0](../protocol/response-codes.md) +- [Rcode 1](../protocol/response-codes.md) +- [Rcode 5](../protocol/response-codes.md) + +**Syntax**: + +- `LMOD clear` + +::: + +Removes all the elements present in the list + + diff --git a/versioned_docs/version-0.7.3/actions/LSET.md b/versioned_docs/version-0.7.3/actions/LSET.md new file mode 100644 index 000000000..9bcda1177 --- /dev/null +++ b/versioned_docs/version-0.7.3/actions/LSET.md @@ -0,0 +1,29 @@ +--- +id: lset +title: LSET +--- +`LSET` can be used to create empty lists or lists with the provided values. +### `LSET` +:::note About +**Time complexity**: O(n) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [Rcode 0](../protocol/response-codes.md) +- [Rcode 1](../protocol/response-codes.md) +- [Rcode 5](../protocol/response-codes.md) + +**Syntax**: + +- `LSET ` +- `LSET ...` + +::: + +Creates a list with the provided values, or simply creates an empty list if it doesn't +already exist in the table. + + diff --git a/versioned_docs/version-0.7.3/actions/LSKEYS.md b/versioned_docs/version-0.7.3/actions/LSKEYS.md new file mode 100644 index 000000000..3a8f3d7e5 --- /dev/null +++ b/versioned_docs/version-0.7.3/actions/LSKEYS.md @@ -0,0 +1,28 @@ +--- +id: lskeys +title: LSKEYS +--- + + +:::note About +**Time complexity**: O(n) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [Typed Array](../protocol/data-types.md#typed-array) + +**Syntax**: + +- `LSKEYS ` +- `LSKEYS ` +- `LSKEYS ` + +::: + +Returns a flat string array of keys present in the current table or in the provided entity. +If no `` is given, then a maximum of 10 keys are returned. If a limit is specified, +then a maximum of `` keys are returned. The order of keys is meaningless. + diff --git a/versioned_docs/version-0.7.3/actions/MGET.md b/versioned_docs/version-0.7.3/actions/MGET.md new file mode 100644 index 000000000..f4f3e077b --- /dev/null +++ b/versioned_docs/version-0.7.3/actions/MGET.md @@ -0,0 +1,23 @@ +--- +id: mget +title: MGET +--- + + +:::note About +**Time complexity**: O(n) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [Typed Array](../protocol/data-types.md#typed-array) + +**Syntax**: + +- `MGET ...` + +::: + +Get the value of 'n' keys from the current table, if they exist diff --git a/versioned_docs/version-0.7.3/actions/MKSNAP.md b/versioned_docs/version-0.7.3/actions/MKSNAP.md new file mode 100644 index 000000000..a6e8c8de3 --- /dev/null +++ b/versioned_docs/version-0.7.3/actions/MKSNAP.md @@ -0,0 +1,32 @@ +--- +id: mksnap +title: MKSNAP +--- + + +:::note About +**Time complexity**: O(n) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [Rcode 0](../protocol/response-codes.md) +- [err-snapshot-disabled](../protocol/errors.md#table-of-errors) +- [err-snapshot-busy](../protocol/errors.md#table-of-errors) + +**Syntax**: + +- `MKSNAP` +- `MKSNAP ` + +::: + +This action can be used to create a snapshot. Do note that this action **requires +snapshotting to be enabled on the server side**, before it can create snapshots. +If you want to create snapshots **without** snapshots being enabled on the server-side, +pass a second argument `` to specify a snapshot name and a snapshot will +be create in a folder called `rsnap` under your data directory. For more +information on snapshots, read [this document](/snapshots) + diff --git a/versioned_docs/version-0.7.3/actions/MPOP.md b/versioned_docs/version-0.7.3/actions/MPOP.md new file mode 100644 index 000000000..d818b0e81 --- /dev/null +++ b/versioned_docs/version-0.7.3/actions/MPOP.md @@ -0,0 +1,26 @@ +--- +id: mpop +title: MPOP +--- + + +:::note About +**Time complexity**: O(n) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [Typed Array](../protocol/data-types.md#typed-array) +- [Rcode 5](../protocol/response-codes.md) + +**Syntax**: + +- `MPOP ...` + +::: + +Deletes and returns the values of the provided 'n' keys from the current table. +If the database is poisoned, this will return a server error + diff --git a/versioned_docs/version-0.7.3/actions/MSET.md b/versioned_docs/version-0.7.3/actions/MSET.md new file mode 100644 index 000000000..fea1043b7 --- /dev/null +++ b/versioned_docs/version-0.7.3/actions/MSET.md @@ -0,0 +1,26 @@ +--- +id: mset +title: MSET +--- + + +:::note About +**Time complexity**: O(n) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [Integer](../protocol/skyhash.md#unsigned-integers-) +- [Rcode 5](../protocol/response-codes.md) + +**Syntax**: + +- `MSET ...` + +::: + +Set the value of 'n' keys in the current table, if they don't already exist. This will +return the number of keys that were set as an unsigned integer. + diff --git a/versioned_docs/version-0.7.3/actions/MUPDATE.md b/versioned_docs/version-0.7.3/actions/MUPDATE.md new file mode 100644 index 000000000..6529fd23e --- /dev/null +++ b/versioned_docs/version-0.7.3/actions/MUPDATE.md @@ -0,0 +1,26 @@ +--- +id: mupdate +title: MUPDATE +--- + + +:::note About +**Time complexity**: O(n) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [Integer](../protocol/skyhash.md#unsigned-integers-) +- [Rcode 5](../protocol/response-codes.md) + +**Syntax**: + +- `MUPDATE ...` + +::: + +Update the value of 'n' keys in the current table, if they already exist. This will return +the number of keys that were updated as an unsigned integer. + diff --git a/versioned_docs/version-0.7.3/actions/POP.md b/versioned_docs/version-0.7.3/actions/POP.md new file mode 100644 index 000000000..f0d135bf9 --- /dev/null +++ b/versioned_docs/version-0.7.3/actions/POP.md @@ -0,0 +1,27 @@ +--- +id: pop +title: POP +--- + + +:::note About +**Time complexity**: O(1) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [String](../protocol/skyhash.md#strings-) +- [Binstr](../protocol/skyhash.md#strings-) +- [Rcode 5](../protocol/response-codes.md) + +**Syntax**: + +- `POP ` + +::: + +Deletes and return the value of the provided key from the current table. +If the database is poisoned, this will return a server error. + diff --git a/versioned_docs/version-0.7.3/actions/SDEL.md b/versioned_docs/version-0.7.3/actions/SDEL.md new file mode 100644 index 000000000..3de71fa4e --- /dev/null +++ b/versioned_docs/version-0.7.3/actions/SDEL.md @@ -0,0 +1,27 @@ +--- +id: sdel +title: SDEL +--- + + +:::note About +**Time complexity**: O(n) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [Rcode 0](../protocol/response-codes.md) +- [Rcode 1](../protocol/response-codes.md) +- [Rcode 5](../protocol/response-codes.md) + +**Syntax**: + +- `SDEL ...` + +::: + +Delete all keys if all of the keys exist in the current table. Do note that if a single key doesn't +exist, then a `Nil` code is returned. + diff --git a/versioned_docs/version-0.7.3/actions/SET.md b/versioned_docs/version-0.7.3/actions/SET.md new file mode 100644 index 000000000..a60ddd08e --- /dev/null +++ b/versioned_docs/version-0.7.3/actions/SET.md @@ -0,0 +1,25 @@ +--- +id: set +title: SET +--- + + +:::note About +**Time complexity**: O(1) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [Rcode 0](../protocol/response-codes.md) +- [Rcode 2](../protocol/response-codes.md) +- [Rcode 5](../protocol/response-codes.md) + +**Syntax**: + +- `SET ` + +::: + +Set the value of a key in the current table, if it doesn't already exist diff --git a/versioned_docs/version-0.7.3/actions/SSET.md b/versioned_docs/version-0.7.3/actions/SSET.md new file mode 100644 index 000000000..ce2a656df --- /dev/null +++ b/versioned_docs/version-0.7.3/actions/SSET.md @@ -0,0 +1,25 @@ +--- +id: sset +title: SSET +--- + + +:::note About +**Time complexity**: O(n) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [Rcode 0](../protocol/response-codes.md) +- [Rcode 2](../protocol/response-codes.md) +- [Rcode 5](../protocol/response-codes.md) + +**Syntax**: + +- `SSET ...` + +::: + +Set all keys to the given values only if all of them don't exist in the current table diff --git a/versioned_docs/version-0.7.3/actions/SUPDATE.md b/versioned_docs/version-0.7.3/actions/SUPDATE.md new file mode 100644 index 000000000..e86414caf --- /dev/null +++ b/versioned_docs/version-0.7.3/actions/SUPDATE.md @@ -0,0 +1,27 @@ +--- +id: supdate +title: SUPDATE +--- + + +:::note About +**Time complexity**: O(n) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [Rcode 0](../protocol/response-codes.md) +- [Rcode 1](../protocol/response-codes.md) +- [Rcode 5](../protocol/response-codes.md) + +**Syntax**: + +- `SUPDATE ...` + +::: + +Update all keys if all of the keys exist in the current table. Do note that if a single key doesn't +exist, then a `Nil` code is returned. + diff --git a/versioned_docs/version-0.7.3/actions/UPDATE.md b/versioned_docs/version-0.7.3/actions/UPDATE.md new file mode 100644 index 000000000..912c4a382 --- /dev/null +++ b/versioned_docs/version-0.7.3/actions/UPDATE.md @@ -0,0 +1,25 @@ +--- +id: update +title: UPDATE +--- + + +:::note About +**Time complexity**: O(1) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [Rcode 0](../protocol/response-codes.md) +- [Rcode 1](../protocol/response-codes.md) +- [Rcode 5](../protocol/response-codes.md) + +**Syntax**: + +- `UPDATE ` + +::: + +Update the value of an existing key in the current table diff --git a/versioned_docs/version-0.7.3/actions/USET.md b/versioned_docs/version-0.7.3/actions/USET.md new file mode 100644 index 000000000..4a0406381 --- /dev/null +++ b/versioned_docs/version-0.7.3/actions/USET.md @@ -0,0 +1,24 @@ +--- +id: uset +title: USET +--- + + +:::note About +**Time complexity**: O(n) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [Integer](../protocol/skyhash.md#unsigned-integers-) +- [Rcode 5](../protocol/response-codes.md) + +**Syntax**: + +- `USET ...` + +::: + +SET all keys if they don't exist, or UPDATE them if they do exist. This operation performs `USET`s in the current table diff --git a/versioned_docs/version-0.7.3/actions/WHEREAMI.md b/versioned_docs/version-0.7.3/actions/WHEREAMI.md new file mode 100644 index 000000000..9ffe58495 --- /dev/null +++ b/versioned_docs/version-0.7.3/actions/WHEREAMI.md @@ -0,0 +1,25 @@ +--- +id: whereami +title: WHEREAMI +--- + + +:::note About +**Time complexity**: O(1) +**Accept type**: + +- [AnyArray](../protocol/data-types.md#any-array) + +**Return type**: + +- [Non-null array](../protocol/data-types.md#typed-non-null-array) + +**Syntax**: + +- `WHEREAMI` + +::: + +Returns an array with either the name of the current keyspace as the first element or if a default table +is set, then it returns the keyspace name as the first element and the table name as the second element + diff --git a/versioned_docs/version-0.7.3/protocol/data-types.md b/versioned_docs/version-0.7.3/protocol/data-types.md new file mode 100644 index 000000000..594c867f4 --- /dev/null +++ b/versioned_docs/version-0.7.3/protocol/data-types.md @@ -0,0 +1,197 @@ +--- +id: data-types +title: Data Types +--- + +This table lists all data types supported by Skytable and their corresponding +type symbols ( `tsymbol` s) and additional information. + +## Simple types + +Simple types only contain one type. This makes them very simple to serialize/deserialize. All simple types have the +following layout: + +``` +\n + +``` + +### Example + +For an unicode string 'sayan', the layout of the unicode string type (`+`) will look like: + +```sh ++5\n # 'sayan' is an unicode string, so '+' and has 5 bytes so '5' +sayan\n # the element 'sayan' itself +``` + +### Table + +| Type symbol (tsymbol) | Type | Additional notes | +| --------------------- | --------------- | -------------------------------------------------------- | +| `+` | String | a string | +| `!` | Response Code | a response code | +| `$` (reserved) | JSON | a `JSON` value | +| `.` (reserved) | smallint | An integer in the range: [0, 255] | +| `-` (reserved) | smallint signed | An integer in the range: [-128, 127] | +| `:` | int | An integer in the range: [0, 4,294,967,295] | +| `;` (reserved) | int signed | An integer in the range: [-2,147,483,647, 2,147,483,647] | +| `%` (reserved) | float | A 32-bit floating point value | +| `?` | binary string | the next line contains binary data (often called a blob) | + +Do keep the matching for this symbol _non-exhaustive_ since we might add more types in future revisions of the protocol. + +## Compound types + +Compound types are derived types -- they are based on simple types, but often with +some additional properties (and serialization/deserialization differences). + +### Table + +| Type symbol (tsymbol) | Type | Additional notes | Protocol | +| --------------------- | -------------------- | ------------------------------------------------------------- | -------- | +| & | Array | A recursive array | 1.0 | +| \_ | Flat array | A non-recursive array | 1.0 | +| @ | Typed array | An array of a specific type, with nullable elements | 1.1 | +| ~ | Any array | An array with a single type but no information about the type | 1.1 | +| ^ | Typed non-null array | A non-recursive array with non-null elements | 1.1 | + +### Array + +See the full discussion on arrays [here](skyhash#arrays-). + +### Flat array + +A flat array is like an array, but with the exception that it is non-recursive. This +means that a flat array can contain all types except other compound types (hence the +name 'flat'). + +So if you represent an array in a programming language like: + +```js +["hello", 12345, "world"]; +``` + +then it will be serialized by Skyhash into: + +``` +_3\n # 3 elements ++5\n # 'hello' is an unicode string, so '+' and has 5 bytes +hello\n # the element 'hello' itself +:5\n # 12345 has 5 bytes and is an unsigned int +12345\n # the element 12345 itself ++5\n # 'world' is an unicode string, so '+' and has 5 bytes +``` + +:::note +A flat array is currently a response specific data type (only sent by the server and never by the client) +::: + +### Typed array + +A typed array is like a flat array, but with the exception that it can only hold +two types: either a [simple type](#simple-types) or a `NULL`. Since this array just has a specific type in its declaration, unlike flat arrays, `tsymbol`s are not required. + +You can think of it to be like: + +- there is either no element (integer value of `0`; also called `NULL`) +- or there is an element of the declared type + +Say a programming language represents an array like: + +```cpp +["omg", NULL, "happened"] +``` + +then it will be serialized by Skyhash into: + +``` +@+3\n +3\n +omg\n +\0\n +8\n +happened\n +``` + +Line-by-line explanation: + +- `@+3\n` because it is a typed array, so `@`, the elements are unicode strings, so `+` + and there are three elements, so `3` +- `3\n` because 'omg' has 3 bytes +- `omg\n`, the element itself +- `\0\n`, `NULL` because there was no element + > Here `\0` corresponds to the [null terminator](https://en.wikipedia.org/wiki/Null_character) (integer value of `0`) +- `8\n` because 'happened' has 8 bytes +- `happened\n`, the element itself + +:::note +A typed array is currently a response specific data type (only sent by the server and never by the client). The `NULL`s correspond to the cases when the server can't find the requested item. +::: + +### Any array + +An `AnyArray` is like a typed array — but without any explicit information about the type that is sent. Currently, +**all the element types have to be the same**, but however, no information about the type has to be sent. It is upto +the server to convert them to the correct types. This makes running actions extremely simple as the clients don't have +to specify the type. The server will convert it into the appropriate type for that action. No matter how flexible this +may sound -- `AnyArray`s are extremely performant. Also, **no element in an `AnyArray` can be null**. + +If you have a programming language that represents a **singly-typed** array like: + +```rust +["sayan", "is", "hiking"] +``` + +then Skyhash will serialize it into: + +``` +~3\n +5\n +sayan\n +2\n +is\n +6\n +hiking\n +``` + +Line-by-line explanation: + +1. `~3\n` because this is an `AnyArray` with 3 elements +2. `5\n` because 'sayan' has 5 bytes +3. `sayan\n`, the element 'sayan' itself +4. `2\n` because 'is' has 2 bytes +5. `is\n` the element 'is' itself +6. `6\n` because 'hiking' has 6 bytes +7. `hiking\n` the element 'hiking' itself + +:::note +An `AnyArray` is currently a query specific data type (only sent by the client and never by the server) +::: + +### Typed non-null array + +A typed non-null array is just like a typed array, except for one thing — its elements can never be null. Say you +have an array of three strings like this: + +```js +["super", "wind"] +``` + +Then it will be represented like this: + +```shell +^+2\n +5\n +super\n +4\n +wind +``` + +Line-by-line explanation: + +1. `^+2\n` because this a typed non-null array, with two string elements +2. `5\n` because the first element is "super" and has 5 chars +3. `super\n` the element itself +4. `4\n` the second element is "wind" and has 4 chars +5. `wind\n` the element itself diff --git a/versioned_docs/version-0.7.3/protocol/errors.md b/versioned_docs/version-0.7.3/protocol/errors.md new file mode 100644 index 000000000..39495b742 --- /dev/null +++ b/versioned_docs/version-0.7.3/protocol/errors.md @@ -0,0 +1,34 @@ +--- +id: errors +title: Error Strings +hide_table_of_contents: true +--- + +In certain situations, the server may return error strings (also known as other errors), instead of the standard response codes. This table is an index of such error strings. + +## Table of errors + +| Error String | Meaning | +| -------------------------- | ------------------------------------------------------------ | +| Unknown action | The [action](../actions-overview) is not known by the server | +| err-snapshot-busy | A snapshot operation is already in progress | +| err-snapshot-disabled | Snapshots have been disabled on the server-side | +| err-invalid-snapshot-name | The supplied snapshot name has invalid chars | +| default-container-unset | The connection level table/keyspace was not set | +| container-not-found | The keyspace/table was not found | +| still-in-use | The object couldn't be removed because it is still in use | +| err-protected-object | The object is not user accessible | +| wrong-model | An action was run against the wrong data model | +| err-already-exists | The table/keyspace already exists | +| not-ready | The table/keyspace is not ready | +| transactional-failure | A transactional action failed to execute | +| unknown-ddl-query | An unknown DDL query was run | +| malformed-expression | The expression in a DDL query was illegal | +| unknown-model | A DDL query was run to create a table of an unknown model | +| too-many-args | More args than required was passed to a DDL query | +| container-name-too-long | The container name was too long | +| bad-container-name | The supplied container name has illegal chars | +| unknown-inspect-query | An unknown `INSPECT` query | +| unknown-property | An unknown table property was passed to `CREATE TABLE` | +| keyspace-not-empty | The keyspace couldn't be removed because it still has tables | +| pipeline-not-supported-yet | Pipelining is not supported in this server version | diff --git a/versioned_docs/version-0.7.3/protocol/response-codes.md b/versioned_docs/version-0.7.3/protocol/response-codes.md new file mode 100644 index 000000000..59957c1c3 --- /dev/null +++ b/versioned_docs/version-0.7.3/protocol/response-codes.md @@ -0,0 +1,20 @@ +--- +id: response-codes +title: Response Codes +--- + +Skytable may return any of the response codes listed here: + +| Code | Description | Notes | +| -------------- | ---------------------------- | ------------------------------------------------------ | +| `0` | Okay | The server succeded in carrying out some operation | +| `1` | Nil | The client asked for a non-existent object | +| `2` | Overwrite Error | The client tried to overwrite data | +| `3` | Action Error | The action didn't expect the arguments sent | +| `4` | Packet Error | The packet contains invalid data | +| `5` | Server Error | An error occurred on the server side | +| `6` | Other error | Some other error response | +| `7` | Wrongtype error | The client sent the wrong type | +| `8` | Unknown data type | The client sent an unknown data type | +| `9` | Encoding error | The client sent a badly encoded query | +| _Error String_ | Other error with description | Some other error occurred. See [this document](errors) | diff --git a/versioned_docs/version-0.7.3/protocol/skyhash.md b/versioned_docs/version-0.7.3/protocol/skyhash.md new file mode 100644 index 000000000..880a1b723 --- /dev/null +++ b/versioned_docs/version-0.7.3/protocol/skyhash.md @@ -0,0 +1,277 @@ +--- +id: skyhash +title: Skyhash Protocol 1.0 +--- + +:::note About this document +Copyright (c) 2021 Sayan Nandan <nandansayan@outlook.com> +**In effect since:** v0.6.0 +**Date:** 11th May, 2021 +::: + +## Introduction + +Skyhash or the Skytable Serialization Protocol (SSP) is a serialization protocol built on top of TCP that is +used by Skytable for client/server communication. All clients willing to communicate with Skytable need to implement this protocol. + +## Concepts + +Skyhash uses a query/response action just like HTTP's request/response action — +clients send queries while the server sends responses. All the bytes sent by a client to a server is called a _Query Packet_ while all the bytes sent by the server in response to this is called the _Response packet_. + +There are different kinds of queries: +- **Simple queries**: These queries just have one action in the query packet, and hence, have just one response in the response packet +- **Pipeline queries**: These queries carry multiple actions in the query pakcet and hence their response packet also contains multiple responses. You can read more about querying [here](../actions-overview). + +Irrespective of the query type, all these packets are made of a metaframe and a dataframe. + + +### The Metaframe + +The metaframe is the first part of the packet separated from the rest of the packet by a line feed (`\n`) character. It looks like +this: + +``` +*\n +``` + +where `` tells us the number of actions this packet corresponds to. For simple queries which run one action, this will be one while for batch queries it can have any value in the range (1, +∞). + +### The Dataframe + +The dataframe is made up of elements. Each element corresponds to +a single action and hence corresponds to a single query. Simple queries will run one action and hence will have one element while batch queries will run a number of actions and hence will have a number of elements. + +Every element is of a certain [data type](#common-data-types) and this type determines how the element is serialized with Skyhash. Responses receive some extra data types which are +highlighted in [response specific data types](#response-specific-data-types). + +## Common Data Types + +Usually serialized data types look like: + +``` +\n +-----DATA------- +``` + +where the `` corresponds to the Type Symbol and the `` corresponds to the length of +this element. Below is a list of data types and their ``s. + +### Strings (+/?) + +String elements are serialized like: + +``` ++\n +\n +``` + +Where `` is the number of bytes in the string '``'. +So a string 'Sayan' will be serialized into: + +``` ++5\n +Sayan\n +``` + +There is also a binary string (binstr) type with a tsymbol `?`. For this kind of string, no unicode validation +is carried out. + +### Unsigned integers (:) + +64-bit usigned integers are serialized into: + +``` +:\n +\n +``` + +Where `` is the number of digits in the integer and `` is the integer itself. + +### Arrays (&) + +Arrays are recursive data types, that is an array can contain another array which in turn can contain another array and so on. And array is essentially a collection of data types, including itself. Also, arrays can be multi-type. + +Skyhash serializes arrays into: + +``` +&\n + +``` + +Where `` is the number of elements in this array and `` are the elements present in the array. Take a look at the following examples: + +1. An array containing two strings: + +``` +&2\n ++5\n +Hello ++5\n +World\n +``` + +This can be represented as: + +```js +Array([String("Hello"), String("World")]); +``` + +2. An array containing a string an two integers: + +``` +&3\n ++5\n +Hello +:1\n +0\n +:1\n +1\n +``` + +Which can be represented as: + +```js +Array([String("Hello"), UnsignedInt64(0), UnsignedInt64(1)]); +``` + +3. An array containing two arrays: + Pipe symbols (|) and underscores (\_) were added for explaining the logical parts of the array: + +``` + ___________________________ +&2\n |_____________| | +&2\n | | | ++5\n | | | +Hello\n | Array 1 | | ++5\n | | | +World\n |_____________| | +&3\n | | Nested | ++5\n | | Array | +Hello\n | | | ++5\n | Array 2 | | +World\n | | | ++5\n | | | +Again\n |_____________|_____________| +``` + +This can be represented as: + +```js +Array([ + Array([String("Hello"), String("World")]), + Array([String("Hello"), String("World"), String("Again")]), +]); +``` + +This can be nested even more! + +### Important notes + +These data types and `` are non-exhaustive. Whenever you are attempting to deserialize a packet, always throw some kind of `UnimplementedError` to indicate that your client cannot yet deserialize this specific type. + +:::info Useful read +**We strongly recommend** you to read the full list of types and how they are serialized [in this document](data-types). +::: + +## Response Specific Data Types + +Responses will return some additional data types. This is a _non-exhaustive_ list of such types. + +### Response Codes (!) + +Response codes are often returned by the server when no +'producable' data can be returned, i.e something like FLUSHDB can only possibly return 'Okay' or an error. This distinction +is made to reduce errors while matching responses. Skyhash will serialize a response code like: + +``` +!\n +\n +``` + +Where `` is the number of characters in the code and `` is the code itself. So Code `0` that corresponds to `OKAY` will be serialized into: + +``` +!1\n +0\n +``` + +You find a full list of response codes [in this table](response-codes). + +## A full example (a simple query) + +Let's take a look at what happens when we send `SET x ex`. First, the client needs to serialize +it into a Skyhash compatible type. Since this is a simple query, we just have one single +element in the query array. Most of Skytable's common actions use arrays, and SET uses an [`AnyArray`](data-types#any-array). So in `SET x ex`: + +- This is a simple query +- We need to send an [`AnyArray`](data-types#any-array) +- It has three elements: `['SET', 'x', 'ex']` + +```shell +*1\n # '*1' because this is a simple query +~3\n # 3 elements +3\n # 'SET' has 3 chars +SET\n # 'SET' itself +1\n # 'x' has 1 char +x\n # 'x' itself +2\n # 'ex' has 2 chars +ex\n # 'ex' itself +``` + +Way to go! We just did it! + +Now the server would return a query array with one element: a response code. This is what +it returns: + +```sh +*1\n +!1\n +0\n +``` + +Here: + +- `*1` because this response corresponds to a simple query +- `!1` because the returned data type is a response code with tsymbol `!` and a length of `1` + char +- `0` because this is the response code that corresponds to _Okay_ + +## A full example (a pipelined query) + +Let's take a look at when we send two queries `HEYA once` and `HEYA twice` to the server, as a pipelined query. + +- This is a pipelined query +- We need to send two [`AnyArray`](data-types#any-array)s, one for each query + +This is what the client has to send (`#`s are used to denote comments): + +```shell +*2\n # *2 because this a pipelined query with two queries +# we begin our first query from here +~2\n # our first query has two elements: "HEYA" and "once" +4\n # "HEYA" has 4 characters +HEYA\n # the element itself +4\n # "once" has 4 characters +once\n # the element itself +# we're done. the second query begins here +~2\n # our second query has two elements: "HEYA" and "twice" +4\n # "HEYA" has 4 characters +HEYA\n # the element itself +5\n # "twice" has 5 characters +twice\n # the element itself +``` + +The server then responds with (`#`s are used to denote comments): + +```shell +*2\n # this response has two responses, for two queries +# the first response ++4\n # the first element "once" has 4 chars +once\n # the element itself +# the second response ++5\n # the second element "twice" has 5 chars +twice\n # the element itself +``` + +And there — you've learned Skyhash! diff --git a/versioned_sidebars/version-0.7.3-sidebars.json b/versioned_sidebars/version-0.7.3-sidebars.json new file mode 100644 index 000000000..5d670487f --- /dev/null +++ b/versioned_sidebars/version-0.7.3-sidebars.json @@ -0,0 +1,69 @@ +{ + "docs": [ + "index", + "getting-started", + "actions-overview", + "containers", + "ddl", + "examples", + "all-actions", + { + "type": "category", + "label": "Configuration", + "items": [ + "config", + "config-files", + "config-env", + "config-cmd", + "persistence", + "snapshots", + "ssl" + ] + }, + "clients", + "perf-guide", + "benchmarking", + "deployment-notes", + "building-from-source", + { + "type": "category", + "label": "Actions", + "items": [ + "actions/dbsize", + "actions/del", + "actions/exists", + "actions/flushdb", + "actions/get", + "actions/heya", + "actions/keylen", + "actions/lskeys", + "actions/lget", + "actions/lmod", + "actions/lset", + "actions/mget", + "actions/mksnap", + "actions/mpop", + "actions/mset", + "actions/mupdate", + "actions/pop", + "actions/sdel", + "actions/set", + "actions/sset", + "actions/supdate", + "actions/update", + "actions/uset", + "actions/whereami" + ] + }, + { + "type": "category", + "label": "Protocol", + "items": [ + "protocol/skyhash", + "protocol/data-types", + "protocol/response-codes", + "protocol/errors" + ] + } + ] +} diff --git a/versions.json b/versions.json index 5dacd36ee..36e1b3ed2 100644 --- a/versions.json +++ b/versions.json @@ -1,4 +1,5 @@ [ + "0.7.3", "0.7.2", "0.7.1", "0.7.0",