{"id":13687291,"url":"https://github.com/denoland/denokv","last_synced_at":"2025-05-14T07:08:10.655Z","repository":{"id":203812593,"uuid":"706548905","full_name":"denoland/denokv","owner":"denoland","description":"A self-hosted backend for Deno KV","archived":false,"fork":false,"pushed_at":"2025-03-14T06:59:43.000Z","size":1449,"stargazers_count":581,"open_issues_count":37,"forks_count":30,"subscribers_count":22,"default_branch":"main","last_synced_at":"2025-04-11T01:41:57.274Z","etag":null,"topics":["database","deno","kv","sqlite"],"latest_commit_sha":null,"homepage":"https://deno.com/kv","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/denoland.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-10-18T07:04:47.000Z","updated_at":"2025-04-07T08:11:41.000Z","dependencies_parsed_at":"2023-12-04T08:27:09.721Z","dependency_job_id":"64b4dad6-00b8-4311-a09c-5400f4f7590c","html_url":"https://github.com/denoland/denokv","commit_stats":{"total_commits":59,"total_committers":12,"mean_commits":4.916666666666667,"dds":0.576271186440678,"last_synced_commit":"a9eb782be66477b32e96a692c8c34f807ad10bcd"},"previous_names":["denoland/denokv"],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denoland%2Fdenokv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denoland%2Fdenokv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denoland%2Fdenokv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denoland%2Fdenokv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/denoland","download_url":"https://codeload.github.com/denoland/denokv/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254092656,"owners_count":22013290,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["database","deno","kv","sqlite"],"created_at":"2024-08-02T15:00:51.695Z","updated_at":"2025-05-14T07:08:10.635Z","avatar_url":"https://github.com/denoland.png","language":"TypeScript","funding_links":[],"categories":["Self hosted","TypeScript","sqlite"],"sub_categories":[],"readme":"# denokv\n\nA self-hosted backend for [Deno KV](https://deno.com/kv), the JavaScript first key-value database:\n\n- Seamlessly integrated JavaScript APIs\n- ACID transactions\n- Multiple consistency levels for optimal performance for every usecase\n\n![Diagram showing how a `denokv` setup looks](./.github/diagram-dark.png#gh-dark-mode-only)\n![Diagram showing how a `denokv` setup looks](./.github/diagram-light.png#gh-light-mode-only)\n\nDeno KV can be used with the built-in single instance database in the CLI,\nuseful for testing and development, with a hosted and [scalable backend](https://deno.com/blog/building-deno-kv) on\n[Deno Deploy](https://deno.com/deploy), or with this self-hostable Deno KV\nbackend.\n\nTo run `denokv`, just run:\n\n```sh\ndocker run -it --init -p 4512:4512 -v ./data:/data ghcr.io/denoland/denokv --sqlite-path /data/denokv.sqlite serve --access-token \u003crandom-token\u003e\n```\n\nThen run your Deno program and specify the access token in the\n`DENO_KV_ACCESS_TOKEN` environment variable:\n\n```ts\nconst kv = await Deno.openKv(\"http://localhost:4512\");\n```\n\nThe self-hosted `denokv` backend is built on the same robust SQLite backend as\nthe built-in single instance database in the CLI. It is designed to be run on a\nVPS or Kubernetes cluster statefully, with Deno processes connecting via the\nnetwork using [KV Connect](https://docs.deno.com/kv/manual/on_deploy#connect-to-managed-databases-from-outside-of-deno-deploy).\n\nThe standalone `denokv` binary is designed to handle thousands of concurrent\nrequests, from hundreds of different Deno processes. It is built on top of the\nrobust SQLite database, and uses non-blocking IO to ensure excellent performance\neven in the face of hundreds of concurrent connections.\n\nJust like the Deno CLI, `denokv` is MIT licensed, free and open source.\n\nRead more in [the announcement of self-hosted Deno KV](https://deno.com/blog/kv-is-open-source-with-continuous-backup).\n\n## When should I use this?\n\nIf you need more than a single Deno process to access the same KV database, and\nyou are ok with running a server, keeping `denokv` updated, handling backups,\nand performing regular maintenance, then this is for you.\n\nYou can use a hosted KV database on Deno Deploy if you don't want to self-host\nand manage a `denokv` server.\n\nIf you are just need a backend for local development or testing, you can use the\nDeno KV backend built into the Deno CLI. You can open a temporary in memory KV\ndatabase with `Deno.openKv(\":memory:\")` or a persistent database by specifying a\npath like `Deno.openKv(\"./my-database.sqlite\")`.\n\n## How to run\n\n### Docker on a VPS\n\n\u003e Ensure that you are running on a service that supports persistent storage, and\n\u003e does not perform auto-scaling beyond a single instance. This means you can not\n\u003e run `denokv` on Google Cloud Run or AWS Lambda.\n\nInstall Docker on your VPS and create a directory for the database to store data\nin.\n\n```sh\n$ mkdir -p /data\n```\n\nThen run the `denokv` Docker image, mounting the `/data` directory as a volume\nand specifying a random access token.\n\n```sh\ndocker run -it --init -p 4512:4512 -v ./data:/data ghcr.io/denoland/denokv --sqlite-path /data/denokv.sqlite serve --access-token \u003crandom-token\u003e\n```\n\nYou can now access the database from your Deno programs by specifying the access\ntoken in the `DENO_KV_ACCESS_TOKEN` environment variable, and the host and port\nof your VPS in the URL passed to `Deno.openKv`.\n\nYou should additionally add a HTTPS terminating proxy or loadbalancer in front\nof `denokv` to ensure that all communication happens over TLS. Not using TLS can\npose a significant security risk. The HTTP protocol used by Deno KV is\ncompatible with any HTTP proxy, such as `caddy`, `nginx`, or a loadbalancer.\n\n### Fly.io\n\nYou can easily host `denokv` on https://fly.io.\n\n\u003e Note: Fly.io is a paid service. You will need to add a credit card to your\n\u003e account to use it.\n\nSign up to Fly.io and\n[install the `flyctl` CLI](https://fly.io/docs/hands-on/install-flyctl/).\n\nSign into the CLI with `flyctl auth login`.\n\nCreate a new app with `flyctl apps create`.\n\nCreate a `fly.toml` file with the following contents. Make sure to replace the\n`\u003cyour-app-name\u003e` and `\u003cregion\u003e` placeholders with your app name and the region\nyou want to deploy to.\n\n```toml\napp = \"\u003cyour-app-name\u003e\"\nprimary_region = \"\u003cregion\u003e\"\n\n[build]\n  image = \"ghcr.io/denoland/denokv:latest\"\n\n[http_service]\n  internal_port = 4512\n  force_https = true\n  auto_stop_machines = true\n  auto_start_machines = true\n  min_machines_running = 0\n\n[env]\n  DENO_KV_SQLITE_PATH=\"/data/denokv.sqlite3\"\n  # access token is set via `flyctl secrets set`\n\n[mounts]\n  destination = \"/data\"\n  source = \"denokv_data\"\n```\n\nRun `flyctl volumes create denokv_data` to create a volume to store the database\nin.\n\nRun `flyctl secrets set DENO_KV_ACCESS_TOKEN=\u003crandom-token\u003e` to set the access\ntoken. Make sure to replace `\u003crandom-token\u003e` with a random string. Keep this\ntoken secret, and don't share it with anyone. You will need this token to\nconnect to your database from Deno.\n\nRun `flyctl deploy` to deploy your app.\n\nYou can now access the database from your Deno programs by specifying the access\ntoken in the `DENO_KV_ACCESS_TOKEN` environment variable, and the URL provided\nby `flyctl deploy` in the URL passed to `Deno.openKv`.\n\nBe aware that with this configuration, your database can scale to 0 instances\nwhen not in use. This means that the first request to your database after a\nperiod of inactivity will be slow, as the database needs to be started. You can\navoid this by setting `min_machines_running` to `1`, and setting\n`auto_stop_machines = false`.\n\n### Install binary\n\nYou can download a prebuilt binary from the\n[releases page](https://github.com/denoland/denokv/releases/tag/0.1.0) and place\nit in your `PATH`.\n\nYou can also compile from source by running `cargo install denokv --locked`.\n\n## How to connect\n\n### Deno\n\nTo connect to a `denokv` server from Deno, use the `Deno.openKv` API:\n\n```ts\nconst kv = await Deno.openKv(\"http://localhost:4512\");\n```\n\nMake sure to specify your access token in the `DENO_KV_ACCESS_TOKEN` environment\nvariable.\n\n\u003c!-- TBD: ### Node.js --\u003e\n\n## Advanced setup\n\n### Running as a replica of a hosted KV database\n\n`denokv` has a mode for running as a replica of a KV database hosted on Deno\nDeploy through the S3 backup feature.\n\nTo run as a replica:\n\n```sh\ndocker run -it --init -p 4512:4512 -v ./data:/data \\\n  -e AWS_ACCESS_KEY_ID=\"\u003caws-access-key-id\u003e\" \\\n  -e AWS_SECRET_ACCESS_KEY=\"\u003caws-secret-access-key\u003e\" \\\n  -e AWS_REGION=\"\u003caws-region\u003e\" \\\n  ghcr.io/denoland/denokv --sqlite-path /data/denokv.sqlite serve \\\n  --access-token \u003crandom-token\u003e --sync-from-s3 --s3-bucket your-bucket --s3-prefix some-prefix/6aea9765-2b1e-41c7-8904-0bdcd70b21d3/\n```\n\nTo sync the local database from S3, without updating the snapshot:\n\n```sh\ndenokv --sqlite-path /data/denokv.sqlite pitr sync --s3-bucket your-bucket --s3-prefix some-prefix/6aea9765-2b1e-41c7-8904-0bdcd70b21d3/\n```\n\nTo list recoverable points:\n\n```sh\ndenokv --sqlite-path /data/denokv.sqlite pitr list\n```\n\nTo checkout the snapshot at a specific recoverable point:\n\n```sh\ndenokv --sqlite-path /data/denokv.sqlite pitr checkout 0100000002c0f4c10000\n```\n\n### Continuous backup using LiteFS\n\nTODO\n\n## Other things in this repo\n\nThis repository contains two crates:\n\n- `denokv_proto` (`/proto`): Shared interfaces backing KV, like definitions of\n  `Key`, `Database`, and `Value`.\n- `denokv_sqlite` (`/sqlite`): An implementation of `Database` backed by SQLite.\n- `denokv_remote` (`/remote`): An implementation of `Database` backed by a\n  remote KV database, acessible via the KV Connect protocol.\n\nThese crates are used by the `deno_kv` crate in the Deno repository to provide a\nJavaScript API for interacting with Deno KV.\n\nThe Deno KV Connect protocol used for communication between Deno and a remote KV\ndatabase is defined in [`/proto/kv-connect.md`](./proto/kv-connect.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdenoland%2Fdenokv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdenoland%2Fdenokv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdenoland%2Fdenokv/lists"}