Skip to content

Latest commit

 

History

History
189 lines (125 loc) · 5.59 KB

README.md

File metadata and controls

189 lines (125 loc) · 5.59 KB
Raw

Redis Client for Crystal

Build Status PRs Welcome

A Redis client for the Crystal programming language.

Features

  • Performance (> 680,000 commands per second using pipeline on a MacBook Air with a single client thread)
  • Pipelining
  • Transactions
  • LUA Scripting
  • All string commands
  • All hash commands
  • All list commands
  • All set commands
  • All hyperloglog commands
  • All commands for bit operations
  • All sorted set commands
  • All geo commands
  • Publish/subscribe

Installation

Add it to your shard.yml:

dependencies:
  redis:
    github: stefanwille/crystal-redis

and then install the library into your project:

$ shards install

Installation on MacOS X

On MacOS X you may get this error:

ld: library not found for -lssl (this usually means you need to install the development package for libssl)
clang: error: linker command failed with exit code 1 (use -v to see invocation)
...

Or this warning:

Package libssl was not found in the pkg-config search path.
Perhaps you should add the directory containing `libssl.pc'
to the PKG_CONFIG_PATH environment variable
No package 'libssl' found
Package libcrypto was not found in the pkg-config search path.
Perhaps you should add the directory containing `libcrypto.pc'
to the PKG_CONFIG_PATH environment variable
No package 'libcrypto' found

The problem is that Crystal can't find openssl, because it is not installed by default on MacOS X.

The fix:

  1. Install openssl via Homebrew:
$ brew install openssl
  1. Set the environment variable PKG_CONFIG_PATH:
$ export PKG_CONFIG_PATH=/usr/local/opt/openssl/lib/pkgconfig

Note: Please write me if you know a better way!

Required Crystal Version

This library needs Crystal version >= 0.34.0

I haven't tested older Crystal versions.

Usage

Require the package:

  require "redis"

then

  redis = Redis.new

Then you can call Redis commands on the redis object:

  redis.set("foo", "bar")
  redis.get("foo")

Connection Pooling

Since version 2.0.0, a connection pool is built in. It is used implicitly through Redis::PooledClient:

redis = Redis::PooledClient.new
10.times do |i|
  spawn do
    redis.set("foo#{i}", "bar")
    redis.get("foo#{i}") # => "bar"
  end
end

This redis instance can be shared across fibers, and accepts the same Redis commands as the Redis class. It automatically allocates and frees connections from/to the pool, per command.

⚠️ If you are using Redis in a web context (e. g. with a framework like Kemal), you need to use connection pooling.

Examples

To get started, see the examples:

Documentation

Performance

I have benchmarked Crystal-Redis against several other client libraries in various programming languages in this blog article.

Here are some results:

  • Crystal: With this library I get > 680,000 commands per second using pipeline on a MacBook Air with a single client thread.

  • C: The equivalent program written in C with Hiredis gets me 340,000 commands per second.

  • Ruby: Ruby 2.2.1 with the redis-rb and Hiredis driver handles 150,000 commands per second.

Read more results for Go, Java, Node.js.

Status

I have exercised every API method in the spec and built some example programs. Some people report production usage.

I took great care to make this library very usable with respect to API, reliability and documentation.

Development

This project requires a locally running redis server running on port 6379 and with a Unix socket located at /tmp/redis.sock. In Homebrew's default redis.config the Unix domain socket option is disabled. To enable, edit /usr/local/etc/redis.conf or whatever your redis.conf is and uncomment this line:

# unixsocket /tmp/redis.sock

so that it reads

unixsocket /tmp/redis.sock

Then you can run the specs via

$ crystal spec

See more information.

WARNING

Running the spec will delete database number 0!

Questions, Bugs & Support

If you have questions or need help, please open a ticket in the GitHub issue tracker. This way others can benefit from the discussion.