add documentation version 4

Author: Simone Mosciatti

doc/docs/index.md

@@ -2,23 +2,31 @@
 
 [RediSQL][github] is a Redis module that embeds a fully functional SQLite database.
 
-At the best of our knowledge is the only system that provides SQL capabilities while being very fast so to be used as cache, simple to integrate with any programming language, since it can be used by every redis client, and with very very low maintenance.
+At the best of our knowledge is the only system that provides SQL capabilities while being very fast so to be used as a cache, simple to integrate with any programming language, since it can be used by every redis client, and with very very low maintenance.
 
-Moreover, for small, not critical services, it can also be used as main database, it can store data not only in memory but also on file and it can also use the same persistency mechanisms of redis itself.
+Moreover, for small, not critical services, it can also be used as the main database, it can store data not only in memory but also on file and it can also use the same persistence mechanisms of redis itself.
 
-## Motivation
+## Obtain
 
-The main motivation behind the project is to provide a quick and hands-off environment to store structured data.
+There are **two version** of the software, a "community", completely open source version and a PRO version that comes with **more features and support plan.**
 
-It also turns out that RediSQL is a great way to cache your content and data in a more structured way.
+Both versions can be [**obtained in the store.**][store]
 
-Anyway, the main history and motivation of the project are explained [in this page.][motivations]
+For the community version, you can just download it, we ask for a small donation if you can support the project but feel free to just input 0€ and download it.
 
-## Sustainable Open Source
+For the PRO version you need to [**sign up here**][signup], after you signed up you will be able to download the software.
 
-The project is based on the idea of sustainable Open Source.
+A detailed coverage of the PRO version [is provided here][pro]
 
-The project provides two versions, an open source one, which is enough for most simple projects, and a PRO version that provides features required from companies and enterprises.
+The motivations of why we decided to sell a PRO version and about its price are [here][pro_motivations] and we hope that you agree on our points.
+
+## Motivation
+
+The main motivation behind the project is to provide a quick and hands-off environment to store structured data.
+
+It also turns out that RediSQL is a great way to cache your content and data in a more structured way.
+
+The main history and motivation of the project are explained [in this page.][motivations]
 
 # Overview
 
@@ -53,18 +61,18 @@ The phase of compilation can be quite expensive, but if you always execute the s
 
 When you use [`REDISQL.CREATE_STATEMENT`][r:create_statement] your statement is compiled, then when you execute it using [`REDISQL.EXEC_STATEMENT`][r:exec_statement] it is not re-compiled but we use the pre-compiled one. It seems a trivial change but it will really speed up some workload.
 
-Statements can also be used as an interface for different application using the same RediSQL instance.
+Statements can also be used as an interface for different applications using the same RediSQL instance.
 
-Once you define the interface of the statement and its behavior, then you are free to change it's implementation while maintaining all the legacy code working.
+Once you define the interface of the statement and its behaviour, then you are free to change it's implementation while maintaining all the legacy code working.
 This is quite useful especially if you have several services using the same RediSQL instance.
 
 ## Query
 
-In most databases there are statements that modify the data and queries that simply reads.
+In most databases there are statements that modify the data and queries that simply read.
 
-Of course, just reading, is usually a faster and simpler operation than modify the data. In order to take advantages of this we provide a different command `REDISQL.QUERY` and `REDISQL.QUERY_STATEMENT` that constraint you to don't modify the data.
+Of course, just reading, is usually a faster and simpler operation than modify the data. In order to take advantages of this, we provide a different command [`REDISQL.QUERY`][r:query] and [`REDISQL.QUERY_STATEMENT`][r:query_statement] that constraint you to don't modify the data.
 
-This commands allow you to have slaves serves query and to balance some load off the master node for better speed and reliability.
+These commands allow you to have slaves/replicas serves query and to balance some load off the master node for better speed and reliability.
 
 # Persistency
 
@@ -80,26 +88,34 @@ When Redis starts to save the RDB file the status of the database get serialized
 
 AOF replication is provided only in the PRO edition.
 
-All the commands are replicated, but the read only ones.
+All the commands are replicated, but the read-only ones.
 
-With AOF replication you also get instance replication that allows replicating the same dataset into different Redis instances in a master slave fashion.
+With AOF replication you also get instance replication that allows replicating the same dataset into different Redis instances in a master/slave fashion.
 
 # PRO
 
-The PRO edition is based on the Open Source one, however it provides one more class of commands that are necessary for bussinesses or where rediSQL is a critical piece of the infrastructure.
+The PRO edition is based on the Open Source one, however, it provides one more class of commands that are necessary for business or where rediSQL is a critical piece of the infrastructure.
 
 Every command, but `REDISQL.CREATE_DB`, blocks the clients and it is executed in the background by a different thread.
 
-With the PRO edition we also provide the `.NOW` commands that are executed immediately without blocking the client.
+With the PRO version, we also provide the `.NOW` commands that are executed immediately without blocking the client.
 
-Basically every command in the PRO version provides the `.NOW` variant, but please refer to the [reference][ref].
+Every command in the PRO version provides the `.NOW` variant, but please refer to the [reference][ref].
 
 Moreover, the PRO version also provides AOF replication, that, indeed, necessitate of commands that don't block the clients.
 
+More information about the PRO version are available [here.][pro]
+
 [github]: https://github.com/RedBeardLab/rediSQL
 [ref]: references.md
 [r:create_db]: references.md#redisqlcreate_db
 [r:exec]: references.md#redisqlexec
 [r:create_statement]: references.md#redisqlcreate_statement
 [r:exec_statement]: references.md#redisqlexec_statement
+[r:query]: references.md#redisqlquery
+[r:query_statement]: references.md#redisqlquery_statement
 [motivations]: motivations.md
+[store]: https://plasso.com/s/epp4GbsJdp-redisql
+[signup]: https://plasso.com/s/epp4GbsJdp-redisql/signup/
+[pro]: pro.md
+[pro_motivations]: pro_motivations.md

doc/docs/pro.md

@@ -0,0 +1,81 @@
+# RediSQL PRO
+
+This document explains the architecture and principle of working of RediSQL PRO.
+
+You can purchase RediSQL PRO, along with support [**here.**][signup]
+
+Motivation and details about the cost are [described here][pro_motivations].
+
+## Main difference
+
+The PRO version offers two main features: **non blocking command** and **replication**
+
+### Non-blocking command
+
+Most command in RediSQL, all but `REDISQL.CREATE_DB`, are blocking command.
+
+This means that Redis block the client, pass the command to a background thread that actually executed it and finally the result is returned to client unblocking it.
+
+This works great in most cases, the main thread of Redis is free of doing other work (like answering standard redis command), there is no difference from the client point of view and your machine can use more than the single thread of redis to work for you.
+
+However, sometimes you want to have non-blocking commands.
+
+The blocking command will be executed in the main redis thread, this means that no other works will be done by Redis while executing your command.
+
+We could expect the non-blocking command to be slightly faster (smaller latency) than the blocking one since there is no need for coordination between threads.
+
+Finally, non-blocking commands are necessary for replication.
+
+Non-blocking commands are invoke adding the `.NOW` suffix.
+
+As an example, instead of `REDISQL.EXEC` that is a blocking command you can use `REDISQL.EXEC.NOW` to use the non-blocking version.
+
+#### When to use non-blocking commands
+
+Non-blocking command takes the priority over blocking one.
+
+Said so, generally, we are expecting users to use mostly the blocking commands.
+
+However, if you need a very quick insert or a very quick lookup, then you should use the non-blocking version.
+
+It is a bad idea to use non blocking commands for slow statements/query.
+
+This because while you are executing a non-blocking command the main redis thread cannot do anything else, this means it cannot answer other redis commands.
+
+### Replication
+
+Redis offers two main methods for persisting data on disk so that in case of power failure of disastrous failure your data are reasonably safe.
+
+RediSQL implement RDB persistency on the community version and AOF replication on the PRO version.
+
+For the details of this two method, I suggest to read the Redis Documentation [on this page][redis_persistence].
+
+The mechanism behind AOF replication is exactly the same behind cluster replication used by redis. The same **bytes** used for AOF replication are also used for cluster replication, just send over different sockets.
+
+For details about cluster replication you can consult the official Redis Documentation on [cluster][redis_cluster] and on [replication][redis_replication]
+
+The PRO version, indeed, implements both AOF and cluster replication.
+
+#### Effective use of Replication
+
+In order to use replication effectively, you should understand a few simple concepts.
+
+If a command is replicated it means that it could be re-executed.
+
+It is **vital** to replicate commands that change the data you are storing, however, is pointless and wasteful to replicate commands that do not apply any change to the data.
+
+You definitely want to replicate every INSERTs, UPDATEs or DELETEs while you should avoid replicating SELECTs.
+
+Replicated commands are usually executed either when you are re-loading your dataset after some sort of failures or in slaves/replica with a train of other replicated commands is coming right after.
+
+Consider what happens if you replicate a big SELECT. RediSQL is going to execute it and it is going to take some time, this while your application is waiting for redis to restart or when a train of replicated commands are piling up in the slaves/replicas buffers. And all this just for discard the result of the SELECT itself.
+
+In order to avoid this effect is a good idea to use the query commands whenever possible ([`REDISQL.QUERY`][query] and [`REDISQL.QUERY_STATEMENT`][query_statement]), this command **do not** replicate and are marked as `readonly` which means that can be executed also on slaves/replicas providing interesting primitives of load balancing. (Eg. You could write on the master and read on the slaves.)
+
+[query]: references.md#redisqlquery
+[query_statement]: references.md#redisqlquery_statement
+[pro_motivations]: pro_motivations.md
+[redis_persistence]: https://redis.io/topics/persistence
+[signup]: https://plasso.com/s/epp4GbsJdp-redisql/signup/
+[redis_cluster]: https://redis.io/topics/cluster-tutorial
+[redis_replication]: https://redis.io/topics/replication

doc/docs/pro_motivations.md

@@ -0,0 +1,62 @@
+# RediSQL PRO Motivation
+
+This document explains why we decide to offer a commercial PRO version alongside the free and open source community version.
+
+## tl;dr;
+
+* We sell a PRO version to make the project sustainable.
+* You can buy the PRO version [**here.**][signup]
+* We offer custom license term if your company need one.
+
+## Necessity to make the project sustainable
+
+We believe that in order to provide the most value Open Source should be sustainable.
+
+Design, implementation and testing are all necessary and valuable steps of any software project, but they do require time.
+
+Open sources projects that are able to really deliver value need to find a way to remunerate the time of their maintainers.
+
+Some successful open source projects are backed by companies (Firefox, React, etc...), other sell supports (mongodb, vernemq, etc...) and other plug their software into a commercial offer (npm, docker, elatic, etc...).
+
+## Our approach
+
+In order to provide a open source, our approach is to offer two different product, a completely free open source one and a PRO version.
+
+Selling the PRO version allows us to dedicate most of the time to the project, having a good work-life balance, enjoy time with our girlfriends, wives or kids and being productive developers and technical writers.
+
+## Benefits for organizations and for the community
+
+Moreover, we believe that this is the best way to serve our users and the community.
+
+Indeed, we are able to maintain the project through the years so that any company or organization that decide to use our product will know that in 3/4/5 years we will still be there to help them if any problem should arise.
+
+On top of this also single programmers, very small start-ups or small companies will benefit from us keeping maintaining the product in its two form, community and pro.
+
+You can support us and buy the commercial version of this product [on this web page.][signup]
+
+We also offer **custom license terms** if your organization needs one.
+
+## About the cost
+
+We set up the cost (€990 / year) to make it a bargain for every company that actually uses it.
+
+Considering the amount of time necessary to replicate the PRO features:
+
+1. Understand the working principle of Redis
+2. Understand SQLite and how to leverage it
+3. Understand the Redis Module API
+4. Design the product
+5. Implement it
+6. Test it
+7. Document it
+8. Maintain it
+
+Multiply it by the hourly rate of a software engineer (~100 €/hours).
+
+It is clear that after a little more than a single day of work our product will be a net positive for your organization.
+
+Moreover, the PRO version comes with **support plan** to help you extract the most value out of the product.
+
+Finally, we offer custom, business-friendly licenses if your business or lawyers need them.
+
+[signup]: https://plasso.com/s/epp4GbsJdp-redisql/signup/