docs

Author: gggeek

README.md

@@ -5,7 +5,7 @@ A platform dedicated to ease comparison of databases:
 
 a) allow testing compatibility of SQL snippets across many different databases and versions
 
-b) allow doing full-fledged performance testing, comparing results across many db versions
+b) allow doing full-fledged performance testing, comparing resource usage across many db versions
 
 
 *** Work In Progress ***
@@ -55,7 +55,6 @@ NB: if you don't have a bash shell interpreter on your host computer, look at th
 the host computer, please change variables COMPOSE_WEB_LISTEN_PORT_HTTP and COMPOSE_WEB_LISTEN_PORT_HTTPS in file
 docker/.env
 
-
 ### Usage
 
 Example: executing the sql statement `select current_date` in parallel on all databases:
@@ -130,15 +129,46 @@ After starting the containers via `./bin/stack.sh build`, you can:
 *NB*: if the `stack.sh` command fails, you can use `docker` and `docker-compose` commands for troubleshooting.
 See the section 'Alternative commands to stack.sh' below for examples.
 
-
 ### Maintenance
 
 3 scripts are provided in the top-level `bin` folder to help keeping disk space usage under control
 
+### How does this work?
+
+The command-line tool `dbconsole`, as well as the web interface are built in php, using the Symfony framework.
+
+Docker is used to run the app:
+
+- each db instance runs in a dedicated container (except SQLite)
+- one container runs the web interface
+- one container runs the command-line tools which connect to the databases
+- one container runs Adminer, a separate, self-contained db administration app, also written in php
+
+Docker-compose is used to orchestrate the execution of the containers, ie. start, stop and connect them.
+
+The data files and logs of all the database instances are stored on the disk of the host computer, and mounted as
+volumes into the containers running the databases.
+
+All the interactions between `dbconsole` and the databases happen, at the moment, through execution of the native
+command-line database client (`psql`, `sqlcmd`, etc...). Those clients are executed in parallel as independent processes
+from the `dbconsole`.
+
+This design has the following advantages:
+
+- parallel execution of queries across all database instances to reduce the total execution time
+- it does not let the warts of php database-connectors influence the results of query execution
+- it can easily expand to run queries on multiple database types, even those not supported by php
+
+On the other hand it comes with some serious drawbacks as well, notably:
+
+- parsing the data sets which result from a SELECT query from the output of a command-line tool is an exercise in pointlessness
+
+More details about advanced use cases are given in the section below.
+
 
 ## FAQ
 
-See the [FAQ](./doc/FAQ.md) for more details
+See the separate [FAQ](./doc/FAQ.md) document.
 
 
 ## Alternative commands to stack.sh

doc/TODO.md

@@ -11,9 +11,6 @@
 
 ## Major features
 
-- test execution of a sql command which creates a table with a few cols (string, int, ...), inserts a couple of lines
-  (ascii chars, utf8 basic plane, utf8 multilingual plane) and then selects data from it
-
 - host: allow building/starting partial docker stack for speed and resources (eg. no oracle, no sqlserver, etc...)
   Being able to start a single 'db type' might also make sense in parallelization of tests on travis.
 
@@ -68,6 +65,9 @@
 
 ## Improvements
 
+- use '-t' options for mysql client ?
+  + investigate the possibility of having the clients emitting directly json results instead of plaintext
+
 - improve travis testing:
   + add tests: ...
   + use 'bats' for shell-driven tests?
@@ -77,6 +77,8 @@
 - improve handling of character sets:
   + allow to use utf16, utf16le, utf16ber as encodings for sqlite
   + add more support for 'universal' charset/collation naming
+ + test execution of a sql command which creates a table with a few cols (string, int, ...), inserts a couple of lines
+   (ascii chars, utf8 basic plane, utf8 multilingual plane) and then selects data from it
 
 - worker: some failures in (temp) db removal are not reported, some are (eg. on mysql, for non existing db).
   make it more uniform ?

doc/WHATSNEW.md

@@ -1,17 +1,17 @@
-Version 0.? (unreleased)
-------------------------
+Version 0.9
+-----------
 
 - Improved: `stack.sh start` and `stack.sh stop` can now start/stop a single container
 
-- Improved: lots of refactoring under the hood, laying the groundwork for more functionality in the future
-
 - Improved: the `instance:list` command now returns database vendor and version for each defined db instance.
   NB: the database version is gotten from querying the databases themselves, rather than relying on configuration
   (unlike the data shown in the web interface, which still relies on the values manually set in config files)
 
 - Improved: the `collation:list`, `database:list` and `user:list` commands now return a more structured output, which
   is better for non-text output formats such as json
 
+- Improved: lots of refactoring under the hood, laying the groundwork for more functionality in the future
+
 
 Version 0.8
 -----------