octoleo/telegram-bot-bash
1
1
Fork 0
mirror of https://github.com/octoleo/telegram-bot-bash.git synced 2024-06-20 02:42:19 +00:00
Code Issues Projects Releases Wiki Activity

doc: improve jsshDB description

Browse Source
This commit is contained in:
Kay Marquardt (Gnadelwartz) 2020-12-29 11:16:14 +01:00
parent cf6f3eedd7
commit fee0615c28
1 changed files with 14 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
doc/6_reference.md
View File

@ -580,28 +580,25 @@ Usually a message is automatically forwarded from within `commands.sh`, but you
---- ----
### jsshDB ### jsshDB
Since output generated by JSON.sh is so handy to use in bash, we use the format for a simple keys/value file store.
The file extensions is '.jssh' and for security reasons location of jssh files is restricted to BASHBOT_ETC and BASHBOT_DATA.. Since output generated by `JSON.sh` is so easy to use in bash, bashbot uses the format for a simple keys/value file store also.
#### fast and slow operations #### fast and slow operations
jsshDB files are simple text files and if you append a new Key/value pairs to the end of the file it overwrites jsshDB files are text files, key/value pairs appearing later in the file overwrites earlier key/value pairs in the file.
an existing key/value pair. We use this behavior for "fast" file operations. Bashbot use this behavior to implement "fast" file operations.
"fast functions" add a new key/value pair to the end of the file without deleting an existing one, this is fast but over (long) "fast functions" add a new key/value pair to the end of a file without deleting an existing one, this is fast but over time the file grows to infinity.
time the file grows infinity.
"slow functions" in contrast modify the key/value pairs in place and write the whole file back, "slow functions" read the file, modify the key/value pairs in memory and write the whole file back, this is slower but removes duplicate keys from the file.
this is slower but clean up the file. All previously added key/value pairs are replaced
and only the last one is written back to the file.
fast functions: Fast functions:
``` ```
jssh_insertKeyDB , jssh_addKeyDB , jssh_countKeyDB jssh_insertKeyDB , jssh_addKeyDB , jssh_countKeyDB
``` ```
slow functions: Slow functions:
``` ```
jssh_writeDB, jssh_updateDB , jssh_deleteKeyDB, jssh_clearDB jssh_writeDB, jssh_updateDB , jssh_deleteKeyDB, jssh_clearDB
@ -610,17 +607,17 @@ slow functions:
#### File naming and locking #### File naming and locking
A jssh fileDB consists of two files which must reside inside `BASHBOT_ETC` or `BASHBOT_DATA`. A jssh fileDB consists of two files and must reside inside `BASHBOT_ETC` or `BASHBOT_DATA`.
- `filename.jssh` is a text file containing the key/value data in json.sh format. - `filename.jssh` is the file containing the key/value pairs in json.sh format.
- `filename.jssh.flock` is used for read/write locking with flock - `filename.jssh.flock` is used to provide read/write locking with flock
Path names containing `..` or not located in `BASHBOT_ETC` or `BASHBOT_DATA` are refused by jsshDB functions with an error. Path names containing `..` or not located in `BASHBOT_ETC` or `BASHBOT_DATA` are refused by jsshDB functions with an error.
jsshDB functions use file locking with flock, if flock is availible. Write/update operations are serialised to wait until jsshDB functions use file locking with flock if flock is available. Write/update operations are serialised to wait until
previous operations are finished, see "man flock". To avoid deadlocks bashbot use a timeout of 10s for write and 5s for read operations. previous operations are finished, see "man flock". To avoid deadlocks bashbot use a timeout of 10s for write and 5s for read operations.
For every `jssh_...DB` function a `jsshj_...DB_async` function exsist also. In case don't want locking, use `jssh_...DB_async` functions. For every `jssh_...DB` function a `jsshj_...DB_async` function exists also. In case don't want locking, use `jssh_...DB_async` functions.
*Example:* for allowed file names: *Example:* for allowed file names:
```bash ```bash
@ -1149,5 +1146,5 @@ The name of your bot is available as bash variable "$ME", there is no need to ca
#### [Prev Best Practice](5_practice.md) #### [Prev Best Practice](5_practice.md)
#### [Next Notes for Developers](7_develop.md) #### [Next Notes for Developers](7_develop.md)
#### $$VERSION$$ v1.21-dev-29-g13d15f4 #### $$VERSION$$ v1.21-dev-30-gcf6f3ee