$ opm get thibaultcha/lua-cassandra

lua-cassandra

![模块版本][badge-version-image] [![构建状态][badge-travis-image]][badge-travis-url] [![覆盖率状态][badge-coveralls-image]][badge-coveralls-url]

一个用于 Apache Cassandra (2.x/3.x) 的纯 Lua 客户端库，兼容 [OpenResty]。

特性

这个库提供两个模块：一个“单主机”模块，兼容 PUC Lua 5.1/5.2、LuaJIT 和 OpenResty，允许您的应用程序连接到指定的 Cassandra 节点；另一个“集群”模块，仅兼容 OpenResty，支持多节点 Cassandra 数据中心。

• 单主机 cassandra 模块

  • 无依赖

  • 支持 Cassandra 2.x 和 3.x

  • 简单、预备和批处理语句

  • 分页（通过 Lua 迭代器进行手动和自动分页）

  • SSL 客户端到节点连接

  • 客户端身份验证

  • 利用 ngx_lua 中的非阻塞、可重用 cosocket API（在不支持的上下文中自动回退到 LuaSocket）

• 集群 resty.cassandra.cluster 模块

  • cassandra 模块的所有功能

  • 集群拓扑发现

  • 高级查询选项

  • 可配置策略（负载均衡、重试、重新连接）

  • 针对 OpenResty 的性能优化

用法

单主机模块（Lua 和 OpenResty）

    local cassandra = require "cassandra"
    
    local peer = assert(cassandra.new {
      host = "127.0.0.1",
      port = 9042,
      keyspace = "my_keyspace"
    })
    
    peer:settimeout(1000)
    
    assert(peer:connect())
    
    assert(peer:execute("INSERT INTO users(id, name, age) VALUES(?, ?, ?)", {
      cassandra.uuid("1144bada-852c-11e3-89fb-e0b9a54a6d11"),
      "John O Reilly",
      42
    }))
    
    local rows = assert(peer:execute "SELECT * FROM users")
    
    local user = rows[1]
    print(user.name) -- John O Reilly
    print(user.age)  -- 42
    
    peer:close()

集群模块（仅限 OpenResty）

    http {
        # you do not need the following line if you are using luarocks
        lua_package_path "/path/to/src/?.lua;/path/to/src/?/init.lua;;";
    
        # all cluster informations will be stored here
        lua_shared_dict cassandra 1m;
    
        server {
            ...
    
            location / {
                content_by_lua_block {
                    local Cluster = require 'resty.cassandra.cluster'
    
                    -- For performance reasons, the cluster variable
                    -- should live in an upvalue at the main chunk level of your
                    -- modules to avoid creating it on every request.
                    -- see the 'intro' example in the online documentation.
                    local cluster, err = Cluster.new {
                        shm = 'cassandra', -- defined by the lua_shared_dict directive
                        contact_points = {'127.0.0.1', '127.0.0.2'},
                        keyspace = 'my_keyspace'
                    }
                    if not cluster then
                        ngx.log(ngx.ERR, 'could not create cluster: ', err)
                        return ngx.exit(500)
                    end
    
                    local rows, err = cluster:execute "SELECT * FROM users"
                    if not rows then
                        ngx.log(ngx.ERR, 'could not retrieve users: ', err)
                        return ngx.exit(500)
                    end
    
                    ngx.say('users: ', #rows)
                }
            }
        }
    }

安装

使用 [Luarocks]

    $ luarocks install lua-cassandra

或通过 opm

    $ opm get thibaultcha/lua-cassandra

或手动

在您拥有此模块的 lib/ 目录的本地副本后，将其添加到您的 LUA_PATH（或 OpenResty 的 lua_package_path 指令）中。

    /path/to/lib/?.lua;/path/to/lib/?/init.lua;

注意：在 OpenResty 之外 使用或在 init_by_lua 上下文中使用时，此模块需要额外的依赖项

• LuaSocket

• 如果您希望使用 SSL 客户端到节点连接，则需要 LuaSec

• 在 PUC-Lua 中使用时，需要 Lua BitOp（由 Luarocks 安装）

文档和示例

请参阅在线 [手册] 和详细的 [文档]。您还可以在其中找到 [示例]，并浏览测试套件以获取深入的示例。

路线图

集群

• 新的负载均衡策略（令牌感知）

CQL

• 实现 decimal 数据类型

• v4：实现 date 和 time 数据类型

• v4：实现 smallint 和 tinyint 数据类型

开发

测试套件

单主机测试需要安装 [busted] 和 [ccm]。它们可以通过以下命令运行

    $ make busted

集群模块测试除了 ccm 之外还需要 Test::Nginx::Socket。它们可以通过以下命令运行

    $ make prove

工具

此模块使用各种工具进行文档和代码质量检查，您可以通过运行以下命令从 Luarocks 轻松安装这些工具

    $ make dev

代码覆盖率使用来自 busted 测试的 luacov 进行分析

    $ make coverage

代码使用 luacheck 进行代码风格检查

    $ make lint

文档使用 ldoc 生成，可以通过以下命令生成

    $ make doc

[Luarocks]: https://luarocks.org [OpenResty]: https://openresty.org.cn [ccm]: https://github.com/pcmanus/ccm [busted]: http://olivinelabs.com/busted

[文档]: http://thibaultcha.github.io/lua-cassandra/ [手册]: http://thibaultcha.github.io/lua-cassandra/manual/README.md.html [示例]: http://thibaultcha.github.io/lua-cassandra/examples/intro.lua.html

[badge-travis-url]: https://travis-ci.org/thibaultcha/lua-cassandra [badge-travis-image]: https://travis-ci.org/thibaultcha/lua-cassandra.svg?branch=master

[badge-coveralls-url]: https://coveralls.io/r/thibaultcha/lua-cassandra?branch=master [badge-coveralls-image]: https://coveralls.io/repos/thibaultcha/lua-cassandra/badge.svg?branch=master&style=flat

[badge-version-image]: https://img.shields.io/badge/version-1.5.2-blue.svg?style=flat