From 10e4215bcee66f9f92eecb6b5cc468ca46a12417 Mon Sep 17 00:00:00 2001 From: Sayan Nandan Date: Sat, 14 Sep 2024 05:55:08 +0000 Subject: [PATCH 1/3] docs: Update docs for 0.8.4 --- docs/a.installation.md | 8 ++++---- docusaurus.config.js | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/a.installation.md b/docs/a.installation.md index 6908a2efa..610367162 100644 --- a/docs/a.installation.md +++ b/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: diff --git a/docusaurus.config.js b/docusaurus.config.js index 0fe12633d..edaff84af 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -125,7 +125,7 @@ module.exports = { lastVersion: 'current', versions: { current: { - label: '0.8.3', + label: '0.8.4', path: '/', } }, From 1ec3e243bcf4ee769fcc887ea5a6d8807c7e3d8b Mon Sep 17 00:00:00 2001 From: Sayan Nandan Date: Sat, 14 Sep 2024 06:04:39 +0000 Subject: [PATCH 2/3] docs: Format all markdown files --- docs/b.using-repl.md | 7 ++++++- docs/blueql/1.overview.md | 14 ++++++++++--- docs/blueql/2.ddl.md | 22 +++++++++++++++++++-- docs/blueql/3.dml.md | 1 + docs/blueql/4.dcl.md | 9 ++++++++- docs/c.architecture.md | 34 ++++++++++++++++++-------------- docs/deployment.md | 1 + docs/index.md | 2 +- docs/limits.md | 8 +++++--- docs/protocol/errors.md | 2 +- docs/protocol/specification.md | 13 ++++++++---- docs/resources/2.migration.md | 4 ++-- docs/system/a.configuration.md | 3 ++- docs/system/b.user-management.md | 9 ++++++--- docs/system/d.disk-usage.md | 2 +- docs/system/f.recovery.md | 2 +- docs/versions.md | 2 +- 17 files changed, 95 insertions(+), 40 deletions(-) diff --git a/docs/b.using-repl.md b/docs/b.using-repl.md index 14ebffcd3..e918c0612 100644 --- a/docs/b.using-repl.md +++ b/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' ``` diff --git a/docs/blueql/1.overview.md b/docs/blueql/1.overview.md index e94745de5..ff3d3c030 100644 --- a/docs/blueql/1.overview.md +++ b/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 diff --git a/docs/blueql/2.ddl.md b/docs/blueql/2.ddl.md index a279b2883..078086b6e 100644 --- a/docs/blueql/2.ddl.md +++ b/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 `: returns a JSON with a list of all models in the space and other information, For example: + ```json {"models":["model1"],"properties":{}} ``` + - `INSPECT 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 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] ``` @@ -96,9 +103,11 @@ DROP SPACE [IF EXISTS] [ALLOW NOT EMPTY] - **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 ``` + - **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] .([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 . ADD one_field { type: string } @@ -165,6 +177,7 @@ ALTER MODEL . 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 . UPDATE one_field { type: string } @@ -210,6 +224,7 @@ ALTER MODEL myspace.mymodel UPDATE ( ### ALTER MODEL REMOVE **Syntax**: + ```sql -- remove one field ALTER MODEL . 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] . ``` @@ -240,9 +256,11 @@ DROP MODEL [IF EXISTS] [ALLOW NOT EMPTY] . - **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 . ``` + - **Returns**: - empty or error - when used with `if exists`: bool indicating whether the model was actually present or not diff --git a/docs/blueql/3.dml.md b/docs/blueql/3.dml.md index f1ceb6376..7b8666c32 100644 --- a/docs/blueql/3.dml.md +++ b/docs/blueql/3.dml.md @@ -28,6 +28,7 @@ INSERT INTO { ... } ``` + ### Requirements and responses - **Access control**: any diff --git a/docs/blueql/4.dcl.md b/docs/blueql/4.dcl.md index 7abe8c834..03af0846d 100644 --- a/docs/blueql/4.dcl.md +++ b/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 WITH { password: 'password' } ``` + - **Access control**: `root` only - **Returns**: empty or error ## SYSCTL ALTER USER **Syntax**: + ```sql SYSCTL ALTER USER 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 ``` + - **Access control**: `root` only - **Returns**: empty or error diff --git a/docs/c.architecture.md b/docs/c.architecture.md index bfe141817..58c15a075 100644 --- a/docs/c.architecture.md +++ b/docs/c.architecture.md @@ -4,18 +4,18 @@ title: Architecture --- Skytable is a modern NoSQL database that prioritises performance, scalability and reliability while providing a rich and powerful querying interface. -We are generally targetting an audience that wants to build high performance, large-scale, low latency applications, such as social networking services, +We are generally targetting an audience that wants to build high performance, large-scale, low latency applications, such as social networking services, auth services, adtech and such. Skytable is designed to work with both **structured and semi-structured data**. -Our goal is to provide you with a powerful and solid foundation for your application with no gimmicks — just a solid core. That's why, every component in +Our goal is to provide you with a powerful and solid foundation for your application with no gimmicks — just a solid core. That's why, every component in Skytable has been engineered from the ground up, from scratch. And all of that, without you having to be an expert, and with the least maintenance that you can expect. ## Fundamental differences from relational systems -BlueQL kind of looks and feels like using SQL with a relational database but that doesn't make Skytable's internals the same, with the most important -distinction being the fact that Skytable has a NoSQL engine! But Skytable's evaluation and execution of queries is fundamentally different from SQL +BlueQL kind of looks and feels like using SQL with a relational database but that doesn't make Skytable's internals the same, with the most important +distinction being the fact that Skytable has a NoSQL engine! But Skytable's evaluation and execution of queries is fundamentally different from SQL counterparts and even NoSQL engines. Here are some key differences: - All DML queries are point queries and **not** range queries: @@ -26,18 +26,18 @@ counterparts and even NoSQL engines. Here are some key differences: - **Remember, in NoSQL systems we denormalize.** Hence, no `JOIN`s or foreign keys as with many other NoSQL systems - A different transactional model: - All DDL and DCL queries are ACID transactions - - However, DML transactions are not ACID and instead are efficiently batched and are automatically made part of a batch - transaction. The engine decides *when* it will execute them, for example based on the pressure on cache. That's because our + - However, DML transactions are not ACID and instead are efficiently batched and are automatically made part of a batch + transaction. The engine decides *when* it will execute them, for example based on the pressure on cache. That's because our focus is to maximize throughput - All these differences mean that **DDL and DCL transactions are ACID transactions** while **DML queries are ACI and *eventually* D** (we call it a *delayed durability transaction*). This delay however can be adjusted to make sure that the DML queries *emulate* ACID transactions but that defeats the point of the eventually durable system which aims to heavily increase throughput. - - The idea of eventually durable transactions relies on the idea that hardware failure even though prominent is still rare, + - The idea of eventually durable transactions relies on the idea that hardware failure even though prominent is still rare, thanks to the extreme hard work that cloud vendors put into reliability engineering. If you plan to run on unreliable hardware, then the delay setting (reliability service) is what you need to change. - For extremely unreliable hardware on the other hand, we're working on a new storage driver `rtsyncblock` that is expected to be released in Q1'24 - The transactional engine powering DDL and DCL queries might often choose to demote a transaction to a virtual transaction which makes sure that the transaction is obviously durable but not necessarily actually executed but is eventually executed. If the system crashes, the engine will still be able to actually execute the transaction (even if it crashed halfway) :::tip -We believe you can now hopefully see how Skytable's workings are fundamentally different from traditional engines. And, we know +We believe you can now hopefully see how Skytable's workings are fundamentally different from traditional engines. And, we know that you might have a lot of questions! If you do, please reach out. We're here to help. ::: @@ -52,7 +52,7 @@ While a `MODEL` is the only data container for now, many more are set to come. N ### A `space` is like a `database` -A `space` in Skytable is a collection of `model`s and other objects, and settings. It is different from a traditional SQL +A `space` in Skytable is a collection of `model`s and other objects, and settings. It is different from a traditional SQL Database (that is created with SQL's `CREATE DATABASE`) because it is not meant for tables only, but many other things. Spaces have "space local" settings that can be set for the space (and will be respected by all its `models` and other items). You'll learn more about this in the section on DDL. @@ -60,10 +60,11 @@ Spaces have "space local" settings that can be set for the space (and will be re ### A `model` is like a `table` A `model` in Skytable is like a `table` in SQL but is vastly different because of certain concepts such as: + - DML queries are point and not range queries by default - Restrictions on indexes - Settings (which can't be created in traditional `table`s) -- Semi-structured data: with collection types in columns such as lists and dictionaries that violates some of the ideas of +- Semi-structured data: with collection types in columns such as lists and dictionaries that violates some of the ideas of traditional schema enforcement ## Query language @@ -75,13 +76,13 @@ For example, Skytable's BlueQLTM *only* allows the parameterization o ## Transactions Skytable's DDL and DCL queries are all ACID transactions. However, DML queries use an AOF-style storage driver that periodically -records, analyses and then intelligently syncs the changes to disk. We're working on making ACID transactions widely available +records, analyses and then intelligently syncs the changes to disk. We're working on making ACID transactions widely available across DML queries as well. ## Storage -Skytable's storage engine is collectively called the Skytable Disk Storage Subsystem or SDSS for short. The storage engine uses -several different storage drivers, using ones appropriate for the task. We do not use RocksDB or any other engine but we +Skytable's storage engine is collectively called the Skytable Disk Storage Subsystem or SDSS for short. The storage engine uses +several different storage drivers, using ones appropriate for the task. We do not use RocksDB or any other engine but we implement everything in house, engineering them piece by piece. :::info Features on track @@ -103,8 +104,9 @@ Skytable will use atleast as many threads as the number of logical CPUs present ## Networking -Skytable uses its own in-house Skyhash protocol for client-server communication. It is built on top of TCP, enabling any programming language that has a +Skytable uses its own in-house Skyhash protocol for client-server communication. It is built on top of TCP, enabling any programming language that has a TCP client to use it without issues. There are three phases in the connection: + - Handshake: All auth data, compatibility information and other data is exchanged at this step - Connection mode selection: based on the handshake parameters a connection mode is chosen and the server responds with the chosen exchange mode - Data exchange: This is where the real querying happens @@ -115,14 +117,16 @@ You can [read more about the protocol here](protocol). ## Backwards compatibility We make the promise to you that no matter what changes in Skytable, you will always be able to: + - Upgrade from one version to another without data loss or too many hoops - Export data from Skytable at any time More technically: + - **For minor/patch releases**: The minor/patch is just in the name but it indicates that no data migration effort is needed. **No minor releases ever need data migration, and any migration is done automatically** - **For major releases**: Major releases generally introduce breaking changes (just like the upgrade from `0.7.x` to `0.8.0` is a largely breaking change). **Major releases will either automatically upgrade the data files or require you to use a migration tool that is shipped with the bundle**. - Definitions (closely following semantic versioning): - - **A major release** is something like `1.0.0` to `2.0.0` or `0.8.0` to `0.9.0` (in development versions, 0.8.0 to 0.9.0 is considered a major version + - **A major release** is something like `1.0.0` to `2.0.0` or `0.8.0` to `0.9.0` (in development versions, 0.8.0 to 0.9.0 is considered a major version bump) - **A minor release** is something like `1.0.0` to `1.1.0` or `0.8.0` to `0.8.1` - **A patch release** is something like `1.0.0` to `1.0.1` or `0.8.0` to `0.8.1` (note that in development versions there is no distinction between a minor and patch release) diff --git a/docs/deployment.md b/docs/deployment.md index b85e92e0f..8788a15ae 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -4,6 +4,7 @@ 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` diff --git a/docs/index.md b/docs/index.md index c45cbd0b5..576503923 100644 --- a/docs/index.md +++ b/docs/index.md @@ -42,7 +42,7 @@ Hit an error? Check out the [error code index](protocol/errors). If you need fur ## Getting help -We have a collection of resources [on this page](resources/useful-links). 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. +We have a collection of resources [on this page](resources/useful-links). 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 diff --git a/docs/limits.md b/docs/limits.md index 45319e642..8094f7eb0 100644 --- a/docs/limits.md +++ b/docs/limits.md @@ -3,10 +3,11 @@ 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 +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 @@ -17,8 +18,8 @@ Skytable's limitations primarily come from a bunch of concerns: - `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 +- **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 @@ -32,6 +33,7 @@ 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. diff --git a/docs/protocol/errors.md b/docs/protocol/errors.md index 39507af03..abfeae40a 100644 --- a/docs/protocol/errors.md +++ b/docs/protocol/errors.md @@ -55,4 +55,4 @@ These errors can occur **when running a query**. | | 109 | DML data validation error | Input data validation failed | | | 110 | DML unindexed column | The column which was referenced as an index is not indexed | | | 111 | DML row not found | The referenced row was not found | -| | 112 | DML needs lock | The operation needs a global lock | \ No newline at end of file +| | 112 | DML needs lock | The operation needs a global lock | diff --git a/docs/protocol/specification.md b/docs/protocol/specification.md index 7cde769b1..61fcfdcb4 100644 --- a/docs/protocol/specification.md +++ b/docs/protocol/specification.md @@ -14,9 +14,11 @@ As noted earlier, Skyhash is a client/server protocol built on top of TCP, that - The handshake contains all necessary information to successfully establish a connection - The structure of the client handshake depends on the authentication plugin in use (since authentication data has to be exchanged before the connection can be established) - For the `pwd` plugin the client handshake looks like this: + ``` H0000\n\n ``` + - For the protocol compatibility code, [see the version matrix](/protocol/#version-matrix) - Please note that `0` means integer value `0` (`0x00`) and NOT the ASCII digit 0 - Both the `` and `` are the respective lengths encoded as ASCII strings @@ -33,6 +35,7 @@ If the server has accepted your connection then you can be sure that the protoco ### Exchange modes The Skyhash/2.0 specification defines the following exchange mode: + - **Query-time**: This works like a request/response action where the client sends a request and the server responds with a response to the query (or an error) Expect other exchange modes (bi-directional) to be added in future protocol revisions. @@ -44,6 +47,7 @@ In query-time exchange, the protocol works like a "request-response" action wher ### Client data types The client side needs to send encoded data types to the server (in the form of parameters) so that the server can process them. The following types are defined: + - Null: Encoded as `0` - Bool: Encoded as `1<0 or 1>\n` - Unsigned integer: A 64-bit unsigned integer. Encoded as `2\n` @@ -52,11 +56,12 @@ The client side needs to send encoded data types to the server (in the form of p - Binary: A binary blob. Encoded as `5\n` - String: An UTF-8 string. Encoded as `6\n` -> **Note**: A `` is the value of the length in question converted to an ASCII string. +> **Note**: A `` is the value of the length in question converted to an ASCII string. ### Server data types The server will respond with different data types, depending on the context. The following types are defined: + - Null: Encoded as `0` - Bool: encoded as `1<0 or 1>\n` - Unsigned integers: @@ -72,13 +77,14 @@ The server will respond with different data types, depending on the context. The - First byte: 11 -> list - Payload: `\n` -> **Note**: A `` is the value of the length in question converted to an ASCII string. +> **Note**: A `` is the value of the length in question converted to an ASCII string. ### Simple query/response #### Simple query A simple query sends a single BlueQL query to the server to which the server responds with a [simple response](#simple-response). It has three sections: + - The metaframe: - Contains metadata about the query - Encoded as: `S\n` (total size of the other two sections) @@ -89,7 +95,6 @@ A simple query sends a single BlueQL query to the server to which the server res #### Simple response - When the client sends a [simple query](#simple-query), the server will respond with a simple response using any of the [response data types](#server-data-types), or it can respond with any of the following response structures: - **Error**: Encoded as `0x10<16-bit error code>` @@ -97,7 +102,7 @@ When the client sends a [simple query](#simple-query), the server will respond w - **Empty**: This indicates that the query ran successfully but nothing appropriate can be returned (like HTTP's 200 status). Encoded as `0x12` - **Multirow**: The server has returned multiple rows. Encoded as `0x13\n` -> **Note**: A `` or `` is the value of the length in question converted to an ASCII string. +> **Note**: A `` or `` is the value of the length in question converted to an ASCII string. [^1]: See the [discussion here](https://github.com/skytable/skytable/issues/332) diff --git a/docs/resources/2.migration.md b/docs/resources/2.migration.md index 7986704a3..1b04c5ffd 100644 --- a/docs/resources/2.migration.md +++ b/docs/resources/2.migration.md @@ -3,8 +3,8 @@ id: migration title: Migrating from an older release --- -Firstly, thank you patron! You're a part of an exclusive *club* which has seen Skytable take shape from *just another key-value* -store into a powerful database and we couldn't be more honored to be a choice in your stack. This document is meant for people +Firstly, thank you patron! You're a part of an exclusive *club* which has seen Skytable take shape from *just another key-value* +store into a powerful database and we couldn't be more honored to be a choice in your stack. This document is meant for people coming from version prior to Skytable Octave (0.8). Let's get you up to speed with the new semantics: diff --git a/docs/system/a.configuration.md b/docs/system/a.configuration.md index 5fe3d2f35..d7d2e72a3 100644 --- a/docs/system/a.configuration.md +++ b/docs/system/a.configuration.md @@ -3,7 +3,7 @@ id: configuration title: Configuration --- -Skytable can be configured to run per your needs. You can use either of command-line arguments, environment variables or a +Skytable can be configured to run per your needs. You can use either of command-line arguments, environment variables or a configuration file. We don't have any specific recommendation for a mode of configuration but we generally consider using a configuration file to be the best practice since it is something that won't get lost (which in other cases can get lost due to lost shell history and such). @@ -42,6 +42,7 @@ To start the server with a configuration file, simply run `skyd --config Date: Sat, 14 Sep 2024 06:09:20 +0000 Subject: [PATCH 3/3] blueql [ddl]: Add section on `TRUNCATE MODEL` --- docs/blueql/2.ddl.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/blueql/2.ddl.md b/docs/blueql/2.ddl.md index 078086b6e..0778927ae 100644 --- a/docs/blueql/2.ddl.md +++ b/docs/blueql/2.ddl.md @@ -271,3 +271,22 @@ DROP MODEL [IF EXISTS] [ALLOW NOT EMPTY] . DROP MODEL myspace.mymodel DROP ALLOW NOT EMPTY myspace.mymodel ``` + +### TRUNCATE MODEL + +```sql +TRUNCATE MODEL . +``` + +- **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 +```