<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Mohammad Talim on Medium]]></title>
        <description><![CDATA[Stories by Mohammad Talim on Medium]]></description>
        <link>https://medium.com/@md-talim?source=rss-6ed67f4e21c7------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*9i0tjJXprlKm3eRhwQFojQ.png</url>
            <title>Stories by Mohammad Talim on Medium</title>
            <link>https://medium.com/@md-talim?source=rss-6ed67f4e21c7------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Fri, 20 Nov 2026 06:40:56 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@md-talim/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[I Built a Database Migration Runner in Go to See What Happens Underneath]]></title>
            <link>https://blog.stackademic.com/i-built-a-database-migration-runner-in-go-to-see-what-happens-underneath-3ec5844a6d3c?source=rss-6ed67f4e21c7------2</link>
            <guid isPermaLink="false">https://medium.com/p/3ec5844a6d3c</guid>
            <category><![CDATA[backend-development]]></category>
            <category><![CDATA[database]]></category>
            <category><![CDATA[golang]]></category>
            <category><![CDATA[postgresql]]></category>
            <dc:creator><![CDATA[Mohammad Talim]]></dc:creator>
            <pubDate>Mon, 09 Nov 2026 00:00:07 GMT</pubDate>
            <atom:updated>2026-11-10T07:26:17.112Z</atom:updated>
            <content:encoded><![CDATA[<h4>What happens when two copies of your service migrate the same database at the same time, and how Vow keeps it safe.</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Xc3ztPXI_Impn0dhYnOkGw.png" /></figure><p>Here is a small question that sent me down a rabbit hole: what happens when two copies of your service start at the same time, and both try to update the database schema?</p><p>If you only run migrations by hand, you may never have to think about this. But the moment you run more than one instance of a service, it becomes a real problem.</p><p>This post is about <strong>Vow</strong>, a small database migration runner I wrote in Go for PostgreSQL. It started as a part of my task queue project, Dhara, and I later pulled it out into its own library. I’ll explain what a migration runner does, how Vow works step by step, and the design choices behind it.</p><p>Code: <a href="https://github.com/Md-Talim/vow">github.com/Md-Talim/vow</a></p><h3>Why I built it</h3><p>Honestly, I wasn’t missing a tool. I had already used migration tools like Goose and Flyway, and they work fine.</p><p>I built Vow because I wanted to see what happens underneath the abstraction. You run one command, and your database schema is magically up to date. How? What is it actually doing? That’s the same reason I built Redis, a shell, and an HTTP server from scratch before this. I understand things much better once I’ve built a small version of them.</p><p>This was also the “from scratch” story I promised in my <a href="https://medium.com/stackademic/i-built-a-distributed-task-queue-from-scratch-with-go-and-postgresql-42b705503737?sharedUserId=md-talim">Dhara post</a>. Dhara needed a way to create its database tables, so I wrote a migration runner inside Dhara first. Once it was working, I moved it out into its own repo so I could reuse it in my other Go projects. Dhara now uses Vow for its own migrations.</p><p>So an internal tool turned into a small library I can use whenever I need PostgreSQL migrations in a Go project.</p><h3>What a migration is, and why you need a runner</h3><p><em>If you already know how migration runners work, skip down to the </em><a href="#8a36"><em>“How Vow works”</em></a><em> section.</em></p><p>Your database schema is not fixed. Over the life of a project you add tables, add columns, create indexes, and rename things. A <strong>migration</strong> is just a SQL file that describes one of those changes.</p><p>For example:</p><pre>-- 000001_create_users.up.sql<br>CREATE TABLE users (<br>    id    BIGSERIAL PRIMARY KEY,<br>    email TEXT NOT NULL UNIQUE<br>);</pre><p>Now imagine you have a few of these files, and your project runs in many places: your laptop, a teammate’s laptop, a test database, staging, and production. Every one of those databases needs the same changes, in the same order.</p><p>If you run the files by hand, a lot of questions come up:</p><ul><li>Which files have I already run on this database?</li><li>What order do they go in?</li><li>What if someone edited a file after it was already applied somewhere?</li><li>What if two people run them at the same time?</li></ul><p>A <strong>migration runner</strong> answers all of these for you. It keeps a record inside the database of which migrations have been applied. When it runs, it applies only the new ones, in order, and it refuses to continue if something looks wrong.</p><p>That record is a table in your own database. In Vow it’s called schema_migrations by default, and you can change the name.</p><h3>How Vow works</h3><h4>The files</h4><p>Vow is built for people who embed it in their Go app, so that your schema is up to date before your service starts taking traffic.</p><p>You put your migrations in a folder, and every migration comes as a pair: one file to apply it, and one to undo it.</p><pre>migrations/<br>  000001_create_users.up.sql<br>  000001_create_users.down.sql<br>  000002_add_email_index.up.sql<br>  000002_add_email_index.down.sql</pre><p>The number at the start decides the order. The name after it is just for humans.</p><p>When you create a migrator, Vow checks this folder right away:</p><ul><li>every .up.sql must have a matching .down.sql, and the other way around</li><li>file names must follow the NNNNNN_name.up.sql pattern</li><li>no subfolders are allowed</li></ul><p>If anything is wrong, you find out when the migrator is created, not later when a migration is already running. I like this a lot. A broken folder should fail fast, before it touches your database.</p><h4>Using it</h4><p>This is the whole thing, from the start of main:</p><pre>migrator, err := vow.New(dbPool, os.DirFS(&quot;./migrations&quot;))<br>if err != nil {<br>    log.Fatalf(&quot;invalid migrations directory: %v&quot;, err)<br>}<br><br>if _, err := migrator.Up(context.Background()); err != nil {<br>    log.Fatalf(&quot;failed to migrate: %v&quot;, err)<br>}</pre><p>dbPool is a normal pgxpool.Pool. That&#39;s the only thing Vow needs from you, plus the folder.</p><h4>What happens inside Up</h4><p>When you call Up, here is what happens, in plain steps:</p><ol><li>Vow checks out a connection from the pool and takes the advisory lock on it, so no other instance can migrate at the same time.</li><li>It makes sure the tracking table exists.</li><li>It lists the migration files in number order and loads the versions already recorded.</li><li>It re-reads every already-applied file and verifies its checksum.</li><li>For each pending migration, it runs the SQL and records the version and checksum in a single transaction.</li><li>It releases the lock, returns the connection, and gives you a Result.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*Bc6KSq3karJ8E4ui.png" /><figcaption>Up Flowchart</figcaption></figure><p>The answer comes back as a Result:</p><pre>type Result struct {<br>    Versions []string      // migrations applied (Up) or rolled back (Down), in order<br>    Skipped  int           // already-applied migrations left untouched<br>    Duration time.Duration // total wall-clock time for the run<br>}</pre><p>If migration 3 of 5 fails, Result still tells you what did succeed before the error, so check both return values, not just the error:</p><pre>result, err := migrator.Up(ctx)<br>if err != nil {<br>    log.Printf(&quot;migration run failed after applying %v: %v&quot;, result.Versions, err)<br>    return err<br>}<br>log.Printf(&quot;applied %d, skipped %d, took %s&quot;, len(result.Versions), result.Skipped, result.Duration)</pre><p>That’s the basic idea. The interesting parts are steps 1 and 3, so let’s go through those.</p><h3>Two instances, one database</h3><p>Here is the problem I started with. Say you deploy your service and your platform starts three copies of it at the same moment. Each copy runs Up on startup.</p><p>Without any protection, this is what can happen:</p><ol><li>Instance A looks at the tracking table and sees that migration 3 is not applied.</li><li>Instance B looks at the tracking table and sees the same thing.</li><li>Both start running migration 3.</li></ol><p>At best, one of them crashes at startup because the table or column already exists. At worst, both succeed and you get duplicate data, or a half-finished change.</p><p>This kind of bug is called a <strong>race condition</strong>. Both instances did “check, then act”, and the state changed between the check and the act.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*A2he9wG6PuTEAlOtfEGhTg.png" /><figcaption>Without an advisory lock</figcaption></figure><h3>The fix: an advisory lock</h3><p>PostgreSQL has a feature for exactly this, called an <strong>advisory lock</strong>.</p><p>A normal lock protects something in the database, like a row or a table. An advisory lock doesn’t protect anything on its own. It’s just a lock with a name (really a number) that your application agrees to respect. If one connection holds it, any other connection that asks for it has to wait.</p><p>That makes it perfect for “only one instance may migrate at a time”. Every instance asks for the same lock before it does anything. One gets it. The others wait.</p><p>Vow’s default lock name is vow:migrations. Postgres identifies advisory locks by number, so Vow turns this name into one. You can change the name with WithLockName, which helps if you keep different sets of migrations in one database and don&#39;t want them to block each other.</p><p>Here is what happens with the lock in place:</p><ol><li>Instance A takes the lock and starts applying migration 3.</li><li>Instance B asks for the lock and waits.</li><li>Instance A finishes, records migration 3, and releases the lock.</li><li>Instance B gets the lock, looks at the tracking table, and sees there is nothing left to do. It skips everything and moves on.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*DpBM4kvq2S0XwPXYPFIs5Q.png" /><figcaption>With an advisory lock</figcaption></figure><p>That last step is what the Skipped count in Result is for. Instance B&#39;s run says &quot;applied 0, skipped 3&quot; and the service starts normally.</p><p>One detail that’s easy to miss: an advisory lock belongs to a <strong>database connection</strong>, not to your program. With a connection pool, that means the lock has to be taken and released on the same connection, and that connection must stay checked out for the whole run.</p><p>Vow handles this by checking out a single connection from the pool and holding it for the whole run. The advisory lock, the checksum checks, and every migration transaction use that same connection. When the run ends, Vow unlocks on it before releasing it back to the pool. The unlock uses a fresh five-second context, so a canceled request can’t strand the lock, and if the process dies, Postgres releases the session-level lock when the connection drops.</p><h3>Immutability: applied migrations can’t change</h3><p>The second safety feature is the one I find most interesting.</p><p>Here is a scenario. Your team applies migration 5 to staging and production. A week later, someone notices a mistake in the file and just edits it, adding a missing column. The file in the repo is now different from what was applied.</p><p>What happens next? Staging and production never run the new version, because they already marked migration 5 as done. But a brand new database, say a new teammate’s laptop, will run the edited version. Now you have databases that look different, and nothing in your system tells you. This is called <strong>schema drift</strong>, and it’s a nasty thing to debug.</p><p>Vow prevents this with <strong>checksums</strong>. When a migration is applied, Vow stores a SHA-256 hash of its .up.sql file next to its version in the tracking table. On every Up or Down run, before it applies or rolls back anything, Vow re-reads every already-applied file and compares its hash with the stored one.</p><p>If a file was edited or deleted after it was applied, the run fails right away, before it touches the database any further.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*rXEtuAtTQm3NAuZw.png" /><figcaption>Checksum check</figcaption></figure><p>The rule this creates is simple: <strong>once a migration is applied, it’s history</strong>. If you need to change something, write a new migration.</p><p>A checksum catches more than a plain file name check would. If I only tracked names, someone could change the contents of a file and nobody would notice. With a hash, any content change is caught. Line endings are the one exception: Vow normalizes CRLF to LF before hashing, so a checkout on Windows doesn’t look like drift.</p><h4>Why .down.sql files are not checksummed</h4><p>You might wonder why Vow doesn’t do the same for the down files. This was a deliberate choice.</p><p>When a migration is rolled back, Vow deletes its row from the tracking table. After that, there is no stored record left to compare against, so there is nothing that can drift. Also, rollbacks often happen <em>because</em> a migration needs to change, so I wanted down files to stay free to edit.</p><p>This also means changes to a down migration aren’t protected by checksum verification, so they should be reviewed carefully before executing a rollback.</p><h3>Rolling back, and what I chose not to automate</h3><p>Every migration has a .down.sql file, and Down uses them:</p><pre>result, err := migrator.Down(context.Background(), 1)<br>if err != nil {<br>    log.Fatalf(&quot;rollback failed: %v&quot;, err)<br>}<br>log.Printf(&quot;rolled back: %v&quot;, result.Versions)</pre><p>Down rolls back the last N applied migrations, in reverse order. For each one it runs the .down.sql file and removes the tracking row in a single transaction, so each step is all-or-nothing. Down as a whole is not one transaction: if the second of three rollbacks fails, the first stays rolled back. If you ask for more steps than there are applied migrations, Vow just rolls back everything and stops. It doesn&#39;t treat that as an error.</p><p>There are two rules here that I want to be honest about.</p><p><strong>Down migrations are best effort.</strong> A down file can undo the <em>shape</em> of a change, like dropping a column it added. But it can’t bring back data. If the up migration dropped a column, the down migration can add the column back, but the data that was in it is gone. Write and review your down files with that in mind.</p><p><strong>Up never calls </strong><strong>Down by itself.</strong> If a migration fails halfway through a deploy, Vow stops and fails loudly. It does not try to roll back automatically. A failed deploy is a bad moment for a tool to try a risky undo that nobody has checked. I&#39;d rather leave that decision to a person: fix it forward with a new migration, or roll back by hand.</p><p>Because of this, I see Down as a tool for local development and test cleanup, not for automatic recovery in production.</p><h3>Other design decisions</h3><p><strong>Only pgx.</strong> Vow’s only dependency is pgx/v5, and I deliberately didn&#39;t add a database/sql compatibility layer. Supporting every database driver would have made the code bigger and made it harder to use Postgres features properly. I wanted to do one thing well.</p><p><strong>It takes an </strong><strong>fs.FS, not a path.</strong> Vow accepts any fs.FS, which means your migrations can be real files on disk, or they can be compiled into your binary with //go:embed. Embedding is useful when your migrations ship together with your app, because the binary doesn&#39;t need a migrations/ folder next to it.</p><p>There is one catch, and it’s easy to trip on. Vow always assumes the file system you give it is already rooted at the migrations folder. os.DirFS(&quot;./migrations&quot;) is rooted correctly. An embedded file system is not, because //go:embed migrations/*.sql keeps the migrations/ folder name in the path. So you need fs.Sub first:</p><pre>//go:embed migrations/*.sql<br>var migrationFS embed.FS<br><br>func newMigrator(pool *pgxpool.Pool) (*vow.Migrator, error) {<br>    rooted, err := fs.Sub(migrationFS, &quot;migrations&quot;)<br>    if err != nil {<br>        return nil, err<br>    }<br>    return vow.New(pool, rooted)<br>}</pre><p>I made that choice so the rooting decision happens in exactly one place, when you create the migrator, instead of being repeated on every call.</p><p><strong>Options as functions.</strong> Settings like the table name, the lock name, and the logger are passed as functional options, which is a common Go pattern:</p><pre>migrator, err := vow.New(dbPool, os.DirFS(&quot;./migrations&quot;),<br>    vow.WithTableName(&quot;app_schema_migrations&quot;),<br>    vow.WithLogger(myLogger),<br>    vow.WithLockName(&quot;my-app:migrations&quot;),<br>)</pre><p><strong>Code first, CLI second.</strong> Vow started as just a library. Later I added a small command line tool, mostly for local development, where running migrations by hand is easier than writing a throwaway program:</p><pre>go install github.com/md-talim/vow/cmd/vow@latest<br><br>DATABASE_URL=postgres://user:pass@localhost:5432/mydb vow up<br>vow down 3    # roll back the three most recent migrations</pre><h3>The bug that broke every restart</h3><p>I shipped Vow v0.1.0 with a bug, and a couple of days later I had to release v0.1.1 to fix it.</p><p>The bug: running Up a second time on the same database failed. I noticed it after I used it in dhara and ran tests in dhara.</p><p>The cause was a small mismatch. Vow’s tracking table stores the migration name without the suffix, like 000001_test. But the code that decides which migrations are still pending compared that stored name against the full file name, 000001_test.up.sql. They never matched, so every migration I had already applied looked new again. Vow tried to apply it a second time and failed with a duplicate key error on the tracking table.</p><p>That is worse than it sounds. A second run of Up is not a rare case. It is what happens every time a service restarts if it migrates on startup. A migration runner that can&#39;t be run twice is not much use.</p><p>The fix was one line, adding the suffix back when loading the applied versions:</p><pre>// before: returned the stored version as it is<br>applied[version] = struct{}{}<br><br>// after: match what the pending check compares against<br>filename := fmt.Sprintf(&quot;%s.up.sql&quot;, version)<br>applied[filename] = struct{}{}</pre><p>Why didn’t I catch it earlier? My only test ran Up once and then Down. Nothing ever ran Up twice. So I added a test that runs Up twice on the same database, and checks that the first run applies the migration and the second run skips it. It&#39;s still in the repo as a regression test.</p><p>This also ties back to the lock. The Skipped count is not just a nice number in Result. It&#39;s what makes the lock useful. When Instance B finally gets the lock, it only behaves because a second run knows to skip what is already applied.</p><p>The lesson I took from this: test the second run, not just the first.</p><h3>How I tested it</h3><p>A migration runner is all about what happens inside a real database, so I didn’t mock anything. The tests run against a real PostgreSQL, with Docker Compose on my machine and a Postgres service container in CI.</p><p>While writing this post, I went through everything I claimed and made sure a test backs it up.</p><p>Running Up twice is safe, failed migrations roll back cleanly, edited or deleted applied migrations are caught, and the advisory lock is released after success, failure, and context cancellation.</p><p>The test I care about most is the concurrency one. It starts five separate instances at the same time, on a migration that takes a second, and checks that exactly one applies it and the other four skip it. A race is hard to trust from a single run, so I run it many times with Go’s race detector on.</p><p>Then I commented out the lock and ran it again, and it failed. That’s when I believed the lock was really doing something.</p><p>You can find the integration tests and the individual cases in the <a href="https://github.com/Md-Talim/vow">repository</a>.</p><h3>What’s next</h3><p>Vow is still a young library, and for now I’m happy with what it does: find migrations, check them, and run them safely. I’m using it in my own projects first, and I want to see where it breaks before calling it stable.</p><p>There is a bigger problem I’ve started reading about, and I’m not sure yet if Vow is the right place for it: running migrations against production databases that are actively serving traffic.</p><p>On my laptop, a migration takes milliseconds. On a table with millions of rows, the same migration can hold a lock for minutes or put heavy load on the database while real users are waiting. Backfilling a large table, changing a column, or adding an index are where things get risky.</p><p>Vow already runs into a small version of this limitation. Because every migration currently runs inside a transaction, it cannot execute operations like CREATE INDEX CONCURRENTLY, which PostgreSQL provides for building indexes without blocking concurrent writes.</p><p>Some things I’d like to explore are batched backfills, resumable migrations, progress tracking, the expand-and-contract pattern (add the new thing first, move over, then remove the old thing), and pausing execution when the database looks overloaded.</p><p>I don’t know yet how much of this belongs in a small library, and I don’t want to make Vow huge just because I can. I want to understand the problem first, and I’ll probably write about it as I learn.</p><p>If you’ve run migrations on a live production database, I’d love to hear what went wrong, or what you wish your migration tool did.</p><p>If you read my Dhara post, thank you. This is the second piece of that story, and Vow is still where my “from scratch” habit paid off the most. If you spot a flaw in the design, or have an idea for something Vow should do, I’d genuinely love to hear it.</p><p>The code is on GitHub at <a href="https://github.com/Md-Talim/vow">Md-Talim/vow</a>. Follow along here and on <a href="https://x.com/talimbuilds">X / talimbuilds</a> for what’s next.</p><p><em>Originally published at </em><a href="https://talim.me/vow"><em>https://talim.me</em></a><em> on November 9, 2026.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3ec5844a6d3c" width="1" height="1" alt=""><hr><p><a href="https://blog.stackademic.com/i-built-a-database-migration-runner-in-go-to-see-what-happens-underneath-3ec5844a6d3c">I Built a Database Migration Runner in Go to See What Happens Underneath</a> was originally published in <a href="https://blog.stackademic.com/">Stackademic</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[I Built a Distributed Task Queue from Scratch with Go and PostgreSQL]]></title>
            <link>https://blog.stackademic.com/i-built-a-distributed-task-queue-from-scratch-with-go-and-postgresql-42b705503737?source=rss-6ed67f4e21c7------2</link>
            <guid isPermaLink="false">https://medium.com/p/42b705503737</guid>
            <category><![CDATA[postgresql]]></category>
            <category><![CDATA[distributed-systems]]></category>
            <category><![CDATA[backend]]></category>
            <category><![CDATA[backend-development]]></category>
            <category><![CDATA[golang]]></category>
            <dc:creator><![CDATA[Mohammad Talim]]></dc:creator>
            <pubDate>Fri, 02 Oct 2026 19:02:54 GMT</pubDate>
            <atom:updated>2026-10-03T14:10:03.862Z</atom:updated>
            <content:encoded><![CDATA[<p>I built <strong>Dhara</strong>, a distributed task queue for Go, using PostgreSQL as the only queue and source of truth. No Redis, no Kafka, no RabbitMQ.</p><p>In this post I&#39;ll cover why I built it, how a task moves through the system, the design decisions that mattered (transactional enqueue and FOR UPDATE SKIP LOCKED), a performance bug that made my queue 8x slower than it should have been, and what I&#39;m building next.</p><p>Code: <a href="https://github.com/Md-Talim/dhara">github.com/Md-Talim/dhara</a></p><h3>Why I built a distributed task queue</h3><p>Honestly, I don&#39;t remember exactly why I decided to build this.</p><p>What I do remember is how I got there. I&#39;d been asking AI models about my next project with very vague prompts like &quot;give me hard backend engineering project ideas&quot;, and since the model had my past context and history, it kept giving me a lot of ideas. Two of them showed up every single time:</p><ul><li>a distributed task queue</li><li>a distributed task orchestration system</li></ul><p>By then I had already built Redis, a shell, an HTTP server, an interpreter, and some parts of Git, all from scratch, as part of the CodeCrafters challenges. I&#39;m very fond of building things from scratch to understand them better, and I like taking on hard challenges. So building a task queue from scratch felt like the obvious next exercise.</p><p>It turned out to be one of the best decisions I&#39;ve made. I learned about concurrency, failure handling, a few core ideas of distributed systems, designing client-side APIs, transactions, and I did a hell of a lot of debugging along the way.</p><h3>What a task queue actually is</h3><p>A task queue is, well, a queue of tasks that need to be executed.</p><p>Why do we need one? Because not every piece of work needs to happen during the client&#39;s request. Some work can be done later, or on a schedule. For performance and a good user experience, anything that <em>can</em> run asynchronously <em>should</em>.</p><p>A few examples:</p><ul><li>sending a welcome email after sign up</li><li>processing images</li><li>converting an uploaded video into different resolutions (like YouTube does with 480p, 720p, and so on)</li></ul><p>The mental model is just the queue data structure you already know. Producers insert tasks at the back (enqueue), and workers take them out from the front when it&#39;s time to execute them.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/979/1*kX2YigGhWj45ympmIcDwbA.png" /><figcaption>Basic task queue</figcaption></figure><h3>The architecture and how a task moves through the system</h3><p>When I started this project, I had very little idea of what a task queue actually was. I hadn&#39;t used a real one in any of my projects either. Plenty of task queues are built on top of Redis or a message broker like Kafka, but I decided to do it all from scratch (I&#39;ll explain what &quot;all&quot; means later in this post).</p><p>A basic task queue needs these components:</p><ul><li><strong>Tasks:</strong> the actual units of work. Each task has a name (type) and a payload, and each type has a handler that knows how to execute it.</li><li><strong>Queue:</strong> where tasks are inserted, and where they wait until it&#39;s time to execute them. I used <strong>PostgreSQL</strong> as the queue.</li><li><strong>Workers:</strong> they take tasks out of the queue and run the matching handlers. In my implementation workers are simple goroutines, but they can be deployed separately too. This is also where most of the &quot;distributed&quot; part lives.</li></ul><p>Then there are the components that take it from a toy to something closer to production grade:</p><ul><li><strong>Reaper:</strong> a separate background process (a goroutine here) that finds tasks stuck on a dead worker and puts them back in the queue so they can run again.</li><li><strong>API server:</strong> we need a way to talk to the system: create tasks, list them, cancel them, retry them. My first version was only an HTTP server.</li><li><strong>Client library:</strong> the other way to use Dhara is to import it in your Go code and manage tasks with function calls. Ease of use wasn&#39;t my main reason for building it, though. It was about <strong>transactions</strong>, and it ended up changing the whole design. I&#39;ll get to that in the section on EnqueueTx.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*1JFwS0g0cFGRLaKFcQJq9g.png" /><figcaption>Architecture of Dhara</figcaption></figure><p>A task goes through a few states in its life:</p><ol><li>It&#39;s created as PENDING (via the API or the client library).</li><li>A worker claims it and it becomes RUNNING.</li><li>If the handler succeeds, it&#39;s COMPLETED.</li><li>If the handler fails (or the worker dies), it goes back to PENDING to be retried, until it runs out of attempts, and then it&#39;s DEAD.</li><li>A task can also be CANCELED through the API while it&#39;s pending or running.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*UHzTkasDIn063g1syueRgw.png" /><figcaption>Task Lifecycle</figcaption></figure><h3>PostgreSQL as the source of truth</h3><p>I used Postgres for two main reasons:</p><ol><li>I knew Postgres.</li><li>The way I designed the whole system, it solves a very real problem.</li></ol><p>Using PostgreSQL as the <em>only</em> queue was a deliberate decision. To understand the problem, imagine I had used Kafka instead. Take an e-commerce example. The typical flow would be:</p><ol><li>The client performs some business logic (a sign up, a product order).</li><li>The client saves the data in their own database in a transaction (user details, order details, and so on).</li><li>The client publishes a message to a Kafka topic like &quot;send confirmation email&quot;, which a consumer later picks up and turns into an actual email.</li></ol><p>See the problem? Steps 2 and 3 talk to two different systems, and there&#39;s no transaction that covers both. This is known as the <strong>dual write problem</strong>. When one of them fails, you get:</p><ul><li><strong>The database transaction fails, but the Kafka publish succeeds:</strong> the user gets an email for an order that doesn&#39;t exist.</li><li><strong>The database succeeds, but the Kafka publish fails:</strong> the order exists, but no email goes out, and the user is left wondering whether the order was even placed.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/751/1*68LlAXq79PRlp9akJRGGtw.png" /><figcaption>The dual write problem</figcaption></figure><p>This is the problem Postgres solves here. If the task is just a row in the <em>same</em> database as your business data, then inserting the task can be part of the <em>same transaction</em> as your business queries. Either both commit, or neither does. This pattern is usually called the <strong>transactional outbox</strong>, and Dhara basically bakes it into the queue itself.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/618/1*ImZgjeTzoPUPoXpniqv4kw.png" /><figcaption>Single Transaction</figcaption></figure><p>Of course there&#39;s a trade-off. Postgres isn&#39;t a purpose-built message broker, so it won&#39;t match Kafka&#39;s raw throughput. But for the vast majority of applications, correctness here matters way more than squeezing out the last bit of throughput.</p><h3>Atomic task claiming with FOR UPDATE SKIP LOCKED</h3><p>The next problem every task queue has to solve: when multiple workers are pulling from the same queue, <strong>how do you make sure a task isn&#39;t claimed concurrently by multiple worker?</strong></p><p>This is a serious problem. If two workers get the same task, that task runs twice, and you can imagine what happens when the task is &quot;charge the customer&quot;.</p><p>This is where pessimistic locking comes in, and the nice part is that I didn&#39;t need a separate lock service. Postgres gives it to us:</p><ul><li><strong>FOR UPDATE:</strong> locks the selected rows. If another transaction already holds the lock, it <em>blocks</em> until the lock is released, and then re-evaluates the row to make sure it still matches the query.</li><li><strong>SKIP LOCKED:</strong> this is the one I used (FOR UPDATE SKIP LOCKED). Instead of waiting, it simply <em>skips</em> the rows that are already locked.</li></ul><p>With plain FOR UPDATE, 20 workers would all line up behind the same row, waiting on each other. With SKIP LOCKED, each worker just grabs the next task that nobody else has touched. (The Postgres docs even call out queue-like tables as the use case for this.)</p><p>Here&#39;s a simplified version of what claiming looks like:</p><pre>UPDATE tasks<br>SET<br>    status = &#39;RUNNING&#39;,<br>    locked_by = $1,<br>    locked_at = now(),<br>    started_at = now(),<br>    attempts = attempts + 1,<br>    updated_at = now()<br>WHERE id = (<br>    SELECT id FROM tasks<br>    WHERE status = &#39;PENDING&#39; AND run_at &lt;= now()<br>    ORDER BY priority DESC, run_at ASC<br>    LIMIT 1<br>    FOR UPDATE SKIP LOCKED<br>)<br>RETURNING id, type, payload, attempts, max_retries, idempotency_key;</pre><p>Once a worker claims a task, another worker can&#39;t concurrently claim that same pending task. And a worker never sits waiting on a locked row; it just gets one of the tasks that isn&#39;t already taken.</p><h3>Worker concurrency, retries, and stale-task recovery</h3><h4>Workers</h4><p>Workers are goroutines: lightweight units of execution in Go, very cheap to start (even compared to a thread). Each worker is its own goroutine, and the loop looks like this:</p><ol><li>Try to claim a task.</li><li>If one is found, execute it, then immediately try to claim the next one.</li><li>If none is found, wait for the poll interval (1 second by default, configurable) and try again.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*EKlBD4W9j_C_S9mDr4NVNw.png" /><figcaption>Worker Loop</figcaption></figure><p>Note that this is a <strong>polling</strong> mechanism: every worker keeps asking the database &quot;anything for me?&quot;. Next on my list is a <strong>push</strong> mechanism using Postgres LISTEN/NOTIFY, which is another reason I picked Postgres over other databases.</p><h4>Retries</h4><p>In distributed systems you can&#39;t avoid failures, so you design the system to keep working even when things fail. In Dhara there are a few mechanisms for that.</p><p>When a task fails for any reason (the handler returned an error, the worker crashed, a database or network call failed), it gets retried. Each time a worker claims a task, the attempt count goes up, and the task can be retried until it hits the max number of attempts (configurable).</p><p>Retries use <strong>exponential backoff with full jitter</strong>. The backoff gives a struggling downstream service some breathing room, and the jitter randomizes <em>when</em> each retry fires, so a thousand failed tasks don&#39;t all come back at the exact same second (the &quot;thundering herd&quot; problem). When a task runs out of attempts, it goes to the DEAD state, and you can manually retry it through the API.</p><h4>Heartbeats and the reaper</h4><p>What if the worker doesn&#39;t fail gracefully, and just dies in the middle of a task? Nothing returns an error. The task just sits in RUNNING forever.</p><p>That&#39;s where heartbeats come in. While a handler is running, a background goroutine periodically sets locked_at and updated_at to now() for that task (matched by task id and worker id). It&#39;s basically the worker saying &quot;still alive, still working on it&quot;.</p><p>If the worker dies, the heartbeat stops. Then the <strong>reaper</strong>, which scans on an interval, looks for RUNNING tasks that haven&#39;t had a heartbeat within the stuck threshold. It puts those tasks back to PENDING so another worker can claim them, or moves them to DEAD if they&#39;re out of attempts.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*QSRB23O6yfXDvf-cBLX7fg.png" /><figcaption>Heartbeat and Reaper</figcaption></figure><p>One important consequence: Dhara gives <strong>at-least-once</strong> execution. A worker could do half of the work (say, send the email) and die before marking the task as done. The reaper will requeue it, and it will run again. So handlers should be <strong>idempotent</strong>, meaning running them twice should be safe. This is also why I added idempotency keys at enqueue time, so the same enqueue request replayed twice doesn&#39;t create two tasks.</p><h4>Graceful shutdown</h4><p>When Dhara receives SIGINT or SIGTERM, workers stop claiming new tasks and give in-flight tasks a configurable amount of time to finish. After that, the connection pool is drained. Without this, every deploy would kill running tasks mid-way and leave the reaper to clean up the mess.</p><h3>What “from scratch” actually meant</h3><p>Earlier I said I decided to do it all from scratch. Here is what I meant.</p><p>Dhara has only three dependencies:</p><ul><li>pgx, the PostgreSQL driver</li><li>google/uuid, for generating UUIDs</li><li>vow, my own database migration runner</li></ul><p>Everything else is the Go standard library. The HTTP API runs on net/http, so there is no web framework or router. Logging uses slog. The Prometheus metrics endpoint is also written by hand, without the official client library. The format is just plain text: a couple of comment lines describing each metric, then a line with the metric name and its current value. Counters like tasks_enqueued_total and gauges like tasks_by_status are only a few lines each.</p><p>The migration runner is the best example of this. Dhara needed a way to set up its database tables, and instead of picking an existing tool, I built one. It started as a small part of Dhara and grew into a project of its own: <a href="https://github.com/Md-Talim/vow">Vow</a>. It runs your SQL files in order, uses PostgreSQL advisory locks so two instances of a service can’t migrate at the same time, and refuses to run if an already applied migration was renamed or deleted. Dhara’s migrations run through Vow. I’ll write about what I learned about database migrations in a separate post.</p><p>I’m not saying you should build everything yourself. I didn’t write a Postgres driver or a UUID generator. I just built the parts I was curious about, and used libraries for the rest.</p><h3>Benchmarking and what the results taught me</h3><p>I’d seen people use throughput and latency numbers as evidence that a backend project was serious.</p><p>I didn’t know how to benchmark a system like this, so I took some help from AI to set up <a href="https://k6.io/">k6</a> load tests against the HTTP API. The important part is that I didn’t just trust HTTP response codes. I used Postgres as the source of truth for what <em>actually</em> happened to each task.</p><p><strong>Setup:</strong> 20 workers, a handler that simulates 50–200ms of I/O, a laptop with an i3 (11th gen) / 8GB RAM / 500GB SSD, and a max of 25 database connections.</p><h4>Finding a real bottleneck</h4><p>Before running anything, I did the math. 20 workers, each finishing a task in ~125ms on average, should give roughly <strong>160 tasks/sec</strong>.</p><p>The first measured result: <strong>~20 tasks/sec</strong>.</p><p>That’s 8x lower than expected, so something was wrong. The cause was in my claim loop. A worker only attempted <em>one</em> claim per poll tick, no matter how quickly the task finished:</p><pre>select {<br>case &lt;-ticker.C:<br>    processNext(ctx)<br>}</pre><p>So 20 workers × 1 claim per second (the 1s poll interval) = 20 tasks/sec. The math matched the measurement almost exactly. A worker would finish a 100ms task and then sit idle for the remaining 900ms.</p><p>The fix: keep claiming continuously while there’s work available, and fall back to the poll interval only when the queue is empty. After the fix: <strong>~148 tasks/sec</strong>, within a few percent of my original prediction.</p><h4>Results</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/654/1*Lv1jhsPYcxGdy92XGboaIQ.png" /></figure><p>Latency here is end-to-end (completed_at - created_at), not just how long the HTTP enqueue took.</p><h4>What this taught me</h4><ol><li><strong>Measure the thing that matters, not the thing that’s easy to measure.</strong> Enqueue latency stayed under 10ms (p99) in every run, even the one that was bottlenecked at 20 tasks/sec. If I’d only looked at HTTP response times, I would have thought everything was fine. I only caught the bug by checking task state in Postgres.</li><li><strong>Predict before you measure.</strong> Having a number in my head (~160/sec) is the only reason I knew 20/sec was wrong. Without a prediction, I might have just accepted it.</li><li><strong>Saturation is not failure.</strong> At ~148 tasks/sec the latency jumps, but that’s queueing delay from running at the edge of worker capacity, not broken correctness. Every run completed 100% of tasks. I also ran a burst test that deliberately oversubmitted (120 tasks/sec against the then-20/sec ceiling), and once workers caught up, the system fully drained a 5,800-task backlog with zero loss.</li></ol><p>To be clear, I’m not claiming 148 tasks/sec is fast. It’s bounded by 20 workers and the handler’s duration, on a laptop, with a simulated handler. What matters to me is that the measured number matched the prediction, and that no task was lost. You can reproduce everything with the scripts in the <a href="https://github.com/Md-Talim/dhara/tree/main/benchmarks">benchmarks</a> folder, including full methodology in RESULTS.md.</p><h3>The decisions that changed my implementation</h3><h4>The poll loop</h4><p>That’s the bug above. Benchmarks changed my worker loop, and it’s a good reminder that you don’t know how your concurrent code behaves until you load it.</p><h4>Building the client library, and why EnqueueTx exists</h4><p>My first version of Dhara only had an HTTP server. You POST /api/v1/tasks and the task gets created. Simple, language-agnostic, works.</p><p>But remember the whole reason I chose Postgres: the task insert should be atomic with the business writes. With an HTTP API, that’s impossible. Your application writes the order in <em>its</em> transaction, then makes an HTTP call, which inserts the task in <em>another</em> transaction on another connection. There’s no way to put both under one commit. If your app crashes between the two, you’re right back to the dual write problem I was trying to escape.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/888/1*iroAUwWL-JOZcvVv5Ww82g.png" /><figcaption>HTTP vs EnqueueTx</figcaption></figure><p>So I built a client library, and the key function is EnqueueTx. It takes <em>your</em> transaction:</p><pre>tx, _ := pool.Begin(ctx)<br><br>// your business logic<br>tx.Exec(ctx, `INSERT INTO orders (id, total) VALUES ($1, $2)`, orderID, 42.00)<br>// the task is committed only if the order is<br>res, err := client.EnqueueTx(ctx, tx, &quot;send_email&quot;, EmailPayload{<br>    To:      &quot;user@example.com&quot;,<br>    Subject: &quot;Order #&quot; + orderID,<br>})<br>tx.Commit(ctx)</pre><p>Roll back the transaction and the task never existed. Commit it and both are there, atomically.</p><p>Two details I’m happy with:</p><ul><li><strong>Idempotent enqueue without poisoning your transaction.</strong> Enqueue uses INSERT ... ON CONFLICT DO NOTHING with an idempotency key. In Postgres, a failed statement aborts the entire transaction, so if a duplicate insert raised an error, it would take down the caller&#39;s whole transaction. Instead, a replay quietly returns the existing task, with Duplicate: true.</li><li><strong>One code path.</strong> The HTTP server and the worker binaries are now thin wrappers built from the library. They can’t drift from it, because they <em>are</em> it.</li></ul><h3>What I’d build next</h3><p>This project got me really interested in distributed systems, and in the finer details of concurrency and handling failures. So I’m going deeper: I’m taking MIT’s distributed systems course, reading the papers, going through the lectures, and implementing the labs.</p><p>The labs mainly come down to three things: MapReduce, a replicated and sharded key/value store, and Raft. I’m focusing on these for now, and the KV store and Raft will be my next flagship projects.</p><p>I should be honest about one thing: in Dhara, the workers scale out horizontally, but PostgreSQL itself is still a single point of failure unless you run it with replication and failover. Understanding how machines agree on shared state, even when some of them fail, is a big part of why I want to go through Raft properly.</p><p>For Dhara itself, the roadmap is:</p><ul><li>replacing constant polling with LISTEN/NOTIFY, so workers get pushed new tasks instead of hitting the database every second</li><li>better dead-letter handling</li><li>execution histograms and queue latency metrics</li><li>rich operational dashboards</li></ul><p>This project will keep evolving.</p><h3>Terms and Concepts I had to look up and learn</h3><p>Some of these I had never heard of before this project, and some I only knew by name. This is the list of terms I had to look up and properly understand while building Dhara.</p><ul><li><strong>Dual write problem:</strong> when you write to two separate systems (like a database and Kafka) and there is no single transaction covering both, so one can succeed while the other fails.</li><li><strong>Transactional outbox:</strong> the fix for the dual write problem. You save the message or task in the same database transaction as your business data, so both happen or neither does.</li><li><strong>Idempotency:</strong> doing the same operation twice has the same result as doing it once.</li><li><strong>At-least-once delivery:</strong> a task is guaranteed to run at least one time, but it might run more than once.</li><li><strong>Pessimistic locking:</strong> locking a row before you work on it, so nobody else can touch it in the meantime.</li><li><strong>FOR UPDATE:</strong> the Postgres clause that locks the rows you select. Other transactions have to wait for the lock to be released.</li><li><strong>FOR UPDATE SKIP LOCKED:</strong> the same, but instead of waiting, it skips the locked rows. This is what lets many workers pull from one queue safely.</li><li><strong>Polling vs pushing:</strong> asking “anything new?” again and again, versus being told when something new arrives.</li><li><strong>LISTEN/NOTIFY:</strong> the Postgres feature that lets the database push a notification to listeners. This is my next step for replacing polling.</li><li><strong>Heartbeat:</strong> a small signal a worker sends regularly to say “I’m still alive”. When the signals stop, something is wrong.</li><li><strong>Reaper:</strong> the background process that finds tasks stuck on dead workers and puts them back in the queue.</li><li><strong>Exponential backoff and jitter:</strong> waiting longer after each failed attempt, with a bit of randomness added to the wait.</li><li><strong>Thundering herd:</strong> many clients all retrying at the exact same moment and overloading a system that was already struggling.</li><li><strong>Dead-letter queue:</strong> a place for tasks that failed too many times, so a human can look at them. In Dhara this is the DEAD state.</li><li><strong>Advisory locks:</strong> Postgres locks that are not tied to a row. I used them in Vow so only one instance runs migrations at a time.</li><li><strong>Percentile latency (p50, p95, p99):</strong> the time within which 50%, 95%, or 99% of requests finish. It shows you what the slow cases look like, which an average hides.</li></ul><p>If you’ve read this far, thank you. The code is on GitHub at <a href="https://github.com/Md-Talim/dhara"><strong>Md-Talim/dhara</strong></a>. If you spot a flaw in the design, I’d genuinely love to hear about it. I’m sharing all of this as part of my learning journey, so follow along for what’s next.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=42b705503737" width="1" height="1" alt=""><hr><p><a href="https://blog.stackademic.com/i-built-a-distributed-task-queue-from-scratch-with-go-and-postgresql-42b705503737">I Built a Distributed Task Queue from Scratch with Go and PostgreSQL</a> was originally published in <a href="https://blog.stackademic.com/">Stackademic</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How visually hiding content using CSS clipping can make your website more accessible]]></title>
            <link>https://medium.com/@md-talim/how-visually-hiding-content-using-css-clipping-can-make-your-website-more-accessible-fb0bdb68ab07?source=rss-6ed67f4e21c7------2</link>
            <guid isPermaLink="false">https://medium.com/p/fb0bdb68ab07</guid>
            <category><![CDATA[accessibility]]></category>
            <category><![CDATA[css]]></category>
            <category><![CDATA[beginner]]></category>
            <category><![CDATA[web-development]]></category>
            <category><![CDATA[front-end-development]]></category>
            <dc:creator><![CDATA[Mohammad Talim]]></dc:creator>
            <pubDate>Tue, 24 Oct 2023 04:10:33 GMT</pubDate>
            <atom:updated>2023-10-24T04:10:33.791Z</atom:updated>
            <content:encoded><![CDATA[<h4>How visually hiding content using CSS clipping can make your website more accessible</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*COGlSXyjVhETfyI70EccGQ.png" /></figure><h3>What is CSS Clipping?</h3><p>Simply put, CSS clipping allows you to hide parts of an element. You can define a rectangle that acts as a mask. Anything outside that mask gets clipped or hidden.</p><p>The clip property lets you specify the coordinates of the clipping rectangle. The coordinates are relative to the element’s top-left corner. For example:</p><pre>clip: rect(10px 20px 30px 40px);</pre><p>This hides everything except a rectangle with a top edge 10px down, a right edge 20px across, a bottom edge 30px down, and a left edge 40px across.<br> To hide the entire element, set clip: react(0 0 0 0) This creates a zero-size rectangle that hides everything.</p><h3><strong>Why Hide Elements?</strong></h3><p>There are many times you may want to hide something visually but keep it for screen readers.</p><p><strong>For example:</strong></p><ul><li>Provide text alternatives for images, icons, or unclear buttons.</li><li>Give extra instructions for the screen reader users.</li></ul><p>CSS clipping hides content from sighted users but leaves it available for assistive technologies</p><p><strong>Example:<br></strong>Here is HTML and CSS to visually hide an element.</p><pre>&lt;div class=&quot;user-offline&quot;&gt;<br>  John &lt;span class=&quot;visually-hidden&quot;&gt;(offline)&lt;/span&gt;<br>&lt;/div&gt;<br>&lt;div class=&quot;user-online&quot;&gt;<br>  Kyle &lt;span class=&quot;visually-hidden&quot;&gt;(online)&lt;/span&gt;<br>&lt;/div&gt;</pre><pre>.visually-hidden {<br>  position: absolute; <br>  clip: rect(0 0 0 0);<br>  width: 1px; <br>  height: 1px;<br>  overflow: hidden;<br>}</pre><p>The visually-hidden class applies the clipping and other CSS to hide elements.</p><ul><li>position: absolute removes it from the document flow</li><li>clip: react(0 0 0 0) hides the entire element</li><li>width: 1px; height: 1px makes it take up minimal space</li><li>overflow: hidden hides any overflowing content</li></ul><p>Screen readers can still read the hidden text.</p><h3>Summary</h3><ul><li>Use CSS clipping to hide elements visually but keep them for screen readers</li><li>Set clip: react(0 0 0 0) to hide the entire element</li><li>Combine with other properties like position and overflow</li><li>Useful for providing text alternatives or extra instructions</li></ul><p>I hope this simple guide helps explain CSS clipping to visually hide elements. Let me know, if you’re still confused or have any other queries.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=fb0bdb68ab07" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>