<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>Snails Blog</title>
    <link>https://snails-rb.org/blog/</link>
    <description>Dated notes on the design, benchmarks, and releases behind Snails.</description>
    <language>en</language>
    <lastBuildDate>Fri, 20 Nov 2026 00:00:00 GMT</lastBuildDate>
    <atom:link href="https://snails-rb.org/blog/rss.xml" rel="self" type="application/rss+xml"/>
<item>
  <title>Why I didn&apos;t rewrite my Rails app in Rust</title>
  <link>https://snails-rb.org/blog/why-i-didnt-rewrite-my-rails-app-in-rust/</link>
  <guid isPermaLink="true">https://snails-rb.org/blog/why-i-didnt-rewrite-my-rails-app-in-rust/</guid>
  <pubDate>Fri, 20 Nov 2026 00:00:00 GMT</pubDate>
  <dc:creator>Rinn</dc:creator>
  <description><![CDATA[A deploy brought my 1 GB Rails API service down. Rust was the obvious answer, but it made the code heavier to read. I kept the Rails conventions, dropped the layers, and let coding agents write what used to be a gem. The result is native performance with the same conventions.]]></description>
  <content:encoded><![CDATA[<p><em>Disclosure: I&#39;m the author of Snails, the framework this post is about. The numbers are from my own deploys, not a lab.</em></p>
<p>In October, a deploy brought my Rails API service down. The app was a stock Rails API app on a 1 GB node with 951 MB usable, running a single Puma process, not cluster mode. Rails starts with a high memory footprint: the app process alone was about 175 MB, and with Postgres running, the node sat at 504 MB of 951 MB. Kamal starts the new container before it stops the old one, so during a deploy the node runs two Rails processes. The new process peaked higher during boot than its steady 175 MB. With the old process still serving, the node ran out of headroom and started swapping.</p>
<p>The service is a telemetry backend. Five services send metrics and logs over OTLP/HTTP. The app has three routes: <code>/up</code>, <code>/v1/metrics</code>, and <code>/v1/logs</code>, all in <code>config/routes.rb</code>. Metrics roll up into five-minute windows; logs are kept for seven days. The stack was standard: Rails 8.1 API-only, Postgres, Puma, and Kamal. The memory baseline came from the full Rails stack, not the app code.</p>
<p>The deploy takes 70–80 seconds, with both processes resident. Under memory pressure it stretched to 200–300 seconds, and swap made it slower still. Kamal&#39;s deploy timeout had to be raised to 180 seconds just to let the new container come up; in the worst case, it took longer and the new container was killed. One deploy froze the node, and I had to force a reboot.</p>
<p>I assumed the Postgres container was using most of the memory. I moved the database to SQLite to remove it; the deploy peak didn&#39;t move. The database wasn&#39;t the problem.</p>
<p>I also turned on zram. It took some of the pressure off swap and made deploys less likely to freeze the node, but the real problem was still there: two Rails processes sharing a 1 GB node.</p>
<p>The allocator wasn&#39;t the problem either. Rails 8.1&#39;s default Dockerfile already preloads jemalloc.</p>
<p>The full Rails stack was the problem. One process was already about 175 MB at steady state, and the new process peaked higher during boot. A deploy had to fit both. On a 1 GB node, I couldn&#39;t find anything left to tune.</p>
<p>Rust was the obvious answer. I had already ported another service to Rust, and it worked. I didn&#39;t port this one. This post is about why, and what I built instead.</p>
<h2 id="rust-already-shipped">Rust, already shipped<a class="anchor" href="https://snails-rb.org/blog/why-i-didnt-rewrite-my-rails-app-in-rust/#rust-already-shipped" aria-label="Link to this section">#</a></h2>
<p>The port was for another Rails service, a smaller mobile API. It covered the API handlers and a job worker. The job worker is where I measured the memory: about 360 MB for the Rails job container, about 2 MB for the Rust service that replaced it, on the same 1 GB node. It&#39;s one data point, not a benchmark. But the gap was real.</p>
<p>The port did what I wanted. If memory were the only goal, I would have stopped there.</p>
<p>What stopped me wasn&#39;t the memory. It was the code. I&#39;m the one who has to read it.</p>
<p>Rust&#39;s explicitness is what makes it good for an agent: static types, explicit contracts, no magic. The same property makes the code heavy for a human to read. The syntax gets familiar; the amount of code doesn&#39;t. Here is the same endpoint in both services.</p>
<p>Rails, <code>Api::DevicesController#show</code>:</p>
<pre class="code language-ruby" tabindex="0"><code><span class="line"><span style="color:var(--syntax-pink)">class</span><span style="color:var(--syntax-cyan)"> Api</span><span style="color:var(--syntax-pink)">::</span><span style="color:var(--syntax-cyan)">DevicesController</span><span style="color:var(--syntax-pink)"> &#x3C;</span><span style="color:var(--syntax-cyan);font-style:italic"> Api</span><span style="color:var(--syntax-pink);font-style:italic">::</span><span style="color:var(--syntax-cyan);font-style:italic">ApplicationController</span></span>
<span class="line"><span style="color:var(--syntax-pink)">  def</span><span style="color:var(--syntax-green)"> show</span></span>
<span class="line"><span style="color:var(--syntax-purple);font-style:italic">    @device</span><span style="color:var(--syntax-pink)"> =</span><span style="color:var(--syntax-cyan);font-style:italic"> Device</span><span style="color:var(--fg)">.</span><span style="color:var(--syntax-green)">find_by!</span><span style="color:var(--fg)">(</span><span style="color:var(--syntax-purple)">uuid:</span><span style="color:var(--fg)"> params[</span><span style="color:var(--syntax-purple)">:id</span><span style="color:var(--fg)">])</span></span>
<span class="line"><span style="color:var(--syntax-pink)">  end</span></span>
<span class="line"><span style="color:var(--syntax-pink)">end</span></span></code></pre><p>Rust, <code>api-gateway</code> <code>devices::show</code>:</p>
<pre class="code language-rust" tabindex="0"><code><span class="line"><span style="color:var(--syntax-pink)">pub</span><span style="color:var(--syntax-pink)"> async</span><span style="color:var(--syntax-pink)"> fn</span><span style="color:var(--syntax-green)"> show</span><span style="color:var(--fg)">(</span></span>
<span class="line"><span style="color:var(--syntax-green)">    State</span><span style="color:var(--fg)">(state)</span><span style="color:var(--syntax-pink)">:</span><span style="color:var(--syntax-cyan);font-style:italic"> State</span><span style="color:var(--fg)">&#x3C;</span><span style="color:var(--syntax-cyan);font-style:italic">AppState</span><span style="color:var(--fg)">>,</span></span>
<span class="line"><span style="color:var(--fg)">    headers</span><span style="color:var(--syntax-pink)">:</span><span style="color:var(--syntax-cyan);font-style:italic"> HeaderMap</span><span style="color:var(--fg)">,</span></span>
<span class="line"><span style="color:var(--syntax-green)">    Path</span><span style="color:var(--fg)">(uuid)</span><span style="color:var(--syntax-pink)">:</span><span style="color:var(--syntax-cyan);font-style:italic"> Path</span><span style="color:var(--fg)">&#x3C;</span><span style="color:var(--syntax-cyan);font-style:italic">String</span><span style="color:var(--fg)">>,</span></span>
<span class="line"><span style="color:var(--fg)">) </span><span style="color:var(--syntax-pink)">-></span><span style="color:var(--syntax-cyan);font-style:italic"> Result</span><span style="color:var(--fg)">&#x3C;</span><span style="color:var(--syntax-cyan);font-style:italic">Json</span><span style="color:var(--fg)">&#x3C;</span><span style="color:var(--syntax-cyan);font-style:italic">Value</span><span style="color:var(--fg)">>, </span><span style="color:var(--syntax-cyan);font-style:italic">ApiError</span><span style="color:var(--fg)">> {</span></span>
<span class="line"><span style="color:var(--syntax-pink)">    let</span><span style="color:var(--fg)"> _auth </span><span style="color:var(--syntax-pink)">=</span><span style="color:var(--fg)"> auth</span><span style="color:var(--syntax-pink)">::</span><span style="color:var(--syntax-green)">authenticate</span><span style="color:var(--fg)">(</span><span style="color:var(--syntax-pink)">&#x26;</span><span style="color:var(--fg)">headers, </span><span style="color:var(--syntax-pink)">&#x26;</span><span style="color:var(--fg)">state)</span><span style="color:var(--syntax-pink)">.await?</span><span style="color:var(--fg)">;</span></span>
<span class="line"><span style="color:var(--syntax-pink)">    let</span><span style="color:var(--fg)"> pool </span><span style="color:var(--syntax-pink)">=</span><span style="color:var(--fg)"> state</span></span>
<span class="line"><span style="color:var(--syntax-pink)">        .</span><span style="color:var(--fg)">pool</span></span>
<span class="line"><span style="color:var(--syntax-pink)">        .</span><span style="color:var(--syntax-green)">as_ref</span><span style="color:var(--fg)">()</span></span>
<span class="line"><span style="color:var(--syntax-pink)">        .</span><span style="color:var(--syntax-green)">ok_or_else</span><span style="color:var(--fg)">(</span><span style="color:var(--syntax-pink)">||</span><span style="color:var(--fg)"> ApiError</span><span style="color:var(--syntax-pink)">::</span><span style="color:var(--syntax-green)">Internal</span><span style="color:var(--fg)">(</span><span style="color:var(--syntax-yellow)">"database not configured"</span><span style="color:var(--syntax-pink)">.</span><span style="color:var(--syntax-green)">to_string</span><span style="color:var(--fg)">()))</span><span style="color:var(--syntax-pink)">?</span><span style="color:var(--fg)">;</span></span>
<span class="line"></span>
<span class="line"><span style="color:var(--syntax-pink)">    match</span><span style="color:var(--fg)"> core_db</span><span style="color:var(--syntax-pink)">::</span><span style="color:var(--syntax-green)">find_device_by_uuid</span><span style="color:var(--fg)">(pool, </span><span style="color:var(--syntax-pink)">&#x26;</span><span style="color:var(--fg)">uuid)</span><span style="color:var(--syntax-pink)">.await?</span><span style="color:var(--fg)"> {</span></span>
<span class="line"><span style="color:var(--syntax-cyan);font-style:italic">        Some</span><span style="color:var(--fg)">(device) </span><span style="color:var(--syntax-pink)">=></span><span style="color:var(--syntax-cyan);font-style:italic"> Ok</span><span style="color:var(--fg)">(</span><span style="color:var(--syntax-green)">Json</span><span style="color:var(--fg)">(</span><span style="color:var(--syntax-green)">device_json</span><span style="color:var(--fg)">(</span><span style="color:var(--syntax-pink)">&#x26;</span><span style="color:var(--fg)">device))),</span></span>
<span class="line"><span style="color:var(--syntax-cyan);font-style:italic">        None</span><span style="color:var(--syntax-pink)"> =></span><span style="color:var(--syntax-cyan);font-style:italic"> Err</span><span style="color:var(--fg)">(</span><span style="color:var(--syntax-cyan);font-style:italic">ApiError</span><span style="color:var(--syntax-pink)">::</span><span style="color:var(--syntax-green)">NotFound</span><span style="color:var(--fg)">(locale</span><span style="color:var(--syntax-pink)">::</span><span style="color:var(--syntax-green)">from_headers</span><span style="color:var(--fg)">(</span><span style="color:var(--syntax-pink)">&#x26;</span><span style="color:var(--fg)">headers))),</span></span>
<span class="line"><span style="color:var(--fg)">    }</span></span>
<span class="line"><span style="color:var(--fg)">}</span></span></code></pre><p>The action is three lines because the rest lives elsewhere: auth is a <code>before_action</code> on the base controller, <code>find_by!</code> raises <code>RecordNotFound</code> and the base controller turns it into a 404, and the JSON is a jbuilder view. The Rust handler carries all of it: the auth call, the pool, the error mapping, the lookup, the 404, and the JSON helper. An agent wrote this handler. It&#39;s correct, typed, and explicit. It&#39;s also more code to read than the Rails action it replaces. The agent can produce it faster than I can read it.</p>
<p>I could read it. I didn&#39;t want to pay that cost every time I opened the file, and I found myself paying it less and less.</p>
<p>That left more of the decisions to the agent: error handling, security boundaries, cost trade-offs. I use coding agents, but I run this service. At 3 a.m., I need to know what the code decided. Reading is how I debug, judge the agent&#39;s fix, and catch a regression.</p>
<p>That&#39;s the cost I feel every day. Reading a small codebase is manageable. The problem is how fast it grows: an agent writes more code than I can review, and Rust gives it more code per behavior. The gap grows with every feature. Then I stopped reading. The service still ran, but I couldn&#39;t explain what it would do next. It had become a black box. That was the bigger problem.</p>
<p>Rust worked, but I didn&#39;t want to own it. I wanted the memory drop and code I could keep reading.</p>
<h2 id="why-not-a-bigger-node">Why not a bigger node?<a class="anchor" href="https://snails-rb.org/blog/why-i-didnt-rewrite-my-rails-app-in-rust/#why-not-a-bigger-node" aria-label="Link to this section">#</a></h2>
<p>The other obvious answer was a bigger node. Amazon Free Tier and Oracle Always Free both offer a 1 GB option, and that was the box I wanted the service to run on. A 2 GB node would have fixed the deploy: the two Rails processes would have had room to overlap, and I could have run Puma in cluster mode.</p>
<p>Cost wasn&#39;t the point. Performance was. The bigger node would have solved the deploy by adding memory, not by making Rails need less of it. The Rust service already ran on 1 GB. The question was whether the Rails conventions could survive on the same hardware.</p>
<p>A framework that needs more than the smallest free-tier node isn&#39;t usable for this class of service. That was the constraint I wasn&#39;t willing to give up. I wanted to keep the conventions inside it. That meant removing the stack that made them expensive to run.</p>
<h2 id="roundhouse-kept-the-rails-stack">Roundhouse kept the Rails stack<a class="anchor" href="https://snails-rb.org/blog/why-i-didnt-rewrite-my-rails-app-in-rust/#roundhouse-kept-the-rails-stack" aria-label="Link to this section">#</a></h2>
<p>I tried <a href="https://rubys.github.io/roundhouse/">Roundhouse</a> first. It&#39;s Sam Ruby&#39;s transpiler: it reads a Rails app as-is and emits a standalone project. One target is <a href="https://github.com/matz/spinel">Spinel</a>, Matz&#39;s ahead-of-time Ruby compiler.</p>
<p>Roundhouse treats the Rails app as the source. It analyzes the app, builds a typed intermediate representation, and emits a standalone project for a target. The Ruby/Spinel target compiles the app and the Rails framework into one binary. The framework is compiled, not removed, so the Rails stack comes with it. The output is regenerated, not edited: the Rails app stays the source, and patching the output is a bug report, not a workflow.</p>
<p>That path only covers the Rails constructs Roundhouse can model. An app outside that subset won&#39;t convert, and an app inside it is still a Rails app with a generated native build.</p>
<p>The binary worked: 2.8 MB on disk, about 19 MB RSS while serving requests. The memory goal was met. But the memory was the only goal it met.</p>
<p>The Rails stack was still there. Roundhouse removed the CRuby process, not the layers: Active Record, the gems, and the Ruby runtime those layers need were still in the binary.</p>
<p>The subset was still the limit.</p>
<p>The source was still Rails. I wanted the app source to be the code I read and change: the controllers, forms, jobs, and tests below. With Roundhouse, the binary is a build artifact of the Rails app.</p>
<p>I wanted a framework for other API apps that kept the Rails conventions and removed the layers Rails added to make writing easier — Active Record, the HTML view layer, and the gems — along with the Ruby runtime those layers need.</p>
<p>I could have contributed to Roundhouse instead. But I wanted a framework, not a transpiler. So I created Snails.</p>
<p>The memory was about the same as Roundhouse&#39;s. The difference was that the code I was reading was the code I was running.</p>
<h2 id="snails">Snails<a class="anchor" href="https://snails-rb.org/blog/why-i-didnt-rewrite-my-rails-app-in-rust/#snails" aria-label="Link to this section">#</a></h2>
<p>Snails is a Rails-like framework for API-only Ruby apps. It keeps the Rails conventions and compiles the app, the framework, and the HTTP server into one native binary with Spinel. The app is still Ruby source. There is no generated source: the files you write are the files the compiler reads. There is no Ruby VM or Rails stack at runtime. It has no gem dependencies. The <a href="https://snails-rb.org/blog/the-snails-design/">Snails Design</a> makes the argument; this post is the test.</p>
<h2 id="what-survived">What survived<a class="anchor" href="https://snails-rb.org/blog/why-i-didnt-rewrite-my-rails-app-in-rust/#what-survived" aria-label="Link to this section">#</a></h2>
<p>The request path looks familiar. The model layer doesn&#39;t.</p>
<h3 id="routes">Routes<a class="anchor" href="https://snails-rb.org/blog/why-i-didnt-rewrite-my-rails-app-in-rust/#routes" aria-label="Link to this section">#</a></h3>
<pre class="code language-ruby" tabindex="0"><code><span class="line"><span style="color:var(--syntax-comment)"># config/routes.rb</span></span>
<span class="line"><span style="color:var(--syntax-pink)">module</span><span style="color:var(--syntax-cyan);font-style:italic"> Snails</span></span>
<span class="line"><span style="color:var(--syntax-pink)">  module</span><span style="color:var(--syntax-cyan);font-style:italic"> RouteTable</span></span>
<span class="line"><span style="color:var(--syntax-pink)">    def</span><span style="color:var(--syntax-green)"> self.table</span></span>
<span class="line"><span style="color:var(--fg)">      [</span></span>
<span class="line"><span style="color:var(--syntax-green)">        get</span><span style="color:var(--fg)">(</span><span style="color:var(--syntax-yellow)">"</span><span style="color:var(--syntax-yellow)">/up</span><span style="color:var(--syntax-yellow)">"</span><span style="color:var(--fg)">, </span><span style="color:var(--syntax-cyan);font-style:italic">Snails</span><span style="color:var(--syntax-pink)">::</span><span style="color:var(--syntax-purple)">HealthController</span><span style="color:var(--fg)">, :</span><span style="color:var(--syntax-purple)">show</span><span style="color:var(--fg)">),</span></span>
<span class="line"><span style="color:var(--syntax-pink)">        *</span><span style="color:var(--syntax-green)">resources</span><span style="color:var(--fg)">(</span><span style="color:var(--syntax-yellow)">"</span><span style="color:var(--syntax-yellow)">/v1/metrics</span><span style="color:var(--syntax-yellow)">"</span><span style="color:var(--fg)">, </span><span style="color:var(--syntax-purple)">MetricsController</span><span style="color:var(--fg)">, :</span><span style="color:var(--syntax-purple)">json</span><span style="color:var(--fg)">, [ :</span><span style="color:var(--syntax-purple)">create</span><span style="color:var(--fg)"> ]),</span></span>
<span class="line"><span style="color:var(--syntax-pink)">        *</span><span style="color:var(--syntax-green)">resources</span><span style="color:var(--fg)">(</span><span style="color:var(--syntax-yellow)">"</span><span style="color:var(--syntax-yellow)">/v1/logs</span><span style="color:var(--syntax-yellow)">"</span><span style="color:var(--fg)">, </span><span style="color:var(--syntax-purple)">LogsController</span><span style="color:var(--fg)">, :</span><span style="color:var(--syntax-purple)">json</span><span style="color:var(--fg)">, [ :</span><span style="color:var(--syntax-purple)">create</span><span style="color:var(--fg)"> ])</span></span>
<span class="line"><span style="color:var(--fg)">      ]</span></span>
<span class="line"><span style="color:var(--syntax-pink)">    end</span></span>
<span class="line"><span style="color:var(--syntax-pink)">  end</span></span>
<span class="line"><span style="color:var(--syntax-pink)">end</span></span></code></pre><p>The route table uses the same <code>get</code>/<code>resources</code> helpers as Rails, but the rows are a plain array of controller classes and actions, not <code>Rails.application.routes.draw</code>. The table is a plain list because the compiler needs a static table to generate the route helpers; there is no <code>draw</code> block to run at boot.</p>
<h3 id="controllers">Controllers<a class="anchor" href="https://snails-rb.org/blog/why-i-didnt-rewrite-my-rails-app-in-rust/#controllers" aria-label="Link to this section">#</a></h3>
<pre class="code language-ruby" tabindex="0"><code><span class="line"><span style="color:var(--syntax-pink)">class</span><span style="color:var(--syntax-cyan)"> MetricsController</span><span style="color:var(--syntax-pink)"> &#x3C;</span><span style="color:var(--syntax-cyan);font-style:italic"> ApplicationController</span></span>
<span class="line"><span style="color:var(--syntax-pink)">  include</span><span style="color:var(--syntax-purple)"> IngestRejection</span></span>
<span class="line"><span style="color:var(--syntax-pink)">  include</span><span style="color:var(--syntax-purple)"> BearerAuth</span></span>
<span class="line"><span style="color:var(--syntax-pink)">  include</span><span style="color:var(--syntax-purple)"> OtlpRequestBody</span></span>
<span class="line"></span>
<span class="line"><span style="color:var(--fg)">  before_action </span><span style="color:var(--syntax-purple)">:authenticate_bearer!</span></span>
<span class="line"><span style="color:var(--fg)">  before_action </span><span style="color:var(--syntax-purple)">:parse_body</span></span>
<span class="line"></span>
<span class="line"><span style="color:var(--syntax-pink)">  def</span><span style="color:var(--syntax-green)"> create</span></span>
<span class="line"><span style="color:var(--fg)">    rows </span><span style="color:var(--syntax-pink)">=</span><span style="color:var(--syntax-cyan);font-style:italic"> OtlpDecoder</span><span style="color:var(--fg)">.</span><span style="color:var(--syntax-pink)">new</span><span style="color:var(--fg)">(parsed_body).</span><span style="color:var(--syntax-green)">rows</span></span>
<span class="line"><span style="color:var(--syntax-cyan);font-style:italic">    MetricSample</span><span style="color:var(--fg)">.</span><span style="color:var(--syntax-green)">upsert_rows!</span><span style="color:var(--fg)">(rows)</span></span>
<span class="line"><span style="color:var(--syntax-green)">    head</span><span style="color:var(--fg)">(:</span><span style="color:var(--syntax-purple)">ok</span><span style="color:var(--fg)">)</span></span>
<span class="line"><span style="color:var(--syntax-pink)">  rescue</span><span style="color:var(--syntax-cyan);font-style:italic"> Sqlx</span><span style="color:var(--syntax-pink)">::</span><span style="color:var(--syntax-purple)">RecordInvalid</span><span style="color:var(--syntax-pink)"> =></span><span style="color:var(--fg)"> e</span></span>
<span class="line"><span style="color:var(--syntax-green)">    reject_ingest</span><span style="color:var(--fg)">(</span><span style="color:var(--syntax-yellow)">"</span><span style="color:var(--syntax-yellow)">invalid_rows</span><span style="color:var(--syntax-yellow)">"</span><span style="color:var(--fg)">, :</span><span style="color:var(--syntax-purple)">unprocessable_content</span><span style="color:var(--fg)">, rows.</span><span style="color:var(--syntax-green)">size</span><span style="color:var(--fg)">, e.</span><span style="color:var(--syntax-green)">record</span><span style="color:var(--fg)">.</span><span style="color:var(--syntax-green)">errors</span><span style="color:var(--fg)">.</span><span style="color:var(--syntax-green)">join</span><span style="color:var(--fg)">(</span><span style="color:var(--syntax-yellow)">"</span><span style="color:var(--syntax-yellow)">, </span><span style="color:var(--syntax-yellow)">"</span><span style="color:var(--fg)">))</span></span>
<span class="line"><span style="color:var(--syntax-pink)">  end</span></span>
<span class="line"><span style="color:var(--syntax-pink)">end</span></span></code></pre><p><code>ApplicationController</code>, <code>before_action</code>, and <code>def create</code> are standard Rails. The concerns and the <code>Sqlx::RecordInvalid</code> rescue are Snails-specific.</p>
<h3 id="forms">Forms<a class="anchor" href="https://snails-rb.org/blog/why-i-didnt-rewrite-my-rails-app-in-rust/#forms" aria-label="Link to this section">#</a></h3>
<pre class="code language-ruby" tabindex="0"><code><span class="line"><span style="color:var(--syntax-pink)">class</span><span style="color:var(--syntax-cyan)"> MetricSampleForm</span><span style="color:var(--syntax-pink)"> &#x3C;</span><span style="color:var(--syntax-cyan);font-style:italic"> Snails</span><span style="color:var(--syntax-pink);font-style:italic">::</span><span style="color:var(--syntax-cyan);font-style:italic">Form</span></span>
<span class="line"><span style="color:var(--syntax-purple)">  KINDS</span><span style="color:var(--syntax-pink)"> =</span><span style="color:var(--syntax-yellow)"> %w[counter delta gauge]</span><span style="color:var(--fg)">.</span><span style="color:var(--syntax-green)">freeze</span></span>
<span class="line"></span>
<span class="line"><span style="color:var(--fg)">  validates </span><span style="color:var(--syntax-purple)">:account_id</span><span style="color:var(--fg)">, </span><span style="color:var(--syntax-purple)">presence:</span><span style="color:var(--syntax-purple)"> true</span></span>
<span class="line"><span style="color:var(--fg)">  validate </span><span style="color:var(--syntax-purple)">:account_id_is_a_count</span></span>
<span class="line"><span style="color:var(--fg)">  validates </span><span style="color:var(--syntax-purple)">:ts</span><span style="color:var(--fg)">, </span><span style="color:var(--syntax-purple)">presence:</span><span style="color:var(--syntax-purple)"> true</span></span>
<span class="line"><span style="color:var(--fg)">  validate </span><span style="color:var(--syntax-purple)">:ts_is_a_time</span></span>
<span class="line"><span style="color:var(--fg)">  validates </span><span style="color:var(--syntax-purple)">:kind</span><span style="color:var(--fg)">, </span><span style="color:var(--syntax-purple)">inclusion:</span><span style="color:var(--fg)"> { </span><span style="color:var(--syntax-purple)">in:</span><span style="color:var(--syntax-purple)"> KINDS</span><span style="color:var(--fg)"> }, </span><span style="color:var(--syntax-purple)">allow_blank:</span><span style="color:var(--syntax-purple)"> true</span></span>
<span class="line"><span style="color:var(--fg)">  validate </span><span style="color:var(--syntax-purple)">:labels_are_flat</span></span>
<span class="line"><span style="color:var(--fg)">  validate </span><span style="color:var(--syntax-purple)">:value_is_finite</span></span>
<span class="line"><span style="color:var(--syntax-pink)">end</span></span></code></pre><p>The <code>validates</code> DSL is standard Rails validation. The form subclasses <code>Snails::Form</code> instead of including <code>ActiveModel::Model</code>.</p>
<h3 id="jobs">Jobs<a class="anchor" href="https://snails-rb.org/blog/why-i-didnt-rewrite-my-rails-app-in-rust/#jobs" aria-label="Link to this section">#</a></h3>
<pre class="code language-ruby" tabindex="0"><code><span class="line"><span style="color:var(--syntax-pink)">class</span><span style="color:var(--syntax-cyan)"> MetricsRollupPruneJob</span><span style="color:var(--syntax-pink)"> &#x3C;</span><span style="color:var(--syntax-cyan);font-style:italic"> ActiveJob</span><span style="color:var(--syntax-pink);font-style:italic">::</span><span style="color:var(--syntax-cyan);font-style:italic">Base</span></span>
<span class="line"><span style="color:var(--syntax-pink)">  def</span><span style="color:var(--syntax-green)"> self.perform</span><span style="color:var(--fg)">(</span><span style="color:var(--syntax-orange);font-style:italic">data</span><span style="color:var(--fg)">)</span></span>
<span class="line"><span style="color:var(--syntax-cyan);font-style:italic">    Account</span><span style="color:var(--fg)">.</span><span style="color:var(--syntax-green)">all</span><span style="color:var(--fg)">.</span><span style="color:var(--syntax-green)">each</span><span style="color:var(--syntax-pink)"> do</span><span style="color:var(--fg)"> |account|</span></span>
<span class="line"><span style="color:var(--fg)">      days </span><span style="color:var(--syntax-pink)">=</span><span style="color:var(--fg)"> account.</span><span style="color:var(--syntax-green)">retention_policy</span><span style="color:var(--fg)">.</span><span style="color:var(--syntax-green)">metrics_days</span></span>
<span class="line"><span style="color:var(--syntax-cyan);font-style:italic">      Metrics5mWindow</span><span style="color:var(--fg)">.</span><span style="color:var(--syntax-green)">prune_before!</span><span style="color:var(--fg)">(account.</span><span style="color:var(--syntax-green)">id</span><span style="color:var(--fg)">, days.</span><span style="color:var(--syntax-green)">days</span><span style="color:var(--fg)">.</span><span style="color:var(--syntax-green)">ago</span><span style="color:var(--fg)">)</span></span>
<span class="line"><span style="color:var(--syntax-pink)">    end</span></span>
<span class="line"><span style="color:var(--syntax-pink)">  end</span></span>
<span class="line"><span style="color:var(--syntax-pink)">end</span></span>
<span class="line"></span>
<span class="line"><span style="color:var(--syntax-cyan);font-style:italic">ActiveJob</span><span style="color:var(--fg)">.</span><span style="color:var(--syntax-green)">recurring</span><span style="color:var(--fg)">(</span><span style="color:var(--syntax-purple)">MetricsRollupPruneJob</span><span style="color:var(--fg)">, </span><span style="color:var(--syntax-purple)">schedule:</span><span style="color:var(--syntax-yellow)"> "</span><span style="color:var(--syntax-yellow)">0 6 * * *</span><span style="color:var(--syntax-yellow)">"</span><span style="color:var(--fg)">)</span></span></code></pre><p><code>ActiveJob::Base</code> is the Rails base class; the class-side <code>perform</code> is Snails&#39;. Rails calls an instance method and offers <code>perform_later</code>; Snails calls the class directly, which is what the compiler needs. <code>ActiveJob.recurring</code> is one line in <code>config/environment.rb</code>.</p>
<h3 id="tests">Tests<a class="anchor" href="https://snails-rb.org/blog/why-i-didnt-rewrite-my-rails-app-in-rust/#tests" aria-label="Link to this section">#</a></h3>
<pre class="code language-ruby" tabindex="0"><code><span class="line"><span style="color:var(--syntax-pink)">class</span><span style="color:var(--syntax-cyan)"> MetricsIngestTest</span><span style="color:var(--syntax-pink)"> &#x3C;</span><span style="color:var(--syntax-cyan);font-style:italic"> Snails::Harness</span><span style="color:var(--syntax-pink);font-style:italic">::</span><span style="color:var(--syntax-cyan);font-style:italic">IntegrationTest</span></span>
<span class="line"><span style="color:var(--syntax-cyan)">  test</span><span style="color:var(--syntax-yellow)"> "</span><span style="color:var(--syntax-yellow)">ingest accepts valid payload</span><span style="color:var(--syntax-yellow)">"</span><span style="color:var(--syntax-pink)"> do</span></span>
<span class="line"><span style="color:var(--syntax-green)">    post_raw</span><span style="color:var(--fg)">(</span><span style="color:var(--syntax-yellow)">"</span><span style="color:var(--syntax-yellow)">/v1/metrics</span><span style="color:var(--syntax-yellow)">"</span><span style="color:var(--fg)">, </span><span style="color:var(--syntax-green)">gauge_json</span><span style="color:var(--fg)">(</span><span style="color:var(--syntax-yellow)">"</span><span style="color:var(--syntax-yellow)">server-proxy</span><span style="color:var(--syntax-yellow)">"</span><span style="color:var(--fg)">), json_headers)</span></span>
<span class="line"><span style="color:var(--fg)">    assert_response </span><span style="color:var(--syntax-purple)">200</span></span>
<span class="line"><span style="color:var(--fg)">    assert_equal </span><span style="color:var(--syntax-purple)">1</span><span style="color:var(--fg)">, </span><span style="color:var(--syntax-cyan);font-style:italic">MetricSample</span><span style="color:var(--fg)">.</span><span style="color:var(--syntax-green)">count</span></span>
<span class="line"><span style="color:var(--syntax-pink)">  end</span></span>
<span class="line"><span style="color:var(--syntax-pink)">end</span></span></code></pre><p>The test sends a real HTTP request and reads the table. The assertions are standard Rails integration-test assertions; the harness is <code>Snails::Harness::IntegrationTest</code>.</p>
<p>That&#39;s where the Rails model convention ends. The model is a plain <code>Sqlx::Base</code> class, and the write path below is the code that replaced Active Record.</p>
<h2 id="what-it-cost">What it cost<a class="anchor" href="https://snails-rb.org/blog/why-i-didnt-rewrite-my-rails-app-in-rust/#what-it-cost" aria-label="Link to this section">#</a></h2>
<p>Active Record was the biggest change. I didn&#39;t have associations or callbacks in this app, but I used relation chaining and validations. Models are plain classes now. Reads and writes go through Sqlx, the framework&#39;s SQL API. There&#39;s no relation API to build the SQL for you, so you write more SQL by hand. The bigger job was the write path: validation, batching, and the derived tables are now explicit steps.</p>
<p>Spinel was the other cost. While I was building Snails, I filed more than twenty Spinel issues: compiler bugs, missing constants, and cases where the emitted code didn&#39;t match the source. The hard part was doing both at once: debugging the compiler, filing issues, waiting for fixes, and building the framework. Spinel is much more stable now and production-ready, but it is not finished. The issues are in the <a href="https://github.com/matz/spinel/issues?q=author%3Akslrinn">Spinel issue tracker</a>.</p>
<h3 id="write-path">Write path<a class="anchor" href="https://snails-rb.org/blog/why-i-didnt-rewrite-my-rails-app-in-rust/#write-path" aria-label="Link to this section">#</a></h3>
<p>This is the write path for one batch:</p>
<pre class="code language-ruby" tabindex="0"><code><span class="line"><span style="color:var(--syntax-pink)">class</span><span style="color:var(--syntax-cyan)"> MetricSample</span><span style="color:var(--syntax-pink)"> &#x3C;</span><span style="color:var(--syntax-cyan);font-style:italic"> Sqlx</span><span style="color:var(--syntax-pink);font-style:italic">::</span><span style="color:var(--syntax-cyan);font-style:italic">Base</span></span>
<span class="line"><span style="color:var(--syntax-pink)">  def</span><span style="color:var(--syntax-green)"> self.table_name</span><span style="color:var(--syntax-pink)"> =</span><span style="color:var(--syntax-yellow)"> "</span><span style="color:var(--syntax-yellow)">metric_samples</span><span style="color:var(--syntax-yellow)">"</span></span>
<span class="line"></span>
<span class="line"><span style="color:var(--syntax-pink)">  def</span><span style="color:var(--syntax-green)"> self.upsert_rows!</span><span style="color:var(--fg)">(</span><span style="color:var(--syntax-orange);font-style:italic">rows</span><span style="color:var(--fg)">)</span></span>
<span class="line"><span style="color:var(--fg)">    forms </span><span style="color:var(--syntax-pink)">=</span><span style="color:var(--fg)"> rows.</span><span style="color:var(--syntax-green)">map</span><span style="color:var(--fg)"> { |row| </span><span style="color:var(--syntax-cyan);font-style:italic">MetricSampleForm</span><span style="color:var(--fg)">.</span><span style="color:var(--syntax-pink)">new</span><span style="color:var(--fg)">(row) }</span></span>
<span class="line"><span style="color:var(--fg)">    forms.</span><span style="color:var(--syntax-green)">each</span><span style="color:var(--fg)"> { |form| </span><span style="color:var(--syntax-pink)">raise</span><span style="color:var(--syntax-cyan);font-style:italic"> Sqlx</span><span style="color:var(--syntax-pink)">::</span><span style="color:var(--syntax-purple)">RecordInvalid</span><span style="color:var(--fg)">, form </span><span style="color:var(--syntax-pink)">unless</span><span style="color:var(--fg)"> form.</span><span style="color:var(--syntax-green)">valid?</span><span style="color:var(--fg)"> }</span></span>
<span class="line"></span>
<span class="line"><span style="color:var(--fg)">    stored </span><span style="color:var(--syntax-pink)">=</span><span style="color:var(--fg)"> forms.</span><span style="color:var(--syntax-green)">map</span><span style="color:var(--syntax-pink)"> do</span><span style="color:var(--fg)"> |form|</span></span>
<span class="line"><span style="color:var(--fg)">      { </span><span style="color:var(--syntax-purple)">account_id:</span><span style="color:var(--fg)"> form.</span><span style="color:var(--syntax-green)">account_id</span><span style="color:var(--fg)">, </span><span style="color:var(--syntax-purple)">ts:</span><span style="color:var(--fg)"> form.</span><span style="color:var(--syntax-green)">ts</span><span style="color:var(--fg)">, </span><span style="color:var(--syntax-purple)">service:</span><span style="color:var(--fg)"> form.</span><span style="color:var(--syntax-green)">service</span><span style="color:var(--fg)">,</span></span>
<span class="line"><span style="color:var(--syntax-purple)">        host:</span><span style="color:var(--fg)"> form.</span><span style="color:var(--syntax-green)">host</span><span style="color:var(--fg)">, </span><span style="color:var(--syntax-purple)">metric:</span><span style="color:var(--fg)"> form.</span><span style="color:var(--syntax-green)">metric</span><span style="color:var(--fg)">, </span><span style="color:var(--syntax-purple)">kind:</span><span style="color:var(--fg)"> form.</span><span style="color:var(--syntax-green)">kind</span><span style="color:var(--fg)">,</span></span>
<span class="line"><span style="color:var(--syntax-purple)">        labels:</span><span style="color:var(--syntax-cyan);font-style:italic"> JSON</span><span style="color:var(--fg)">.</span><span style="color:var(--syntax-green)">generate</span><span style="color:var(--fg)">(form.</span><span style="color:var(--syntax-green)">labels</span><span style="color:var(--fg)">.</span><span style="color:var(--syntax-green)">sort</span><span style="color:var(--fg)">.</span><span style="color:var(--syntax-green)">to_h</span><span style="color:var(--fg)">), </span><span style="color:var(--syntax-purple)">value:</span><span style="color:var(--fg)"> form.</span><span style="color:var(--syntax-green)">value</span><span style="color:var(--fg)"> }</span></span>
<span class="line"><span style="color:var(--syntax-pink)">    end</span></span>
<span class="line"></span>
<span class="line"><span style="color:var(--fg)">    transaction </span><span style="color:var(--syntax-pink)">do</span></span>
<span class="line"><span style="color:var(--fg)">      count </span><span style="color:var(--syntax-pink)">=</span><span style="color:var(--syntax-purple)"> 0</span></span>
<span class="line"><span style="color:var(--fg)">      stored.</span><span style="color:var(--syntax-green)">each_slice</span><span style="color:var(--fg)">(</span><span style="color:var(--syntax-purple)">500</span><span style="color:var(--fg)">) </span><span style="color:var(--syntax-pink)">do</span><span style="color:var(--fg)"> |batch|</span></span>
<span class="line"><span style="color:var(--fg)">        count </span><span style="color:var(--syntax-pink)">+=</span><span style="color:var(--syntax-green)"> upsert_all!</span><span style="color:var(--fg)">(batch, </span><span style="color:var(--syntax-purple)">unique_by</span><span style="color:var(--fg)">: %i[</span><span style="color:var(--syntax-purple)">account_id ts service host metric labels</span><span style="color:var(--fg)">])</span></span>
<span class="line"><span style="color:var(--syntax-pink)">      end</span></span>
<span class="line"><span style="color:var(--syntax-cyan);font-style:italic">      MetricSeriesLatest</span><span style="color:var(--fg)">.</span><span style="color:var(--syntax-green)">upsert_newer!</span><span style="color:var(--fg)">(stored)</span></span>
<span class="line"><span style="color:var(--syntax-cyan);font-style:italic">      Metrics5mWindow</span><span style="color:var(--fg)">.</span><span style="color:var(--syntax-green)">refresh!</span><span style="color:var(--fg)">(stored)</span></span>
<span class="line"><span style="color:var(--fg)">      count</span></span>
<span class="line"><span style="color:var(--syntax-pink)">    end</span></span>
<span class="line"><span style="color:var(--syntax-pink)">  end</span></span>
<span class="line"><span style="color:var(--syntax-pink)">end</span></span></code></pre><p>The form validates each row. The model writes the raw rows and the two derived tables — the latest series and the five-minute window — in one transaction. The 500-row batches keep each statement under SQLite&#39;s bind limit. There are no callbacks; the refresh is a line in the method, and you have to remember it. The tests check the derived tables, so a forgotten refresh fails the suite.</p>
<p>Snails isn&#39;t less explicit than Rails; it moves the explicitness to the model layer. The request path stays Rails-shaped, and the SQL is in the model layer, where I can read it. That&#39;s the trade I wanted. The conventions are what make an agent&#39;s output reviewable: I know where the route, the validation, and the SQL are. Rust makes every layer explicit, including the request path.</p>
<h2 id="what-the-numbers-say">What the numbers say<a class="anchor" href="https://snails-rb.org/blog/why-i-didnt-rewrite-my-rails-app-in-rust/#what-the-numbers-say" aria-label="Link to this section">#</a></h2>
<p>The Rails baseline was about 175 MB for the app process and 504 MB on the node. The Snails build&#39;s app process is about 20 MB RSS; the binary is 4.3 MB. The node is using 362 MB.</p>
<table>
<thead>
<tr>
<th>Measure</th>
<th align="right">Rails baseline</th>
<th align="right">Snails build</th>
</tr>
</thead>
<tbody><tr>
<td>App process memory</td>
<td align="right">~175 MB</td>
<td align="right">~20 MB</td>
</tr>
<tr>
<td>Node used</td>
<td align="right">504 MB</td>
<td align="right">362 MB</td>
</tr>
<tr>
<td>Node available</td>
<td align="right">447 MB</td>
<td align="right">589 MB</td>
</tr>
<tr>
<td>Binary on disk</td>
<td align="right">—</td>
<td align="right">4.3 MB</td>
</tr>
<tr>
<td>Database</td>
<td align="right">Postgres container</td>
<td align="right">SQLite in the app</td>
</tr>
<tr>
<td>Server</td>
<td align="right">one Puma process</td>
<td align="right">one native process</td>
</tr>
</tbody></table>
<p>The app process dropped by about 155 MB. The node&#39;s used memory dropped by 142 MB, and available memory rose by the same amount. The node also runs a query agent and the proxy now, so its memory use fell by less than the app process did. The database moved from a Postgres container to SQLite in the app. That change shows up in the node&#39;s memory, not in the app process.</p>
<p>The Rails baseline is from the October deploy. The Snails numbers are from the production node now. The current numbers are steady-state measurements: process RSS for the app, <code>free -m</code> for the node, and <code>ls -lh</code> for the binary. This is one service, not a benchmark.</p>
<p>Throughput is a separate question. The <a href="https://github.com/snails-rb/snails-benchmark">snails-benchmark</a> repo has a measurement on <code>/up</code> against Rails in cluster mode, with the method and raw results.</p>
<p>The server is one native process, multi-threaded, across all cores: no worker processes, no GVL.</p>
<p>Rails conventions, native performance. The code shows the first; the numbers show the second. Neither is the trade. The trade is in the features I gave up.</p>
<h2 id="the-trade-off">The trade-off<a class="anchor" href="https://snails-rb.org/blog/why-i-didnt-rewrite-my-rails-app-in-rust/#the-trade-off" aria-label="Link to this section">#</a></h2>
<p>The obvious trade is Active Record, gems, and HTML views. For an API app, views are already out of scope. The real trade is the dependencies themselves: Active Record, the web server, the cron parser, the validation library.</p>
<p>A few years ago, that would have sounded insane. Drop gem compatibility? Write your own web server and cron parser? You&#39;d be rebuilding a decade of work. Coding agents change the math. They can write the missing pieces, and you can read them. Snails is the proof: the web server, the cron parser, and the rest are implemented in the framework, only as much as it needs. The cron parser is one file: it accepts the five-field grammar the scheduler needs and rejects everything else at parse time. This app does the same: forms, SQL, jobs.</p>
<p>Snails starts from one assumption: agents write the code, and developers read it. That assumption is what makes the trade possible. If the agent can write the web server, the cron parser, and the forms, I don&#39;t need a gem for them. I need code I can read.</p>
<p>That&#39;s why I didn&#39;t rewrite in Rust. Rust made the code I had to read heavier, not lighter. Snails keeps the Rails conventions and puts the explicit parts where I can read them. For this API app, that was the right trade.</p>
<h2 id="what-would-you-not-give-up">What would you not give up?<a class="anchor" href="https://snails-rb.org/blog/why-i-didnt-rewrite-my-rails-app-in-rust/#what-would-you-not-give-up" aria-label="Link to this section">#</a></h2>
<p>The question for your app is not whether you can live without Active Record. It&#39;s whether you&#39;re willing to own the code that used to be a gem. Would you remove Active Record, cut the external dependencies, and write the pieces yourself?</p>
<p>If the answer is no, stay on Rails. The memory problem is real, but the choice is yours.</p>
<p>Snails is at 1.x, and the public API is stable. The conventions are the compatibility promise, and they won&#39;t change.</p>
<p>If you try Snails and hit a wall, I want to know.</p>
<p>The <a href="https://snails-rb.org/manual/coming-from-rails/">manual&#39;s Coming from Rails chapter</a> covers the port. The <a href="https://snails-rb.org/blog/the-snails-design/">Snails Design</a> makes the case. The <a href="https://github.com/snails-rb/snails">repository</a> has the code, and the <a href="https://github.com/snails-rb/snails-benchmark">benchmark</a> has the method and raw results.</p>
<p>What would you not give up?</p>
]]></content:encoded>
</item>
<item>
  <title>The Snails Design</title>
  <link>https://snails-rb.org/blog/the-snails-design/</link>
  <guid isPermaLink="true">https://snails-rb.org/blog/the-snails-design/</guid>
  <pubDate>Fri, 13 Nov 2026 00:00:00 GMT</pubDate>
  <dc:creator>Snails</dc:creator>
  <description><![CDATA[The design choices behind Snails — Rails conventions without the runtime overhead.]]></description>
  <content:encoded><![CDATA[<p>Snails is a Rails-like framework for API-only Ruby apps. It keeps the Rails conventions that make an API app predictable — routes, controllers, form objects, mailers, jobs, and a conventional folder layout — and compiles the app, the framework, and the HTTP server into one native executable. The design keeps the developer-friendly Rails conventions and removes the abstractions that were chosen for human writing and added runtime overhead.</p>
<h2 id="rails-39-abstraction-trade">Rails&#39; abstraction trade<a class="anchor" href="https://snails-rb.org/blog/the-snails-design/#rails-39-abstraction-trade" aria-label="Link to this section">#</a></h2>
<p>Rails is developer-friendly because it abstracts work a human would otherwise do: ActiveRecord hides SQL, the view layer and asset pipeline hide the browser stack, and gems supply behavior a team would otherwise build. Those abstractions made a human team faster, and Rails accepted the runtime overhead: a Ruby runtime, a GVL, worker processes, and layers between the request and the database.</p>
<p>Coding agents change that trade-off. They write SQL, maintain a backend and a frontend as two stacks, and implement the missing behavior instead of adding a dependency. The abstractions that saved a human team time now add layers an agent does not need and a human has to trust. Snails keeps the Rails conventions and the developer-friendly API style, and removes the layers that add runtime overhead: no ORM, no view layer, no gem compatibility, one native binary. The developer-friendly conventions no longer have to carry that overhead.</p>
<p>A common argument now is that abstraction is over. The claim is too broad. The more specific claim is that the abstractions Rails chose for human writing no longer justify their runtime overhead when agents write the code. Abstraction is still necessary, but it must be light and shared: conventions and rules the agent follows and the reviewer checks. The agent produces predictable code; the reviewer checks the route, the SQL, the migration, and the test evidence, and decides what ships. Review is the constraint, not the reason for the design. The reason is the abstraction trade: keep what makes Rails productive, remove what makes it slow.</p>
<h2 id="predictable-rails-conventions">Predictable Rails conventions<a class="anchor" href="https://snails-rb.org/blog/the-snails-design/#predictable-rails-conventions" aria-label="Link to this section">#</a></h2>
<p>The point of the Rails conventions is predictability: an agent can add code without inventing a layout, and a human knows where to look. Routes live in <code>config/routes.rb</code>, controllers are classes with actions, forms own validation, mailers and jobs have their own folders, and migrations are numbered files. A new endpoint has one obvious place, and a human can find the request path without a map. The <a href="https://snails-rb.org/manual/coming-from-rails/">Coming from Rails</a> chapter is the translation table for the habits that carry over and the ones that do not.</p>
<h2 id="the-frontend-is-a-separate-app">The frontend is a separate app<a class="anchor" href="https://snails-rb.org/blog/the-snails-design/#the-frontend-is-a-separate-app" aria-label="Link to this section">#</a></h2>
<p>Rails 7 made Hotwire (Turbo and Stimulus) the default frontend for new apps. That stack is part of Rails&#39; server-rendered default. Snails removes the Rails frontend stack entirely. The closest comparison is Rails API-only mode: controllers answer JSON, and the frontend is a separate app.</p>
<p>There is no view layer, no asset pipeline, no Hotwire, no session store, and no CSRF middleware. The framework provides the HTTP authentication handshake, not a user model. The app owns the credential model and session design. With coding agents, maintaining a frontend as a separate stack is practical, and the JSON API gives both sides a clear interface. The frontend can live in the same repository or its own; the backend does not choose React, a native app, or a server-rendered page.</p>
<h2 id="build-time-code-generation">Build-time code generation<a class="anchor" href="https://snails-rb.org/blog/the-snails-design/#build-time-code-generation" aria-label="Link to this section">#</a></h2>
<p>Rails removes boilerplate by handling it at runtime. Zeitwerk autoloads constants from <code>app/</code>, Active Record reads the schema and defines column methods, and the route set defines path helpers. All three are runtime conveniences: the app does not declare the boilerplate, and the framework creates it while the app runs.</p>
<p>Snails keeps the convenience without runtime metaprogramming. It does not autoload, define model methods from the schema at boot, or build route helpers from the route table at runtime. The compiler needs a static require graph, and the app needs generated code a human can review. The CLI generates the code before every build: <code>gen/</code> holds the literal require lists for each app folder, <code>gen/model_columns.rb</code> holds the column readers and type lists from <code>db/schema.sql</code>, and <code>gen/route_helpers.rb</code> holds the path methods from <code>config/routes.rb</code>. The agent adds files under <code>app/</code> and route declarations; the next <code>bin/dev</code> or <code>bin/test</code> refreshes the generated files.</p>
<p>The schema is the input. A <code>posts</code> table with <code>title</code> and <code>status</code> produces readers on <code>Post</code>:</p>
<pre class="code language-sql" tabindex="0"><code><span class="line"><span style="color:var(--syntax-pink)">CREATE</span><span style="color:var(--syntax-pink)"> TABLE</span><span style="color:var(--syntax-green)"> posts</span><span style="color:var(--fg)"> (</span></span>
<span class="line"><span style="color:var(--fg)">  id </span><span style="color:var(--syntax-pink)">INTEGER</span><span style="color:var(--syntax-pink)"> PRIMARY KEY</span><span style="color:var(--fg)">,</span></span>
<span class="line"><span style="color:var(--fg)">  title </span><span style="color:var(--syntax-pink)">TEXT</span><span style="color:var(--syntax-pink)"> NOT NULL</span><span style="color:var(--fg)">,</span></span>
<span class="line"><span style="color:var(--syntax-pink)">  status</span><span style="color:var(--syntax-pink)"> TEXT</span><span style="color:var(--syntax-pink)"> NOT NULL</span><span style="color:var(--syntax-pink)"> DEFAULT</span><span style="color:var(--syntax-yellow)"> '</span><span style="color:var(--syntax-yellow)">draft</span><span style="color:var(--syntax-yellow)">'</span></span>
<span class="line"><span style="color:var(--fg)">);</span></span></code></pre><pre class="code language-ruby" tabindex="0"><code><span class="line"><span style="color:var(--syntax-comment)"># gen/model_columns.rb (generated)</span></span>
<span class="line"><span style="color:var(--syntax-pink)">module</span><span style="color:var(--syntax-cyan);font-style:italic"> GeneratedModelReaders</span></span>
<span class="line"><span style="color:var(--syntax-pink)">  module</span><span style="color:var(--syntax-cyan);font-style:italic"> Post</span></span>
<span class="line"><span style="color:var(--syntax-pink)">    def</span><span style="color:var(--syntax-green)"> title</span><span style="color:var(--syntax-pink)"> =</span><span style="color:var(--syntax-orange);font-style:italic"> read_attribute</span><span style="color:var(--fg)">(</span><span style="color:var(--syntax-purple)">:title</span><span style="color:var(--fg)">)</span></span>
<span class="line"><span style="color:var(--syntax-pink)">    def</span><span style="color:var(--syntax-green)"> status</span><span style="color:var(--syntax-pink)"> =</span><span style="color:var(--syntax-orange);font-style:italic"> read_attribute</span><span style="color:var(--fg)">(</span><span style="color:var(--syntax-purple)">:status</span><span style="color:var(--fg)">)</span></span>
<span class="line"><span style="color:var(--syntax-pink)">  end</span></span>
<span class="line"><span style="color:var(--syntax-pink)">end</span></span></code></pre><p>The generated file also carries <code>COLUMNS</code> and the type lists used for conversion. The model file names its table; it does not declare those readers. The next section shows the model code that uses them.</p>
<h2 id="models-over-sql">Models over SQL<a class="anchor" href="https://snails-rb.org/blog/the-snails-design/#models-over-sql" aria-label="Link to this section">#</a></h2>
<p>Coding agents write SQL well; an ORM&#39;s abstraction does not help that work. The framework needs a standard API for the common reads and writes. Without one, every model grows its own helpers and the code becomes inconsistent. <code>Sqlx</code> is that standard API, not a domain model. It keeps the common path the same across models: the agent calls the same methods, and the human reads the SQL and the bound values.</p>
<p>A model names its table. The columns come from the schema and the generated readers, and the inherited reads and writes operate on the table. There are no associations, callbacks, or model validations. Validation belongs to form objects, and the schema constraint is the model layer&#39;s last line. The common reads and writes use a focused set of methods with parameterized values; joins, views, and aggregates use raw SQL.</p>
<pre class="code language-ruby" tabindex="0"><code><span class="line"><span style="color:var(--syntax-pink)">class</span><span style="color:var(--syntax-cyan)"> Post</span><span style="color:var(--syntax-pink)"> &#x3C;</span><span style="color:var(--syntax-cyan);font-style:italic"> Sqlx</span><span style="color:var(--syntax-pink);font-style:italic">::</span><span style="color:var(--syntax-cyan);font-style:italic">Base</span></span>
<span class="line"><span style="color:var(--syntax-pink)">  def</span><span style="color:var(--syntax-green)"> self.table_name</span><span style="color:var(--syntax-pink)"> =</span><span style="color:var(--syntax-yellow)"> "</span><span style="color:var(--syntax-yellow)">posts</span><span style="color:var(--syntax-yellow)">"</span></span>
<span class="line"><span style="color:var(--syntax-pink)">end</span></span>
<span class="line"></span>
<span class="line"><span style="color:var(--fg)">post </span><span style="color:var(--syntax-pink)">=</span><span style="color:var(--syntax-cyan);font-style:italic"> Post</span><span style="color:var(--fg)">.</span><span style="color:var(--syntax-green)">find_by</span><span style="color:var(--fg)">({ </span><span style="color:var(--syntax-purple)">title:</span><span style="color:var(--syntax-yellow)"> "</span><span style="color:var(--syntax-yellow)">Hello</span><span style="color:var(--syntax-yellow)">"</span><span style="color:var(--fg)"> })</span></span>
<span class="line"><span style="color:var(--fg)">post.</span><span style="color:var(--syntax-green)">title</span></span>
<span class="line"><span style="color:var(--fg)">post.</span><span style="color:var(--syntax-green)">status</span></span>
<span class="line"><span style="color:var(--syntax-cyan);font-style:italic">Post</span><span style="color:var(--fg)">.</span><span style="color:var(--syntax-green)">update!</span><span style="color:var(--fg)">(post.</span><span style="color:var(--syntax-green)">id</span><span style="color:var(--fg)">, { </span><span style="color:var(--syntax-purple)">status:</span><span style="color:var(--syntax-yellow)"> "</span><span style="color:var(--syntax-yellow)">published</span><span style="color:var(--syntax-yellow)">"</span><span style="color:var(--fg)"> })</span></span>
<span class="line"><span style="color:var(--syntax-cyan);font-style:italic">Post</span><span style="color:var(--fg)">.</span><span style="color:var(--syntax-green)">fetch_many</span><span style="color:var(--fg)">({ </span><span style="color:var(--syntax-purple)">status:</span><span style="color:var(--syntax-yellow)"> "</span><span style="color:var(--syntax-yellow)">draft</span><span style="color:var(--syntax-yellow)">"</span><span style="color:var(--fg)"> }, </span><span style="color:var(--syntax-purple)">order:</span><span style="color:var(--syntax-purple)"> :desc</span><span style="color:var(--fg)">)</span></span></code></pre><p>The model layer is thin on purpose: the SQL is the source, and the framework gives the common queries a standard API. A join or a cascade is written as a query where a human can read it. An empty condition is refused unless the caller explicitly asks for an ordered whole-table read. Writes raise when the database rejects them.</p>
<h2 id="migrations-are-sql">Migrations are SQL<a class="anchor" href="https://snails-rb.org/blog/the-snails-design/#migrations-are-sql" aria-label="Link to this section">#</a></h2>
<p>The migration is SQL because the agent writes the statements the human reads. There is no Ruby DSL to translate, and a human does not need to hand-write the file. The schema dump comes from the same files; the migration and the generated column readers share one source.</p>
<p>A schema change is a numbered SQL file under <code>db/migrate/</code>. <code>snails migrate apply</code> runs the pending files in order, and <code>snails migrate dump</code> regenerates <code>db/schema.sql</code>. <code>snails migrate verify</code> checks the dump against a replay, and <code>snails migrate check</code> stops a deploy while anything is pending. If another system owns the schema, <code>DB_OWNER=&quot;external&quot;</code> tells the CLI to refuse DDL.</p>
<p>A later change adds a stable URL segment and backfills existing rows:</p>
<pre class="code language-sql" tabindex="0"><code><span class="line"><span style="color:var(--syntax-comment)">-- Add a stable URL segment and backfill existing posts.</span></span>
<span class="line"><span style="color:var(--syntax-pink)">ALTER</span><span style="color:var(--syntax-pink)"> TABLE</span><span style="color:var(--fg)"> posts </span><span style="color:var(--syntax-pink)">ADD</span><span style="color:var(--fg)"> COLUMN slug </span><span style="color:var(--syntax-pink)">TEXT</span><span style="color:var(--fg)">;</span></span>
<span class="line"><span style="color:var(--syntax-pink)">UPDATE</span><span style="color:var(--fg)"> posts </span><span style="color:var(--syntax-pink)">SET</span><span style="color:var(--fg)"> slug </span><span style="color:var(--syntax-pink)">=</span><span style="color:var(--syntax-yellow)"> '</span><span style="color:var(--syntax-yellow)">post-</span><span style="color:var(--syntax-yellow)">'</span><span style="color:var(--syntax-pink)"> ||</span><span style="color:var(--syntax-cyan)"> CAST</span><span style="color:var(--fg)">(id </span><span style="color:var(--syntax-pink)">AS</span><span style="color:var(--syntax-pink)"> TEXT</span><span style="color:var(--fg)">) </span><span style="color:var(--syntax-pink)">WHERE</span><span style="color:var(--fg)"> slug </span><span style="color:var(--syntax-pink)">IS</span><span style="color:var(--syntax-pink)"> NULL</span><span style="color:var(--fg)">;</span></span>
<span class="line"><span style="color:var(--syntax-pink)">CREATE</span><span style="color:var(--syntax-pink)"> UNIQUE INDEX</span><span style="color:var(--syntax-green)"> posts_slug_key</span><span style="color:var(--syntax-pink)"> ON</span><span style="color:var(--fg)"> posts (slug);</span></span></code></pre><p>The statements are the change: a column, a backfill, and a uniqueness constraint. A human reviews them in the file the agent applies; the next <code>snails migrate dump</code> feeds the generated column readers from the same source.</p>
<h2 id="performance-first">Performance first<a class="anchor" href="https://snails-rb.org/blog/the-snails-design/#performance-first" aria-label="Link to this section">#</a></h2>
<p>Rails is often criticized for its performance. Ruby&#39;s global VM lock (GVL) limits one process to one thread of application code. Rails runs worker processes to use more cores; each worker carries its own VM, connection pool, heap, and resident set.</p>
<p>Snails makes a major architectural choice: no Ruby runtime, no gem compatibility, and one native binary that contains the app, the framework, and the HTTP server. App code stays Ruby; the compiler turns it into the binary. That removes the GVL, the Bundler load path, and the per-worker memory footprint. One process runs request handlers on the cores the OS gives it, and the binary boots in single-digit milliseconds. The <a href="https://snails-rb.org/manual/performance/">Performance</a> chapter measures about 3× the throughput of Rails in cluster mode, 10× or more peak-memory savings under load, and about 12× the throughput of a default Rails app.</p>
<p>The no-gem choice is what coding agents make practical. A gem assumes a Ruby runtime and a Bundler load path; the binary has none. The framework provides the helpers an API app needs, and the app provides the rest; the agent implements the missing behavior in the app, in the same language and test suite. That is why the performance choice is practical now.</p>
<p><a id="integration-tests-against-a-real-server"></a></p>
<h2 id="integration-by-default">Integration by default<a class="anchor" href="https://snails-rb.org/blog/the-snails-design/#integration-by-default" aria-label="Link to this section">#</a></h2>
<p>Stubs and mocks are easier to write; an agent choosing on its own will often produce a suite that describes the system instead of exercising it. The harness makes integration the default: <code>bin/test</code> builds the app, boots it on a spare port, and sends real HTTP requests. One fresh server serves the suite; each case resets the tables it declares.</p>
<p>The test code follows the Rails integration-test pattern:</p>
<pre class="code language-ruby" tabindex="0"><code><span class="line"><span style="color:var(--syntax-comment)"># harness/test/posts_test.rb</span></span>
<span class="line"><span style="color:var(--syntax-pink)">require_relative</span><span style="color:var(--syntax-yellow)"> "</span><span style="color:var(--syntax-yellow)">../boot</span><span style="color:var(--syntax-yellow)">"</span></span>
<span class="line"></span>
<span class="line"><span style="color:var(--syntax-pink)">class</span><span style="color:var(--syntax-cyan)"> PostsTest</span><span style="color:var(--syntax-pink)"> &#x3C;</span><span style="color:var(--syntax-cyan);font-style:italic"> Snails::Harness</span><span style="color:var(--syntax-pink);font-style:italic">::</span><span style="color:var(--syntax-cyan);font-style:italic">IntegrationTest</span></span>
<span class="line"><span style="color:var(--syntax-pink)">  def</span><span style="color:var(--syntax-green)"> tables</span><span style="color:var(--syntax-pink)"> =</span><span style="color:var(--fg)"> [</span><span style="color:var(--syntax-yellow)">"</span><span style="color:var(--syntax-yellow)">posts</span><span style="color:var(--syntax-yellow)">"</span><span style="color:var(--fg)">]</span></span>
<span class="line"></span>
<span class="line"><span style="color:var(--syntax-cyan)">  test</span><span style="color:var(--syntax-yellow)"> "</span><span style="color:var(--syntax-yellow)">creating a post stores the row</span><span style="color:var(--syntax-yellow)">"</span><span style="color:var(--syntax-pink)"> do</span></span>
<span class="line"><span style="color:var(--syntax-green)">    post</span><span style="color:var(--fg)">(</span><span style="color:var(--syntax-yellow)">"</span><span style="color:var(--syntax-yellow)">/posts</span><span style="color:var(--syntax-yellow)">"</span><span style="color:var(--fg)">, </span><span style="color:var(--syntax-purple)">params</span><span style="color:var(--fg)">: { </span><span style="color:var(--syntax-yellow)">"</span><span style="color:var(--syntax-yellow)">title</span><span style="color:var(--syntax-yellow)">"</span><span style="color:var(--syntax-pink)"> =></span><span style="color:var(--syntax-yellow)"> "</span><span style="color:var(--syntax-yellow)">Hello</span><span style="color:var(--syntax-yellow)">"</span><span style="color:var(--fg)"> }, </span><span style="color:var(--syntax-purple)">as</span><span style="color:var(--fg)">: :</span><span style="color:var(--syntax-purple)">json</span><span style="color:var(--fg)">)</span></span>
<span class="line"><span style="color:var(--syntax-green)">    assert_response</span><span style="color:var(--fg)">(:</span><span style="color:var(--syntax-purple)">success</span><span style="color:var(--fg)">)</span></span>
<span class="line"><span style="color:var(--fg)">    assert_equal </span><span style="color:var(--syntax-yellow)">"</span><span style="color:var(--syntax-yellow)">Hello</span><span style="color:var(--syntax-yellow)">"</span><span style="color:var(--fg)">, </span><span style="color:var(--syntax-cyan);font-style:italic">Post</span><span style="color:var(--fg)">.</span><span style="color:var(--syntax-green)">find_by</span><span style="color:var(--fg)">({ </span><span style="color:var(--syntax-purple)">title:</span><span style="color:var(--syntax-yellow)"> "</span><span style="color:var(--syntax-yellow)">Hello</span><span style="color:var(--syntax-yellow)">"</span><span style="color:var(--fg)"> }).</span><span style="color:var(--syntax-green)">title</span></span>
<span class="line"><span style="color:var(--syntax-pink)">  end</span></span>
<span class="line"><span style="color:var(--syntax-pink)">end</span></span></code></pre><p>The <code>post</code> call sends a real HTTP request. <code>assert_response</code> checks the real status, and <code>Post.find_by</code> reads the row the request wrote. The test does not stub or mock the framework. The default path is the real HTTP server; a passing suite exercises the app as it runs.</p>
<h2 id="a-note-on-why-i-built-snails">A note on why I built Snails<a class="anchor" href="https://snails-rb.org/blog/the-snails-design/#a-note-on-why-i-built-snails" aria-label="Link to this section">#</a></h2>
<p>I built Snails because I like Ruby and Rails. I do not want them to be treated as a dying language and framework in the agent era. Ruby and Rails are developer-friendly for a reason: the conventions, the API style, the way a team can build a real product. Those strengths do not disappear when coding agents write more of the code. What changes is the runtime overhead of the abstractions that were added for human writing.</p>
<p>Snails keeps those strengths and removes the runtime overhead. The design is working when the human can decide from the route, the SQL, the migration, and the test evidence. The agent can add code; the review stays a decision, not an audit. That is the abstraction trade: keep what makes Ruby and Rails good, remove what makes them slow.</p>
<p>That is the only reason I built Snails. I want Ruby and Rails to keep being useful in the agent era, and I want Snails to be one way to do that.</p>
<h2 id="for-ruby-and-rails-developers">For Ruby and Rails developers<a class="anchor" href="https://snails-rb.org/blog/the-snails-design/#for-ruby-and-rails-developers" aria-label="Link to this section">#</a></h2>
<p>I built a working framework, not a prototype. I have migrated an existing Rails app and run new apps in production. The <a href="https://github.com/snails-rb/snails-benchmark">benchmark</a> shows about 3× the throughput of Rails in cluster mode and 10× or more peak-memory savings under load. Those are benchmark numbers; the <a href="https://snails-rb.org/blog/why-i-didnt-rewrite-my-rails-app-in-rust/">field report</a> measures the production node at steady state. In production, the migrated app runs the full application on a 1 GB node. 512 MB is the next target, not yet verified. The base design is validated in use. 1.0 was the first stable release; the project is on 1.x now. The conventions are the compatibility promise, and they won&#39;t change.</p>
<p>The next question is whether it fits the way other Ruby and Rails developers work. I would like to hear from Ruby and Rails developers: what you would try, what you would change, and what is missing. Interest, feedback, and ideas are the next step. The source is open, and the discussion is open. Open a <a href="https://github.com/snails-rb/snails/discussions">discussion</a> or send an <a href="https://github.com/snails-rb/snails/issues">issue</a> with the Rails convention you would miss.</p>
<h2 id="further-reading">Further reading<a class="anchor" href="https://snails-rb.org/blog/the-snails-design/#further-reading" aria-label="Link to this section">#</a></h2>
<ul>
<li><a href="https://snails-rb.org/manual/welcome-to-snails/">Welcome to Snails</a></li>
<li><a href="https://snails-rb.org/manual/coming-from-rails/">Coming from Rails</a></li>
<li><a href="https://snails-rb.org/manual/database-and-models/">Database and Models</a></li>
<li><a href="https://snails-rb.org/manual/migrations/">Migrations</a></li>
<li><a href="https://snails-rb.org/manual/testing/">Testing</a></li>
<li><a href="https://snails-rb.org/manual/concurrency/">Concurrency</a></li>
<li><a href="https://snails-rb.org/manual/performance/">Performance</a></li>
<li><a href="https://snails-rb.org/blog/why-i-didnt-rewrite-my-rails-app-in-rust/">Why I didn&#39;t rewrite my Rails app in Rust</a> — a field report on one app&#39;s version of this trade.</li>
<li><a href="https://github.com/snails-rb/snails-benchmark">Snails benchmark</a></li>
<li><a href="https://github.com/matz/spinel">Spinel</a></li>
<li><a href="https://rubyonrails.org/2021/12/15/Rails-7-fulfilling-a-vision">Rails 7 release notes</a></li>
</ul>
]]></content:encoded>
</item>
  </channel>
</rss>
