{"id":20840299,"url":"https://github.com/kong/lua-resty-lmdb","last_synced_at":"2025-05-08T21:44:49.294Z","repository":{"id":38257775,"uuid":"241681692","full_name":"Kong/lua-resty-lmdb","owner":"Kong","description":"Safe API for manipulating LMDB databases using OpenResty/Lua.","archived":false,"fork":false,"pushed_at":"2025-03-17T09:37:02.000Z","size":75,"stargazers_count":30,"open_issues_count":5,"forks_count":5,"subscribers_count":91,"default_branch":"master","last_synced_at":"2025-05-06T08:17:50.484Z","etag":null,"topics":["lmdb","luajit","openresty","openresty-module"],"latest_commit_sha":null,"homepage":"","language":"Raku","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kong.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":"2020-02-19T17:35:35.000Z","updated_at":"2025-04-04T03:12:59.000Z","dependencies_parsed_at":"2023-01-31T02:45:48.332Z","dependency_job_id":"eefe9f94-a8b4-44a3-8263-fe84ff31a3ea","html_url":"https://github.com/Kong/lua-resty-lmdb","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kong%2Flua-resty-lmdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kong%2Flua-resty-lmdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kong%2Flua-resty-lmdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kong%2Flua-resty-lmdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kong","download_url":"https://codeload.github.com/Kong/lua-resty-lmdb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253154238,"owners_count":21862485,"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":["lmdb","luajit","openresty","openresty-module"],"created_at":"2024-11-18T01:15:53.135Z","updated_at":"2025-05-08T21:44:49.285Z","avatar_url":"https://github.com/Kong.png","language":"Raku","funding_links":[],"categories":[],"sub_categories":[],"readme":"# lua-resty-lmdb\n\nThis module allows OpenResty applications to use the LMDB (Lightning Memory-Mapped Database)\ninside the Nginx worker process. It has two parts, a core module built into Nginx that\ncontrols the life cycle of the database environment, and a FFI based Lua binding for\ninteracting with the module to access/change data.\n\n# Table of Contents\n\n* [lua-resty-lmdb](#lua-resty-lmdb)\n    * [APIs](#apis)\n        * [resty.lmdb](#restylmdb)\n            * [get](#get)\n            * [set](#set)\n            * [get_env_info](#get_env_info)\n        * [db\\_drop](#db_drop)\n        * [prefix](#prefix)\n        * [resty.lmdb.transaction](#restylmdbtransaction)\n            * [reset](#reset)\n            * [get](#get)\n            * [set](#set)\n            * [db\\_open](#db_open)\n            * [db\\_drop](#db_drop)\n            * [commit](#commit)\n        * [resty.lmdb.prefix](#restylmdbprefix)\n            * [page](#page)\n    * [Directives](#directives)\n        * [lmdb_environment_path](#lmdb_environment_path)\n        * [lmdb_max_databases](#lmdb_max_databases)\n        * [lmdb_map_size](#lmdb_map_size)\n        * [lmdb_validation_tag](#lmdb_validation_tag)\n    * [Copyright and license](#copyright-and-license)\n\n## APIs\n\n### resty.lmdb\n\n#### get\n\n**syntax:** *value, err = lmdb.get(key, db?)*\n\n**context:** *any context **except** init_by_lua\u0026#42;*\n\nGets the value corresponding to `key` from LMDB database `db`. If `db` is omitted,\nit defaults to `\"_default\"`.\n\nIf the key does not exist, `nil` will be returned.\n\nIn case of error, `nil` and a string describing the error will be returned instead.\n\n[Back to TOC](#table-of-contents)\n\n#### set\n\n**syntax:** *ok, err = lmdb.set(key, value, db?)*\n\n**context:** *any context **except** init_by_lua\u0026#42;*\n\nSets the value corresponding to `key` to `value` inside LMDB database `db`. If `db` is omitted,\nit defaults to `\"_default\"`.\n\nSetting a key's value to `nil` will remove that key from the corresponding database.\n\nIn case of error, `nil` and a string describing the error will be returned instead.\n\n[Back to TOC](#table-of-contents)\n\n#### get_env_info\n\n**syntax:** *status, err = lmdb.get_env_info()*\n\n**context:** *any context **except** init_by_lua\u0026#42;*\n\nGet the LMDB database runtime information. `status` table struct as below.\n```\n{\n    \"page_size\": 4096,\n    \"max_readers\":126,\n    \"num_readers\": 1,\n    \"allocated_pages\": 2,\n    \"in_use_pages\": 0,\n    \"entries\": 0,\n    \"map_size\": 10485760 # in bytes\n}\n```\n\nIn case of error, `nil` and a string describing the error will be returned instead.\n\n\n[Back to TOC](#table-of-contents)\n\n### db\\_drop\n\n**syntax:** *ok, err = lmdb.db_drop(delele?, db?)*\n\n**context:** *any context **except** init_by_lua\u0026#42;*\n\nClears the contents of database `db`. If `delete` is `true`, then the database handle is also dropped.\n\nIn case of error, `nil` and a string describing the error will be returned instead.\n\n[Back to TOC](#table-of-contents)\n\n### prefix\n\n**syntax:** *for key, value in lmdb.prefix(prefix) do*\n\n**context:** *any context*\n\nReturns all key and their associated value for keys starting with `prefix`.\nFor example, if the database contains:\n\n```\nkey1: value1\nkey11: value11\nkey2: value2\n```\n\nThen a call of `lmdb.prefix(\"key\")` will yield `key1`, `key11` and `key2` respectively.\n\nIn case of errors while fetching from LMDB, `key` will be `nil` and `value` will be\na string describing the error. The caller must anticipate this happening and check each return\nvalue carefully before consuming.\n\n**Warning on transaction safety:** Since the number of keys that could potentially\nbe returned with this method could be very large, this method does not return all\nresults inside a single transaction as this will be very expensive. Instead, this\nmethod gets keys from LMDB in batches using different read transaction. Therefore, it\nis possible that the database content has changed between batches. We may introduce a\nmechanism for detecting this case in the future, but for now there is a small opportunity\nfor this to happen and you should guard your application for concurrent writes if this\nis a huge concern. This function makes best effort to detect when database content\ndefinitely changed between iterations, in this case `nil, \"DB content changed while iterating\"`\nwill be returned from the iterator.\n\n[Back to TOC](#table-of-contents)\n\n### resty.lmdb.transaction\n\n#### reset\n\n**syntax:** *txn:reset()*\n\n**context:** *any context*\n\nResets a transaction object. Removes all existing transactions and results (if any) from the object but\nkeeps the table's capacity. After this call the transaction can be reused as if it was a new transaction\nreturned by `transaction.begin()`.\n\n[Back to TOC](#table-of-contents)\n\n#### get\n\n**syntax:** *txn:get(key, db?)*\n\n**context:** *any context*\n\nAppends a `get` operation in the transactions table. If `db` is omitted,\nit defaults to `\"_default\"`. The output table contains the following\nfields:\n\n* `value`: Value for `key`, or `nil` if `key` is not found\n\n[Back to TOC](#table-of-contents)\n\n#### set\n\n**syntax:** *txn:set(key, value, db?)*\n\n**context:** *any context*\n\nAppends a `set` operation in the transactions table. If `db` is omitted,\nit defaults to `\"_default\"`. The output able contains the following\nfields:\n\n* `result`: Always `true` for successful transaction commits\n\n[Back to TOC](#table-of-contents)\n\n#### db\\_open\n\n**syntax:** *txn:db_open(create, db?)*\n\n**context:** *any context*\n\nAppends a `db_open` operation in the transactions table. If `db` is omitted,\nit defaults to `\"_default\"`. This operation does not return anything\nin case of successful transaction commits.\n\n[Back to TOC](#table-of-contents)\n\n#### db\\_drop\n\n**syntax:** *txn:db_drop(delete, db?)*\n\n**context:** *any context*\n\nAppends a `db_drop` operation in the transactions table. If `db` is omitted,\nit defaults to `\"_default\"`. This operation does not return anything\nin case of successful transaction commits.\n\n[Back to TOC](#table-of-contents)\n\n#### commit\n\n**syntax:** *local res, err = txn:commit()*\n\n**context:** *any context **except** init_by_lua\u0026#42;*\n\nCommits all operations currently inside the transactions table using a single LMDB\ntransaction. Since LMDB transaction exhibits ACID (atomicity, consistency, isolation, durability)\nproperties, this method will either commit all operations at once or fail without causing\nside effects.\n\nIn case of successful transaction commit, `true` will be returned. Output value of each operation\ncan be accessed like this: `txn[3].value`. Please note that Lua table index starts at `1` and the\norder corresponds to the order operations were appended into the transaction. So the first operation's\noutput will be inside `txn[1]` and second operation's result will be inside `txn[2]`.\n\nIn case of any error during the transaction, it will be rolled back and `nil` and\nan string describing the reason of the failure will be returned instead. Accessing the output value\nfrom the `txn` table when `commit()` returned an error is undefined.\n\n[Back to TOC](#table-of-contents)\n\n### resty.lmdb.prefix\n\n#### page\n\n**syntax:** *res, err_or_more = prefix.page(start, prefix, db?, page_size?)*\n\n**context:** *any context*\n\nReturn all keys `\u003e= start` and starts with `prefix`. If `db` is omitted,\nit defaults to `\"_default\"`.\n\nIf `page_size` is specified, up to `page_size` results will be returned. The `page_size`\ncannot be smaller than 1.\n\nThe return value of this function is a table `res` where `res[1].key` and `res[1].value`\ncorresponds to the first key and value, `res[2].key` and `res[2].value` corresponds to the\nsecond and etc. If no keys matched the provided criteria, then an empty table will be\nreturned.\n\nIn case of success, the second return value will be a boolean indicating if more keys are\npossibly present. However, even when this value is `true`, it is possible subsequent `page`\nmight return an empty list. If this value is `false`, then it is guaranteed no more keys\nmatching the `prefix` is available.\n\nIn case of errors, `nil` and an string describing the reason of the failure will be returned.\n\nThis is a low level function, most of the use case should use the higher level\n[lmdb.prefix](#prefix) iterator instead.\n\n[Back to TOC](#table-of-contents)\n\n## Directives\n\n### lmdb_environment_path\n\n**syntax:** *lmdb_environment_path path;*\n\n**context:** *main*\n\nSet the directory in which the LMDB database files reside.\n\n[Back to TOC](#table-of-contents)\n\n### lmdb_max_databases\n\n**syntax:** *lmdb_max_databases number;*\n\n**context:** *main*\n\nSet the maximum number of named databases, the default value is `1`.\n\n[Back to TOC](#table-of-contents)\n\n### lmdb_map_size\n\n**syntax:** *lmdb_map_size number;*\n\n**context:** *main*\n\nSet the size of the memory map, the default value is `1048576`(1MB).\n\n[Back to TOC](#table-of-contents)\n\n### lmdb_validation_tag\n\n**syntax:** *lmdb_validation_tag value;*\n\n**default:** *none*\n\n**context:** *main*\n\nSet a content validation tag into LMDB.\nWhen LMDB starts, it will check the tag value,\nif the value is different from the directive value,\nthe content of LMDB will be cleaned up.\n\nWhen this directive is not set, tag validation is disabled.\n\n[Back to TOC](#table-of-contents)\n\n## Copyright and license\n\nCopyright (c) 2021-2022 Kong, Inc.\n\nLicensed under the Apache License, Version 2.0 \u003cLICENSE or\n[https://www.apache.org/licenses/LICENSE-2.0](https://www.apache.org/licenses/LICENSE-2.0)\u003e.\nFiles in the project may not be copied, modified, or distributed except according to those terms.\n\n[Back to TOC](#table-of-contents)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkong%2Flua-resty-lmdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkong%2Flua-resty-lmdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkong%2Flua-resty-lmdb/lists"}