{"id":15056778,"url":"https://github.com/thibaultcha/lua-cassandra","last_synced_at":"2025-04-10T04:35:20.257Z","repository":{"id":32985765,"uuid":"36612614","full_name":"thibaultcha/lua-cassandra","owner":"thibaultcha","description":"Pure Lua driver for Apache Cassandra","archived":false,"fork":false,"pushed_at":"2022-09-20T04:58:27.000Z","size":1135,"stargazers_count":98,"open_issues_count":12,"forks_count":36,"subscribers_count":15,"default_branch":"master","last_synced_at":"2024-04-14T20:01:52.631Z","etag":null,"topics":["cassandra","lua","lua-resty","luajit","ngx-lua","openresty"],"latest_commit_sha":null,"homepage":"https://thibaultcha.github.io/lua-cassandra","language":"Lua","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/thibaultcha.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-05-31T16:51:40.000Z","updated_at":"2024-03-09T10:34:03.000Z","dependencies_parsed_at":"2023-01-14T22:56:20.470Z","dependency_job_id":null,"html_url":"https://github.com/thibaultcha/lua-cassandra","commit_stats":null,"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thibaultcha%2Flua-cassandra","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thibaultcha%2Flua-cassandra/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thibaultcha%2Flua-cassandra/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thibaultcha%2Flua-cassandra/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thibaultcha","download_url":"https://codeload.github.com/thibaultcha/lua-cassandra/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248158293,"owners_count":21057147,"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":["cassandra","lua","lua-resty","luajit","ngx-lua","openresty"],"created_at":"2024-09-24T21:56:26.308Z","updated_at":"2025-04-10T04:35:20.226Z","avatar_url":"https://github.com/thibaultcha.png","language":"Lua","readme":"# lua-cassandra\n\n![Module Version][badge-version-image]\n[![Build Status][badge-travis-image]][badge-travis-url]\n[![Coverage Status][badge-coveralls-image]][badge-coveralls-url]\n\nA pure Lua client library for Apache Cassandra (2.x/3.x), compatible with\n[OpenResty].\n\n## Table of Contents\n\n- [Features](#features)\n- [Usage](#usage)\n- [Installation](#installation)\n- [Documentation and Examples](#documentation-and-examples)\n- [Roadmap](#roadmap)\n- [Development](#development)\n\n## Features\n\nThis library offers 2 modules: a \"single host\" module, compatible with PUC Lua 5.1/5.2,\nLuaJIT and OpenResty, which allows your application to connect itself to a\ngiven Cassandra node, and a \"cluster\" module, only compatible with OpenResty\nwhich adds support for multi-node Cassandra datacenters.\n\n- Single host `cassandra` module:\n  - no dependencies\n  - support for Cassandra 2.x and 3.x\n  - simple, prepared, and batch statements\n  - pagination (manual and automatic via Lua iterators)\n  - SSL client-to-node connections\n  - client authentication\n  - leverage the non-blocking, reusable cosocket API in ngx_lua (with\n    automatic fallback to LuaSocket in non-supported contexts)\n\n- Cluster `resty.cassandra.cluster` module:\n  - all features from the `cassandra` module\n  - cluster topology discovery\n  - advanced querying options\n  - configurable policies (load balancing, retry, reconnection)\n  - optimized performance for OpenResty\n\n[Back to TOC](#table-of-contents)\n\n## Usage\n\nSingle host module (Lua and OpenResty):\n\n```lua\nlocal cassandra = require \"cassandra\"\n\nlocal peer = assert(cassandra.new {\n  host = \"127.0.0.1\",\n  port = 9042,\n  keyspace = \"my_keyspace\"\n})\n\npeer:settimeout(1000)\n\nassert(peer:connect())\n\nassert(peer:execute(\"INSERT INTO users(id, name, age) VALUES(?, ?, ?)\", {\n  cassandra.uuid(\"1144bada-852c-11e3-89fb-e0b9a54a6d11\"),\n  \"John O Reilly\",\n  42\n}))\n\nlocal rows = assert(peer:execute \"SELECT * FROM users\")\n\nlocal user = rows[1]\nprint(user.name) -- John O Reilly\nprint(user.age)  -- 42\n\npeer:close()\n```\n\nCluster module (OpenResty only):\n\n```\nhttp {\n    # you do not need the following line if you are using luarocks\n    lua_package_path \"/path/to/src/?.lua;/path/to/src/?/init.lua;;\";\n\n    # all cluster informations will be stored here\n    lua_shared_dict cassandra 1m;\n\n    server {\n        ...\n\n        location / {\n            content_by_lua_block {\n                local Cluster = require 'resty.cassandra.cluster'\n\n                -- For performance reasons, the cluster variable\n                -- should live in an upvalue at the main chunk level of your\n                -- modules to avoid creating it on every request.\n                -- see the 'intro' example in the online documentation.\n                local cluster, err = Cluster.new {\n                    shm = 'cassandra', -- defined by the lua_shared_dict directive\n                    contact_points = {'127.0.0.1', '127.0.0.2'},\n                    keyspace = 'my_keyspace'\n                }\n                if not cluster then\n                    ngx.log(ngx.ERR, 'could not create cluster: ', err)\n                    return ngx.exit(500)\n                end\n\n                local rows, err = cluster:execute \"SELECT * FROM users\"\n                if not rows then\n                    ngx.log(ngx.ERR, 'could not retrieve users: ', err)\n                    return ngx.exit(500)\n                end\n\n                ngx.say('users: ', #rows)\n            }\n        }\n    }\n}\n```\n\n[Back to TOC](#table-of-contents)\n\n## Installation\n\nWith [Luarocks]:\n\n```bash\n$ luarocks install lua-cassandra\n```\n\nOr via [opm](https://github.com/openresty/opm):\n\n```\n$ opm get thibaultcha/lua-cassandra\n```\n\nOr manually:\n\nOnce you have a local copy of this module's `lib/` directory, add it to your\n`LUA_PATH` (or `lua_package_path` directive for OpenResty):\n\n```\n/path/to/lib/?.lua;/path/to/lib/?/init.lua;\n```\n\n**Note**: When used *outside* of OpenResty, or in the `init_by_lua` context,\nthis module requires additional dependencies:\n\n- [LuaSocket](http://w3.impa.br/~diego/software/luasocket/)\n- If you wish to use SSL client-to-node connections,\n  [LuaSec](https://github.com/brunoos/luasec)\n- When used in PUC-Lua,\n  [Lua BitOp](http://bitop.luajit.org/) (installed by Luarocks)\n\n[Back to TOC](#table-of-contents)\n\n## Documentation and Examples\n\nRefer to the online [manual] and detailed [documentation]. You will also find\n[examples] there and you can browse the test suites for in-depth ones.\n\n[Back to TOC](#table-of-contents)\n\n## Roadmap\n\nCluster:\n- new load balancing policies (token-aware)\n\nCQL:\n- implement `decimal` data type\n- v4: implement `date` and `time` data types\n- v4: implement `smallint` and `tinyint` data types\n\n[Back to TOC](#table-of-contents)\n\n## Development\n\n#### Test Suites\n\nThe single host tests require [busted] and [ccm] to be installed. They can be\nrun with:\n\n```\n$ make busted\n```\n\nThe cluster module tests require\n[Test::Nginx::Socket](http://search.cpan.org/~agent/Test-Nginx-0.23/lib/Test/Nginx/Socket.pm)\nin addition to ccm. They can be run with:\n\n```\n$ make prove\n```\n\n#### Tools\n\nThis module uses various tools for documentation and code quality, they can\neasily be installed from Luarocks by running:\n\n```\n$ make dev\n```\n\nCode coverage is analyzed with [luacov](http://keplerproject.github.io/luacov/)\nfrom the **busted** tests:\n\n```\n$ make coverage\n```\n\nThe code is linted with [luacheck](https://github.com/mpeterv/luacheck):\n\n```\n$ make lint\n```\n\nThe documentation is generated with\n[ldoc](https://github.com/stevedonovan/LDoc) and can be generated with:\n\n```\n$ make doc\n```\n\n[Back to TOC](#table-of-contents)\n\n[Luarocks]: https://luarocks.org\n[OpenResty]: https://openresty.org\n[ccm]: https://github.com/pcmanus/ccm\n[busted]: http://olivinelabs.com/busted\n\n[documentation]: http://thibaultcha.github.io/lua-cassandra/\n[manual]: http://thibaultcha.github.io/lua-cassandra/manual/README.md.html\n[examples]: http://thibaultcha.github.io/lua-cassandra/examples/intro.lua.html\n\n[badge-travis-url]: https://travis-ci.org/thibaultcha/lua-cassandra\n[badge-travis-image]: https://travis-ci.org/thibaultcha/lua-cassandra.svg?branch=master\n\n[badge-coveralls-url]: https://coveralls.io/r/thibaultcha/lua-cassandra?branch=master\n[badge-coveralls-image]: https://coveralls.io/repos/thibaultcha/lua-cassandra/badge.svg?branch=master\u0026style=flat\n\n[badge-version-image]: https://img.shields.io/badge/version-1.5.2-blue.svg?style=flat\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthibaultcha%2Flua-cassandra","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthibaultcha%2Flua-cassandra","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthibaultcha%2Flua-cassandra/lists"}