release: Freeze 0.8.0 documentation

docusaurus.config.js

@@ -125,7 +125,7 @@ module.exports = {
           lastVersion: 'current',
           versions: {
             current: {
-              label: '0.8',
+              label: '0.8.1',
               path: '/',
             }
           },

package.json

@@ -12,10 +12,10 @@
     "clear": "docusaurus clear"
   },
   "dependencies": {
-    "@docusaurus/core": "^3.1.1",
-    "@docusaurus/plugin-client-redirects": "^3.1.1",
-    "@docusaurus/preset-classic": "^3.1.1",
-    "@docusaurus/theme-search-algolia": "^3.1.1",
+    "@docusaurus/core": "^3.2.0",
+    "@docusaurus/plugin-client-redirects": "^3.2.0",
+    "@docusaurus/preset-classic": "^3.2.0",
+    "@docusaurus/theme-search-algolia": "^3.2.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },

versioned_docs/version-0.8.0/1.index.md

@@ -0,0 +1,45 @@
+---
+id: index
+title: Introduction
+sidebar_label: Home
+slug: /
+---
+
+Welcome to Skytable's docs! Skytable is a free and open-source modern NoSQL database that builds on the foundations of performance, scalability, powerful querying and a robust type system. Skytable can be deployed as just a single binary file with no special system dependencies and only relies on the operating system's `libc` implementation.
+
+## Guide
+
+Skytable has it's own query language, BlueQL<sup>TM</sup> which provides everything across DDL, DCL and DML queries and exists to be a very powerful and secure alternative to SQL. If you're coming from SQL, you should feel just at home — BlueQL has a few small but important operating differences from SQL but has very similar syntax.
+
+We recommend you to follow the guide in this sequence (but feel free to skip any sections):
+    - [**Installation**](installation) and [**using the CLI**](using-the-repl): Get everything installed on your local system
+    - [**System overview**](architecture): A brief introduction to Skytable, including an overview of the data model, query systems and storage
+    - **BlueQL**:
+      - [**Introduction**](blueql/overview): Serves as a basic introduction to the query language and an (currently incomplete) informal specification with information on keywords, syntax and stuctures.
+      - [**DDL**](blueql/ddl): Data definition with BlueQL
+      - [**DML**](blueql/dml): Data manipulation with BlueQL
+      - [**DCL**](blueql/dcl): Data control with BlueQL
+    - [**Configuration**](system/configuration): Information to help you configure Skytable with custom settings such as custom ports, hosts, TLS, and etc.
+    - [**Administration**](system/administration): Information on access control, user and other administration features
+    - [**Resources**](resources/overview): Helpful resources
+    - [**A guide to the new Skytable**](resources/migration): For old our returning Skytable users who are coming from older versions
+    - [**Benchmarking**](benchmarking): A guide for load testing Skytable
+    - [**Deployment**](deployment): An useful guide for deploying
+    - [**Limits**](limits): An useful guide on system limits
+
+## Client drivers
+
+Looking to integrate Skytable in your application? Great! [Find a driver for your language/framework here](libraries).
+
+## Getting help
+
+We have a collection of resources [on this page](resources/overview). If you need in help in real-time, we recommend that you join our [Discord Community](https://discord.gg/QptWFdx) where you can get help directly from the developers and our community members. 
+Most queries are usually answered there in a few hours!
+
+## 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)

versioned_docs/version-0.8.0/13.libraries.md

@@ -0,0 +1,35 @@
+---
+id: libraries
+title: Client drivers
+---
+
+
+## Official drivers
+
+The drivers that are officially maintained can be expected to be feature complete and stable. We currently support the following drivers:
+
+| Language/Framework             | Links                                                                                               | Status   | Package manager command |
+| ------------------------------ | --------------------------------------------------------------------------------------------------- | -------- | ----------------------- |
+| Rust                           | [GitHub](https://github.com/skytable/client-rust), [crates.io](https://crates.io/crates/skytable)   | Stable ✅ | `cargo add skytable`    |
+| NodeJS (JavaScript/TypeScript) | [GitHub](https://github.com/skytable/client-nodejs), [npm](https://npmjs.com/package/skytable-node) | Beta 🏗   | `npm i skytable-node`   |
+
+:::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 our chat!
+:::
+
+## Community powered
+
+List of community powered drivers (sorted alphabetically):
+
+| Language/Framework               | Client source code                                            | Upstreamed | License    | Remarks                                                                           |
+| -------------------------------- | ------------------------------------------------------------- | ---------- | ---------- | --------------------------------------------------------------------------------- |
+| **C#/.NET**                      |                                                               | ❗          |            |                                                                                   |
+|                                  | [C# driver](https://github.com/martinmolin/skytable-dotnet)   | ❗          | Apache-2.0 | Available on [NuGet](https://www.nuget.org/packages/Skytable.Client)              |
+| **Go**                           |                                                               | ❗          |            |                                                                                   |
+|                                  | [Go driver](https://github.com/No3371/go-skytable)            | ❗          | Apache-2.0 | Written from scratch                                                              |
+|                                  | [Go driver](https://github.com/satvik007/skytable-go)         | ❗          | Apache-2.0 | Easy for migration from go-redis                                                  |
+| **JavaScript/TypeScript (Node)** |                                                               | ❗          |            |                                                                                   |
+|                                  | [NodeJS Driver](https://github.com/zhangyuannie/skytable.js)  | ❗          | Apache-2.0 | Available on [npm](https://www.npmjs.com/package/skytable.js)                     |
+| **PHP**                          |                                                               | ❗          |            |                                                                                   |
+|                                  | [PHP client driver](https://github.com/hkulekci/skytable-php) | ❗          | MIT        | Can be found on [Packagist](https://packagist.org/packages/hkulekci/skytable-php) |

versioned_docs/version-0.8.0/14.benchmarking.md

@@ -0,0 +1,35 @@
+---
+id: benchmarking
+title: Benchmarking
+---
+
+Due to Skytable having in-house implementations of almost everything, starting from the protocol, the storage engine and query 
+language — we have our own custom load testing tool called `sky-bench` that is distributed with the bundle.
+
+## Setting up for benchmarking
+
+**Quick notes**:
+- The benchmark tool will create:
+  - a space called `bench`
+  - a model called `bench`
+- **Be sure that these objects don't already exist!** But don't worry, if they do — the benchmark tool will error. You won't lose any data
+- **Once the benchmark is complete, the `bench` space is removed!**
+- **Do not use the `bench` space during the benchmark**: You might lose data
+
+**The benchmark tool will:**
+- Run a total of 4,000,000 queries (don't worry, they run pretty fast!):
+  - Run 1,000,000 `INSERT`s
+  - Run 1,000,000 `SELECT`s
+  - Run 1,000,000 `UPDATE`s
+  - Run 1,000,000 `DELETE`s
+- The model used has the declaration `(un: string, pw: uint8)`
+- The `SELECT` will select and return all fields
+- The `UPDATE` will increment the value of `pw` like this `pw += 1`
+- The `DELETE` removes the entire collection
+- The default primary key size is 7 bytes. All generated keys will be padded with zeros from to 0 to 999,999 like this: `0000000` or `0999999`
+
+## Off to the races
+
+1. Start up the database server
+2. Run `./sky-bench --password <your root password>`. We need your `root` password because only the root account can create, alter and drop models and the benchmark tool needs to run these queries
+3. Wait for it to happen. You may not believe your eyes, so we recommend that you keep your eyes hydrated 🔥🚀✨💣

versioned_docs/version-0.8.0/15.deployment.md

@@ -0,0 +1,16 @@
+---
+id: deployment
+title: Deployment
+---
+
+Here are some recommendations for deployment:
+1. **Make sure you have enough memory and storage!** The server will start returning errors when your server runs out of resources, as you'd expect.
+2. **When deploying on docker**:
+   - Try to map the volume to a local path. We've had unwarranted data losses when we accidentally ended up running a `docker system prune`
+   - Make sure you have your networking configured right. For example, if you don't map your ports correctly, you'll not be able to access the database outside docker (without running `docker inspect` to find the IP of the container)
+   - Keep a separate folder for all your docker containers:
+     - Create a directory in your home directory like: `$HOME/docker-data`
+     - Then for every Docker image (whether it is Skytable or any other container) create a subfolder in that directory and map
+       the subfolder as a volume for persistence
+3. **Check your firewall**: You want to be very sure about this! If you're starting your database on a different server (as you should; ideally you keep your database server separate from the host running your application server) then make sure that the ports are open and allowed
+4. **Set up virtual memory and monitoring**: To avoid exhausting resources, set up monitoring on your node and enable virtual memory to temporarily avoid OOMs

versioned_docs/version-0.8.0/16.limits.md

@@ -0,0 +1,37 @@
+---
+id: limits
+title: Limits
+---
+
+We've made every effort to provide a robust querying interface, but there are some **temporary limitations** that we think you 
+should know about. We aim to remove the limitations over the next few releases which we expect should happen fairly quickly.
+
+Skytable's limitations primarily come from a bunch of concerns:
+- **Performance and scalability**: Most of our design decisions are influenced by concerns about performance. For example, it's very hard to efficiently scale multi-column indexes.
+- **Reliability**: how reliable is the execution of the task? If it's like walking on eggshells, then we're not going to implement it (for example, unreliable distributed locking)
+- **Security**: If it can't be run securely, then it's off our list
+
+## Temporary limitations
+
+- **DML in collections are still limited**: You'll be able to easily `INSERT` data into any collections but the manipulations on them are currently limited.:
+  - `SELECT` will return the entire collection and cannot yet return a single element
+  - `UPDATE` can append elements to *non-nested* collections but can't do the same for nested collections
+  - `DELETE` can't remove individual elements
+- **Models cannot be `volatile` yet**. If you've used Skytable before, you'd know that you could previously create `volatile` 
+  models which were used as *caching tables* as in they didn't persist data across restarts. The `volatile` feature has been 
+  temporarily removed because we're working on integrating it with the new storage engine.
+
+:::tip Nested collections will get an upgrade
+We understand that collections are fundamental to the complexity of today's data and hence we're working on this! The only reason our team spends so much time *perfecting* features is because it has match our design philosophy.
+
+> You can have 100 fancy but slow features, or 10 powerful and performant features.
+
+If it scales, we ship it. **We're on it!**
+:::
+
+## Soft limitations
+
+Following Skytable's design philosophy that closely encompasses NoSQL systems, the following soft limitations are set:
+- **Only one index**: Right now, the only index that you can use is the primary index (primary_key -> row). This is due to  concerns about performance and scale
+- **No mass updates**: We consider mass updates, such as setting `counter += 1` to every row in a model with multi-million rows
+to be very slow and bad for performance. Hence, we do not allow mass updates at this time.

versioned_docs/version-0.8.0/2.installation.md

@@ -0,0 +1,95 @@
+---
+id: installation
+title: Installation
+---
+
+Getting started with Skytable involves choosing a mode of installation, downloading any required files and then starting up the database. You can choose to either use:
+
+- [**Native binaries (recommended)**](#native-binaries): This is what is generally recommended for the best performance. You will need to download a bundle and then start the server binary; no expert knowledge required
+- [**Using a Debian package (recommended)**](#debian-package): If you're deploying on Ubuntu or any other Debian based Linux distribution, then consider using this method. Configuration files, users and passwords are autogenerated.
+- [**A Docker image**](#docker-image): We generally recommend using a Docker image for experimenting with Skytable on your local system during development and you want to keep your local system *clean*. If you want to use a Docker image for deployment, you're always free to do so!
+  > **Note:** You might experience slightly degraded performance from the storage engine due to Docker engine's abstractions.
+
+## Native binaries
+
+To use native binaries you need to download a bundle which is simply a ZIP file with all the necessary binaries that you'll ever need to develop on and deploy Skytable.
+
+1. **First download the latest bundle** for your platform. You can find [download links on the releases page](https://github.com/skytable/skytable/releases).
+2. **Unzip the ZIP file**. You'll find the following binaries in the extracted archive:
+   - `skyd`: This is the database server binary which when started runs as a daemon, serving requests
+   - `skysh`: This is the Skytable shell and it provides a very helpful interactive REPL database client
+   - `sky-bench`: This is the benchmarking tool that you can use to load test Skytable
+3. **Start up the server**. You need to choose a `root` password for the `root` account which will have complete control over the database.
+
+    ```bash
+    ./skyd --auth-root-password=<your root password>
+    ```
+
+    **Replace with your own secure password!**
+
+    Explanation:
+    - `--auth-root-password`: sets the root password
+
+The server starts up at `localhost:2003` and is ready to run queries.
+
+:::info
+Your operating system might sometimes not let you run binaries directly. On Unix based systems, you'll need to run: `chmod +x skyd skysh sky-bench`.
+
+And on Windows systems you might need to right-click on the binaries and click on "unblock"
+:::
+
+## Debian package
+
+Find the correct `*.deb` file [from the releases page](https://github.com/skytable/skytable/releases). Now simply run:
+
+```sh
+sudo dpkg -i <file name>.deb
+```
+
+The package will:
+
+- **Generate a root password:** Watch the terminal output!
+- **Create a `systemd` unit**: So you can start and stop the process using `systemd` like `systemd start skyd`
+- **Generate a configuration**: Your configuration is stored in `/var/lib/skytable/config.yaml`. Go ahead and modify it if you need to!
+
+## Docker image
+
+:::info You must have docker set up!
+
+- Use [this great guide from Docker](https://docs.docker.com/engine/install/) to install and get started
+- To be able to run `docker run` and related commands, you may need administrative privileges
+:::
+
+### Simple setup
+
+1. **Download the bundle**: To be able to run queries you need to download the bundle as described above
+2. **Start the container**:
+
+    ```shell
+    docker run -d --name skydb -p 2003:2003 skytable/skytable:latest
+    ```
+
+:::tip
+The password for the Skytable instance on the Docker container is auto-generated. Run `docker logs -f skydb` and you'll see a log
+message with the generated password.
+:::
+
+### With persistence
+
+1. **Download the bundle**: To be able to run queries you need to download the bundle as described above
+2. **Create the data directory**: To ensure that our database is persistent and all our data doesn't vanish as soon as the container is terminated, we'll map the data directory to an actual directory on our local system.
+    > **Note:** Create a folder called `skytable` in a convenient location. We recommend having a directory in `$HOME/docker-containers` where you can store the Skytable container's data and any other containers that you might use. It's a great way to keep things organized.
+3. **Create your configuration**: [Download this template file](https://raw.githubusercontent.com/skytable/skytable/next/examples/config-files/template.yaml) and place it into the directory you created. Update the password with your `root` password of choice.
+4. **Start the container**:
+
+     ```shell
+     docker run -d --name skydb \
+        -v $HOME/docker-containers/skytable:/var/lib/skytable \
+        -p 2003:2003 \
+        skytable/skytable:latest
+     ```
+
+     Explanation:
+     - This starts a container with name `skydb`
+     - It maps the folder (as discussed earlier) `$HOME/docker-containers/skytable` from your local file system to `/var/skytable` (in the container's file system)
+     - Maps port `2003` on the host to the containers port `2003` so that you can use the command-line client `skysh` without having to inspect the container's IP address