Skip to content

Commit 1ec3e24

Browse files
committed
docs: Format all markdown files
1 parent 10e4215 commit 1ec3e24

17 files changed

+95
-40
lines changed

docs/b.using-repl.md

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,15 +73,20 @@ CREATE MODEL myspace.mymodel(username: string, password: string, notes: list { t
7373

7474
### Add, update and remove some data
7575

76-
- **Insert some data**:
76+
- **Insert some data**:
77+
7778
```sql
7879
INSERT INTO myspace.mymodel('sayan', 'password123', [])
7980
```
81+
8082
- **Update some data**:
83+
8184
```sql
8285
UPDATE myspace.mymodel SET notes += "mynewnote" WHERE username = 'sayan'
8386
```
87+
8488
- **Select some data**:
89+
8590
```sql
8691
SELECT notes, password FROM myspace.mymodel WHERE username = 'sayan'
8792
```

docs/blueql/1.overview.md

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ id: overview
66
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.
77

88
Design principles:
9+
910
- **Simplicity and clarity**: The language shouldn't be overwhelming to understand
1011
- **Security with mandatory parameterization**: We want to reduce the surface of injection attacks. For this reason, [parameterization is mandatory](#parameters).
1112

@@ -18,17 +19,18 @@ Just like SQL, BlueQL has three categories of commands/queries inside it:
1819
Jump to [differences from SQL](#differences-from-sql).
1920

2021
:::info
21-
This text is *not* a detailed, formal guide. It's meant for developers and users who want to work with
22-
Skytable. If you need a more formal specification, like a grammar definition, please ask us, and we'll create
22+
This text is *not* a detailed, formal guide. It's meant for developers and users who want to work with
23+
Skytable. If you need a more formal specification, like a grammar definition, please ask us, and we'll create
2324
it. We haven't published it yet because no one has requested it.
2425
:::
2526

2627
## Identifiers
28+
2729
Can begin with any ASCII alphabet or an underscore (`_`) and then have any number of alphanumeric characters and/or underscores.
2830

2931
## Keywords
3032

31-
Keywords are identifiers with special meanings and hence can't be used as identifiers in other places. Here's a full-list of
33+
Keywords are identifiers with special meanings and hence can't be used as identifiers in other places. Here's a full-list of
3234
keywords:
3335

3436
```ts
@@ -45,6 +47,7 @@ keywords:
4547
## Data types
4648

4749
### Boolean
50+
4851
A boolean value, either `true` or `false`
4952

5053
### Unsigned integers
@@ -75,9 +78,11 @@ A boolean value, either `true` or `false`
7578

7679
- `list`: a list of any of the data types, including nested lists
7780
- A list is represented as: `[]` with values inbetween. For example, a `list { type:string }` would be represented as:
81+
7882
```sql
7983
["sayan", "loves", "dogs"]
8084
```
85+
8186
- **Lists cannot contain null values**
8287
- **List can be nested**: You can have heavily nested lists like: `[[[]], [["another one"]]]`
8388
- **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.
100105
101106
:::warning Literals are not available everywhere
102107
It is very important for you to know that literals are not allowed everywhere. The only literals allowed everywhere are:
108+
103109
- Lists
104110
- Dictionaries
105111
@@ -150,6 +156,7 @@ On a final note, BlueQL doesn't support comments of any form also for security r
150156
## DDL
151157

152158
Queries include:
159+
153160
- Spaces:
154161
- `CREATE SPACE myspace [WITH { property: value, ... }]`
155162
- `ALTER SPACE myspace [WITH { property: updated_value, ... }]`
@@ -172,6 +179,7 @@ Queries include:
172179
## DCL
173180

174181
Queries include:
182+
175183
- `SYSCTL REPORT STATUS`: returns the status of the system. (Not a control query per se)
176184
- `SYSCTL CREATE USER "username" WITH { password: ... }`: create a new user
177185
- `SYSCTL DROP USER "username"`: removes the user in question

docs/blueql/2.ddl.md

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,21 +22,27 @@ This is so that you're specific about what DDL object you want to manipulate.
2222
Exception: `INSPECT` queries will respect the currently set `SPACE` if required.
2323
:::
2424

25-
### INSPECT:
25+
### INSPECT
2626

2727
- **Syntax**:
2828
- `INSPECT GLOBAL`: returns a JSON with a list of all spaces, users and other information. For example:
29+
2930
```json
3031
{"spaces":["space1"],"users":["root"],"settings":{}}
3132
```
33+
3234
- `INSPECT SPACE <space>`: returns a JSON with a list of all models in the space and other information, For example:
35+
3336
```json
3437
{"models":["model1"],"properties":{}}
3538
```
39+
3640
- `INSPECT MODEL <space>.<model>`: returns a JSON with information about the model such as the declaration, row count and such:
41+
3742
```json
3843
{"decl":"{*username: string, !password: string, ?notes: [string]}","size":12345678,"properties":{}}
3944
```
45+
4046
- **Access control**: any
4147
- **Returns**: string or error
4248

@@ -68,8 +74,8 @@ CREATE SPACE IF NOT EXISTS apps
6874

6975
### ALTER SPACE
7076

71-
7277
**Syntax:**
78+
7379
```sql
7480
ALTER SPACE <space_name> WITH { property_name: property_value }
7581
```
@@ -87,6 +93,7 @@ ALTER SPACE apps WITH { new_cache_value: 1234 }
8793
### DROP SPACE
8894

8995
**Syntax:**
96+
9097
```sql
9198
DROP SPACE [IF EXISTS] [ALLOW NOT EMPTY] <space_name>
9299
```
@@ -96,9 +103,11 @@ DROP SPACE [IF EXISTS] [ALLOW NOT EMPTY] <space_name>
96103
- **A non-empty space cannot be dropped**
97104
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
98105
run:
106+
99107
```sql
100108
DROP SPACE ALLOW NOT EMPTY <space_name>
101109
```
110+
102111
- **Returns**:
103112
- empty or error
104113
- 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
126135
### CREATE MODEL
127136

128137
**Syntax**:
138+
129139
```sql
130140
CREATE MODEL [IF NOT EXISTS] <space_name>.<model_name>([primary] [null] field_name: field_type) [ WITH {property_name: property_value} ]
131141
```
142+
132143
- **Access control**: `root` only
133144
- **Properties**: None
134145
- **Operational notes**:
@@ -151,6 +162,7 @@ CREATE MODEL IF NOT EXISTS myspace.mymodel(username: string, password: string, n
151162
### ALTER MODEL ADD
152163

153164
**Syntax:**
165+
154166
```sql
155167
-- add a single field
156168
ALTER MODEL <space_name>.<model_name> ADD one_field { type: string }
@@ -165,6 +177,7 @@ ALTER MODEL <space_name>.<model_name> ADD (
165177
- **Returns**: empty or error
166178

167179
#### Examples
180+
168181
```sql
169182
ALTER MODEL myspace.mymodel ADD one_field { type: list { type: string } }
170183
ALTER MODEL myspace.mymodel ADD (
@@ -182,6 +195,7 @@ ALTER MODEL myspace.mymodel ADD (
182195
### ALTER MODEL UPDATE
183196

184197
**Syntax**
198+
185199
```sql
186200
-- update one field
187201
ALTER MODEL <space_name>.<model_name> UPDATE one_field { type: string }
@@ -210,6 +224,7 @@ ALTER MODEL myspace.mymodel UPDATE (
210224
### ALTER MODEL REMOVE
211225

212226
**Syntax**:
227+
213228
```sql
214229
-- remove one field
215230
ALTER MODEL <space_name>.<model_name> REMOVE one_field
@@ -232,6 +247,7 @@ ALTER MODEL myspace.mymodel REMOVE (useless_field_1, useless_field2)
232247
### DROP MODEL
233248

234249
**Syntax**:
250+
235251
```sql
236252
DROP MODEL [IF EXISTS] [ALLOW NOT EMPTY] <space_name>.<model_name>
237253
```
@@ -240,9 +256,11 @@ DROP MODEL [IF EXISTS] [ALLOW NOT EMPTY] <space_name>.<model_name>
240256
- **Operational notes**
241257
- **Non-empty models cannot be dropped** to avoid catastrophic drops
242258
- **To drop a non-empty model**: you must run:
259+
243260
```sql
244261
DROP MODEL ALLOW NOT EMPTY <space_name>.<model_name>
245262
```
263+
246264
- **Returns**:
247265
- empty or error
248266
- when used with `if exists`: bool indicating whether the model was actually present or not

docs/blueql/3.dml.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ INSERT INTO <model_name> {
2828
...
2929
}
3030
```
31+
3132
### Requirements and responses
3233

3334
- **Access control**: any

docs/blueql/4.dcl.md

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,17 @@ id: dcl
33
title: DCL
44
---
55

6-
Data Control Language or DCL can be used to perform administrative tasks on the database. Currently, all DCL commands are
6+
Data Control Language or DCL can be used to perform administrative tasks on the database. Currently, all DCL commands are
77
available under the `SYSCTL` query.
88

99
## SYSCTL REPORT STATUS
1010

1111
**Syntax**:
12+
1213
```sql
1314
SYSCTL REPORT STATUS
1415
```
16+
1517
- **Access control**: any
1618
- **Operational notes**:
1719
- This returns the current overall health of the system
@@ -20,15 +22,18 @@ SYSCTL REPORT STATUS
2022
## SYSCTL CREATE USER
2123

2224
**Syntax**:
25+
2326
```sql
2427
SYSCTL CREATE USER <username> WITH { password: 'password' }
2528
```
29+
2630
- **Access control**: `root` only
2731
- **Returns**: empty or error
2832

2933
## SYSCTL ALTER USER
3034

3135
**Syntax**:
36+
3237
```sql
3338
SYSCTL ALTER USER <username> WITH { password: 'new password' }
3439
```
@@ -44,8 +49,10 @@ Trying to change the `root` account password will throw an error. You can only c
4449
## SYSCTL DROP USER
4550

4651
**Syntax**:
52+
4753
```sql
4854
SYSCTL DROP USER <username>
4955
```
56+
5057
- **Access control**: `root` only
5158
- **Returns**: empty or error

docs/c.architecture.md

Lines changed: 19 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -4,18 +4,18 @@ title: Architecture
44
---
55

66
Skytable is a modern NoSQL database that prioritises performance, scalability and reliability while providing a rich and powerful querying interface.
7-
We are generally targetting an audience that wants to build high performance, large-scale, low latency applications, such as social networking services,
7+
We are generally targetting an audience that wants to build high performance, large-scale, low latency applications, such as social networking services,
88
auth services, adtech and such. Skytable is designed to work with both **structured and semi-structured data**.
99

10-
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
10+
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
1111
Skytable has been engineered from the ground up, from scratch.
1212

1313
And all of that, without you having to be an expert, and with the least maintenance that you can expect.
1414

1515
## Fundamental differences from relational systems
1616

17-
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
18-
distinction being the fact that Skytable has a NoSQL engine! But Skytable's evaluation and execution of queries is fundamentally different from SQL
17+
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
18+
distinction being the fact that Skytable has a NoSQL engine! But Skytable's evaluation and execution of queries is fundamentally different from SQL
1919
counterparts and even NoSQL engines. Here are some key differences:
2020

2121
- All DML queries are point queries and **not** range queries:
@@ -26,18 +26,18 @@ counterparts and even NoSQL engines. Here are some key differences:
2626
- **Remember, in NoSQL systems we denormalize.** Hence, no `JOIN`s or foreign keys as with many other NoSQL systems
2727
- A different transactional model:
2828
- All DDL and DCL queries are ACID transactions
29-
- However, DML transactions are not ACID and instead are efficiently batched and are automatically made part of a batch
30-
transaction. The engine decides *when* it will execute them, for example based on the pressure on cache. That's because our
29+
- However, DML transactions are not ACID and instead are efficiently batched and are automatically made part of a batch
30+
transaction. The engine decides *when* it will execute them, for example based on the pressure on cache. That's because our
3131
focus is to maximize throughput
3232
- 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
3333
queries *emulate* ACID transactions but that defeats the point of the eventually durable system which aims to heavily increase throughput.
34-
- The idea of eventually durable transactions relies on the idea that hardware failure even though prominent is still rare,
34+
- The idea of eventually durable transactions relies on the idea that hardware failure even though prominent is still rare,
3535
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.
3636
- 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
3737
- 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)
3838

3939
:::tip
40-
We believe you can now hopefully see how Skytable's workings are fundamentally different from traditional engines. And, we know
40+
We believe you can now hopefully see how Skytable's workings are fundamentally different from traditional engines. And, we know
4141
that you might have a lot of questions! If you do, please reach out. We're here to help.
4242
:::
4343

@@ -52,18 +52,19 @@ While a `MODEL` is the only data container for now, many more are set to come. N
5252

5353
### A `space` is like a `database`
5454

55-
A `space` in Skytable is a collection of `model`s and other objects, and settings. It is different from a traditional SQL
55+
A `space` in Skytable is a collection of `model`s and other objects, and settings. It is different from a traditional SQL
5656
Database (that is created with SQL's `CREATE DATABASE`) because it is not meant for tables only, but many other things.
5757

5858
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.
5959

6060
### A `model` is like a `table`
6161

6262
A `model` in Skytable is like a `table` in SQL but is vastly different because of certain concepts such as:
63+
6364
- DML queries are point and not range queries by default
6465
- Restrictions on indexes
6566
- Settings (which can't be created in traditional `table`s)
66-
- Semi-structured data: with collection types in columns such as lists and dictionaries that violates some of the ideas of
67+
- Semi-structured data: with collection types in columns such as lists and dictionaries that violates some of the ideas of
6768
traditional schema enforcement
6869

6970
## Query language
@@ -75,13 +76,13 @@ For example, Skytable's BlueQL<sup>TM</sup> *only* allows the parameterization o
7576
## Transactions
7677

7778
Skytable's DDL and DCL queries are all ACID transactions. However, DML queries use an AOF-style storage driver that periodically
78-
records, analyses and then intelligently syncs the changes to disk. We're working on making ACID transactions widely available
79+
records, analyses and then intelligently syncs the changes to disk. We're working on making ACID transactions widely available
7980
across DML queries as well.
8081

8182
## Storage
8283

83-
Skytable's storage engine is collectively called the Skytable Disk Storage Subsystem or SDSS for short. The storage engine uses
84-
several different storage drivers, using ones appropriate for the task. We do not use RocksDB or any other engine but we
84+
Skytable's storage engine is collectively called the Skytable Disk Storage Subsystem or SDSS for short. The storage engine uses
85+
several different storage drivers, using ones appropriate for the task. We do not use RocksDB or any other engine but we
8586
implement everything in house, engineering them piece by piece.
8687

8788
:::info Features on track
@@ -103,8 +104,9 @@ Skytable will use atleast as many threads as the number of logical CPUs present
103104

104105
## Networking
105106

106-
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
107+
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
107108
TCP client to use it without issues. There are three phases in the connection:
109+
108110
- Handshake: All auth data, compatibility information and other data is exchanged at this step
109111
- Connection mode selection: based on the handshake parameters a connection mode is chosen and the server responds with the chosen exchange mode
110112
- Data exchange: This is where the real querying happens
@@ -115,14 +117,16 @@ You can [read more about the protocol here](protocol).
115117
## Backwards compatibility
116118

117119
We make the promise to you that no matter what changes in Skytable, you will always be able to:
120+
118121
- Upgrade from one version to another without data loss or too many hoops
119122
- Export data from Skytable at any time
120123

121124
More technically:
125+
122126
- **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**
123127
- **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**.
124128
- Definitions (closely following semantic versioning):
125-
- **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
129+
- **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
126130
bump)
127131
- **A minor release** is something like `1.0.0` to `1.1.0` or `0.8.0` to `0.8.1`
128132
- **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)

docs/deployment.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ title: Deployment
44
---
55

66
Here are some recommendations for deployment:
7+
78
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.
89
2. **When deploying on docker**:
910
- 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`

0 commit comments

Comments
 (0)