Upgrading from 2.13: runtime dependencies

The first release after 2.13.0 changes which gems familia declares and which libraries require 'familia' loads. familia 2.12.0 declared and loaded the same gems as 2.13.0, so this guide also covers an upgrade from 2.12. Each section below says what an application has to change. Sections that do not apply to your application need no action.

require 'familia' no longer loads base64

familia 2.13.0 required base64 when it loaded, so application code could call Base64 without requiring it. familia no longer requires base64 or depends on it. Code that relied on this raises NameError: uninitialized constant Base64 after the upgrade, on every Ruby version, unless another library in the process happens to load base64.

Earlier versions of familia's documentation generated encryption keys like this, with only require 'familia':

# Before
Familia.configure do |config|
  config.encryption_keys = {
    v1: Base64.strict_encode64(SecureRandom.bytes(32))
  }
end

SecureRandom.base64(32) generates the key without the base64 gem:

# After
require 'securerandom'

Familia.configure do |config|
  config.encryption_keys = {
    v1: SecureRandom.base64(32)
  }
end

To encode bytes you already have, such as fixed test keys, use [bytes].pack('m0'). Both use the encoding Base64.strict_encode64 uses, because all three make the same core call: Ruby's Random::Formatter#base64, which SecureRandom.base64 uses, is [random_bytes(n)].pack("m0"), and the base64 gem's strict_encode64 is [bin].pack("m0").

Code that keeps calling Base64 must require 'base64' itself. Under Bundler on Ruby 3.4 and later it must also list base64 in the Gemfile, because Ruby 3.4 moved base64 out of the default gems. Ruby 3.4's bundled_gems.rb lists it as "base64" => "3.4.0".

familia no longer depends on connection_pool

familia 2.13.0 declared connection_pool (>= 2.4, < 4.0) and required it when it loaded. familia calls no connection_pool API, so it now does neither, and it no longer limits which connection_pool version your bundle resolves. Another gem in the bundle may still install and load connection_pool, but nothing in familia ensures it.

Currently redis-client, which redis depends on, does both: the redis-client 0.29.0 gem specification declares s.add_runtime_dependency(%q<connection_pool>.freeze, [">= 0".freeze]), and its lib/redis_client/pooled.rb contains require "connection_pool". With that version require 'familia' still defines ConnectionPool, so the steps below keep a pool working if a later redis-client stops providing it.

An application that uses a ConnectionPool in Familia.connection_provider should add the gem to its Gemfile and require it before building the pool:

# Gemfile
gem 'connection_pool'
require 'connection_pool'

The provider itself does not change. See "Connection Pooling" in the README for a complete provider.

Minimum oj and json_schemer versions

familia.gemspec now requires oj ~> 3.16, >= 3.16.2 (was ~> 3.16) and json_schemer ~> 2.2 (was ~> 2.0). A Gemfile or lockfile that pins an older oj or json_schemer no longer resolves with familia. Raise or remove the pin.

The excluded releases require libraries that Ruby 3.4 moved out of the default gems without declaring them, so under Bundler on Ruby 3.4 and later they fail to load unless the bundle happens to contain those libraries: oj 3.16.0 and 3.16.1 require bigdecimal, which breaks require 'familia', and json_schemer 2.0.0 to 2.1.1 require base64 and bigdecimal, which breaks schema validation.

json_schemer 2.2.0 to 2.5.0 declare bigdecimal, so a bundle that resolves familia's new json_schemer requirement contains bigdecimal, and oj 3.16.0 and 3.16.1 would load in it. The json_schemer floor is what fixes the oj failure. The oj floor excludes those releases as well, because they require bigdecimal without declaring it.

oj 3.16.2 to 3.16.4 also require ostruct without declaring it, but they rescue the failure, so they load and work. Ruby 3.4 and later print a warning that ostruct was loaded from, or is no longer part of, the default gems. Upgrade oj, or add ostruct to your Gemfile, to silence it.

familia declares json_schemer, so an application needs no Gemfile entry for it. If you keep one, it must allow 2.2 or later.

Minimum redis version

familia.gemspec now requires redis >= 5.4, < 6.0 (was >= 5.0, < 6.0). A Gemfile or lockfile that pins redis below 5.4 no longer resolves with familia. Raise or remove the pin:

# Gemfile
gem 'redis', '>= 5.4', '< 6.0'

Some familia methods return true or false only with redis 5.4 or later. "familia requires redis-rb 5.4 or later" in Command Replies Inside Transactions and Pipelines names them and what they would return with an older redis.

Interactive migrations raise PreconditionFailed

A Familia::Migration::Model migration with @interactive = true loads pry-byebug when #migrate starts. familia does not depend on pry-byebug. When it is missing from the bundle or fails to load, #migrate now raises Familia::Migration::Errors::PreconditionFailed instead of LoadError, and Familia::Migration::Runner records the migration as :failed instead of letting the LoadError end the run.

  • To use interactive mode, add pry-byebug to the Gemfile, for example in the development group.
  • Code that rescued LoadError around #migrate should rescue Familia::Migration::Errors::PreconditionFailed instead.
  • rake familia:migrate:run and familia:migrate:dry_run now print Failed: <migration id> with the error and exit 0, as they do for any other failed migration. The uncaught LoadError used to end them with exit status 1. A deploy step that relied on that status should check the task's output or rake familia:migrate:status instead.

Schema validation raises when json_schemer cannot load

When json_schemer is installed but one of its own requires fails, schema validation now raises Familia::SchemaValidatorLoadError, whose cause is the LoadError. familia 2.13.0 warned json_schemer gem not installed in that case and disabled validation, so every record passed.

How a migration meets the error depends on its kind:

  • Familia::Migration::Model#migrate raises it at the first record it validates, through validate_before_transform?, validate_after_transform? or a validate_schema call in #process_record, in a dry run as well as an actual run.
  • Familia::Migration::Pipeline does not run the validation hooks, so validate_before_transform? and validate_after_transform? have no effect in a Pipeline, with or without a working json_schemer. A Pipeline raises the error only when #should_process?, #build_update_fields or #execute_update calls validate_schema, and only in an actual run. A dry run does not call those methods, so a Pipeline dry run succeeds while json_schemer cannot load.

Where #migrate raises it, Familia::Migration::Base.run and .cli_run let it propagate rather than returning false or an exit code, and Familia::Migration::Runner records the migration as :failed.

If you see this error, fix the bundle so that json_schemer loads. The error's cause names the file that could not be loaded. When json_schemer itself is absent, validation still warns and is disabled, as before.