{"id":15713658,"url":"https://github.com/jgaskins/redis","last_synced_at":"2025-04-09T09:10:39.807Z","repository":{"id":40603538,"uuid":"275411005","full_name":"jgaskins/redis","owner":"jgaskins","description":"Pure-Crystal Redis client, supporting clustering, RedisJSON, RediSearch, RedisGraph, and RedisTimeSeries","archived":false,"fork":false,"pushed_at":"2025-03-23T18:50:42.000Z","size":1423,"stargazers_count":58,"open_issues_count":10,"forks_count":18,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-02T00:36:49.451Z","etag":null,"topics":["crystal","crystal-lang","redis","redis-client","redis-cluster","redis-graph","redis-json","redis-timeseries","redisearch","redisjson","redistimeseries"],"latest_commit_sha":null,"homepage":"https://jgaskins.dev/redis/","language":"Crystal","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jgaskins.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-06-27T16:28:23.000Z","updated_at":"2025-03-23T18:50:45.000Z","dependencies_parsed_at":"2024-02-01T02:45:47.588Z","dependency_job_id":"6530d3ba-299b-489c-9643-bace5d60a61c","html_url":"https://github.com/jgaskins/redis","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/jgaskins%2Fredis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgaskins%2Fredis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgaskins%2Fredis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgaskins%2Fredis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jgaskins","download_url":"https://codeload.github.com/jgaskins/redis/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248008630,"owners_count":21032556,"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":["crystal","crystal-lang","redis","redis-client","redis-cluster","redis-graph","redis-json","redis-timeseries","redisearch","redisjson","redistimeseries"],"created_at":"2024-10-03T21:32:45.378Z","updated_at":"2025-04-09T09:10:39.776Z","avatar_url":"https://github.com/jgaskins.png","language":"Crystal","funding_links":[],"categories":[],"sub_categories":[],"readme":"# redis\n\nA pure-Crystal implementation of the Redis protocol\n\n## Installation\n\n1. Add the dependency to your `shard.yml`:\n\n   ```yaml\n   dependencies:\n     redis:\n       github: jgaskins/redis\n   ```\n\n2. Run `shards`\n\n## Usage\n\n```crystal\nrequire \"redis\"\n\nredis = Redis::Client.new # Defaults to `localhost` port 6379\n\nredis.set \"foo\", \"bar\"\nredis.get \"foo\" # =\u003e \"bar\"\n\nredis.incr \"counter\" # =\u003e 1\nredis.incr \"counter\" # =\u003e 2\nredis.decr \"counter\" # =\u003e 1\n\nredis.del \"foo\", \"counter\" # =\u003e 2\n```\n\n### Pipelined queries\n\nTo mitigate latency with multiple queries whose inputs and outputs are completely independent of each other, you can \"pipeline\" your queries by sending them all at once before reading them. To do this, you can use the `pipeline` method:\n\n```crystal\nredis.pipeline do |pipe|\n  pipe.incr \"foo\"\n  pipe.set \"bar\", \"baz\"\n  pipe.lpush \"my-list\", \"my value\"\nend\n```\n\nThe return value of `pipeline` will be an array containing the values of each of those calls in the order they were sent. So in this case, it might be `[1, nil, 2]` to match the return values of `incr`, `set`, and `lpush`, respectively.\n\n### Transactions\n\nThe Redis [`MULTI` command](https://redis.io/commands/multi) begins a transaction, so you can use the `multi` method to execute a transaction against the server:\n\n```crystal\nredis.multi do |txn|\n  txn.set \"foo\", \"bar\"\n  txn.incr \"baz\"\n  txn.lpush \"my-list\", \"my value\"\nend\n```\n\nThe transaction is automatically committed with [`EXEC`](https://redis.io/commands/exec) at the end of the block. If an exception occurs within the block, the transaction will be rolled back with [`DISCARD`](https://redis.io/commands/discard) before exiting the block.\n\nYou may also call `txn.discard`, which will effectively disable the transaction (all further methods called on the transaction do nothing), but will not exit the block. You will need to exit the block explicitly with `break` if there are operations within the block that cannot be rolled back, such as sending an email or sending a request to a third-party API.\n\nThe reason for this is that the only way to exit a containing block from an inner method in Crystal is to raise an exception, and this library chooses not to use exceptions for flow control.\n\n### Beyond `localhost`\n\nTo use a Redis server that isn't at `localhost:6379`, pass a `URI` to the client. For example, if you store it in your shell environment:\n\n```crystal\nredis = Redis::Client.new(URI.parse(ENV[\"REDIS_URL\"]))\n\n# ... or ...\n\nredis = Redis::Client.from_env(\"REDIS_URL\")\n```\n\nTo connect via SSL, make sure you use the `rediss://` URL scheme. If your Redis server requires a password or uses a different database slot than `0`, make sure you include them in the URL:\n\n```crystal\nredis = Redis::Client.new(URI.parse(\"rediss://:my_password@example.com/3\"))\n```\n\n### Connection Pool\n\nThe `Redis::Client` maintains a connection pool, so there is no need to run your own within your application. When you execute a command on the `Redis::Client`, it is automatically executed against a connection. When you execute a pipeline or transaction with `multi`, all commands within that block will automatically be routed to the same connection.\n\n**Configuration**\n\nFor this shard, we use the following default setting (outside of the Standard Lib defaults);\n\n```\nmax_idle_pool_size = 25\n```\n\n\u003e You can override this manually using the URI parameters.\n\u003e All other settings follow the DB::Pool defaults.\n\nThe behaviour of the connection pool can be configured from a set of query string parameters in the connection URI.\n\n| Name | Default value |\n| :--- | :--- |\n| initial\\_pool\\_size | 1 |\n| max\\_pool\\_size | 0 \\(unlimited\\) |\n| max\\_idle\\_pool\\_size | 1 |\n| checkout\\_timeout | 5.0 \\(seconds\\) |\n| retry\\_attempts | 1 |\n| retry\\_delay | 1.0 \\(seconds\\) |\n\nSee [Crystal guides](https://crystal-lang.org/reference/1.6/database/connection_pool.html) to learn more.\n\n**Example**\n\n```crystal\npool_params = \"?initial_pool_size=1\u0026max_pool_size=10\u0026checkout_timeout=10\u0026retry_attempts=2\u0026retry_delay=0.5\u0026max_idle_pool_size=50\"\nredis = Redis::Client.new(URI.parse(\"redis://localhost:6379/0#{pool_params}\"))\n```\n\n**Recommendations**\n\nIf you encounter any issues, keep these setting the same;\n\n- `initial_pool_size`\n- `max_pool_size`\n- `max_idle_pool_size`\n\nExample:\n\n```\ninitial_pool_size = 50\nmax_pool_size = 50\nmax_idle_pool_size = 50\n```\n\n### TCP Keep-Alive\n\nThe `Redis::Client` uses a pool of `Redis::Connection` under the hood.\nWithin `Redis::Connection` we create a `TCPSocket`, which can accept keepalive params.\nThe TCP keepalive settings can help you mitigate Redis connection stability issues.\n\n\u003e NOTE: This behaviour is disabled by default. See Configuration below on how to enable it.\n\n**Configuration**\n\nFor this shard, we use the following override setting;\n\n| Name | Default value |\n| :--- | :--- |\n| keepalive | false |\n| keepalive\\_count | 3 |\n| keepalive\\_idle | 60 |\n| keepalive\\_interval | 30 |\n\n\u003e You can override this manually using the URI parameters.\n\u003e The settings above have proven to have good results in production environments. However, every environment is different, so tweaking these settings may be necessary.\n\nSee [Crystal API](https://crystal-lang.org/api/1.6.0/TCPSocket.html) to learn more.\n\n**Example**\n\n```crystal\nparams = \"?keepalive=true\u0026keepalive_count=5\u0026keepalive_idle=10\u0026keepalive_interval=15\"\n\nredis = Redis::Client.new(URI.parse(\"redis://localhost:6379/0#{params}\"))\n# or direct connections\nredis = Redis::Connection.new(URI.parse(\"redis://localhost:6379/0#{params}\"))\n```\n\n**Recommendations**\n\nEnable this setting with the defaults if you are encountering connection issues.\n\nExample:\n\n```crystal\nparams = \"?keepalive=true\"\n\nredis = Redis::Client.new(URI.parse(\"redis://localhost:6379/0#{params}\"))\n# or direct connections\nredis = Redis::Connection.new(URI.parse(\"redis://localhost:6379/0#{params}\"))\n```\n\n## Development\n\nMake sure you have a Redis or KeyDB server running locally on port 6379.\n\nRedis must be installed with a stack server for the full text search (`ft`) and time series modules (`ts`) in order for all specs to run.\n\n### With Docker\n\nYou can use this for your docker-compose file\n\n```yaml\nredis:\n  image: redis/redis-stack-server\n  ports:\n    - \"6379:6379\"\n```\n\n### With Homebrew\n\nInstall the [`redis-stack` from homebrew](https://github.com/redis-stack/homebrew-redis-stack)\n\n\n## Contributing\n\n1. Fork it (\u003chttps://github.com/jgaskins/redis/fork\u003e)\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create a new Pull Request\n\n## Contributors\n\n- [Jamie Gaskins](https://github.com/jgaskins) - creator and maintainer\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjgaskins%2Fredis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjgaskins%2Fredis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjgaskins%2Fredis/lists"}