Atomic Config Writes in Go: Why renameio Beats Plain OverwritesNote · digest for October 30
Infographic patent-style blueprint showing atomic file writes in Go using a temporary file and the POSIX rename syscall to prevent O_TRUNC race conditions.
Note3 sections≈ 4 min

Atomic Config Writes in Go: Why renameio Beats Plain Overwrites

Imagine a routine task: your Go service periodically writes updated configuration or auth tokens to disk, while a background daemon (say, Envoy or a metrics agent) watches the file with inotify and reloads it on change. In Go's standard library, your fingers naturally reach for the familiar one-liner:

err := os.WriteFile("/etc/app/config.json", data, 0644)

It looks clean and harmless. Then one day in production, an inexplicable failure hits: the background daemon crashes with unexpected end of JSON input. You SSH into the box and open the file—and the JSON is completely valid. You've just caught a classic filesystem truncate race condition.

The O_TRUNC Trap: Why a File Briefly Turns Empty

Under the hood, os.WriteFile issues an open syscall with the flags os.O_WRONLY | os.O_CREATE | os.O_TRUNC.

That's where the trap snaps shut:

  1. The Linux O_TRUNC flag immediately zeroes out the existing file's length the moment the descriptor is opened.
  2. Only after that does the Go runtime begin copying the new bytes from memory into the filesystem buffer.
  3. Finally, it closes the descriptor with close.

If a concurrent goroutine or an external daemon reads the file during that microscopic gap, it sees a 0-byte empty file or a half-written JSON payload. Any parser will choke on it.

How renameio Works: Atomicity via POSIX rename

To guarantee that readers always see either the complete old file or the complete new file, you need atomic replacement. In the Go ecosystem, the gold-standard library for this is Google's renameio and its second major version, renameio/v2.

The library follows a strict sequence:

  1. Creates a temporary file in the same directory as the target file.
  2. Writes the new payload into that temporary file.
  3. Calls fsync to flush memory buffers down to the physical drive.
  4. Issues an atomic rename(2) syscall. The Linux kernel simply swaps the directory entry to point to the new inode, leaving zero intermediate state for other processes to observe.
  5. Automatically cleans up the temporary file if anything fails along the way.

In our look at testing files in Go without temporary directories via fstest.MapFS, we focused on keeping tests isolated. Real disk isolation in production relies on this exact kind of atomicity.

Here is how a safe write looks with renameio/v2:

package main

import (
    "log"
    "github.com/google/renameio/v2"
)

func updateConfig(filePath string, payload []byte) error {
    // Atomically overwrite the file while respecting the process umask
    if err := renameio.WriteFile(filePath, payload, 0644); err != nil {
        log.Printf("Сбой атомарного обновления: %v", err)
        return err
    }
    return nil
}

For streaming larger payloads, renameio/v2 also provides PendingFile:

t, err := renameio.TempFile("", "/etc/app/config.json")
if err != nil {
    return err
}
defer t.Cleanup()

if _, err := t.Write(payload); err != nil {
    return err
}
return t.CloseAtomicallyReplace()

What Changed in v2 and Where Atomicity Ends

The main difference between renameio/v2 and v1 is proper handling of the system umask. Version 1's WriteFile forced exact permissions, whereas v2 applies umask just like os.WriteFile does. If you actually want the old behavior, pass the renameio.IgnoreUmask() option.

Atomicity Boundaries and Different Filesystems

The rename syscall is only guaranteed to be atomic within a single mounted filesystem. If your temp file lives in /tmp and your target lives on a separate volume at /var/data, rename will fail with EXDEV. Always keep the temporary file next to the target.

Against application-level race conditions and half-written configs in production, pairing a same-directory temp file with renameio/v2 is rock solid.

Want a deep diveVotes help us choose what to break down in detail. This material has 0 votes.
Sources · 2