Merge pull request #125 from skytable/0.8.4/init

docs: Add 0.8.4 docs

Author: ohsayan

docs/a.installation.md

@@ -20,7 +20,7 @@ However, we strongly recommend **not** using it outside testing environments.
 
 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/v0.8.3).
+1. **First download the latest bundle** for your platform. You can find [download links on the releases page](https://github.com/skytable/skytable/releases/v0.8.4).
 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
@@ -72,7 +72,7 @@ The package will:
 2. **Start the container**:
 
     ```shell
-    docker run -d --name skydb -p 2003:2003 skytable/skytable:v0.8.3
+    docker run -d --name skydb -p 2003:2003 skytable/skytable:v0.8.4
     ```
 
 :::tip
@@ -85,14 +85,14 @@ message with the generated password.
 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/v0.8.3/examples/config-files/template.yaml) and place it into the directory you created. Update the password with your `root` password of choice.
+3. **Create your configuration**: [Download this template file](https://raw.githubusercontent.com/skytable/skytable/v0.8.4/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:v0.8.3
+        skytable/skytable:v0.8.4
      ```
 
      Explanation:

docs/b.using-repl.md

@@ -73,15 +73,20 @@ CREATE MODEL myspace.mymodel(username: string, password: string, notes: list { t
 
 ### Add, update and remove some data
 
-- **Insert some data**: 
+- **Insert some data**:
+
   ```sql
     INSERT INTO myspace.mymodel('sayan', 'password123', [])
   ```
+
 - **Update some data**:
+
     ```sql
     UPDATE myspace.mymodel SET notes += "mynewnote" WHERE username = 'sayan'
     ```
+
 - **Select some data**:
+
     ```sql
     SELECT notes, password FROM myspace.mymodel WHERE username = 'sayan'
     ```

docs/blueql/1.overview.md

@@ -6,6 +6,7 @@ id: overview
 In this document we explore some of the meta parts of BlueQL. If you want to look at how you can use BlueQL, consider looking at the sections that follow.
 
 Design principles:
+
 - **Simplicity and clarity**: The language shouldn't be overwhelming to understand
 - **Security with mandatory parameterization**: We want to reduce the surface of injection attacks. For this reason, [parameterization is mandatory](#parameters).
 
@@ -18,17 +19,18 @@ Just like SQL, BlueQL has three categories of commands/queries inside it:
 Jump to [differences from SQL](#differences-from-sql).
 
 :::info
-This text is *not* a detailed, formal guide. It's meant for developers and users who want to work with 
-Skytable.  If you need a more formal specification, like a grammar definition, please ask us, and we'll create 
+This text is *not* a detailed, formal guide. It's meant for developers and users who want to work with
+Skytable.  If you need a more formal specification, like a grammar definition, please ask us, and we'll create
 it. We haven't published it yet because no one has requested it.
 :::
 
 ## Identifiers
+
 Can begin with any ASCII alphabet or an underscore (`_`) and then have any number of alphanumeric characters and/or underscores.
 
 ## Keywords
 
-Keywords are identifiers with special meanings and hence can't be used as identifiers in other places. Here's a full-list of 
+Keywords are identifiers with special meanings and hence can't be used as identifiers in other places. Here's a full-list of
 keywords:
 
 ```ts
@@ -45,6 +47,7 @@ keywords:
 ## Data types
 
 ### Boolean
+
 A boolean value, either `true` or `false`
 
 ### Unsigned integers
@@ -75,9 +78,11 @@ A boolean value, either `true` or `false`
 
 - `list`: a list of any of the data types, including nested lists
   - A list is represented as: `[]` with values inbetween. For example, a `list { type:string }` would be represented as:
+
     ```sql
     ["sayan", "loves", "dogs"]
     ```
+
   - **Lists cannot contain null values**
   - **List can be nested**: You can have heavily nested lists like: `[[[]], [["another one"]]]`
   - **List can only have one base type**: This means that if you have a list like `[[[string]]]` each element must either be the same nested list, or an empty list
@@ -100,6 +105,7 @@ New data types are frequently added, so treat this list as non-exhaustive.
 
 :::warning Literals are not available everywhere
 It is very important for you to know that literals are not allowed everywhere. The only literals allowed everywhere are:
+
 - Lists
 - Dictionaries
 
@@ -150,6 +156,7 @@ On a final note, BlueQL doesn't support comments of any form also for security r
 ## DDL
 
 Queries include:
+
 - Spaces:
   - `CREATE SPACE myspace [WITH { property: value, ... }]`
   - `ALTER SPACE myspace [WITH { property: updated_value, ... }]`
@@ -172,6 +179,7 @@ Queries include:
 ## DCL
 
 Queries include:
+
 - `SYSCTL REPORT STATUS`: returns the status of the system. (Not a control query per se)
 - `SYSCTL CREATE USER "username" WITH { password: ... }`: create a new user
 - `SYSCTL DROP USER "username"`: removes the user in question

docs/blueql/2.ddl.md

@@ -22,21 +22,27 @@ This is so that you're specific about what DDL object you want to manipulate.
 Exception: `INSPECT` queries will respect the currently set `SPACE` if required.
 :::
 
-### INSPECT:
+### INSPECT
 
 - **Syntax**:
   - `INSPECT GLOBAL`: returns a JSON with a list of all spaces, users and other information. For example:
+
     ```json
     {"spaces":["space1"],"users":["root"],"settings":{}}
     ```
+
   - `INSPECT SPACE <space>`: returns a JSON with a list of all models in the space and other information, For example:
+
     ```json
     {"models":["model1"],"properties":{}}
     ```
+
   - `INSPECT MODEL <space>.<model>`: returns a JSON with information about the model such as the declaration, row count and such:
+
     ```json
     {"decl":"{*username: string, !password: string, ?notes: [string]}","size":12345678,"properties":{}}
     ```
+
 - **Access control**: any
 - **Returns**: string or error
 
@@ -68,8 +74,8 @@ CREATE SPACE IF NOT EXISTS apps
 
 ### ALTER SPACE
 
-
 **Syntax:**
+
 ```sql
 ALTER SPACE <space_name> WITH { property_name: property_value }
 ```
@@ -87,6 +93,7 @@ ALTER SPACE apps WITH { new_cache_value: 1234 }
 ### DROP SPACE
 
 **Syntax:**
+
 ```sql
 DROP SPACE [IF EXISTS] [ALLOW NOT EMPTY] <space_name>
 ```
@@ -96,9 +103,11 @@ DROP SPACE [IF EXISTS] [ALLOW NOT EMPTY] <space_name>
   - **A non-empty space cannot be dropped**
       To avoid catastrophic `DROP`s, a `SPACE` can only be dropped directly if it is non-empty. To drop a non-empty space, you must
       run:
+
       ```sql
       DROP SPACE ALLOW NOT EMPTY <space_name>
     ```
+
 - **Returns**:
   - empty or error
   - when used with `if exists`: bool indicating whether the space was actually present or not
@@ -126,9 +135,11 @@ DROP SPACE ALLOW NOT EMPTY myspace
 ### CREATE MODEL
 
 **Syntax**:
+
 ```sql
 CREATE MODEL [IF NOT EXISTS] <space_name>.<model_name>([primary] [null] field_name: field_type) [ WITH {property_name: property_value} ]
 ```
+
 - **Access control**: `root` only
 - **Properties**: None
 - **Operational notes**:
@@ -151,6 +162,7 @@ CREATE MODEL IF NOT EXISTS myspace.mymodel(username: string, password: string, n
 ### ALTER MODEL ADD
 
 **Syntax:**
+
 ```sql
 -- add a single field
 ALTER MODEL <space_name>.<model_name> ADD one_field { type: string }
@@ -165,6 +177,7 @@ ALTER MODEL <space_name>.<model_name> ADD (
 - **Returns**: empty or error
 
 #### Examples
+
 ```sql
 ALTER MODEL myspace.mymodel ADD one_field { type: list { type: string } }
 ALTER MODEL myspace.mymodel ADD (
@@ -182,6 +195,7 @@ ALTER MODEL myspace.mymodel ADD (
 ### ALTER MODEL UPDATE
 
 **Syntax**
+
 ```sql
 -- update one field
 ALTER MODEL <space_name>.<model_name> UPDATE one_field { type: string }
@@ -210,6 +224,7 @@ ALTER MODEL myspace.mymodel UPDATE (
 ### ALTER MODEL REMOVE
 
 **Syntax**:
+
 ```sql
 -- remove one field
 ALTER MODEL <space_name>.<model_name> REMOVE one_field
@@ -232,6 +247,7 @@ ALTER MODEL myspace.mymodel REMOVE (useless_field_1, useless_field2)
 ### DROP MODEL
 
 **Syntax**:
+
 ```sql
 DROP MODEL [IF EXISTS] [ALLOW NOT EMPTY] <space_name>.<model_name>
 ```
@@ -240,9 +256,11 @@ DROP MODEL [IF EXISTS] [ALLOW NOT EMPTY] <space_name>.<model_name>
 - **Operational notes**
   - **Non-empty models cannot be dropped** to avoid catastrophic drops
   - **To drop a non-empty model**: you must run:
+
     ```sql
     DROP MODEL ALLOW NOT EMPTY <space_name>.<model_name>
     ```
+
 - **Returns**:
   - empty or error
   - when used with `if exists`: bool indicating whether the model was actually present or not
@@ -253,3 +271,22 @@ DROP MODEL [IF EXISTS] [ALLOW NOT EMPTY] <space_name>.<model_name>
 DROP MODEL myspace.mymodel
 DROP ALLOW NOT EMPTY myspace.mymodel
 ```
+
+### TRUNCATE MODEL
+
+```sql
+TRUNCATE MODEL <space_name>.<model_name>
+```
+
+- **Access control**: `root` only
+- **Operational notes**:
+  - Blocking
+  - Blocks all DML queries until completion of execution
+- **Returns**:
+  - empty or error
+
+#### Examples
+
+```sql
+TRUNCATE MODEL myspace.mymodel
+```

docs/blueql/3.dml.md

@@ -28,6 +28,7 @@ INSERT INTO <model_name> {
     ...
 }
 ```
+
 ### Requirements and responses
 
 - **Access control**: any

docs/blueql/4.dcl.md

@@ -3,15 +3,17 @@ id: dcl
 title: DCL
 ---
 
-Data Control Language or DCL can be used to perform administrative tasks on the database. Currently, all DCL commands are 
+Data Control Language or DCL can be used to perform administrative tasks on the database. Currently, all DCL commands are
 available under the `SYSCTL` query.
 
 ## SYSCTL REPORT STATUS
 
 **Syntax**:
+
 ```sql
 SYSCTL REPORT STATUS
 ```
+
 - **Access control**: any
 - **Operational notes**:
   - This returns the current overall health of the system
@@ -20,15 +22,18 @@ SYSCTL REPORT STATUS
 ## SYSCTL CREATE USER
 
 **Syntax**:
+
 ```sql
 SYSCTL CREATE USER <username> WITH { password: 'password' }
 ```
+
 - **Access control**: `root` only
 - **Returns**: empty or error
 
 ## SYSCTL ALTER USER
 
 **Syntax**:
+
 ```sql
 SYSCTL ALTER USER <username> WITH { password: 'new password' }
 ```
@@ -44,8 +49,10 @@ Trying to change the `root` account password will throw an error. You can only c
 ## SYSCTL DROP USER
 
 **Syntax**:
+
 ```sql
 SYSCTL DROP USER <username>
 ```
+
 - **Access control**: `root` only
 - **Returns**: empty or error