The Isolator caveats list skips from 2 to 4, and its callback example ends in a stray e
Detect non-atomic interactions within DB transactions
At a glance
- What is it?
- Isolator is a Ruby gem that raises when an HTTP call or a background job is enqueued inside a database transaction, by wrapping the libraries that would do those things. The detection is clever and the operational story is load order: the gem has to be required last, an APM that patches Net::HTTP can hide the interception, and the queue adapter cannot tell a safe backend from an unsafe one. The documentation has two small breaks of its own.
- Who is it for?
- Isolator is worth adding to a test suite for any Rails app that charges payments, sends mail or enqueues jobs from inside a transaction, because those are the bugs that only appear under concurrency. Three things to know before you wire it up.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 32 days ago.
- What is it written in?
- Mainly Ruby, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- palkan/isolator1,127 ★ · +8
| Repository | 2026-09-11 | 2026-11-15 |
|---|---|---|
| palkan/isolator | 1.1k | 1.1k |
8 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The caveats list runs 1, 2, 4, 5, and the configuration example never closes
The usage section is introduced as plug and play, begins working as soon as it is required, and then lists potential caveats. The list has four items and they are numbered one, two, four and five. There is no third one. Whatever it was, it either was folded into the others or was dropped without renumbering, which is the kind of small break that makes readers doubt the items that are there. The configuration block below has the same character. It shows an isolating configure call assigning a logger, an exception flag, a notification flag, a backtrace filter taking the top five lines, and a custom ignorer class, and then the example stops. The block never closes and neither does the code fence. Copying that example means guessing what came next.
Isolator.configure do |config|
config.logger = nilThat fragment is what the page actually ends on.
The callbacks example ends with a stray character that would not parse
The callbacks section is the better-written half of the same page, and it documents three hooks: one fired when the gem enters a within-transaction context, one fired when it leaves, and one fired every time a transaction opens, whether root or nested. The third one is where the example breaks. After printing the connection id and the current depth it continues onto a line with a single lowercase letter standing alone, and that line is inside the fence.
# This callback is called every time a new transaction is open (root or nested)
Isolator.on_transaction_begin do |event|
puts "New transaction from #{event[:connection_id]}. " \
"Current depth: #{event[:depth]}"
eThe letter is not valid Ruby, so the example cannot be pasted as printed. The information it was meant to carry is still useful: the event carries a connection id and a depth counter, which is what you would need to log nesting or to distinguish one database connection from another when you are running more than one.
Load order is the real constraint, and the page states it three separate times
The gem detects the environment and includes only the adapters it thinks are necessary, which means it is sensitive to the order things get required in. The general rule is that it must be required last, with a Rails-specific note that all adapters load after application initialisation. Then two more specific versions of the same rule appear further down for two different libraries. With database_cleaner, you are told to require the gem after it. With the sidekiq testing helper, requiring it after the gem will blow away the hooks, so the order has to be the other way round. Three statements, one principle, three different orderings depending on what else is in your test bundle. This is the failure mode to design around: the gem often appears to work, then silently stops detecting anything after another library is added to the test group.
The queue adapter cannot tell a safe backend from an unsafe one
The adapters are grouped by framework rather than by the underlying implementation, and the page is upfront about the consequence. The active job spy does not take into account which Active Job adapter you are using. The stated remedy, if you are on a safe one such as Que, is to disable the adapter rather than configure it. There is an oddity in how that is worded: the page describes the change as avoiding false negatives, while switching off a detector is the move that would produce them, so the sentence reads as though the argument ran in a circle. The instruction itself is unambiguous either way. Two lines of Ruby in an initializer require the Active Job base class and then disable the adapter by name, and each adapter can be turned off and back on the same way.
An APM that patches Net::HTTP can hide the interception, and the fix is in an issue comment
The HTTP adapter is built on a separate gem called Sniffer, which means detection depends on how Net::HTTP has been wrapped. That becomes a problem when something else in your stack instruments the same library. There is a specific note about it: if you are instrumenting Net::HTTP, for example by running an APM on staging or even in development, you may need to force Sniffer into prepend mode, and the answer is not in this repository's documentation. It is a comment on a specific issue, linked by number and with an anchor into the thread. That is a reasonable place to put a workaround that depends on the other gem's version, but it does mean the one integration detail most apt to bite you is documented somewhere a reader has to already know to look.
Ignores are combined with AND, so every proc has to return false
Offenses can be suppressed, and the reason given is structural rather than accidental: each adapter is a thin wrapper over the original code, so another library patching the same behaviour will produce false positives. The worked example is a queue library that postpones enqueueing until a transaction commits by patching the client's raw push method, which is exactly the case where raising would be wrong. You register a proc per adapter that returns true to ignore. The combining rule is the part worth internalising: an offense is registered if and only if all of the ignores return false. Two ignores that both say ignore therefore behave as a single suppression rather than a second condition, so adding a second proc does not make suppression stricter. The page does say you can add as many as you want.
The ignorer reads a todo file that is not in the repository
The configuration exposes an ignorer, documented as needing a custom class that implements a prepare method, and the default implementation uses a row-number-based list read from a file with a YAML extension named for the gem. That file is not present at the top of the repository, where the visible entries are release configuration, lint configuration for both Ruby and Markdown, the gemspec, a rakefile, a bin directory, a gemfiles directory, lib and spec. So the default ignore list is either created on first use or expected to come from somewhere the page does not name. The other two settings have their own small dependencies. Notifications go through a separate notifier gem that has to be installed separately and added to your Gemfile, and the backtrace filter is a callable of your own with a default that keeps the top five lines.
The newest release tag is two years older than the newest commit
The release history stops well before the branch does. Tags run 0.11.0 in late 2023, 1.0.0 in January 2024 and 1.1.0 in August 2024, while the last push to the default branch is dated 2026-09-11. So there is close to two years of commits on the branch with no tag covering them, which means installing the gem from a release feed gives you 2024 code and installing from the branch gives you something newer and untagged. The default branch is also called master rather than main, which dates the repository's conventions. On support, Active Record 6.0 and above is the supported path, with older Isolator releases named for earlier versions, and a second ORM is supported only conditionally, since it works only if an Active Support instrumentation extension happens to be loaded.
Editorial conclusion
Isolator is worth adding to a test suite for any Rails app that charges payments, sends mail or enqueues jobs from inside a transaction, because those are the bugs that only appear under concurrency. Three things to know before you wire it up. Load order is not optional, and the page states the same requirement in three separate places for three separate libraries. If anything else in your stack patches the same method, expect false positives and write an ignore proc rather than deleting the check. And the newest release tag is two years older than the newest commit on the default branch, so install from the branch you are reviewing rather than from what the release feed says is latest.
Frequently asked questions
What does Isolator do when it finds an offense?
It raises, with a separate exception class per kind of offence, HTTPError for an HTTP call inside a transaction and BackgroundJobError for an enqueue. Exception raising is on by default in the test environment and off elsewhere, and it can be set through the configuration block.
In which environments should Isolator be installed?
Tests and staging. The page suggests putting the gem in the development and test groups, or adding it with `require: false` and requiring it manually, which is the approach it recommends if you also want it running in the staging environment.
Why does Isolator need to be required last?
It detects the environment and loads only the adapters it needs, so load order decides which ones get installed. The page repeats the rule for other gems too, asking you to require it after database_cleaner and before sidekiq/testing, since requiring sidekiq/testing afterwards blows away the hooks.
How do I stop Isolator reporting false positives?
Register an ignore proc on the relevant adapter, as the page does for a queue library that postpones enqueueing until commit. An offense is registered only if every registered ignore returns false, and each adapter can also be disabled and re-enabled by name.
Which ORMs does Isolator support?
Active Record 6.0 and above, with older Isolator releases named for earlier versions. A second ORM is supported only if the Active Support instrumentation extension is loaded, and experimental multiple database support was added in version 0.7.0.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/palkan-isolator)Star history chart for your README
[](https://hysenlabs.com/projects/palkan-isolator)Was this useful?