{"id":13630404,"url":"https://github.com/auula/urnadb","last_synced_at":"2026-04-21T07:03:53.084Z","repository":{"id":43320240,"uuid":"448509398","full_name":"auula/vasedb","owner":"auula","description":"VaseDB is a NoSQL that supports multiple data types and transactions.","archived":false,"fork":false,"pushed_at":"2024-06-10T08:13:55.000Z","size":72,"stargazers_count":251,"open_issues_count":0,"forks_count":28,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-06-19T00:36:08.401Z","etag":null,"topics":["bitcask","database","go","golang","kv","kvdb","kvstore","nosql","nosql-database","storage","storage-engine","storage-provider"],"latest_commit_sha":null,"homepage":"","language":"Go","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/auula.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}},"created_at":"2022-01-16T09:29:22.000Z","updated_at":"2024-06-19T00:36:12.347Z","dependencies_parsed_at":"2023-11-27T09:59:10.064Z","dependency_job_id":"7b060966-44e8-45c0-b012-7d7d5c2f145f","html_url":"https://github.com/auula/vasedb","commit_stats":null,"previous_names":["auula/kalasa","auula/classdb","vasedb/vasedb","auula/vasedb","classdb/classdb"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auula%2Fvasedb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auula%2Fvasedb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auula%2Fvasedb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auula%2Fvasedb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/auula","download_url":"https://codeload.github.com/auula/vasedb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227652567,"owners_count":17799235,"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":["bitcask","database","go","golang","kv","kvdb","kvstore","nosql","nosql-database","storage","storage-engine","storage-provider"],"created_at":"2024-08-01T22:01:41.391Z","updated_at":"2026-04-21T07:03:53.077Z","avatar_url":"https://github.com/auula.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"\n\u003cdiv align=\"center\"\u003e\n    \u003c!-- \u003cimg src=\"cmd/urnadb.png\" style=\"width: 86px; height: auto; display: inline-block;\"\u003e --\u003e\n    \u003ch1\u003e🏺️\u003c/h1\u003e\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003eUrnaDB is a NoSQL database support diverse data types and transactions.\u003c/p\u003e\n\n\n---\n\n\n[![Go Report Card](https://img.shields.io/badge/go%20report-A+-brightgreen.svg?style=flat)](https://img.shields.io/badge/go%20report-A+-brightgreen.svg?style=flat)\n[![Go Reference](https://pkg.go.dev/badge/github.com/auula/urnadb.svg)](https://pkg.go.dev/github.com/auula/urnadb)\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/55bc449808ca4d0c80c0122f170d7313)](https://app.codacy.com/gh/auula/urnadb/dashboard?utm_source=gh\u0026utm_medium=referral\u0026utm_content=\u0026utm_campaign=Badge_grade)\n[![codecov](https://codecov.io/gh/auula/urnadb/graph/badge.svg?token=xTcPzdLFkJ)](https://codecov.io/gh/auula/urnadb)\n[![DeepSource](https://app.deepsource.com/gh/auula/urnadb.svg/?label=active+issues\u0026show_trend=false\u0026token=Bymkt0xcKcmlGI8WOo3JMxHc)](https://app.deepsource.com/gh/auula/urnadb/)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![release](https://img.shields.io/github/release/auula/urnadb.svg)](https://github.com/auula/urnadb/releases)\n\n\n\n---\n\n[简体中文](README.md) | [English](README_EN.md)\n\n---\n\n## 🎉 Feature\n\n- 支持多种内置的数据结构\n- 高吞吐量、低延迟、高效批量数据写入\n- 支持磁盘数据存储和磁盘垃圾数据回收\n- 支持磁盘数据静态加密和静态数据压缩\n- 支持 IP 白名单功能保障数据的安全访问\n- 支持通过基于 RESTful API 协议操作数据\n\n---\n\n## 🚀 Quick Start\n\n使用 Docker 可以快速部署 [`urnadb:latest`](https://hub.docker.com/r/auula/urnadb) 的镜像来测试 UrnaDB 提供的服务，运行以下命令即可拉取 UrnaDB 镜像：\n\n```bash\ndocker pull auula/urnadb:latest\n```\n\n运行 UrnaDB 镜像启动容器服务，并且映射端口到外部主机网络，执行下面的命令：\n\n```bash\ndocker run -p 2668:2668 auula/urnadb:latest\n```\n\nUrnaDB 提供使用 RESTful API 的方式进行数据交互，理论上任意具备 HTTP 协议的客户端都支持访问和操作 UrnaDB 服务实例。在调用 RESTful API 时需要在请求头中添加 `Auth-Token` 进行鉴权，该密钥由 UrnaDB 进程自动生成，可通过容器运行时日志获取，使用以下命令查看启动日志：\n\n```text\nroot@2c2m:~# docker logs 66ae91bc73a6\n              __  __              ___  ___\n             / / / /______  ___ _/ _ \\/ _ )\n            / /_/ / __/ _ \\/ _ `/ // / _  |\n            \\____/_/ /_//_/\\_,_/____/____/  v1.1.2\n\n  UrnaDB is a NoSQL database based on Log-structured file system.\n  Software License: Apache 2.0  Website: https://urnadb.github.io\n\n[UrnaDB:C] 2023/06/04 18:35:15 [WARN] The default password is: QGVkh8niwL2TSkj72icaKBC9B\n[UrnaDB:C] 2023/06/04 18:35:15 [INFO] Logging output initialized successfully\n[UrnaDB:C] 2023/06/04 18:35:15 [INFO] Loading and parsing region data files...\n[UrnaDB:C] 2023/06/04 18:35:15 [INFO] Regions compression activated successfully\n[UrnaDB:C] 2023/06/04 18:35:15 [INFO] File system setup completed successfully\n[UrnaDB:C] 2023/06/04 18:35:15 [INFO] HTTP server started at http://192.168.31.221:2668 🚀\n```\n\n如果计划将 UrnaDB 作为长期运行的服务，推荐直接使用主流 Linux 发行版来运行而非容器技术。采用裸机 Linux 部署 UrnaDB 服务，可手动优化存储引擎参数，以获得更稳定的性能和更高的资源利用率，具体参数配置建议查看[官方文档](https://urnadb.github.io)。\n\n---\n\n## 🕹️ RESTful API \n\n目前 UrnaDB 服务对外提供数据交互接口是基于 HTTP 协议的 RESTful API ，只需要通过支持  `HTTP` 协议客户端软件就可以进行数据操作。这里推荐使用 `curl` 软件进行数据交互操作，UrnaDB 内部提供了多种数据结构抽象，例如 Table 、Record 、 Variant 、Lock 类型。这些数据类型对应着常见的业务代码所需使用的数据结构，这里以 Tables 类型结构为例进行 RESTful API 数据交互的演示。\n\n\nTable 结构类似关系数据库 SQL 中的一张表结构，一旦创建完成之后 Table 会为每条记录分配一个全局唯一递增的 `t_id` 索引，Table 的每列可以存储任何有映射关系的半结构化数据，例如编程语言中的 struct 和 class 字段都可以使用 Table 进行存储，下面是一张 Table 结构 Rows 的 JSON 抽象，其中的 `t_id` 为数据库主动分配的自增主键：\n\n```json\n{\n    \"table\": {\n        \"1\": {\n            \"active\": true,\n            \"age\": 25,\n            \"name\": \"Leon Ding\",\n            \"score\": 95.5,\n            \"tags\": [\n                \"admin\",\n                \"user\"\n            ]\n        },\n        \"2\": {\n            \"active\": false,\n            \"age\": 30,\n            \"name\": \"Alice Wang\",\n            \"config\": {\n                \"font\": 14,\n                \"theme\": \"dark\"\n            },\n            \"email\": \"example@xxx.com\"\n        },\n        \"3\": {}\n    },\n    \"t_id\": 4\n}\n```\n\n下面是 curl 进行数据存储操作的例子，由于是 RESTful API 设计风格，需要在 HTTP 的请求路径 URL 加上数据类型信息。如何数类型新建操作，都需要使用 HTTP 协议的 PUT 方法进行操作，命令如下：\n\n```bash\ncurl -X PUT http://localhost:2668/table/key-01 -v \\\n     -H \"Content-Type: application/json\" \\\n     -H \"Auth-Token: QGVkh8niwL2TSkj72icaKBC9B\" \\\n     --data @tests/table.json\n```\n\n获取数据的方式只需要将 HTTP 的请求改为 GET 方式就会获取得 Key 相应的存储记录，命令如下：\n\n```bash\ncurl -X GET http://localhost:2668/table/key-01 -v \\\n-H \"Auth-Token: QGVkh8niwL2TSkj72icaKBC9B\" \n```\n\n删除对应的数据记录，只需要将 HTTP 的请求改为 DELETE 的方式即可，命令如下：\n\n```bash\ncurl -X DELETE http://localhost:2668/table/key-01 -v \\\n-H \"Auth-Token: QGVkh8niwL2TSkj72icaKBC9B\" \n```\n\n更多针对数据类型复杂的操作使用示例请查看[官方文档](https://urnadb.github.io)。\n\n---\n\n## 📦 Java SDK 使用\n\n相较于基于 HTTP 协议的数据交互方式，官方更推荐使用 SDK 来进行操作的，例如使用 Java 语言的 SDK 可以使用 Lambda 函数式编程风格进行数据交互操作。下面是创建一张名为 `users` 表并且向 `users` 表中插入一条数据记录，这条操作类似于关系数据库 SQL 中的 `INSERT ... INTO ... VALUES ...` 语句，代码如下：\n\n```java\n// 第二参数支持设置 120 秒\nvar isOk = sdk.createTable(\"users\",120);\n// tables 支持重载，put 还可以直接插入一个 Object 对象实例。\nvar tid = sdk.tables(\"users\").put(p -\u003e {\n    p.set(\"name\", \"Leon\")\n     .set(\"age\", 18)\n     .set(\"config\", Map.of(\"theme\", \"dark\", \"font\", 14))\n     .set(\"meta\", new Meta(\"author\", \"leon\"))\n     .set(\"extra\", m -\u003e {\n         m.put(\"role\", \"admin\");\n         m.put(\"verified\", true);\n     });\n}).commit();\n```\n\n根据条件对 Table 中已有数据记录进行部分字段数据内容更新的操作，这个操作类似于关系数据库 SQL 中的 `UPDATE ... SET ... WHERE ...` 语句，代码示例如下：\n\n```java\nvar count = sdk.tables(\"users\").patch(p -\u003e {\n    p.where(w -\u003e w.eq(\"name\",\"Leon\"));\n    p.sets(s -\u003e s\n        .set(\"age\", 25)\n        .set(\"active\", true)\n        .set(\"meta\", m -\u003e {\n            m.put(\"editor\", \"system\");\n        })\n    );\n}).commit();\n```\n\n对 Table 中已有的数据记录，执行条件删除操作，类似于关系数据库 SQL 中的 `DELETE FROM ... WHERE ...` 的语句，代码如下：\n\n```java\nvar count = sdk.tables(\"users\").remove(r -\u003e \n    r.where(w -\u003e w.tid(4))\n).commit();\n```\n\n对 Table 中已有的数据记录，执行条件查询操作，类似于关系数据库 SQL 中的 `SELECT * FROM ... WHERE ...` 的语句，代码如下：\n\n```java\nvar user = sdk.tables(\"users\").query(q -\u003e \n    q.where(w -\u003e w.eq(\"age\", 18))\n).commit();\n```\n\n相关的 SDK 的 API 使用示例请查看[官方文档](https://urnadb.github.io)。\n\n---\n\n## 🧪 Benchmark Test\n\n由于底层存储引擎是以 Append-Only Log 的方式将所有的操作写入到数据文件中，所以这里给出的测试用例报告，是针对的其核心文件系统 [`vfs`](./vfs/) 包的写入性能测试的结果。运行测试代码的硬件设备配置信息为（Intel i5-7360U, 8GB LPDDR3 RAM），写入基准测试结果如下：\n\n```bash\n$: go test -benchmem -run=^$ -bench ^BenchmarkVFSWrite$ github.com/auula/urnadb/vfs\ngoos: darwin\ngoarch: amd64\npkg: github.com/auula/urnadb/vfs\ncpu: Intel(R) Core(TM) i5-7360U CPU @ 2.30GHz\nBenchmarkVFSWrite-4   \t  173533\t      7283 ns/op\t     774 B/op\t      20 allocs/op\nPASS\nok  \tgithub.com/auula/urnadb/vfs\t2.806s\n```\n\n在项目根目录下有一个 [`tools.sh`](./tools.sh) 的工具脚本文件，可以快速帮助完成各项辅助工作。\n\n---\n\n## 🌟 Stargazers over time\n\n[![Stargazers over time](https://starchart.cc/auula/urnadb.svg?variant=adaptive)](https://starchart.cc/auula/urnadb)\n\n---\n\n## 👬 Contributors\n\n🤝 Thanks to all the contributors below! \n\n![Contributors](https://contributors-img.web.app/image?repo=auula/urnadb)\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fauula%2Furnadb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fauula%2Furnadb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fauula%2Furnadb/lists"}