{"id":51317725,"url":"https://github.com/abhiksark/valkey-embedded","last_synced_at":"2026-07-01T09:03:29.135Z","repository":{"id":365738982,"uuid":"1265192764","full_name":"abhiksark/valkey-embedded","owner":"abhiksark","description":"Embedded, auto-managed Valkey server for Python- a modern redislite. Zero-infra Redis-compatible engine for tests, CI, and local dev.","archived":false,"fork":false,"pushed_at":"2026-06-18T16:18:42.000Z","size":98,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-18T18:07:49.165Z","etag":null,"topics":["embedded-database","pytest-plugin","python","redis","testing","valkey"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/abhiksark.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-10T14:48:46.000Z","updated_at":"2026-06-18T16:17:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/abhiksark/valkey-embedded","commit_stats":null,"previous_names":["abhiksark/valkey-embedded"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/abhiksark/valkey-embedded","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abhiksark%2Fvalkey-embedded","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abhiksark%2Fvalkey-embedded/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abhiksark%2Fvalkey-embedded/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abhiksark%2Fvalkey-embedded/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/abhiksark","download_url":"https://codeload.github.com/abhiksark/valkey-embedded/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abhiksark%2Fvalkey-embedded/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34999795,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["embedded-database","pytest-plugin","python","redis","testing","valkey"],"created_at":"2026-07-01T09:03:28.206Z","updated_at":"2026-07-01T09:03:29.129Z","avatar_url":"https://github.com/abhiksark.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# valkey-embedded\n\n[![CI](https://github.com/abhiksark/valkey-embedded/actions/workflows/ci.yml/badge.svg)](https://github.com/abhiksark/valkey-embedded/actions/workflows/ci.yml)\n[![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD--3--Clause-blue.svg)](LICENSE.txt)\n[![Python versions](https://img.shields.io/badge/python-3.9%20%E2%80%93%203.13-blue.svg)](pyproject.toml)\n\nEmbedded, auto-managed [Valkey](https://valkey.io/) server for Python. Construct a\nclient and a private `valkey-server` starts; it shuts down and cleans up when the\nlast client closes. No separate server install or running daemon required.\n\n```python\nfrom valkey_embedded import Valkey\n\nconn = Valkey()\nconn.set(\"key\", \"value\")\nconn.get(\"key\")          # b'value'\n# server is stopped and cleaned up when the process exits\n```\n\nThis project is motivated by [redislite](https://github.com/yahoo/redislite) — the\nsame embed-the-real-engine idea, reimplemented from scratch under BSD-3-Clause and\ntargeting [Valkey](https://valkey.io/) so the embedded binary can be freely\nredistributed on PyPI.\n\n## When to use valkey-embedded\n\nvalkey-embedded runs the **real Valkey engine** as an **embedded, auto-managed server** on a\n**single machine**, persisting via **RDB snapshots** (a cache/buffer, not a durable\nsystem-of-record). Those four properties decide where it fits.\n\n**Strong fit — this is what it's for:**\n\n- **Testing Redis/Valkey code.** Every `Valkey()` is a private, clean server, so tests\n  isolate cleanly and run in parallel. Because it's the real engine, expiry, eviction,\n  blocking ops, `MULTI`/`EXEC`, and your Lua scripts behave exactly as in production —\n  unlike reimplementations that drift.\n- **CI without service containers.** No `services: redis`, no docker-compose, no\n  testcontainers, no \"wait for healthy\" — just `pip install` and run.\n- **Local development \u0026 onboarding.** Clone, run, works. No daemon to install or keep\n  alive; the binary is bundled, so it works offline.\n- **Demos, tutorials, notebooks.** Ship something that *just runs*, with zero prerequisites.\n\n**Works, with caveats:**\n\n- **Single-box inter-process coordination / queues** (shared mode). Treat it as an\n  ephemeral buffer unless you open it with `connect(path, durable=True)`; don't call\n  `.shutdown()` from one process while others share the server; set `maxmemory` and TTLs\n  to bound memory growth.\n- **Local cache for a single-node app or CLI.** Reach for it when you specifically want\n  Redis data structures, pub/sub, or TTL semantics — otherwise SQLite is simpler.\n\n**Wrong tool — use something else:**\n\n| You want… | Use instead |\n|---|---|\n| Production serving, HA, or multi-host | a real Valkey/Redis deployment |\n| A durable system-of-record | PostgreSQL |\n| A durable single-file *in-process* database | SQLite |\n| Cross-machine shared state | a real Valkey/Redis deployment |\n| Windows-native (without WSL) | a real Valkey/Redis deployment |\n\nIn short: valkey-embedded owns the \"I need the real Valkey engine, on one box, with zero infra\n— mostly for testing and local dev\" niche. It is an embedded *server*, not an in-process\ndatabase.\n\n## Install\n\n```bash\npip install valkey-embedded          # prebuilt wheels: Linux x86_64, macOS 14+ arm64\n```\n\nOther POSIX platforms build Valkey from source at install time (needs `gcc`/`clang`\nand `make`). Windows is unsupported (WSL works).\n\n## Usage\n\n- **Isolated server:** `Valkey()` — a private server per instance.\n- **Persistent / shared:** `Valkey(\"/path/to/db.rdb\")` — persists across runs;\n  instances sharing the path attach to one server (last to close shuts it down).\n\n  \u003e Note: the first positional argument is the **RDB file path**, not `host` — the\n  \u003e embedded server has no host. Pass server overrides via\n  \u003e `serverconfig={\"maxmemory\": \"64mb\"}`.\n\n- **SQLite-style open with durability:** `connect()` is sugar over `Valkey()` that\n  reads like `sqlite3.connect` — open a file-backed store, opt into crash-safety, and\n  release it by leaving a `with` block:\n\n  ```python\n  import valkey_embedded\n\n  with valkey_embedded.connect(\"data.db\", durable=True) as db:\n      db.set(\"user:1\", \"ada\")     # AOF-backed: survives a crash, not just a clean exit\n  # leaving the block persists and stops the embedded server\n  ```\n\n  `durable=True` enables the append-only file with `appendfsync everysec` (≤1s of\n  writes lost on a crash); `durable=\"always\"` fsyncs every write. Default\n  (`durable=False`) is RDB snapshots only, which can lose writes since the last\n  snapshot. `durable=` requires a path — an isolated server's data is discarded on\n  exit. Force a snapshot anytime with `db.bgsave()`.\n\n- **Explicit server with a TCP endpoint:** `ValkeyServer` is the other half of\n  the API — you control start/stop, and the server listens on host/port so *any*\n  Redis-compatible client (or another process) can connect:\n\n  ```python\n  from valkey_embedded import ValkeyServer\n\n  with ValkeyServer() as server:          # port auto-assigned; or ValkeyServer(port=6380)\n      print(server.connection_url)        # valkey://127.0.0.1:\u003cport\u003e\n      client = server.client()            # built-in valkey-py client\n      client.set(\"k\", \"v\")\n      # bring your own: valkey.Valkey(**server.connection_kwargs)\n  ```\n\n  Explicit form: `server = ValkeyServer(); server.start(); ...; server.stop()`\n  (`is_running()`, `terminate()`, `persist=True`, `data_dir=…`, `config={…}` too).\n\n  \u003e `Valkey()` stays unix-socket-only with no TCP listener (private by default);\n  \u003e reach for `ValkeyServer` when you need a port.\n\n- **Pytest fixtures:** installing the package registers fixtures automatically —\n  no conftest wiring. One server runs per test session; each test gets a client\n  with a clean keyspace (`FLUSHALL` on setup):\n\n  ```python\n  def test_thing(valkey_client):           # client to the session server, keys wiped per test\n      valkey_client.set(\"k\", \"v\")\n      assert valkey_client.get(\"k\") == b\"v\"\n\n  def test_other(valkey_server, valkey_url):\n      assert valkey_server.is_running()    # the session ValkeyServer; valkey_url is its URL\n\n  def test_pristine(valkey_server_factory):\n      private = valkey_server_factory(persist=False)   # fresh server just for this test\n      assert private.client().ping()\n  ```\n\n  Only keys are reset between tests; server-level state (`CONFIG SET`, loaded Lua\n  scripts) persists for the session — use `valkey_server_factory` when a test\n  needs a pristine process. Under pytest-xdist each worker gets its own server.\n\n- **Command line:** run a server in the foreground:\n\n  ```bash\n  valkey-embedded --port 6380        # or: python -m valkey_embedded\n  ```\n\n- **Diagnostics:** `python -m valkey_embedded.debug`\n\n- **Errors:** failures to start the embedded server raise\n  `valkey_embedded.ServerStartError`; its base class `ValkeyEmbeddedError` catches\n  every error this library raises. (Command errors from the server itself are\n  raised by `valkey-py` as usual.)\n\n- **Also exported:** `StrictValkey` (alias of `Valkey`, mirroring valkey-py);\n  `durable=\"everysec\"` as the explicit spelling of `durable=True`;\n  `__valkey_executable__` (path to the bundled `valkey-server`) and\n  `__valkey_server_version__` (its version, e.g. `8.1.8`). A bundled\n  `valkey-cli` ships next to the server binary for manual inspection:\n\n  ```python\n  import os, valkey_embedded\n  cli = os.path.join(os.path.dirname(valkey_embedded.__valkey_executable__), \"valkey-cli\")\n  ```\n\n## Examples\n\nRunnable scripts for each feature live in [`examples/`](examples/) (basic usage,\npersistence, shared vs. isolated servers, patching, `serverconfig`, replication,\nand diagnostics):\n\n```bash\npython examples/01_basic.py\n```\n\n## Migration from redislite\n\n| redislite | valkey-embedded |\n|---|---|\n| `redislite.Redis` | `valkey_embedded.Valkey` |\n| `redislite.patch.patch_redis` | `valkey_embedded.patch.patch_valkey` |\n\nValkey is wire-compatible with Redis and `valkey-py` is forked from `redis-py`, so\napplication logic is unchanged — only imports and class names differ.\n\n## Versioning \u0026 support\n\nvalkey-embedded follows [Semantic Versioning](https://semver.org/). While on\n`0.x` the API may still change between minor versions; any change is recorded in\n[CHANGELOG.md](CHANGELOG.md). Supported Python versions are 3.9–3.13 on Linux and\nmacOS (14+ arm64); Windows is supported only under WSL.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, the test tiers, and the\nprocedure for pinning a new Valkey release. Participation is governed by our\n[Code of Conduct](CODE_OF_CONDUCT.md); security issues go through\n[SECURITY.md](SECURITY.md).\n\n## License\n\nvalkey-embedded is licensed under [BSD-3-Clause](LICENSE.txt). Built wheels\nbundle a compiled `valkey-server` binary, also BSD-3-Clause; its license — and\nthe notices of the third-party code statically linked into it (Lua,\nhdr_histogram, fpconv, linenoise) — ship as `valkey_embedded/bin/VALKEY_COPYING.txt`\nalongside the binary. The `valkey` Python client is a runtime dependency, not\nredistributed here.\n\n## Trademark\n\nvalkey-embedded is an independent project and is not affiliated with, sponsored, or\nendorsed by the Valkey project or the Linux Foundation. Valkey is a trademark of\nLF Projects, LLC.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabhiksark%2Fvalkey-embedded","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabhiksark%2Fvalkey-embedded","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabhiksark%2Fvalkey-embedded/lists"}