keyvalue-db

fast, secure, private, and memory leak resistant in-memory key-value js-sqlite based datastore or database that supports tcp mtls (tls), and a command shell (without or with [todo] authentication)

indevelopment - use in production with caution

please note:

• redis-like is an inference most of the shell commands are like redis but a few changes have been made to accomodate the architecture.
• you can run the index.js using the below commands or package it into a executable to run as a executable
• to run as executable run npm run build

FEATURES

• ✓ runs in ✓tcp tls, or ✓tcp mtls, or ✒️ws, or ✒️wss (in development for tests)
• ✓ runs a database or shell mode with ✓redis-like commands (in development)
• ✓ has a nodejs client api.
• ✓ has a python client api.
• ✒️ has a php client api.
• ✒️ any programming language that supports tcp tls, tcp mtls requests can be used as a client [todo add request structure and parameters to docs]

Watch the comprehensive video

Server Database Documentation

🖥️ Server Mode Prefixes

The following command-line arguments are used when running the application in server mode (-s server):

TLite is a lightweight, TLS-encrypted, in-memory SQLite database system designed for speed and security. It features periodic disk persistence, robust search modes, and a dynamic interactive shell.

1. Server Startup Prefixes

The server manages the database state in memory and handles periodic synchronization to the disk.

| Prefix | Description | Default | | :--- | :--- | :--- | | -p, --port | Port to listen on. | 9999 | | -ip, -h | IP address to bind to. | 127.0.0.1 | | -dt | Persistence interval (e.g., 10s, 1m, 1h2m). | 60s | | --dump-file | Primary file for startup load and periodic saving. needed for final graceful shutdown. | None | | -l, --load | Secondary file (used if --dump-file is missing). | data.sqlite | | -ca | Path to CA certificate. | ca.crt | | -c, --cert | Path to Server certificate. | server.crt | | -k, --key | Path to Server private key. | server.key | | -s, --mode | --mode db will start in database mode | shell | | -lp, --log-prefix | the logger file path. logger follows the structure: [Timestamp] [Remote_IP] [Command] [Status] "Message" | --dump-file or working directory |

Example Command:

node index.js --mode db -h localhost -p 8000 -dt 5m --dump-file data.sqlite --cert "./certs/server.crt" --key "./certs/server.key" --ca-cert "./certs/ca.crt"

💻 Shell Client Mode Prefixes

The following command-line arguments are used when running the application in shell mode (-s shell):

2. Client Startup Prefixes

The client provides a secure interactive shell. The prompt is dynamically generated only after a successful connection to ensure the displayed port is accurate: user@host:port>.

| Prefix | Description | Default | | :--- | :--- | :--- | | -p, --port | The port the server is listening on. | 9999 | | -ip, -h | The server's IP address or hostname. | 127.0.0.1 | | -ca | Path to the CA certificate for server verification. | ca.crt | | -c | Path to the Client certificate for authentication. | client.crt | | -k | Path to the Client private key. | client.key | | --mode , -s | will start in database shell mode | --mode shell |

Startup Example:

node index.js --mode shell -h localhost -p 8000 --cert "./certs/client.crt" --key "./certs/client.key" --ca-cert "./certs/ca.crt"

Architecture of kvdb - Basic Storage

How Synchronization (Dumping) Happens

The script implements exactly the three triggers you requested:

• Interval-based Sync: The setInterval function runs a VACUUM INTO command every $X$ seconds (defined by the -dt flag). This creates a consistent snapshot of the memory state into the disk file without locking the database for users.
• Graceful Exit Sync: The handleShutdown function captures SIGINT (Ctrl+C) and SIGTERM. It executes a final synchronous dump to the disk file before the process terminates.
• Crash Recovery Sync: The uncaughtException listener acts as a safety net. If the Node.js process encounters a fatal error, it attempts one last emergency dump to prevent data loss.

Shell Commands

| Command | Alias | Syntax | Description | | :--- | :--- | :--- | :--- | | set | write | set <key> <value> | Sets a single key with a string, number, or JSON value. Note: The value is everything after the key and first space. | | get | read | get <key> | Retrieves and prints the value associated with the specified key. | | del | deletekey | del <key> | Deletes the key-value pair from the store. | | has | hasKey | has <key> | Checks if a key exists in the store (returns true or false). | | init | | init -cmd <JSON String> or init -f <filename> | REPLACES the entire store with the provided JSON object or the contents of a local file. | | load | load | load -f <JSON> or load -f <filename> | MERGES the provided JSON object or file contents into the existing store. | | clear | | clear | Clears the entire in-memory store (same as init {}). Use with caution. | | search | | search <criteria> | Searches for the criteria in Keys AND Values. | | searchkey | | searchkey <criteria> | Searches for the criteria in Keys Only. | | searchvalue | | searchvalue <criteria> | Searches for the criteria in Values Only. | | dump | | dump | Retrieves the entire store data and prints it to the shell console. | | dump | | dump -f <filename> | Instructs the server to save the current store to the specified filename on the server's disk. | | list | | list -n <count> | Lists all records in the current table. Use -n to enable pagination (e.g., list -n 10). Action: Press ENTER at the pagination prompt to load the next batch. | | sql | | sql -cmd <sql command> | Executes raw SQL against the in-memory database. Use backticks for the query | | use | | use <tablename> | use the context of which table/ database is being used for key-value store | | drop | | drop <tablename> | drop the context of which table/ database is being mentioned. tables are given a context of key-value database | | exit | quit | exit | Disconnects the shell client and quits. | | help | | help | Displays the help menu. |

set

> set <key> <value>

example> set testvalue

example> set test 10

get

> get <key>

example> get test

del

> del <key>

example> del test

has

> has <key>

example> has test

search

> search <string>

example> search test

search

> searchvalues <string>

example> searchvalues 10

search

> searchkeys <string>

example> searchkeys test

search

> search <string>

example> search test

load

> load -f <filename>

example> load -f "./dump/filename.json"

load

> load <jsonobject>

example> load "{'test': 10}"

read

> read <key>

example> read test

clear

> clear

example> clear

init

> init -f <filename>

example> init -f "./dump/filename.json"

init

> init <jsonobject>

example> init "{'test': 10}"

update

> update -f <filename>

example> update -f "./dump/filename.json"

update

> update <jsonobject>

example> update "{"test": 10}"

del

> del <key>

example> del test

dump

> dump -f "<filename/within/quotes>"

example> dump -f "./dump/filename.json"

TODO

add docs for other features