Prateek Codes - Building Scalable Backend Systems

Multi-hop delegation for AI agents: porting OAuth's on-behalf-of pattern into MCP topologies

Tue, 07 Apr 2026 00:00:00 +0000

Most AI agent deployments hit an awkward authentication problem inherited from web auth. A user authenticates. The user invokes an agent. The agent calls a tool. The tool calls another tool. By the time the request reaches the third service down, the identity of the original principal has either been lost, forged, or smuggled forward as a bearer credential that the agent could just as easily exfiltrate. The naive solutions are familiar. Hand the agent the user’s access token, and it leaks the first time a prompt injection succeeds. Give the agent its own credential, and downstream services lose user attribution. Pass a custom header full of user claims, and the claims have no cryptographic binding to the original session.

The IAM community already has the right pattern. It is RFC 8693 Token Exchange and the on-behalf-of grant flow it formalizes. Several IETF drafts now extend that flow specifically for agent topologies. This post is about that pattern.

Introducing: delegated authorization with actor chains

Delegation is the old IAM word for “principal A authorizes principal B to act for them, with some bounded scope.” Impersonation is the variant where the downstream service cannot tell whether A or B made the call. Delegation is the variant where it can. For agent topologies, the second is the only acceptable design.

RFC 8693 Token Exchange formalizes both. The relevant primitives are two token parameters: subject_token (the principal the request is being made for) and actor_token (the principal making the request on their behalf). When an agent calls a tool, the token it presents has the user as subject and the agent itself as actor. When that tool, in turn, calls another tool, the second tool receives a token whose subject is still the user, whose immediate actor is the first tool, and whose actor’s actor is the agent. The chain is preserved.

The act claim is what makes this work. It is a nested JWT claim whose value is itself an actor description, recursively. A four-hop call carries four-deep actor nesting. The token is no longer “a bearer credential that names a principal.” It is a transcript of who delegated to whom, signed by the issuer, that any downstream verifier can interpret.

This inverts the trust direction. In a bearer-token world, every downstream service has to trust that the immediate caller is legitimately the principal it claims to be. In an actor-chain world, every downstream service can verify the entire chain of delegation from issuer-signed claims. The agent does not need the user’s secret. The agent has its own credential, presented alongside a delegation token that binds it to a specific user context.

Why bearer tokens fail in agent topologies

Three failure modes show up immediately when bearer credentials are reused across composed agent tool calls. Each is recognizable from older IAM experience. Each is amplified by the probabilistic nature of agent behavior.

Token exfiltration through prompt injection. If the agent holds the user’s bearer token, the agent can be coerced into sending it somewhere. Prompt injection is the agent-shaped variant of an attack that web-IAM solved by binding tokens to channels (cookies with HttpOnly, proof-of-possession tokens, mTLS-bound sessions). Bearer tokens in the agent’s working context are stored, transmitted, and reasoned about by a language model that does not have HttpOnly. The mitigation is structural: the agent must not hold a credential that grants it the user’s authority. It must hold a credential that grants it the right to ask, on the user’s behalf, with the issuer mediating each ask.

Audit blindness. When a downstream service sees a bearer token whose subject is the user, the audit log can only record “the user did this.” If the call was actually initiated by an agent acting for the user, that distinction is missing from the record. Post-incident forensics on agent activity then becomes impossible: every agent action looks like a user action, and the principal-of-record for the call is wrong. The actor chain fixes this because it records, in the token itself, which agent invoked which tool, and the audit log can capture it without trusting the agent’s self-report.

Cross-tool replay. Bearer tokens are valid wherever the issuer is trusted. An agent that received a token for one tool can present the same token to a different tool if that tool’s verifier accepts the same issuer. RFC 8707 Resource Indicators address part of this by binding tokens to specific audiences. RFC 8693 addresses the rest by ensuring that each hop receives a fresh token narrowed to its audience and scope, derived from but not equal to the token the previous hop received. Replay across the topology becomes a token forgery problem, not a token reuse problem.

What the actor chain looks like

The mechanics are clarified by walking through a single exchange. An agent has just received a request from a user. The agent has its own credential (the agent assertion). To call a downstream tool on the user’s behalf, the agent presents both: its own credential as actor_token, and the user’s authorization assertion as subject_token. The authorization server returns a new access token whose subject is the user and whose immediate actor (the act claim) is the agent.

When that tool in turn needs to call another tool, it performs another exchange. It presents its own credential as actor_token. It presents the token it just received as subject_token. The authorization server returns a token whose subject is still the user, whose immediate actor is the tool, and whose actor’s actor is the original agent. The claim structure looks like this:

{
  "iss": "https://auth.example.com",
  "aud": "tool_b",
  "sub": "user:alice",
  "act": {
    "sub": "tool_a",
    "act": {
      "sub": "agent:session-7f3a"
    }
  },
  "scope": "orders:read",
  "exp": 1715800000
}

That structure is the delegation history of the request, signed by the issuer, verifiable by any party that trusts the issuer’s keys. The downstream verifier knows three things at once: who the action is ultimately for, who the most recent actor was, and the full chain of actors that brought the request to this point. The authorization policy at each hop can use any of those claims, individually or in combination, as inputs to its decision.

What this fixes, and what it does not

The chain pattern fixes the three failure modes named earlier, and a couple more besides.

Attribution becomes precise. Every audit record at every hop names the user, the agent, and the intermediate tools. Post-incident analysis stops being guesswork. Scoped delegation per hop becomes possible: the token exchange at each hop can narrow scope. An agent granted broad read access by the user can still choose to invoke only orders:read against tool A; the narrowing is recorded in the token A receives. If A then calls B, A can narrow further. The narrowing is monotonic, since downstream tokens cannot widen what upstream tokens granted. Revocation becomes selective: revoking the agent’s authority does not require revoking the user’s session, and revoking one tool’s authority does not require revoking the agent.

What this pattern does not fix is worth naming.

It does not verify agent intent. The user authorized the agent in general, not for this specific action. If the agent’s interpretation of the user’s request is wrong, every token in the chain is correctly issued for a request the user did not actually want. Step-up authorization is the answer there, and it is a separate problem.

It does not replace the policy decision. The actor chain is input to authorization, not output. Each hop still needs an RBAC or ABAC decision based on the claims in the token. Token exchange is a transport mechanism for delegation context, not a policy engine.

The state of the standards work

The IETF work is moving, with several drafts active. draft-oauth-ai-agents-on-behalf-of-user-02 (published August 2025) extends RFC 8693 with requested_actor and actor_token parameters specifically scoped to agent flows. It is the most direct port of the on-behalf-of pattern for MCP-shaped topologies. draft-rosenberg-oauth-aauth-00 (“AAuth: Agentic Authorization OAuth 2.1 Extension”) addresses a different slice: a grant flow for agents operating in voice, SMS, or messaging channels where the browser redirect at the heart of standard OAuth is not available. The two drafts are not competing so much as partitioning the problem space.

Inside the on-behalf-of slice specifically, the live question is how much new machinery is needed. One position holds that RFC 8693 already covers the essential semantics, and what is needed is profile-level guidance: standard claim shapes, conventions for naming agent principals, sensible defaults for token lifetime in agent contexts. The other position argues for explicit new parameters, on the basis that the assumptions in RFC 8693 (especially around how actor_token is obtained for a non-human actor) do not map cleanly onto stochastic agent sessions.

Either way, the direction is settled. Multi-hop delegation for agents will be expressed in the language of RFC 8693, with or without a profile draft on top. Reading the drafts now, rather than after the WG adopts one, is the cheaper option.

Conclusion

On-behalf-of is the second IAM lesson worth porting into agent terms, after scoped delegation. Together they cover most of what an MCP authorization design needs to get right at the protocol layer. The remaining lessons (sender-constrained tokens via DPoP, workload identity via SPIFFE-style attestation, step-up authorization through out-of-band re-auth) extend the pattern further but do not change its shape. The shape was decided in January 2020 when RFC 8693 was published. Agent authorization is, mostly, a question of adopting it deliberately rather than reinventing parts of it accidentally.

References

RFC 8693 - OAuth 2.0 Token Exchange
RFC 8707 - Resource Indicators for OAuth 2.0
draft-oauth-ai-agents-on-behalf-of-user-02 - IETF draft extending RFC 8693 for agent flows
AAuth: Agentic Authorization OAuth 2.1 Extension - competing IETF draft with broader scope
Model Context Protocol authorization specification
The multi-hop delegation problem for AI agents - explainer on the bearer-token failure mode
Read-only database MCPs as a scoped-delegation pattern - prior post on the RBAC/capability-surface half of the problem

Stop Pasting Schema Into Your AI: Connect PostgreSQL Directly with MCP

Sun, 05 Apr 2026 00:00:00 +0000

Agentic coding tools have gotten good at reading your codebase. Claude Code will find your schema.rb, Cursor will pick up your Prisma schema, and most tools know how to navigate ORM-based projects well enough to understand your data model structurally.

What they can’t do is reason about your actual data - and that gap matters more than most developers realize.

When you ask an AI to help design a new feature, it’s working from structure alone. It knows what columns exist, not how they’re used. It doesn’t know that your notifications table has 400M rows and any fan-out design will be a problem. It doesn’t know that 80% of your users have never set a preferences value, which changes how you’d model the feature. It doesn’t know whether a background job is necessary or whether the data volume makes a synchronous approach fine. These are the tradeoffs that determine whether a feature ships well or causes incidents - and without live data access, the AI is guessing.

The same gap shows up in debugging. When a query is slow, the AI has to ask you to run EXPLAIN ANALYZE and paste the results. When it needs row counts or value distributions, it asks you to run those too. You become the relay between the AI and your database.

Model Context Protocol (MCP) is an open standard that lets AI tools connect to external systems and query them directly. With a Postgres MCP server configured, your AI can inspect live data volumes, run EXPLAIN ANALYZE, check value distributions, and make recommendations grounded in what’s actually in your database.

The Problem

Here’s what designing a new feature looks like without MCP:

You: “I want to add a real-time notification feed for users.”

AI: “How many users do you have, and roughly how many notifications per user per day?”

You: (checks, pastes numbers)

AI: “And what does the current notifications table look like? How many rows total?”

You: (runs SELECT COUNT(*), pastes result)

AI: “What’s the read pattern - are users mostly reading recent notifications or querying by type?”

You: (runs a distribution query, pastes result)

The AI knows your schema. It has no idea what’s in it. Every data-dependent decision becomes a round-trip where you run the query and report back. For a non-trivial feature this happens five or ten times before you get a recommendation you can act on.

With a Postgres MCP Server

Once connected, the same conversation looks like this:

You: “I want to add a real-time notification feed for users.”

AI: (checks notifications table row count, queries user and notification distribution, inspects existing indexes)

AI: “You have 400M notification rows across 2.1M users, with a long tail - the top 5% of users account for 60% of rows. A naive fan-out on write will be a problem at this scale. I’d recommend a pull-based feed with a covering index on (user_id, created_at DESC) rather than pre-computing feeds. Here’s the schema and the background job design.”

No relay. The AI queries your database when it needs data and gives you a recommendation grounded in actual numbers. The same applies to debugging - understanding query plans becomes something the AI does directly rather than something you transcribe into the conversation.

Setting Up @modelcontextprotocol/server-postgres

The official Postgres MCP server is @modelcontextprotocol/server-postgres. The source repository was archived in May 2025, but the npm package remains functional and is the most straightforward way to get started.

Step 1: Create a Read-Only Database User

Never connect your AI tool using the same credentials your application uses. Create a dedicated user with read-only access:

-- Create a dedicated user for AI access
CREATE USER ai_readonly WITH PASSWORD 'your-secure-password';

-- Grant connect on the database
GRANT CONNECT ON DATABASE your_database TO ai_readonly;

-- Grant schema usage
GRANT USAGE ON SCHEMA public TO ai_readonly;

-- Grant read-only access to all current tables
GRANT SELECT ON ALL TABLES IN SCHEMA public TO ai_readonly;

-- Ensure future tables are also covered
ALTER DEFAULT PRIVILEGES IN SCHEMA public
  GRANT SELECT ON TABLES TO ai_readonly;

This limits blast radius significantly. Worth noting: the MCP server also runs all queries inside a READ ONLY transaction - the README states this explicitly - so it refuses mutations at the server level regardless of user permissions. The read-only DB user is a second, independent layer of protection. Both should be in place.

Step 2: Configure Claude Desktop or Claude Code

For Claude Desktop, edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://ai_readonly:your-secure-password@localhost:5432/your_database"
      ]
    }
  }
}

For Claude Code, open ~/.claude/settings.json and add the same mcpServers block:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://ai_readonly:your-secure-password@localhost:5432/your_database"
      ]
    }
  }
}

Restart Claude after saving.

Step 3: Verify the Connection

Ask Claude: “What tables are in my database?”

If it responds with your actual schema, you’re connected. The server exposes two capabilities to the AI:

Schema inspection - lists tables, columns, data types, constraints, and indexes
Query execution - runs SQL and returns results into the conversation context

That’s enough for the AI to write accurate migrations, suggest indexes based on actual table sizes, and debug slow queries by running EXPLAIN ANALYZE itself.

Other MCP Database Options

The official Postgres server works well for most local setups, but depending on your database host or what you need the AI to do, there are more capable alternatives.

Neon MCP is worth using if you’re on Neon’s serverless Postgres. It’s actively maintained, supports both read and write operations through proper authorization, and integrates branch management. This makes it practical for letting the AI help apply migrations against a staging branch without touching production.

Supabase MCP ships as part of Supabase’s tooling and gives the AI access to your project’s tables, schema, and Row Level Security policies. Useful if your authorization logic lives in the database.

SQLite MCP (@modelcontextprotocol/server-sqlite) is the equivalent for local SQLite databases.

For cloud-hosted databases - RDS, Azure Database, Cloud SQL - the configuration is identical to the local example above. If you’re on a primary-replica setup, point the connection string at the replica rather than the primary.

Security

Use a Read-Only Connection

Use a dedicated database user with SELECT-only privileges, as shown in Step 1. The MCP server’s built-in transaction protection is a safety net, not a substitute for database-level access control.

Zero Data Retention for Sensitive Databases

If your database contains PII, financial records, or anything you’d classify as sensitive, pay attention to your AI provider’s data retention policy. When the AI queries your database through MCP, the results - including actual row data - pass through the conversation context. That context may be retained by default.

For sensitive workloads:

Enable zero data retention (ZDR) through Anthropic’s API if it’s available on your plan. With ZDR enabled, prompts and outputs aren’t stored or used for model training.
Avoid querying raw PII through the AI - have the AI write the query, review it yourself, then run it outside the AI context.
Mask sensitive columns using a view that exposes only what the AI needs:

-- Expose a masked version of the users table
CREATE VIEW public.users_masked AS
SELECT
  id,
  created_at,
  updated_at,
  role,
  subscription_plan,
  '***' AS email,
  '***' AS phone_number
FROM users;

-- Grant access to the masked view only
GRANT SELECT ON public.users_masked TO ai_readonly;
REVOKE SELECT ON public.users FROM ai_readonly;

The AI still has enough context to answer questions about user behavior, subscription distribution, and counts - without seeing the actual values.

What Changes Day to Day

Once the MCP server is running, the AI can:

Understand your full schema without you explaining it
Suggest indexes based on actual table sizes and existing constraints
Write migrations that account for real foreign keys and default values
Debug slow queries by running EXPLAIN ANALYZE itself
Answer data questions like “how many orders shipped last week?” directly

The manual loop of pasting schema, waiting for a clarifying question, then pasting more schema mostly disappears.

Conclusion

The Postgres MCP server takes under ten minutes to set up, runs all queries in read-only transactions, and removes a class of manual work that compounds fast. Start with a dedicated read-only DB user, be deliberate about what data flows through the AI’s context, and you have a setup that’s practical and secure.

References

Rails 8.2 adds this_week?, this_month?, and this_year? to Date and Time

Sat, 04 Apr 2026 00:00:00 +0000

ActiveSupport already has today?, yesterday?, and tomorrow? on Date and Time. Rails 8.2 adds the next logical set: this_week?, this_month?, and this_year?.

Before

Checking whether a date falls within the current week, month, or year required range comparisons:

# Is this order from the current week?
order.placed_at.between?(Time.current.beginning_of_week, Time.current.end_of_week)

# Is this subscription expiring this month?
subscription.expires_on.between?(Date.current.beginning_of_month, Date.current.end_of_month)

# Is this event happening this year?
event.date.year == Date.current.year

Each check is readable enough on its own, but they add up quickly in controllers and views where you are branching on date ranges.

Rails 8.2

PR #55770 introduces three new predicate methods on Date and Time:

order.placed_at.this_week?           # true if within the current week
subscription.expires_on.this_month?  # true if within the current month
event.date.this_year?                # true if within the current year

They follow the same pattern as the existing predicates:

Date.current.this_week?   # => true
Date.current.this_month?  # => true
Date.current.this_year?   # => true

Date.yesterday.this_week? # => true (yesterday is still this week, usually)
Date.current.next_month.this_month? # => false

In controllers

def index
  @orders = Order.all
  @this_week_orders = @orders.select { |o| o.placed_at.this_week? }
  @this_month_orders = @orders.select { |o| o.placed_at.this_month? }
end

In views

<% if subscription.expires_on.this_month? %>
  <div class="warning">Your subscription expires this month.</div>
<% end %>

<% if report.generated_at.this_week? %>
  <span class="badge">Recent</span>
<% end %>

In scopes

For database queries, ActiveSupport already provides all_week, all_month, and all_year on Date and Time, which return ranges suitable for use in where clauses:

class Order < ApplicationRecord
  scope :placed_this_week,  -> { where(placed_at: Time.current.all_week) }
  scope :placed_this_month, -> { where(placed_at: Time.current.all_month) }
  scope :placed_this_year,  -> { where(placed_at: Time.current.all_year) }
end

The new predicate methods (this_week?, this_month?, this_year?) complement these scopes when working with already-loaded records in memory rather than filtering at the database level.

How to change the week boundary

this_week? uses Monday as the start of the week by default, consistent with ActiveSupport’s beginning_of_week. If your application configures a different week start, that is respected:

Date.beginning_of_week = :sunday
Date.current.beginning_of_week  # => last Sunday

Conclusion

this_week?, this_month?, and this_year? are small additions that remove a common category of boilerplate. They complete the set of readable date predicates that ActiveSupport has offered since Rails 3.

References

Read-only database MCPs as a scoped-delegation pattern: applying IAM primitives to AI agents

Thu, 02 Apr 2026 00:00:00 +0000

AI agents are useful in proportion to the context they can read. That is the productive observation. The unproductive one, which follows about thirty seconds later, is that giving an agent the context it wants usually means giving it broad access to production data. Most teams reach for one of three approaches: hand the agent a database credential, filter the agent’s behavior at the prompt layer (“don’t query the customers table unless asked”), or trust the agent because the model is good now. The first reproduces every shared-credential failure of the last twenty years. The second is policy enforcement at the wrong layer, since it depends on the thing being constrained to cooperate with the constraint. The third is not a policy.

The pattern that holds up is one identity engineers already recognize: scoped delegation through a narrow, audited, RBAC-governed capability surface. The Model Context Protocol (the emerging interface for exposing tools to LLM agents) provides a natural place to implement that pattern, and a read-only database MCP server, designed correctly, is an instance of it. This post is about the principles underneath it.

Introducing: scoped delegation pattern

In IAM terms, an AI agent is a non-human principal. That framing is doing more work than it looks. Principals need identities, capabilities they are authorized to invoke, and audit trails attached to each invocation. The model is not new; it is the model used for every service account, every workload identity, every cross-account role a backend service has held for the last decade. What changes with AI agents is the cardinality and the unpredictability: there are more of them, they are spun up casually, and their behavior is governed by a probabilistic policy nobody fully controls.

An MCP server is a policy-enforcement point. The policy decision is encoded in the surface of the server: which tools exist, what each tool accepts as input, what each tool is permitted to return, and which principals are allowed to invoke which tools. A backend service calling a database through a narrow IAM role does not hold credentials for the database; it holds authorization to invoke a specific set of capabilities. The agent’s relationship to the MCP server is structurally identical. The agent never holds database credentials. It holds an identity and an authorization to call tools.

That distinction is the entire point. If the agent held credentials, the surface of “what the agent can do” would be “anything the credentials grant.” With a capability surface in front of it, the surface of “what the agent can do” is the union of behaviors the tools permit. Those two surfaces look adjacent on a diagram. In production, they are an order of magnitude apart in blast radius.

The MCP server, in this framing, is not a convenience layer for the agent. It is the policy-enforcement point in an authorization model that already exists. Building one well is the job of porting that authorization model into agent-shaped terms.

Why RBAC is the right starting model

There is a temptation, when designing the authorization model for an agent, to reach immediately for attribute-based authorization. Each tool call gets a policy decision computed from request context, agent attributes, target object attributes, environmental conditions. The model is expressive, the model is the future, and the model is wrong for the first version.

Start with RBAC for agents the same way you would for humans. Define a small set of agent roles, each describing a coherent job: read_only_analyst, customer_support_lookup, engineering_debug. Bind each role to a fixed set of MCP tools. Bind each tool to a fixed set of database objects: which tables it touches, which columns it returns, which row-level predicates it always applies. The tool itself is a parameterized query, not a raw SQL interface, and the role grants the right to invoke it.

That last constraint is load-bearing. A run_sql(query) tool collapses the entire authorization model down to “agent can do anything the database role can do.” Every refinement above the database role becomes window dressing. The capability surface is supposed to be narrower than what the underlying credentials permit. A raw-query tool throws that away for flexibility the agent does not actually need.

The shape of a well-designed tool, in pseudocode:

tool "lookup_customer_orders":
  binds_to_role: customer_support_lookup
  params:
    customer_id: uuid (required)
    limit: int (max=50, default=10)
  query: |
    SELECT order_id, status, created_at, total_cents
    FROM orders
    WHERE customer_id = :customer_id
      AND created_at >= now() - interval '90 days'
    ORDER BY created_at DESC
    LIMIT :limit
  rate_limit: 100/hour per principal
  audit: full

RBAC for agents pays for itself on the human side of the system. Reviews are tractable: the question reduces to “which tools is this role bound to, and is that set still appropriate.” Audits are tractable: every invocation maps back to a role, and every role maps back to a fixed surface. Onboarding a new agent reduces to picking a role. Incident response reduces to revoking one.

ABAC and ReBAC are escape hatches for the 5% of cases RBAC genuinely cannot express: data sensitive because of its content rather than its location, relationships that bleed across object types, decisions that depend on request-time context. Reach for them when needed. Most teams reach too early, mistake expressive power for clarity, and end up with a policy graph nobody can answer questions about three months later.

What “read-only” actually has to mean

“Read-only” is a phrase that does not survive contact with a real authorization model. Most teams hear it and think “no INSERT, no UPDATE, no DELETE.” Necessary, not sufficient. Read-only at the IAM layer means a stricter set of things, all of which translate familiar IAM concerns into agent terms.

No raw query interface. Every tool is a parameterized query with a fixed shape. The agent supplies values for the parameters, not the query itself. This is least privilege expressed at the capability level: the agent gets the queries it has been authorized for, not “the database, in read-only mode.”

PII is redacted at the tool layer, not at the prompt layer. Prompt-layer redaction is policy enforcement at the wrong layer; it depends on the agent cooperating with the system that constrains it. Tool-layer redaction is enforced by the policy-enforcement point itself. The agent never sees what it is not entitled to see. This is data minimization translated from “do not log this field” to “do not return this field to this principal.”

Output volume is bounded. An agent that can invoke a per-customer lookup ten thousand times can extract the customers table. Per-tool rate limits, per-principal rate limits, and result-set caps are not optimizations; they are policy. They prevent capability misuse by repetition.

Cross-tool capability chaining is policed. If tool A returns a customer ID and tool B accepts a customer ID, the composition of A and B grants relationship access that neither tool grants alone. Static analysis of the tool surface catches the obvious cases. Runtime detection of suspicious call sequences catches the rest.

Audit is where this pattern earns its keep

Audit is where the design earns most of its keep, and it is the part most early implementations underweight. Every tool invocation is a policy decision the system has already made, which means every invocation is a logged event with a fixed shape: which agent invoked the call, under which role, against which tool, with which parameters, returning which result fingerprint, at which timestamp.

Two payoffs from getting this right.

First, the audit log is the post-incident forensic record, the role audit logs have always played in human-IAM systems. When something has gone wrong, the question “what did this principal do, when, and against what” needs a deterministic answer. Reconstructing agent behavior from prompts and model outputs is hopeless. Reconstructing it from a list of tool calls is mechanical.

Second, the audit log is the dataset on which agent behavior is tuned. Anomaly detection on agent activity becomes concrete once the data exists. A customer_support_lookup role that suddenly starts paginating through every customer in the database is a signal whose detection does not require understanding the model; it requires understanding the policy. The same techniques that flagged a service account exfiltrating data in 2015 flag an agent doing the same thing now.

What this pattern does not solve

Three honest limits, worth naming so they are not mistaken for places the pattern silently covers.

Write paths. Agents that need to write are a different problem. Approval workflows, dry-run modes, two-person rules, staged commits: all of these are familiar from the write side of human-IAM systems and none of them are addressed by the read-only capability pattern. Read is the easier half of the problem. Write deserves its own design.

Sensitive-by-context data. RBAC by tool and column does not capture “this record is sensitive because of who it is about.” A customer who is a minor, a transaction that is part of an active fraud investigation, an employee under HR review: none of these are detectable from the schema, and none of them are caught by the role-to-tool-to-column binding. This is genuinely ABAC territory, and a real reason to graduate from pure RBAC once the read pattern is solid.

Capability chaining at scale. The surface of an MCP server with five tools is reviewable by inspection. The surface of one with fifty is not. The combinatorics of what an agent can infer from a sequence of legitimate calls become a real threat model, and the inferential reach can exceed the apparent permission of any single tool. Static analysis of the tool surface helps. Runtime detection of suspicious call sequences helps more. Neither makes the problem go away.

Conclusion

AI agents are non-human principals at scale. The IAM community spent two decades figuring out how to give non-human principals safe access to systems. The teams that ignore that body of knowledge will rediscover its lessons the hard way, usually after an incident. The MCP read-only pattern is a way of porting one lesson, scoped delegation governed by RBAC, into the agentic era. The next ones worth porting, in roughly the order they are about to be needed, are just-in-time credentials, mutual authentication between agent and capability surface, and capability auditing across composed tool calls. Each is its own post.

References

Model Context Protocol specification
NIST Role-Based Access Control (RBAC) project
NIST Attribute-Based Access Control (ABAC) project
Zanzibar: Google’s Consistent, Global Authorization System - canonical modern reference for relationship-based access control (ReBAC)
Connecting PostgreSQL to AI tools via MCP - prior post covering MCP server setup mechanics

Rails 8.2 lets retry_on read the error when calculating wait time

Wed, 01 Apr 2026 00:00:00 +0000

Active Job’s retry_on accepts a wait: proc for custom backoff logic. Before Rails 8.2, that proc only received the execution count. When a remote API returns a Retry-After header, there was no way to use that value inside the proc. Rails 8.2 fixes this by passing the exception as a second argument.

Before

The wait: proc only knew how many times the job had been attempted:

class PaymentSyncJob < ApplicationJob
  retry_on Stripe::RateLimitError,
           attempts: 5,
           wait: ->(executions) { executions * 10 }

  def perform(order_id)
    Stripe::Charge.retrieve(order_id)
  end
end

If Stripe responded with a Retry-After: 30 header, the job ignored it. The wait time was always based on the execution count, regardless of what the API actually asked for.

To work around this, teams typically stored retry delay information on the exception class itself and then retrieved it through other means, which added boilerplate and coupling.

Rails 8.2

PR #56601 allows the wait: proc to accept the exception as a second argument. Rails checks the proc’s arity, so existing one-argument procs continue to work without any changes.

class PaymentSyncJob < ApplicationJob
  retry_on Stripe::RateLimitError,
           attempts: 5,
           wait: ->(executions, error) { error.retry_after || executions * 10 }

  def perform(order_id)
    Stripe::Charge.retrieve(order_id)
  end
end

When the job retries, it calls the proc with both the execution count and the exception. If the error has a retry_after value, that gets used. Otherwise, it falls back to the execution-based formula.

This works for any error class that exposes delay information:

class ExternalApiJob < ApplicationJob
  retry_on ApiRateLimitError,
           attempts: 10,
           wait: ->(executions, error) do
             # Use the header value if available, cap at 5 minutes
             [error.retry_after || executions ** 2, 300].min
           end

  def perform(resource_id)
    ExternalApi.fetch(resource_id)
  end
end

Backward Compatibility

The change is fully backward compatible. A proc with one argument behaves exactly as before:

# Still works, receives only executions
retry_on SomeError, wait: ->(executions) { executions * 5 }

# New behavior, receives both
retry_on SomeError, wait: ->(executions, error) { error.retry_after || executions * 5 }

Rails uses Ruby’s arity to determine which form the proc uses and calls it accordingly.

When to Use This

Use the two-argument form when:

The API you call returns a Retry-After header or equivalent
Your error class already captures the suggested wait time
You want backoff logic that adapts to what the remote service requests rather than using a fixed formula

Conclusion

Rails 8.2 makes retry logic more accurate for jobs that talk to rate-limited APIs. By exposing the exception to the wait: proc, jobs can respect what the remote service actually asks for instead of guessing.

References

Ruby::Box Practical Guide: Use Cases and Integration Patterns (Part 2)

Thu, 15 Jan 2026 00:00:00 +0000

In Part 1, we covered what Ruby::Box is and how it provides namespace isolation. Now let’s explore practical patterns for integrating it into real applications.

Use Case: Plugin Systems

Plugin systems benefit significantly from Ruby::Box. Each plugin runs in its own isolated environment, preventing plugins from interfering with each other or the host application.

class PluginManager
  def initialize
    @plugins = {}
  end

  def load_plugin(name, path)
    box = Ruby::Box.new
    box.require(path)

    # Access the plugin class from within the box
    plugin_class = box.eval('Plugin')
    @plugins[name] = {
      box: box,
      instance: plugin_class.new
    }
  end

  def run(name, method, *args)
    plugin = @plugins[name]
    plugin[:instance].public_send(method, *args)
  end

  def unload(name)
    @plugins.delete(name)
    # Box becomes eligible for garbage collection
  end
end

# Usage
manager = PluginManager.new
manager.load_plugin(:markdown, './plugins/markdown_plugin')
manager.load_plugin(:syntax_highlight, './plugins/syntax_plugin')

# Each plugin has its own isolated environment
# If markdown_plugin patches String, syntax_plugin won't see it
manager.run(:markdown, :process, content)

This pattern ensures that a misbehaving plugin cannot corrupt the global namespace or break other plugins.

Use Case: Multi-Tenant Configuration

Applications serving multiple tenants often need per-tenant configurations. Ruby::Box provides clean isolation without complex scoping logic.

class TenantContext
  def initialize(tenant_id, config_path)
    @tenant_id = tenant_id
    @box = Ruby::Box.new
    @box.require(config_path)
  end

  def config
    @box.eval('TenantConfig')
  end

  def execute(code)
    @box.eval(code)
  end
end

# Each tenant gets isolated configuration
tenant_a = TenantContext.new('acme', './tenants/acme/config')
tenant_b = TenantContext.new('globex', './tenants/globex/config')

tenant_a.config.theme      # => "dark"
tenant_b.config.theme      # => "light"

# Global variables are isolated too
tenant_a.execute('$rate_limit = 100')
tenant_b.execute('$rate_limit = 500')

tenant_a.execute('$rate_limit')  # => 100
tenant_b.execute('$rate_limit')  # => 500

Use Case: Running Multiple Gem Versions

During migrations, you might need to run two versions of the same gem simultaneously. Ruby::Box makes this possible without separate processes.

# Load v1 API client in one box
v1_box = Ruby::Box.new
v1_box.eval <<~RUBY
  $LOAD_PATH.unshift('./vendor/api_client_v1/lib')
  require 'api_client'
RUBY

# Load v2 API client in another box
v2_box = Ruby::Box.new
v2_box.eval <<~RUBY
  $LOAD_PATH.unshift('./vendor/api_client_v2/lib')
  require 'api_client'
RUBY

# Compare behavior during migration
def compare_responses(endpoint, params)
  code = "ApiClient.get('#{endpoint}', #{params.inspect})"
  v1_response = v1_box.eval(code)
  v2_response = v2_box.eval(code)

  if v1_response != v2_response
    log_difference(endpoint, v1_response, v2_response)
  end

  v1_response  # Return v1 for now, switch to v2 when ready
end

Use Case: Isolated Monkey Patches for Testing

Some tests require monkey patches that would pollute the global namespace. Ruby::Box keeps these contained.

# test_helper.rb
def create_time_frozen_box(frozen_time)
  box = Ruby::Box.new
  box.eval <<~RUBY
    class Time
      def self.now
        Time.new(#{frozen_time.year}, #{frozen_time.month}, #{frozen_time.day})
      end
    end
  RUBY
  box
end

# In your test
def test_subscription_expiry
  box = create_time_frozen_box(Time.new(2026, 1, 1))

  # Load and test code within the frozen-time box
  box.eval <<~RUBY
    expiry_date = Time.new(2025, 12, 31)
    subscription = Subscription.new(expires_at: expiry_date)
    raise "Expected expired" unless subscription.expired?
  RUBY

  # Time.now is unchanged outside the box
  Time.now  # => Current actual time
end

Use Case: Shadow Testing

Run new code paths alongside production code to compare results without affecting users. This pattern is useful for validating refactors or new implementations.

class ShadowRunner
  def initialize(production_box, shadow_box)
    @production = production_box
    @shadow = shadow_box
  end

  def run(method, *args)
    code = "#{method}(#{args.map(&:inspect).join(', ')})"

    # Production path returns the result
    production_result = @production.eval(code)

    # Shadow path runs asynchronously, logs differences
    Thread.new do
      shadow_result = @shadow.eval(code)

      unless production_result == shadow_result
        Logger.warn("Shadow mismatch for #{method}",
          production: production_result,
          shadow: shadow_result
        )
      end
    end

    production_result
  end
end

Working Around Native Extension Issues

Native extensions may fail to install with RUBY_BOX=1 enabled. The solution is to separate installation from execution:

# Gemfile installation without Boxing
bundle install

# Application execution with Boxing
RUBY_BOX=1 bundle exec ruby app.rb

For CI/CD pipelines:

# .github/workflows/test.yml
jobs:
  test:
    steps:
      - name: Install dependencies
        run: bundle install

      - name: Run tests with Ruby::Box
        run: RUBY_BOX=1 bundle exec rspec
        env:
          RUBY_BOX: "1"

Working Around ActiveSupport Issues

Some ActiveSupport core extensions have compatibility issues. Load them in your main context before creating boxes:

# At application startup, before creating any boxes
require 'active_support/core_ext/string/inflections'
require 'active_support/core_ext/hash/keys'

# Now create boxes for isolated code
plugin_box = Ruby::Box.new
# Plugins can use the already-loaded extensions

Alternatively, selectively load only what you need inside boxes:

box = Ruby::Box.new
box.eval <<~RUBY
  # Load specific extensions that are known to work
  require 'active_support/core_ext/object/blank'
RUBY

Performance Considerations

Ruby::Box adds minimal overhead for most operations:

Method dispatch: Slightly more indirection through separate method tables
Object creation: Unaffected, objects pass freely between boxes
Memory: Each box maintains its own class/module definitions

For performance-critical paths, cache class references:

class OptimizedPluginRunner
  def initialize(box)
    @box = box
    # Cache the class reference once
    @processor_class = box.eval('DataProcessor')
  end

  def process(data)
    # Use cached reference instead of evaluating each time
    @processor_class.new.process(data)
  end
end

When to Use `Ruby::Box`

Good candidates:

Plugin or extension systems where isolation is critical
Multi-tenant applications with per-tenant customizations
Testing scenarios requiring invasive monkey patches
Gradual migration between gem versions
Applications loading third-party code that might conflict

Poor candidates:

Running untrusted or potentially malicious code (use OS-level sandboxing)
Production systems until the feature stabilizes
Applications heavily dependent on native extensions
Simple applications without isolation requirements

Migration Strategy

If you’re considering Ruby::Box for an existing application:

Step 1: Test compatibility

# Run your test suite with Boxing enabled
RUBY_BOX=1 bundle exec rspec

Step 2: Identify issues

Look for failures related to:

Shared global state across files
Assumptions about class modifications being visible everywhere
Native extension loading errors

Step 3: Refactor incrementally

Start with isolated subsystems that don’t share state with the rest of your application. Move more code into boxes as you gain confidence.

Step 4: Monitor in staging

Run your staging environment with RUBY_BOX=1 before considering production deployment.

What’s Next for `Ruby::Box`

The Ruby core team has discussed building a higher-level “packages” API on top of Ruby::Box. This would provide more ergonomic ways to manage gem isolation without manual box management. Track progress in Ruby Issue #21681.

Ruby::Box solves real problems around namespace pollution and gem conflicts. While still experimental, it’s worth exploring for applications where isolation matters. Start with non-critical paths, understand the limitations, and provide feedback to the Ruby core team as you experiment.

References

Ruby 4.0 Introduces Ruby::Box for In-Process Isolation (Part 1)

Wed, 14 Jan 2026 00:00:00 +0000

Ruby 4.0 introduces Ruby::Box, a feature that provides isolated namespaces within a single Ruby process. This solves a long-standing problem: monkey patches and global modifications from one gem affecting all other code in your application.

The Problem with Shared Namespaces

When you load a gem that modifies core classes, those changes affect everything in your Ruby process:

# Gem A adds a titleize method to String
class String
  def titleize
    split.map(&:capitalize).join(' ')
  end
end

# Now EVERY piece of code in your process sees this method
# Including Gem B, which might have its own expectations

"hello world".titleize  # => "Hello World"

This becomes problematic when:

Two gems define conflicting methods on the same class
A gem’s monkey patch breaks another library’s assumptions
You want to test code in isolation from invasive patches
You need to run multiple versions of a gem simultaneously

Before Ruby 4.0, the only solutions were separate Ruby processes (with IPC overhead) or containers (with even more overhead).

Ruby 4.0: Enter Ruby::Box

Ruby::Box creates isolated spaces where code runs with its own class definitions, constants, and global variables. Changes made inside a box stay inside that box.

# Enable with environment variable at startup
# RUBY_BOX=1 ruby my_script.rb

# Check if Boxing is available
Ruby::Box.enabled?  # => true

# Create an isolated box
box = Ruby::Box.new

# Load code that patches String
box.eval <<~RUBY
  class String
    def shout
      upcase + "!!!"
    end
  end
RUBY

# The patch exists only inside the box
box.eval('"hello".shout')  # => "HELLO!!!"

# Outside the box, String is unchanged
"hello".shout  # => NoMethodError: undefined method `shout'

Understanding Box Types

Ruby::Box operates with three types of boxes:

Root Box: Contains all built-in Ruby classes and modules. This is established before any user code runs and serves as the template for other boxes.

Main Box: Your application’s default execution context. It’s automatically created from the root box when the process starts. This is where your main script runs.

User Boxes: Custom boxes you create with Ruby::Box.new. Each is copied from the root box, giving it a clean slate of built-in classes without any modifications from the main box or other user boxes.

# Your script runs in the "main" box
Ruby::Box.current  # => #<Ruby::Box main>

# Create isolated boxes
plugin_box = Ruby::Box.new
another_box = Ruby::Box.new

# Each box is independent
plugin_box.object_id != another_box.object_id  # => true

The Ruby::Box API

The API is straightforward with just a few methods:

# Creation
box = Ruby::Box.new

# Loading code
box.require('some_library')        # Respects box's $LOAD_PATH
box.require_relative('./my_file')  # Relative to current file
box.load('script.rb')              # Direct file execution

# Executing code
box.eval('1 + 1')                  # Execute Ruby code as string

# Inspection
Ruby::Box.current    # Returns the currently executing box
Ruby::Box.enabled?   # Check if Boxing is active

What Gets Isolated

Ruby::Box isolates several aspects of the Ruby runtime:

Classes and Constants: Reopening a built-in class in one box doesn’t affect other boxes.

box = Ruby::Box.new
box.eval <<~RUBY
  class Array
    def sum_squares
      map { |n| n ** 2 }.sum
    end
  end
RUBY

box.eval('[1, 2, 3].sum_squares')  # => 14
[1, 2, 3].sum_squares              # => NoMethodError

Global Variables: Changes to globals stay within the box.

box = Ruby::Box.new
box.eval('$my_config = { debug: true }')

box.eval('$my_config')  # => { debug: true }
$my_config              # => nil

Top-Level Methods: Methods defined at the top level become private instance methods of Object within that box only.

box = Ruby::Box.new
box.eval <<~RUBY
  def helper_method
    "I'm only available in this box"
  end
RUBY

box.eval('helper_method')  # => "I'm only available in this box"
helper_method              # => NoMethodError

Enabling Ruby::Box

Ruby::Box is disabled by default. Enable it by setting the RUBY_BOX environment variable before the Ruby process starts:

RUBY_BOX=1 ruby my_application.rb

Important: Setting RUBY_BOX after the process has started has no effect. The boxing infrastructure must be initialized during Ruby’s boot sequence, so the variable must be set before the Ruby process starts.

# This check should be at the top of your application
unless Ruby::Box.enabled?
  warn "Ruby::Box is not enabled. Start with RUBY_BOX=1"
  exit 1
end

Important Limitations

Before adopting Ruby::Box, be aware of these constraints:

Not a Security Sandbox: Ruby::Box provides namespace isolation, not security isolation. Code in a box can still access the filesystem, network, and system resources. Do not use it to run untrusted code.

Native Extensions: Installing gems with native extensions may fail when RUBY_BOX=1 is set. The workaround is to install gems without the flag, then run your application with it enabled.

# Install gems normally
bundle install

# Run with Boxing enabled
RUBY_BOX=1 bundle exec ruby app.rb

ActiveSupport Compatibility: Some parts of active_support/core_ext have compatibility issues with Ruby::Box. Load ActiveSupport in your main context before creating boxes if needed.

Experimental Status: This feature is experimental in Ruby 4.0. Behavior may change in future versions. The Ruby core team recommends experimentation but advises caution in production environments.

File Scope Execution

One important detail: Ruby::Box operates on a file-scope basis. Each .rb file executes entirely within a single box. Once loaded, all methods and procs defined in that file operate within their originating box, regardless of where they’re called from.

# helper.rb
def process(data)
  # This method always runs in the box where helper.rb was loaded
  data.transform
end

# main.rb
box = Ruby::Box.new
box.require_relative('helper')

# Even when called from main, process() runs in box's context
box.eval('process(my_data)')

Ruby::Box brings a long-requested capability to Ruby: proper namespace isolation without process boundaries. In Part 2, we’ll explore practical use cases including plugin systems, multi-tenant configurations, and strategies for gradual adoption.

References

Rails 8.2 makes enqueue_after_transaction_commit the default

Wed, 31 Dec 2025 00:00:00 +0000

Rails 7.2 introduced enqueue_after_transaction_commit to prevent race conditions when jobs are enqueued inside database transactions. However, it required explicit opt-in. Rails 8.2 flips the default. Jobs are now automatically deferred until after the transaction commits.

The Problem with Opt-In

With the opt-in approach in Rails 7.2, teams had to remember to enable the feature:

config.active_job.enqueue_after_transaction_commit = :default

Or configure it per-job:

class WelcomeEmailJob < ApplicationJob
  self.enqueue_after_transaction_commit = :always
end

This created inconsistency. Some jobs would be transaction-aware, others would not. The safer behavior required explicit action.

Rails 8.2 Changes the Default

PR #55788 changes this. When you upgrade to Rails 8.2 and run load_defaults "8.2", jobs are automatically deferred until after the transaction commits.

def create
  User.transaction do
    user = User.create!(params)
    WelcomeEmailJob.perform_later(user)  # Deferred until commit
  end
end

No configuration needed. The job waits for the transaction to complete before being dispatched to the queue.

Opting Out

If you need immediate enqueueing for backward compatibility or specific use cases, you have two options.

Global configuration:

config.active_job.enqueue_after_transaction_commit = false

Per-job configuration:

class TimeStampedJob < ApplicationJob
  self.enqueue_after_transaction_commit = false
end

Why the Global Config Was Restored

The global configuration option has an interesting history. It was deprecated and removed in Rails 8.1. The team initially wanted each job to declare its own preference. However, changing the default behavior without a global opt-out would break existing applications.

The PR restored the global configuration specifically to allow apps upgrading to Rails 8.2 to maintain their existing behavior without modifying every job class.

When This Matters

The new default primarily affects jobs enqueued to external queues like Redis (Sidekiq, Resque). If you use a database-backed queue like Solid Queue or GoodJob with the same database, your jobs are already part of the same transaction.

Jobs that do not depend on transaction data can still be configured for immediate enqueueing if needed.

Conclusion

Rails 8.2 makes the safer behavior the default. Jobs enqueued inside transactions automatically wait for the commit, eliminating a common source of race conditions without requiring explicit configuration.

References

Pull Request #55788 making this the default
Pull Request #51426 introducing the feature in Rails 7.2
Rails 7.2 enqueue_after_transaction_commit - detailed explanation of the feature

Rails 7.2 adds enqueue_after_transaction_commit to prevent job race conditions

Tue, 30 Dec 2025 00:00:00 +0000

Scheduling background jobs inside database transactions is a common anti-pattern which is a source of several production bugs in Rails applications. The job can execute before the transaction commits, leading to RecordNotFound or ActiveJob::DeserializationError because the data it needs does not exist yet. Or worse, the job could run assuming the txn would commit, but it rolls back at a later stage. We don’t need that kind of optimism.

Rails 7.2 addresses this with enqueue_after_transaction_commit, which automatically defers job enqueueing until the transaction completes.

Before

Consider a typical pattern where you create a user and send a welcome email:

class UsersController < ApplicationController
  def create
    User.transaction do
      @user = User.create!(user_params)
      WelcomeEmailJob.perform_later(@user)
    end
  end
end

This code works fine in development where your job queue is slow and transactions commit quickly. In production, with a fast Redis-backed queue like Sidekiq and a busy database, the job can start executing before the transaction commits:

Timeline:
1. Transaction begins
2. User INSERT executes (not committed yet)
3. Job enqueued to Redis
4. Sidekiq picks up job immediately
5. Job tries to find User -> RecordNotFound!
6. Transaction commits (too late)

The same problem occurs with after_create callbacks in models:

class Project < ApplicationRecord
  after_create -> { NotifyParticipantsJob.perform_later(self) }
end

The Workaround

The standard fix was to use after_commit callbacks instead:

class Project < ApplicationRecord
  after_create_commit -> { NotifyParticipantsJob.perform_later(self) }
end

Or wrap job scheduling in explicit after_commit blocks:

class UsersController < ApplicationController
  def create
    User.transaction do
      @user = User.create!(user_params)

      ActiveRecord::Base.connection.after_transaction_commit do
        WelcomeEmailJob.perform_later(@user)
      end
    end
  end
end

This worked but had problems:

Easy to forget: Using after_create instead of after_create_commit is a common mistake
Scattered logic: Job scheduling gets coupled to model callbacks instead of staying in controllers or service objects
Verbose: Wrapping every perform_later call in after_commit blocks adds boilerplate
Testing friction: Transaction callbacks behave differently in test environments using database cleaner with transactions

The after_commit_everywhere gem became popular specifically to address this problem. It lets you use after_commit callbacks anywhere in your application, not just in ActiveRecord models:

class UserRegistrationService
  include AfterCommitEverywhere

  def call(params)
    User.transaction do
      user = User.create!(params)

      after_commit do
        WelcomeEmailJob.perform_later(user)
      end
    end
  end
end

The gem hooks into ActiveRecord’s transaction lifecycle and ensures callbacks only fire after the outermost transaction commits. It handled nested transactions correctly and became a go-to solution for service objects that needed transaction-safe job scheduling.

Some teams built their own lightweight wrappers instead:

# Custom AsyncRecord class that hooks into transaction callbacks
class AsyncRecord
  def initialize(&block)
    @callback = block
  end

  def has_transactional_callbacks?
    true
  end

  def committed!(*)
    @callback.call
  end

  def rolledback!(*)
    # Do nothing if transaction rolled back
  end
end

# Usage
User.transaction do
  user = User.create!(params)
  record = AsyncRecord.new { WelcomeEmailJob.perform_later(user) }
  user.class.connection.add_transaction_record(record)
end

Both approaches worked, but required teams to remember to use them consistently.

Rails 7.2

Rails 7.2 makes Active Job transaction-aware. Jobs are automatically deferred until the transaction commits, and dropped if it rolls back.

Enable it globally in your application:

# config/application.rb
config.active_job.enqueue_after_transaction_commit = :default

Now the original code just works:

class UsersController < ApplicationController
  def create
    User.transaction do
      @user = User.create!(user_params)
      WelcomeEmailJob.perform_later(@user)  # Deferred until commit
    end
  end
end

The job only gets enqueued after the transaction successfully commits. If the transaction rolls back, the job is never enqueued.

Configuration Options

You can control this behavior at three levels:

Global configuration:

# config/application.rb
config.active_job.enqueue_after_transaction_commit = :default

Per-job configuration:

class WelcomeEmailJob < ApplicationJob
  self.enqueue_after_transaction_commit = :always
end

class AuditLogJob < ApplicationJob
  self.enqueue_after_transaction_commit = :never  # Queue immediately
end

The available values are:

:default - Let the queue adapter decide the behavior
:always - Always defer until transaction commits
:never - Queue immediately (pre-7.2 behavior)

Checking Enqueue Status

Since perform_later returns immediately even when the job is deferred, you can check if it was actually enqueued:

User.transaction do
  user = User.create!(user_params)
  job = WelcomeEmailJob.perform_later(user)

  # job.successfully_enqueued? returns false here (still deferred)
end

# After transaction commits, job.successfully_enqueued? returns true

Model Callbacks Simplified

You can now safely use after_create for job scheduling without worrying about transaction timing:

class Project < ApplicationRecord
  # This is now safe with enqueue_after_transaction_commit enabled
  after_create -> { NotifyParticipantsJob.perform_later(self) }
end

The job automatically waits for any enclosing transaction to complete.

When to Disable

Some scenarios require immediate enqueueing:

Database-backed queues: If you use Solid Queue, GoodJob, or Delayed Job with the same database, jobs are part of the same transaction and this deferral is unnecessary
Fire-and-forget jobs: Jobs that do not depend on the transaction data can run immediately
Time-sensitive operations: If you need the job queued at a specific moment regardless of transaction state

class TimeStampedJob < ApplicationJob
  self.enqueue_after_transaction_commit = :never

  def perform
    # This job needs to capture the exact enqueue time
  end
end

Update: Rails 8.2 Makes This the Default

Rails 8.2 makes enqueue_after_transaction_commit the default behavior. Jobs are now automatically deferred until after the transaction commits without requiring explicit configuration.

See Rails 8.2 makes enqueue_after_transaction_commit the default for details on the change, opting out, and the deprecation history.

Conclusion

enqueue_after_transaction_commit eliminates a common source of race conditions in Rails applications. Instead of remembering to use after_commit callbacks or building custom workarounds, jobs are automatically deferred until transactions complete.

References

Pull Request #51426 introducing the feature
Pull Request #55788 making this the default in Rails 8.2
Original Issue #26045 by DHH describing the problem
Active Job Basics Guide

Rails 8.2 introduces Rails.app.creds for unified credential management

Mon, 29 Dec 2025 00:00:00 +0000

Applications often store secrets in both environment variables and encrypted credential files. Migrating between these storage methods or using both simultaneously has traditionally required code changes. Rails 8.2 solves this with Rails.app.creds, a unified API that checks ENV first, then falls back to encrypted credentials.

Before

Managing credentials from multiple sources meant mixing different APIs:

class StripeService
  def initialize
    # Check ENV first, fallback to credentials
    @api_key = ENV["STRIPE_API_KEY"] || Rails.application.credentials.dig(:stripe, :api_key)
    @webhook_secret = ENV.fetch("STRIPE_WEBHOOK_SECRET") {
      Rails.application.credentials.stripe&.webhook_secret
    }

    raise "Missing Stripe API key!" unless @api_key
  end
end

class DatabaseConfig
  def connection_url
    # Different syntax for each source
    ENV["DATABASE_URL"] || Rails.application.credentials.database_url
  end

  def redis_url
    ENV.fetch("REDIS_URL", Rails.application.credentials.dig(:redis, :url) || "redis://localhost:6379")
  end
end

This approach has several problems:

Inconsistent APIs between ENV.fetch() and credentials.dig()
Manual fallback logic scattered throughout the codebase
Code changes required when moving secrets between storage methods
Easy to forget nil checks on nested credentials

Rails 8.2

The new Rails.app.creds provides a consistent interface:

class StripeService
  def initialize
    @api_key = Rails.app.creds.require(:stripe_api_key)
    @webhook_secret = Rails.app.creds.require(:stripe_webhook_secret)
  end
end

class DatabaseConfig
  def connection_url
    Rails.app.creds.require(:database_url)
  end

  def redis_url
    Rails.app.creds.option(:redis_url, default: "redis://localhost:6379")
  end
end

The require method mandates a value exists and raises KeyError if missing from both ENV and encrypted credentials. The option method returns nil or a default value gracefully.

Nested Keys

For nested credentials, pass multiple keys. Rails automatically converts them to the appropriate format for each source:

# Checks ENV["AWS__ACCESS_KEY_ID"] first, then credentials.dig(:aws, :access_key_id)
Rails.app.creds.require(:aws, :access_key_id)

# Multi-level nesting
# ENV["REDIS__CACHE__TTL"] || credentials.dig(:redis, :cache, :ttl)
Rails.app.creds.option(:redis, :cache, :ttl, default: 3600)

The ENV lookup uses double underscores (__) as separators for nested keys:

:database_url → ENV["DATABASE_URL"]
[:aws, :region] → ENV["AWS__REGION"]
[:redis, :cache, :ttl] → ENV["REDIS__CACHE__TTL"]

Dynamic Defaults

The option method accepts callable defaults, evaluated only when needed:

Rails.app.creds.option(:cache_ttl, default: -> { 1.hour })
Rails.app.creds.option(:max_connections, default: -> { calculate_pool_size })

ENV-Only Access

Access environment variables directly using the same API via Rails.app.envs:

# Only checks ENV, no encrypted credentials fallback
Rails.app.envs.require(:port)
Rails.app.envs.option(:log_level, default: "info")

Custom Credential Sources

Under the hood, Rails.app.creds is powered by ActiveSupport::CombinedConfiguration, which checks multiple credential sources (called backends) in order. By default, it checks ENV first, then encrypted credentials. You can customize this chain to include external secret managers:

# config/initializers/credentials.rb
Rails.app.creds = ActiveSupport::CombinedConfiguration.new(
  Rails.app.envs,                   # Check ENV first
  VaultConfiguration.new,           # Then HashiCorp Vault
  OnePasswordConfiguration.new,     # Then 1Password
  Rails.app.credentials             # Finally, encrypted credentials
)

Each credential source needs to implement require and option methods matching the API.

Rails.app Alias

This feature comes alongside a new Rails.app alias for Rails.application:

# Before
Rails.application.credentials.aws.access_key_id

# After
Rails.app.credentials.aws.access_key_id

The shorter alias makes chained method calls more pleasant to read and write.

Conclusion

Rails.app.creds eliminates the friction of managing credentials across multiple sources. Secrets can move between ENV and encrypted files without touching application code.

References

PR #56404 - Add Rails.app.creds for combined credentials lookup
PR #56403 - Add Rails.app alias for Rails.application

Prateek Codes - Building Scalable Backend Systems

Multi-hop delegation for AI agents: porting OAuth's on-behalf-of pattern into MCP topologies

Introducing: delegated authorization with actor chains

Why bearer tokens fail in agent topologies

What the actor chain looks like

What this fixes, and what it does not

The state of the standards work

Conclusion

References

Stop Pasting Schema Into Your AI: Connect PostgreSQL Directly with MCP

The Problem

With a Postgres MCP Server

Setting Up @modelcontextprotocol/server-postgres

Step 1: Create a Read-Only Database User

Step 2: Configure Claude Desktop or Claude Code

Step 3: Verify the Connection

Other MCP Database Options

Security

Use a Read-Only Connection

Zero Data Retention for Sensitive Databases

What Changes Day to Day

Conclusion

References

Rails 8.2 adds this_week?, this_month?, and this_year? to Date and Time

Before

Rails 8.2

In controllers

In views

In scopes

How to change the week boundary

Conclusion

References

Read-only database MCPs as a scoped-delegation pattern: applying IAM primitives to AI agents

Introducing: scoped delegation pattern

Why RBAC is the right starting model

What “read-only” actually has to mean

Audit is where this pattern earns its keep

What this pattern does not solve

Conclusion

References

Rails 8.2 lets retry_on read the error when calculating wait time

Before

Rails 8.2

Backward Compatibility

When to Use This

Conclusion

References

Ruby::Box Practical Guide: Use Cases and Integration Patterns (Part 2)

Use Case: Plugin Systems

Use Case: Multi-Tenant Configuration

Use Case: Running Multiple Gem Versions

Use Case: Isolated Monkey Patches for Testing

Use Case: Shadow Testing

Working Around Native Extension Issues

Working Around ActiveSupport Issues

Performance Considerations

When to Use Ruby::Box

Migration Strategy

What’s Next for Ruby::Box

References

Ruby 4.0 Introduces Ruby::Box for In-Process Isolation (Part 1)

The Problem with Shared Namespaces

Ruby 4.0: Enter Ruby::Box

Understanding Box Types

The Ruby::Box API

What Gets Isolated

Enabling Ruby::Box

Important Limitations

File Scope Execution

References

Rails 8.2 makes enqueue_after_transaction_commit the default

The Problem with Opt-In

Rails 8.2 Changes the Default

Opting Out

Why the Global Config Was Restored

When This Matters

Conclusion

References

Rails 7.2 adds enqueue_after_transaction_commit to prevent job race conditions

Before

When to Use `Ruby::Box`

What’s Next for `Ruby::Box`