Virtual actors in Ruby on Rails

• Five-minute guide
• Overview
• Agent guide (Markdown)
• This page as Markdown

Short answer

Yes. Solid Objects is a SQL-backed virtual actor library for Ruby on Rails. The gem is solid_objects. It gives each actor a stable identity, durable state, ordered operations, and automatic activation.

Solid Objects requires Rails. It is a Rails engine for Ruby 3.3 or newer and Rails 7.1 or newer. It is not a framework-independent Ruby actor runtime. State and mailboxes live in the SQLite, PostgreSQL, or MySQL database that the Rails application already uses. Redis and a separate actor service are not necessary.

Solid Objects is a pre-1.0 release. It makes no production-ready claim. Read Compatibility and maturity before you choose it.

What a virtual actor is

A virtual actor is a logical object that always exists by name. The caller does not create it, start it, or stop it. The runtime loads it when a message arrives and releases it when it is idle. Microsoft Orleans made this model known as "virtual actors".

Solid Objects implements four properties of that model:

Different identities run concurrently. One identity is a serialization point on purpose.

A small example

This actor holds one ticket for a buyer and releases the hold after ten minutes. Put it in app/actors/ticket_sale.rb:

class TicketSale < SolidObjects::Actor
  attribute :available, default: 1
  attribute :holds, default: -> { {} }

  def hold(buyer:)
    return { held: false, available: } if available.zero? || holds.key?(buyer)

    self.available -= 1
    self.holds = holds.merge(buyer => Time.current.to_i)
    schedule(at: 10.minutes.from_now, key: buyer).expire(buyer:)
    { held: true, available: }
  end

  def expire(buyer:)
    return available unless holds.key?(buyer)

    self.holds = holds.except(buyer)
    self.available += 1
  end
end

Call it from a controller, a job, or the console:

TicketSale.ref("event-42").hold(buyer: "ada")

Two concurrent hold calls for event-42 enter the same mailbox. They commit one at a time, so only one buyer gets the ticket. The hold and its reminder commit in one transaction. The reminder runs in the Solid Objects runtime process:

bundle exec solid_objects start

If that process stops, the reminder stays in SQL. It runs when the process starts again.

The example needs installation, migrations, and an authorization policy. The generated policies deny every operation by default. For the complete setup, use one of these guides:

• Installation in the README.
• The clean-install quickstart, which a smoke check runs against the built gem in a new Rails application.
• The agent guide, which gives setup and verification steps for coding agents.

When to use it

Solid Objects is a good candidate when most of these conditions are true:

• State belongs to one durable identity, such as a cart, room, booking, device, account, or workflow.
• Writes for that identity must be serialized across requests, jobs, and processes.
• The work must happen later, survive a restart, or stay ordered across more than one request.
• The state is a bounded JSON document.
• The identity needs reminders, external effects, or reactive Rails views that follow its committed state.

When to use something else

Do not use an actor when a simpler tool enforces the invariant:

• One short transaction, with_lock, or a database constraint is enough. A row lock is often the clearest answer.
• The work is CPU-intensive or data-parallel. An actor serializes work. It does not add CPU parallelism.
• One hot identity must accept many writes for each second, for example a request-path rate limiter or a page-view counter.
• The state is large, relational, or query-heavy. Keep that data in normal tables.
• The operation must change two actor identities in one atomic transaction. Solid Objects has no cross-actor transactions.
• You need exactly-once calls to an external API. No actor library can promise that through every network failure. Solid Objects gives at-least-once delivery and stable effect IDs for idempotency keys.
• You need replay of named workflow steps from a step log. That is a durable execution engine, not an actor.

Choosing Solid Objects has the full checklist and the cost model.

How it compares

This table compares coordination models for a Rails application. It does not rank the projects. Facts about other projects were checked on October 7, 2026, against the sources in Primary references.

Orleans concept map

Orleans is the reference design for virtual actors on .NET. Solid Objects uses the same programming model on a SQL database. It does not copy the Orleans cluster, placement, or feature set.

Solid Objects delivery is at least once. Write each handler so that it can run again without harm.

Guarantees and boundaries

• Calls are durably ordered per identity. Different identities can run concurrently.
• Delivery is at least once, not exactly once. A handler can start again after a crash or a lost lease.
• Ordered turns do not cancel stale Ruby code. Fencing stops a stale activation from a commit, but that code can continue to run.
• External effects can run more than once. Use the stable effect ID, or another durable key, as the idempotency key at the provider.
• There are no transactions across actor identities, and there is no replay of durable function steps.
• Reminders, async calls, effects, and broadcasts need the bundle exec solid_objects start process. When that process stops, the work waits in SQL. The gem does not supply a hosted worker.
• One hot identity is sequential. The core gem is not a high-throughput request-path rate limiter.
• The guarantees apply only to changes made through the actor APIs. Actor fencing does not protect direct writes to the same data or other external requests.

The correctness contract states each guarantee and the crash matrix.

Compatibility and maturity

• Ruby 3.3 or newer and Rails 7.1 or newer. CI runs Ruby 3.3, 3.4, and 4.0 against Rails 7.1, 7.2, 8.0, and 8.1.
• SQLite 3.35 or newer, PostgreSQL 14 or newer, or MySQL 8.0 or newer with InnoDB. MySQL works through mysql2 or trilogy.
• SQLite is correct for the same contract, but it is best for development and modest single-host workloads.
• Pre-1.0. Expect changes that break compatibility. The correctness core has tests against all three databases. The project has no production-ready claim and no measured scale claim.

The roadmap records what is tested, what is partial, and what is next. For TypeScript and Node.js, use the solid-objects package.

Primary references

• Orleans: Overview, Request scheduling, Timers and reminders, Grain persistence, and Grain placement.
• Ruby: Ractor and the Ruby 4.0.0 release notes.
• concurrent-ruby: repository and Concurrent::Actor.
• Solid Queue: concurrency controls.
• Sidekiq: Enterprise unique jobs and Enterprise rate limiting.
• Dapr: Actors overview, Actor timers and reminders, and SDKs.
• Temporal: Ruby SDK and Event History.

Other projects change. Check these sources again before you base an architecture decision on one row.

Generated from docs/virtual-actors.md in cardmagic/solid-objects-ruby, v0.17.1, commit 7e19e64. For TypeScript and Node.js, read Virtual actors in TypeScript and Node.js.