doc: support postgres

Author: nalgeon

README.md

@@ -1,17 +1,28 @@
 <img alt="Redka" src="logo.svg" height="80" align="center">
 
-Redka aims to reimplement the core parts of Redis with SQLite, while remaining compatible with Redis API.
+Redka aims to reimplement the core parts of Redis with SQL, while remaining compatible with Redis API.
 
 Notable features:
 
--   Data does not have to fit in RAM.
--   ACID transactions.
--   SQL views for better introspection and reporting.
--   Both in-process (Go API) and standalone (RESP) servers.
--   Redis-compatible commands and wire protocol.
+-   Data doesn't have to fit in RAM.
+-   Supports ACID transactions.
+-   SQL views for easier analysis and reporting.
+-   Works with both SQLite and PostgreSQL (coming v0.6.0) backends.
+-   Runs in-process (Go API) or as a standalone server.
+-   Redis-compatible commands and wire protocol (RESP).
 
 Redka is [functionally ready](docs/roadmap.md) for 1.0. Feel free to try it in non-critical production scenarios and provide feedback in the issues.
 
+## Use cases
+
+Here are some situations where Redka might be helpful:
+
+_Embedded cache for Go applications_. If your Go app already uses SQLite or just needs a simple, built-in key-value store, Redka is a natural fit. It gives you Redis-like features without the hassle of running a separate server. The cache persists across application restarts, and backup is as easy as copying a file.
+
+_Lightweight testing environment_. Your app uses Redis in production, but setting up a Redis server for local development or integration tests can be a hassle. Redka, when used with an in-memory SQLite database, gives you a fast alternative with complete isolation for each test run.
+
+_Postgres-first data structures_. If you prefer to use PostgreSQL for everything but need Redis-like data structures (like lists and sorted sets), Redka can use your existing database as the backend. This way, you can manage both relational data and specialized data structures with the same tools and transactional guarantees.
+
 ## Commands
 
 Redka supports five core Redis data types:
@@ -31,17 +42,21 @@ Redka comes in two flavors:
 -   Standalone Redis-compatible server: [installation](docs/install-standalone.md), [usage](docs/usage-standalone.md).
 -   Go module for in-process use: [installation](docs/install-module.md), [usage](docs/usage-module.md).
 
+## Storage
+
+Redka can use either SQLite or PostgreSQL as its backend. It stores data in a [SQL database](docs/persistence.md) with a simple schema and provides views for better introspection.
+
 ## Performance
 
-According to the [benchmarks](docs/performance.md), Redka is several times slower than Redis. Still, it can do up to 100K op/sec on a Macbook Air, which is pretty good if you ask me (and probably 10x more than most applications will ever need).
+Redka is not about raw performance. You can't beat a specialized data store like Redis with a general-purpose relational backend like SQLite. However, Redka can still handle tens of thousands of operations per second, which should be more than enough for many apps.
 
-Redka stores data in a [SQLite database](docs/persistence.md) with a simple schema and provides views for better introspection.
+See the [benchmarks](docs/performance.md) for more details.
 
 ## Contributing
 
 Contributions are welcome. For anything other than bugfixes, please first open an issue to discuss what you want to change.
 
-Be sure to add or update tests as appropriate.
+Make sure to add or update tests as needed.
 
 ## Acknowledgements
 

docs/install-module.md

@@ -6,12 +6,18 @@ Install the module as follows:
 go get github.com/nalgeon/redka
 ```
 
-You'll also need an SQLite driver. Use one of the following:
+You'll also need an SQLite or PostgreSQL driver.
+
+Use one of the following for SQLite:
 
 -   `github.com/mattn/go-sqlite3` (CGO, fastest)
 -   `github.com/ncruces/go-sqlite3` (pure Go, WASM)
--   `github.com/tursodatabase/go-libsql` (CGO)
--   `modernc.org/sqlite` (pure Go)
+-   `modernc.org/sqlite` (pure Go, libc port)
+
+Or one of the following for PostgreSQL:
+
+-   `github.com/lib/pq`
+-   `github.com/jackc/pgx/v5`
 
 Install a driver with `go get` like this:
 

docs/performance.md

@@ -7,46 +7,72 @@ I've compared Redka with Redis using [redis-benchmark](https://redis.io/docs/man
 -   10000 randomized keys
 -   GET/SET commands
 
-SQLite settings:
-
-```
-pragma journal_mode = wal;
-pragma synchronous = normal;
-pragma temp_store = memory;
-pragma mmap_size = 268435456;
-pragma foreign_keys = on;
-```
-
-Hardware: Apple M1 8-core CPU, 16GB RAM
+## Results
 
 Redis:
 
-```
+```text
 redis-server --appendonly no
 redis-benchmark -p 6379 -q -c 10 -n 1000000 -r 10000 -t get,set
 
 SET: 133262.25 requests per second, p50=0.055 msec
 GET: 139217.59 requests per second, p50=0.055 msec
 ```
 
-Redka (in-memory):
+Redka (SQLite, in-memory):
 
-```
+```text
 ./redka -p 6380
 redis-benchmark -p 6380 -q -c 10 -n 1000000 -r 10000 -t get,set
 
 SET: 36188.62  requests per second, p50=0.167 msec
 GET: 104405.93 requests per second, p50=0.063 msec
 ```
 
-Redka (persisted to disk):
+Redka (SQLite, persisted to disk):
 
-```
-./redka -p 6380 data.db
+```text
+./redka -p 6380 redka.db
 redis-benchmark -p 6380 -q -c 10 -n 1000000 -r 10000 -t get,set
 
 SET: 26773.76  requests per second, p50=0.215 msec
 GET: 103092.78 requests per second, p50=0.063 msec
 ```
 
-So while Redka is 2-5 times slower than Redis (not surprising, since we are comparing a relational database to a key-value data store), it can still do 26K writes/sec and 94K reads/sec, which is pretty good if you ask me.
+Redka (PostgreSQL):
+
+```text
+./redka -p 6380 "postgres://redka:redka@localhost:5432/redka?sslmode=disable"
+redis-benchmark -p 6380 -q -c 10 -n 100000 -r 10000 -t get,set
+
+SET: 11941.72 requests per second, p50=0.775 msec
+GET: 25766.55 requests per second, p50=0.359 msec
+```
+
+So while Redka is noticeably slower than Redis (not surprising, since we are comparing a relational database to a key-value data store), it can still handle tens of thousands of operations per second. That should be more than enough for many apps.
+
+## Environment
+
+Hardware: Apple M1 8-core CPU, 16GB RAM
+
+SQLite settings:
+
+```text
+pragma journal_mode = wal;
+pragma synchronous = normal;
+pragma temp_store = memory;
+pragma mmap_size = 268435456;
+pragma foreign_keys = on;
+```
+
+PostgreSQL settings:
+
+```text
+checkpoint_completion_target=0.9
+effective_cache_size=4GB
+maintenance_work_mem=512MB
+max_wal_size=1GB
+random_page_cost=1.1
+shared_buffers=1GB
+wal_buffers=16MB
+```

docs/persistence.md

@@ -1,6 +1,6 @@
 # Persistence
 
-Redka stores data in a SQLite database using the following tables:
+Redka stores data in a SQL database using the following tables:
 
 ```
 rkey

docs/usage-module.md

@@ -96,5 +96,4 @@ Redka supports the following SQLite drivers:
 
 -   `github.com/mattn/go-sqlite3` ([example](../example/simple/main.go))
 -   `github.com/ncruces/go-sqlite3` ([example](../example/ncruces/main.go))
--   `github.com/tursodatabase/go-libsql` ([example](../example/libsql/main.go))
 -   `modernc.org/sqlite` ([example](../example/modernc/main.go))

docs/usage-standalone.md

@@ -9,10 +9,20 @@ redka [-h host] [-p port] [-s unix-socket] [db-path]
 For example:
 
 ```shell
+# use in-memory sqlite database
 ./redka
+
+# use file sqlite database
 ./redka data.db
+
+# listen on all network interfaces
 ./redka -h 0.0.0.0 -p 6379 data.db
+
+# listen on unix socket
 ./redka -s /tmp/redka.sock data.db
+
+# use postgres database
+./redka -p 6379 "postgres://redka:redka@localhost:5432/redka?sslmode=disable"
 ```
 
 Server defaults are host `localhost`, port `6379` and empty DB path. The unix socket path, if given, overrides the host/port arguments.
@@ -42,7 +52,7 @@ Once the server is running, connect to it using `redis-cli` or an API client lik
 redis-cli -h localhost -p 6379
 ```
 
-```
+```text
 127.0.0.1:6379> echo hello
 "hello"
 127.0.0.1:6379> set name alice