{"id":13483722,"url":"https://github.com/datastax/ruby-driver","last_synced_at":"2025-05-15T13:06:31.456Z","repository":{"id":20137328,"uuid":"23407534","full_name":"datastax/ruby-driver","owner":"datastax","description":"[MAINTENANCE ONLY] DataStax Ruby Driver for Apache Cassandra","archived":false,"fork":false,"pushed_at":"2024-07-10T16:48:12.000Z","size":7957,"stargazers_count":235,"open_issues_count":7,"forks_count":91,"subscribers_count":38,"default_branch":"master","last_synced_at":"2025-04-11T21:49:07.620Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://docs.datastax.com/en/developer/ruby-driver/latest","language":"Ruby","has_issues":false,"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/datastax.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"support/ccm.py","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-08-27T22:24:31.000Z","updated_at":"2025-02-08T12:39:17.000Z","dependencies_parsed_at":"2024-01-08T17:13:05.434Z","dependency_job_id":"e07fd1e2-4eb9-465a-89fb-7f6221d3ebca","html_url":"https://github.com/datastax/ruby-driver","commit_stats":{"total_commits":2539,"total_committers":47,"mean_commits":54.02127659574468,"dds":0.5116187475384009,"last_synced_commit":"2c9070cbb8f484da901bd0454a4c20478430615e"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datastax%2Fruby-driver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datastax%2Fruby-driver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datastax%2Fruby-driver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datastax%2Fruby-driver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/datastax","download_url":"https://codeload.github.com/datastax/ruby-driver/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254346624,"owners_count":22055808,"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":[],"created_at":"2024-07-31T17:01:14.600Z","updated_at":"2025-05-15T13:06:26.447Z","avatar_url":"https://github.com/datastax.png","language":"Ruby","readme":":warning: **The Ruby driver is in maintenance mode. We are still accepting pull-requests and we will occasionally release critical bug fixes, but no ongoing active development is being done currently.**\n\n# Datastax Ruby Driver for Apache Cassandra\n\n*If you're reading this on GitHub, please note that this is the readme for the development version and that some\nfeatures described here might not yet have been released. You can view the documentation for the latest released\nversion [here](http://docs.datastax.com/en/developer/ruby-driver/latest).*\n\n[![Build Status](https://travis-ci.org/datastax/ruby-driver.svg?branch=master)](https://travis-ci.org/datastax/ruby-driver)\n\nA Ruby client driver for Apache Cassandra. This driver works exclusively with\nthe Cassandra Query Language version 3 (CQL3) and Cassandra's native protocol.\n\nUse the [Ruby DSE driver](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/) for\nbetter compatibility and support for DataStax Enterprise.\n\n- Code: https://github.com/datastax/ruby-driver\n- Docs: http://docs.datastax.com/en/developer/ruby-driver\n- Jira: https://datastax-oss.atlassian.net/browse/RUBY\n- Mailing List: https://groups.google.com/a/lists.datastax.com/forum/#!forum/ruby-driver-user\n\nThis driver is based on [the cql-rb gem](https://github.com/iconara/cql-rb) by [Theo Hultberg](https://github.com/iconara) and we added support for:\n\n* [Asynchronous execution](http://docs.datastax.com/en/developer/ruby-driver/3.2/features/asynchronous_io/)\n* One-off, [prepared](http://docs.datastax.com/en/developer/ruby-driver/3.2/features/basics/prepared_statements/) and [batch statements](http://docs.datastax.com/en/developer/ruby-driver/3.2/features/basics/batch_statements/)\n* Automatic peer discovery and cluster metadata with [support for change notifications](http://docs.datastax.com/en/developer/ruby-driver/3.2/features/state_listeners/)\n* Various [load-balancing](http://docs.datastax.com/en/developer/ruby-driver/3.2/features/load_balancing/), [retry](http://docs.datastax.com/en/developer/ruby-driver/3.2/features/retry_policies/) and [reconnection](http://docs.datastax.com/en/developer/ruby-driver/3.2/features/reconnection/) policies with [ability to write your own](http://docs.datastax.com/en/developer/ruby-driver/3.2/features/load_balancing/implementing_a_policy/)\n* [SSL encryption](http://docs.datastax.com/en/developer/ruby-driver/3.2/features/security/ssl_encryption/)\n* [Flexible and robust error handling](http://docs.datastax.com/en/developer/ruby-driver/3.2/features/error_handling/)\n* [Per-request execution information and tracing](http://docs.datastax.com/en/developer/ruby-driver/3.2/features/debugging/)\n* [Configurable address resolution](http://docs.datastax.com/en/developer/ruby-driver/3.2/features/address_resolution/)\n\n[Check out the slides from Ruby Driver Explained](https://speakerdeck.com/avalanche123/ruby-driver-explained) for a detailed overview of the Ruby Driver architecture.\n\n## Compatibility\n\nThis driver works exclusively with the Cassandra Query Language v3 (CQL3) and Cassandra's native protocol. The current version works with:\n\n* Apache Cassandra versions 2.1, 2.2, 3.0+, and 4.0.x\n* DataStax Enterprise 4.8 and above. However, the [Ruby DSE driver](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/) provides more features and is recommended for use with DataStax Enterprise.\n* Ruby (MRI) 2.2, 2.3, 2.4\n* JRuby 9k\n\n__Note__: Rubinius is not supported. \n\n__Note__: Big-endian systems are not supported.\n\n## Quick start\n\n```ruby\nrequire 'cassandra'\n\ncluster = Cassandra.cluster # connects to localhost by default\n\ncluster.each_host do |host| # automatically discovers all peers\n  puts \"Host #{host.ip}: id=#{host.id} datacenter=#{host.datacenter} rack=#{host.rack}\"\nend\n\nkeyspace = 'system_schema'\nsession  = cluster.connect(keyspace) # create session, optionally scoped to a keyspace, to execute queries\n\nfuture = session.execute_async('SELECT keyspace_name, table_name FROM tables') # fully asynchronous api\nfuture.on_success do |rows|\n  rows.each do |row|\n    puts \"The keyspace #{row['keyspace_name']} has a table called #{row['table_name']}\"\n  end\nend\nfuture.join\n```\n\n__Note__: The host you specify is just a seed node, the driver will automatically discover all peers in the cluster.\n\nRead more:\n\n* [`Cassandra.cluster` options](http://docs.datastax.com/en/developer/ruby-driver/3.2/api/cassandra/#cluster-class_method)\n* [`Session#execute_async` options](http://docs.datastax.com/en/developer/ruby-driver/3.2/api/cassandra/session/#execute_async-instance_method)\n* [Usage documentation](http://docs.datastax.com/en/developer/ruby-driver/3.2/features)\n\n## Installation\n\nInstall via rubygems\n\n```bash\ngem install cassandra-driver\n```\n\nInstall via Gemfile\n\n```ruby\ngem 'cassandra-driver'\n```\n\n__Note__: if you want to use compression you should also install [snappy](http://rubygems.org/gems/snappy) or [lz4-ruby](http://rubygems.org/gems/lz4-ruby). [Read more about compression.](http://docs.datastax.com/en/developer/ruby-driver/3.2/features/#compression)\n\n\n## Upgrading from cql-rb\n\nSome of the new features added to the driver have unfortunately led to changes in the original cql-rb API.\nIn the examples directory, you can find [an example of how to wrap the ruby driver to achieve almost complete\ninterface parity with cql-rb](https://github.com/datastax/ruby-driver/blob/v3.2.5/examples/cql-rb-wrapper.rb)\nto assist you with gradual upgrade.\n\nIf you are upgrading to DataStax Enterprise, use the [Ruby DSE driver](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/) for more features and better compatibility.\n\n## What's new in v3.2\nThis minor release adds support for MRI 2.4.x and also contains a few miscellaneous defect fixes. It also removes\nsupport for Ruby versions prior to 2.2. This was already officially the case, but the minimum version limit is\nnow enforced.\n\nSee the [changelog](https://github.com/datastax/ruby-driver/blob/v3.2.5/CHANGELOG.md) for more information on all\nchanges in this version and past versions.\n\n## What's new in v3.1\n\nThis minor release introduces features and fixes around resiliency, schema metadata, usability, and performance. One\nof the most user-impacting of these is the introduction of\n[execution profiles](http://docs.datastax.com/en/developer/ruby-driver/3.1/features/basics/execution_profiles).\nExecution profiles allow you to group various execution options into a 'profile' and you reference the desired\nprofile at execution time. Get the scoop\n[here](http://docs.datastax.com/en/developer/ruby-driver/3.1/features/basics/execution_profiles).\n\n## What's new in v3.0\n\n### Features:\n\n* Add support for Apache Cassandra native protocol v4\n* Add support for smallint, tinyint, date (`Cassandra::Date`) and time (`Cassandra::Time`) data types.\n* Include schema metadata for User Defined Functions and User Defined Aggregates.\n* Augment the `Cassandra::Table` object to expose many more attributes: `id`, `options`, `keyspace`, `partition_key`, `clustering_columns`, and `clustering_order`. This makes it significantly easier to write administration scripts that report various attributes of your schema, which may help to highlight areas for improvement.\n* Include client ip addresses in request traces, only on Cassandra 3.x.\n* Add new retry policy decision `Cassandra::Retry::Policy#try_next_host`.\n* Support specifying statement idempotence with the new `idempotent` option when executing.\n* Support sending custom payloads when preparing or executing statements using the new `payload` option.\n* Expose custom payloads received with responses on server exceptions and `Cassandra::Execution::Info` instances.\n* Expose server warnings on server exceptions and `Cassandra::Execution::Info` instances.\n* Add `connections_per_local_node`, `connections_per_remote_node`, `requests_per_connection` cluster configuration options to tune parallel query execution and resource usage.\n* Add `Cassandra::Logger` class to make it easy for users to enable debug logging in the client.\n* Add `protocol_version` configuration option to allow the user to force the protocol version to use for communication with nodes.\n* Add support for materialized views and indexes in the schema metadata.\n* Support the `ReadError`, `WriteError`, and `FunctionCallError` Cassandra error responses introduced in Cassandra 2.2.\n* Add support for unset variables in bound statements.\n* Support DSE security (`DseAuthenticator`, configured for LDAP).\n* Add a timeout option to `Cassandra::Future#get`.\n\n### Breaking Changes from 2.x:\n\n* `Cassandra::Future#join` is now an alias to Cassandra::Future#get and will raise an error if the future is resolved with one.\n* Default consistency level is now LOCAL_ONE.\n* Enable tcp no-delay by default.\n* Unavailable errors are retried on the next host in the load balancing plan by default.\n* Statement execution no longer retried on timeouts, unless the statement is marked as idempotent in the call to `Cassandra::Session#execute*` or when creating a `Cassandra::Statement` object. \n* `Cassandra::Statements::Batch#add` and `Cassandra::Session#execute*` signatures have changed in how one specifies query parameters. Specify the query parameters array as the value of the arguments key:\n \n```ruby\nbatch.add(query, ['val1', 'val2'])\n# becomes\nbatch.add(query, arguments: ['val1', 'val2'])\n\nbatch.add(query, {p1: 'val1'})\n# becomes\nbatch.add(query, arguments: {p1: 'val1'})\n```\n* The Datacenter-aware load balancing policy (`Cassandra::LoadBalancing::Policies::DCAwareRoundRobin`) defaults to using\n  nodes in the local DC only. In prior releases, the policy would fall back to remote nodes after exhausting local nodes.\n  Specify a positive value (or nil for unlimited) for `max_remote_hosts_to_use` when initializing the policy to allow remote node use.\n* Unspecified variables in statements previously resulted in an exception. Now they are essentially ignored or treated as null.\n\n## Code examples\n\nThe DataStax Ruby Driver uses the awesome [Cucumber Framework](http://cukes.info/) for\nboth end-to-end, or acceptance, testing and constructing documentation. All of the\nfeatures supported by the driver have appropriate acceptance tests with easy-to-copy code\nexamples in the `features/` directory.\n\n## Running tests\n\nIf you don't feel like reading through the following instructions on how to run\nruby-driver tests, feel free to [check out .travis.yml for the entire build code](https://github.com/datastax/ruby-driver/blob/v3.2.5/.travis.yml).\n\n* Check out the driver codebase and install test dependencies:\n\n```bash\ngit clone https://github.com/datastax/ruby-driver.git\ncd ruby-driver\nbundle install --without docs\n```\n\n* [Install ccm](http://www.datastax.com/dev/blog/ccm-a-development-tool-for-creating-local-cassandra-clusters)\n\n* Run tests against different versions of Cassandra:\n\n```bash\nCASSANDRA_VERSION=3.1.1 bundle exec cucumber # runs end-to-end tests (or bundle exec rake cucumber)\nCASSANDRA_VERSION=3.0.0 bundle exec rspec # runs unit tests (or bundle exec rake rspec)\nCASSANDRA_VERSION=2.1.12 bundle exec rake integration # run integration tests\nCASSANDRA_VERSION=2.1.12 bundle exec rake test # run both as well as integration tests\n```\n\n## Changelog \u0026 versioning\n\nCheck out the [releases on GitHub](https://github.com/datastax/ruby-driver/releases) and\n[changelog](https://github.com/datastax/ruby-driver/blob/v3.2.5/CHANGELOG.md). Version\nnumbering follows the [semantic versioning](http://semver.org/) scheme.\n\nPrivate and experimental APIs, defined as whatever is not in the\n[public API documentation][1], i.e. classes and methods marked as `@private`, will change\nwithout warning. If you've been recommended to try an experimental API by the maintainers,\nplease let them know if you depend on that API. Experimental APIs will eventually become\npublic, and knowing how they are used helps in determining their maturity.\n\nPrereleases will be stable, in the sense that they will have finished and properly tested\nfeatures only, but may introduce APIs that will change before the final release. Please\nuse the prereleases and report bugs, but don't deploy them to production without\nconsulting the maintainers, or doing extensive testing yourself. If you do deploy to\nproduction please let the maintainers know as this helps in determining the maturity of\nthe release.\n\n## Known bugs \u0026 limitations\n\n* Specifying a `protocol_version` option of 1 or 2 in cluster options will fail with a\n  `NoHostsAvailable` error rather than a `ProtocolError` against Cassandra node versions 3.0-3.4.\n* Because the driver reactor is using `IO.select`, the maximum number of tcp connections allowed is 1024.\n* Because the driver uses `IO#write_nonblock`, Windows is not supported.\n\nPlease [refer to the usage documentation for more information on common pitfalls](http://docs.datastax.com/en/developer/ruby-driver/3.2/features/)\n\n## Contributing\n\nFor contributing read [CONTRIBUTING.md](https://github.com/datastax/ruby-driver/blob/master/CONTRIBUTING.md)\n\n## Credits\n\nThis driver is based on the original work of [Theo Hultberg](https://github.com/iconara)\non [cql-rb](https://github.com/iconara/cql-rb/) and adds a series of advanced features\nthat are common across all other DataStax drivers for Apache Cassandra.\n\nThe development effort to provide an up to date, high performance, fully featured Ruby\nDriver for Apache Cassandra will continue on this project, while\n[cql-rb](https://github.com/iconara/cql-rb/) has been discontinued.\n\n## Copyright\n\n\u0026copy; DataStax, Inc.\n\nLicensed under the Apache License, Version 2.0 (the \"License\"); you may not use this file\nexcept in compliance with the License. You may obtain a copy of the License at\n\n[http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)\n\nUnless required by applicable law or agreed to in writing, software distributed under the\nLicense is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,\neither express or implied. See the License for the specific language governing permissions\nand limitations under the License.\n\n  [1]: http://docs.datastax.com/en/developer/ruby-driver/3.2/api\n","funding_links":[],"categories":["Database Drivers","Packages"],"sub_categories":["Libraries"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatastax%2Fruby-driver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatastax%2Fruby-driver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatastax%2Fruby-driver/lists"}