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-byebugto the Gemfile, for example in the development group. - Code that rescued
LoadErroraround#migrateshould rescueFamilia::Migration::Errors::PreconditionFailedinstead. rake familia:migrate:runandfamilia:migrate:dry_runnow printFailed: <migration id>with the error and exit 0, as they do for any other failed migration. The uncaughtLoadErrorused to end them with exit status 1. A deploy step that relied on that status should check the task's output orrake familia:migrate:statusinstead.
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#migrateraises it at the first record it validates, throughvalidate_before_transform?,validate_after_transform?or avalidate_schemacall in#process_record, in a dry run as well as an actual run.Familia::Migration::Pipelinedoes not run the validation hooks, sovalidate_before_transform?andvalidate_after_transform?have no effect in a Pipeline, with or without a workingjson_schemer. A Pipeline raises the error only when#should_process?,#build_update_fieldsor#execute_updatecallsvalidate_schema, and only in an actual run. A dry run does not call those methods, so a Pipeline dry run succeeds whilejson_schemercannot 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.