{"id":31795798,"url":"https://github.com/davissp14/etcdv3-ruby","last_synced_at":"2025-10-10T20:21:32.883Z","repository":{"id":45853955,"uuid":"85432977","full_name":"davissp14/etcdv3-ruby","owner":"davissp14","description":"Etcd v3 Ruby Client","archived":false,"fork":false,"pushed_at":"2023-12-08T01:36:56.000Z","size":271,"stargazers_count":54,"open_issues_count":8,"forks_count":16,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-10-07T16:57:17.237Z","etag":null,"topics":["etcd","etcd-client","etcd3","etcdv3","etcdv3-ruby","grpc"],"latest_commit_sha":null,"homepage":"","language":"Ruby","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/davissp14.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":"2017-03-18T21:24:43.000Z","updated_at":"2025-06-04T11:57:04.000Z","dependencies_parsed_at":"2024-06-18T22:37:47.369Z","dependency_job_id":"6dcfcd8c-b18a-4ea7-9066-d9bacf991be6","html_url":"https://github.com/davissp14/etcdv3-ruby","commit_stats":{"total_commits":209,"total_committers":13,"mean_commits":"16.076923076923077","dds":"0.16267942583732053","last_synced_commit":"af8d2f095c72fde9949c77e2ab03ef127981248f"},"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/davissp14/etcdv3-ruby","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davissp14%2Fetcdv3-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davissp14%2Fetcdv3-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davissp14%2Fetcdv3-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davissp14%2Fetcdv3-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davissp14","download_url":"https://codeload.github.com/davissp14/etcdv3-ruby/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davissp14%2Fetcdv3-ruby/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279005273,"owners_count":26083861,"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","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["etcd","etcd-client","etcd3","etcdv3","etcdv3-ruby","grpc"],"created_at":"2025-10-10T20:21:31.216Z","updated_at":"2025-10-10T20:21:32.877Z","avatar_url":"https://github.com/davissp14.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# etcdv3-ruby  [![Gem Version](https://badge.fury.io/rb/etcdv3.svg)](https://badge.fury.io/rb/etcdv3) [![Build Status](https://travis-ci.org/davissp14/etcdv3-ruby.svg?branch=master)](https://travis-ci.org/davissp14/etcdv3-ruby) [![codecov](https://codecov.io/gh/davissp14/etcdv3-ruby/branch/master/graph/badge.svg)](https://codecov.io/gh/davissp14/etcdv3-ruby)\n\n\nRuby client for Etcd V3\n\n## Getting Started\n\n[RubyDocs](http://www.rubydoc.info/gems/etcdv3)\n\nTo install etcdv3, run the following command:\n```ruby\ngem install etcdv3\n```\n\n## Establishing a connection\n\n```ruby\nrequire 'etcdv3'\n\n# Insecure connection\nconn = Etcdv3.new(endpoints: 'http://127.0.0.1:2379, http://127.0.0.1:2389, http://127.0.0.1:2399')\n\n# Secure connection using default certificates\nconn = Etcdv3.new(endpoints: 'https://hostname:port')\n\n# Secure connection with Auth\nconn = Etcdv3.new(endpoints: 'https://hostname:port', user: 'root', password: 'mysecretpassword')\n\n# Scope CRUD operations to a specific keyspace. \nconn = Etcdv3.new(endpoints: 'https://hostname:port', namespace: \"/target_keyspace/\")\n\n# Secure connection specifying custom certificates\n# Coming soon...\n\n```\n**High Availability**\n\nIn the event of a failure, the client will work to restore connectivity by cycling through the specified endpoints until a connection can be established.  With that being said, it is encouraged to specify multiple endpoints when available.\n\nHowever, sometimes this is not what you want. If you need more control over\nfailures, you can suppress this mechanism by using\n\n```ruby\nconn = Etcdv3.new(endpoints: 'https://hostname:port', allow_reconnect: false)\n```\n\nThis will still rotate the endpoints, but it will raise an exception so you can\nhandle the failure yourself. On next call to the new endpoint (since they were\nrotated) is tried. One thing you need to keep in mind if auth is enabled, you \nneed to take care of `GRPC::Unauthenticated` exception and manually re-authenticate \nwhen token expires. To reiterate, you are responsible for handling the errors, so \nsome understanding of how this gem and etcd works is recommended.\n\n## Namespace support\n\nNamespacing is a convenience feature used to scope CRUD based operations to a specific keyspace.\n\n```ruby\n# Establish connection\nconn = Etcdv3.new(endpoints: 'https://hostname:port', namespace: '/service-a/')\n\n# Write key to /service-a/test_key\nconn.put(\"test_key\", \"value\"). \n\n# Get the key we just wrote.\nconn.get(\"test_key\")\n\n# Retrieve everything under the namespace.\nconn.get(\"\", \"\\0\") \n\n# Delete everything under the namespace.\nconn.del(\"\", \"\\0\")\n```\n\n_Note: Namespaces are stripped from responses._\n\n\n## Adding, Fetching and Deleting Keys\n```ruby\n # Put\n conn.put('foo', 'bar')\n\n # Get\n conn.get('my')\n\n # Get actual value\n value = conn.get('my').kvs.first.value\n\n # Get Key Range\n conn.get('foo', range_end: 'foo80')\n\n # Delete Key\n conn.del('foo')\n\n # Delete Key Range\n conn.del('foo', range_end: 'foo80')\n ```\n\n## User Management\n```ruby\n# Add User\nconn.user_add('admin', 'secret')\n\n# Delete User\nconn.user_delete('admin')\n\n# Get User\nconn.user_get('admin')\n\n# List Users\nconn.user_list\n```\n\n## Role Management\n```ruby\n# Add Role\nconn.role_add('admin')\n\n# Grant Permission to Role\nconn.role_grant_permission('admin', :readwrite, 'foo', 'foo99')\n\n# Delete Role\nconn.role_delete('admin')\n\n# List Roles\nconn.role_list\n```\n\n## Authentication Management\n```ruby\n# Configure a root user\nconn.user_add('root', 'mysecretpassword')\n\n# Grant root role to root user\nconn.user_grant_role('root', 'root')\n\n# Enable Authentication\nconn.auth_enable\n```\nAfter you enable authentication, you must authenticate.\n```ruby\n# This will generate and assign an auth token that will be used in future requests.\nconn.authenticate('root', 'mysecretpassword')\n```\nDisabling auth will clear the auth token and all previously attached user information\n```\nconn.auth_disable\n```\n\n## Leases\n```ruby\n# Grant a lease with a 100 second TTL\nconn.lease_grant(100)\n\n# Attach key to lease\nconn.put('foo', 'bar', lease: 1234566789)\n\n# Get information about lease and its attached keys\nconn.lease_ttl(1234566789)\n\n# Revoke lease and delete all keys attached\nconn.lease_revoke(1234566789)\n```\n\n## Transaction\nTransactions provide an easy way to process multiple requests in a single transaction.\n\n_Note: You cannot modify the same key multiple times within a single transaction._\n\n```ruby\n# https://github.com/davissp14/etcdv3-ruby/blob/master/lib/etcdv3/kv/transaction.rb\nconn.transaction do |txn|\n  txn.compare = [\n    # Is the value of 'target_key' equal to 'compare_value'\n    txn.value('target_key', :equal, 'compare_value'),\n    # Is the version of 'target_key' greater than 10\n    txn.version('target_key', :greater, 10)\n  ]\n\n  txn.success = [\n    txn.put('txn1', 'success')\n  ]\n\n  txn.failure = [\n    txn.put('txn1', 'failed', lease: lease_id)\n  ]\nend\n```\n\n## Watch\n```ruby\n# Watch for changes on a specified key for at most 10 seconds and return\nevents = conn.watch('foo', timeout: 10)\n\n# Watch for changes on a specified key range and return\nevents = conn.watch('foo', range_end: 'fop')\n\n# Watch for changes since a given revision\nevents = conn.watch('foo', start_revision: 42)\n\n# Watches for changes continuously until killed.\nevent_count = 0\nconn.watch('boom') do |events|\n  puts events\n  event_count = event_count + 1\n  break if event_count \u003e= 10\nend\n```\n\n## Locks\n```ruby\n# First, get yourself a lease\nlease_id = conn.lease_grant(100)['ID']\n\n# Attempt to lock distibuted lock 'foo', wait at most 10 seconds\nlock_key = conn.lock('foo', lease_id, timeout: 10).key\n\n# Unlock the 'foo' lock using the key returned from `lock`\nconn.unlock(key)\n\n# Perform a critical section while holding the lock 'hello'\nconn.with_lock('hello', lease_id) do\n  puts \"kitty!\"\nend\n```\n\n## Alarms\n```ruby\n# List all active Alarms\nconn.alarm_list\n\n# Deactivate ALL active Alarms\nconn.alarm_deactivate\n```\n\n## Timeouts\n\nThe default timeout for all requests is 120 seconds.\n\n```ruby\n# Specify `command_timeout` to override the default global timeout.\nconn = Etcdv3.new(endpoints: 'https://hostname:port', command_timeout: 5) # 5 seconds\n\n# You can also specify request specific timeouts.\nconn.get(\"foo\", timeout: 2)\n```\n\nTimeouts apply to and can be set when:\n - Adding, Fetching and Deleting keys\n - User, Role, and Authentication Management\n - Leases\n - Transactions\n\n_Note: Timeouts currently do not affect Watch or Maintenance related commands._\n\n## Contributing\n\nIf you're looking to get involved, [Fork the project](https://github.com/davissp14/etcdv3-ruby) and send pull requests.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavissp14%2Fetcdv3-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavissp14%2Fetcdv3-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavissp14%2Fetcdv3-ruby/lists"}