github-ds and the case for putting a Result object between you and the database

Three libraries, one ActiveRecord connection

github-ds is a collection of Ruby libraries for working with SQL on top of ActiveRecord's connection, and it is three libraries rather than one.

GitHub::KV is a key/value data store backed by MySQL. GitHub::SQL is for building and executing a SQL query, and it uses ActiveRecord's connection class while providing a better API for bind values and raw data access. GitHub::Result makes it easier to bake in resiliency by using a Result object instead of raising exceptions.

That last one is the thread through all three. The other two could have been separate libraries, but the reason they work together is that a key-value miss and a failed query both come back as the same kind of value.

The status note explains the trade in plain terms. The project is used in production extensively at GitHub, and because of that all changes will be thoroughly vetted, which could slow the process of contributing. The project says it will do its best to actively communicate the status of pull requests, and asks that anyone with substantial changes open an issue first to discuss.

The licence is MIT, the primary language is Ruby, and the last push to the repository was on 2026-10-16.

The Result object is the reason to look at this at all

The Result class is a small type, and the examples show both of its modes.

A successful call gives you a value and no exception:

result = GitHub::Result.new { do_something }
p result.ok? # => true
p result.value! # => 1

A failing one gives you the error instead:

result = GitHub::Result.new { do_something_that_errors }
p result.ok? # => false
p result.value { "default when error happens" } # => "default when error happens"
begin
  result.value! # raises exception because error happened
rescue => error
  p result.error
  p error
end

So there are three ways to read the outcome. ok? is a predicate with no side effect. value with a block gives you a fallback without an exception. value! raises, so it behaves like the call would have without the wrapper.

The key-value API uses the first form throughout. A get that finds nothing returns a Result whose value is nil rather than raising, and while the set and delete operations return nil directly. That consistency is what lets the library say it is used in production extensively without every caller writing a begin block.

The then method is the other half, and it is where the resiliency claim gets tested:

result = GitHub::Result.new {
  GitHub::Result.new { puts "Step 1: success!" }
}.then { |value|
  GitHub::Result.new { puts "Step 2: success!" }
}.then { |value|
  GitHub::Result.new { puts "Step 3: success!" }
}

When a step in the middle raises, the chain stops there and ok? is false, and the later step never runs. That is short-circuiting behaviour for a sequence of fallible operations, without exceptions crossing the chain.

GitHub::SQL is a query builder that only builds SQL

The SQL class is a thin layer, and the example makes the shape clear.

There are three static entry points, results, run and value, each taking a SQL string and optionally bind values:

GitHub::SQL.results <<-SQL
  SELECT * FROM example_key_values
SQL

GitHub::SQL.run <<-SQL, key: "foo", value: "bar"
  INSERT INTO example_key_values (`key`, `value`)
  VALUES (:key, :value)
SQL

The bind values are what make it more than a string wrapper. In the run example the values are passed as named parameters and bound with the :key and :value placeholders, which means the value does not get interpolated into the SQL text.

The instance form exists for the case where the query is built up conditionally, and the add method appends fragments to an existing query:

sql = GitHub::SQL.new <<-SQL
  SELECT `value` FROM example_key_values
SQL

key = ENV["KEY"]
unless key.nil?
  sql.add <<-SQL, key: key
    WHERE `key` = :key
  SQL
end

Note what this class is not. There is no schema abstraction, no relation, no lazy loading, no chainable where clause. It builds a SQL string with bound values and runs it on the ActiveRecord connection. The comparison with ActiveRecord's own query interface is therefore not a competition, and if you want the ORM, this is not it.

The examples directory holds separate files for the plain query, the add method, the key-value store, the Result type and running with an explicit connection, so the intended usage is documented per feature rather than in one narrative.

GitHub::KV is a MySQL key-value store with a schema you migrate yourself

The key-value store needs a table, and the library ships a Rails migration generator for it:

rails generate github:ds:active_record
rails db:migrate

The table name is configurable, and the README shows configuring it before the migration runs:

GitHub::KV.configure do |config|
  config.table_name = "new_key_values_table"
end

After that, the API is the one you would expect from a key-value store. There is get, set, mget for several keys at once, exists, mexists, setnx to set only if the key is absent, del, and mdel. The m-prefixed forms are batch variants, and in the example a get of a missing key returns a Result whose value is nil rather than raising.

The instance is created with an ActiveRecord connection, and the example passes the default one:

kv = GitHub::KV.new { ActiveRecord::Base.connection }

There is one behavioural quirk worth knowing before you build on it. Due to MySQL's default collation, KV keys are case-insensitive. So a key set as Foo and a key looked up as foo are the same key, which is fine for most uses and quietly wrong for the ones where case is meaningful.

Expiration is honoured but not cleaned up

The caveats section is short and it covers exactly one thing, and the thing is a real operational detail.

KV supports expiring keys and obeys expiration when performing operations, but it does not actually purge the expired rows. At GitHub, the team uses pt-archiver from the Percona toolkit to nibble the expired rows away, configured with a replica lag check and a specific set of options: the index name set to the index on the key values table for expires_at, a limit of 1000, and a where clause of expires_at less than or equal to the current time.

The shape of this is worth noticing. The library enforces the semantic, so a get on an expired key behaves as if it is gone, and the physical cleanup is left to a separate archival tool. That is a reasonable division of responsibility, since a library that deleted rows during reads would turn every read into a write.

The cost is that adopting KV means adopting pt-archiver too, or accepting a table that grows forever. The key_values table needs an index on expires_at for the archiver to work efficiently, and the configuration assumes one exists.

The index name in the configuration is specific enough to be a hint about the schema, since it names the key values table and the expires_at column, and the where clause is written against the current time in SQL rather than passed in from Ruby.

Local development, the MySQL requirement, and a project that plans to stay put

The development instructions are conventional Ruby, and the one requirement is the one that trips people up.

After checking out the repository you run script/bootstrap to install dependencies, script/test to run the tests, and script/console for an interactive prompt to experiment in. To install the gem locally you run script/install, and to release a new version you update the number in version.rb, commit, and run script/release, which creates a git tag, pushes the commits and tags, and pushes the gem file to rubygems.org.

The test requirement is specific: you need a MySQL database with no password set for the root user, and running docker-compose up boots just that. The project says this functionality is not currently used by GitHub and was from a contributor, so it asks you to say if it does not work or gets out of date.

The compose file is minimal. It is a version 3 file with a single mysql service on the 5.6 image, with the empty root password allowed through an environment variable and port 3306 published.

The roadmap section is the most telling part of the whole document. Nothing is currently on the radar other than continued maintenance, and the project invites you to open an issue if you have a big idea.

The maintainers table names four people, and the contributing section asks contributors to adhere to the Contributor Covenant and to read the contributing guide. Bug reports and pull requests are welcome on GitHub, and the project describes itself as intended to be a safe, welcoming space for collaboration.

Editorial conclusion

github-ds suits a Rails application that already has a MySQL connection and wants raw SQL with proper bind values, a key-value store without adding a second datastore, and error handling that does not unwind the stack. It does not suit a team that wants a query builder or an ORM, because the SQL is yours to write, and it does not suit a project that expects a maintained community roadmap, because the stated plan is continued maintenance only. Before adopting it, look at the KV expiration behaviour, since expired rows are honoured but never purged by the library itself, and note that the last push was on 2026-10-16 with the project publishing no GitHub releases.

Frequently asked questions

Official sources

1. github/github-ds on GitHub
2. Issues
3. License: MIT
4. README