I'm embarking on a pretty ambitious project, and I've decided to build it in public and share the journey with all of you. I'm building VrootKV: a high-performance, transactional key-value storage engine from scratch in modern C++.

This blog series will be my build log, documenting the entire process from the lowest-level file I/O all the way up to complex multi-version concurrency control (MVCC). I'll be sharing my design decisions, the code, the tests, and the lessons I learn along the way.

So, where do you start when building a database? Before we can write a single byte of data, we need to decide how we're going to talk to the disk. It might be tempting to just sprinkle std::ofstream or fopen calls throughout the codebase, but for a serious system like this, that's a recipe for disaster. We need to start with a solid, clean foundation.

That foundation is the I/O Abstraction Layer.

Why Bother Abstracting the Filesystem?

At first glance, creating a whole layer just to read and write files might seem like over-engineering. Why not just use the standard library or OS-level file APIs directly? It comes down to three critical principles for systems programming that save you from a world of pain later on :

1. Testability: How do you unit test logic that writes to disk? You don't want your tests to be constantly creating and deleting real files. That makes them slow, flaky, and dependent on the host machine's state. By abstracting file operations behind an interface, we can easily create a "mock" file manager in our tests that simulates disk behavior entirely in memory. This makes our unit tests fast, reliable, and perfectly isolated.

2. Portability: The core logic of a storage engine shouldn't be tied to a specific operating system. While I'm developing on macOS, I want VrootKV to compile and run on Linux and Windows without changing a single line of the database's core logic. An abstraction layer allows us to hide the platform-specific details (open/write on POSIX vs. CreateFileW/WriteFile on Windows) behind a common, clean API.

3. Clarity and Intent: A well-defined interface clearly communicates the exact requirements the storage engine has for the filesystem. It forms a contract. We don't just need to "write bytes"; we need to guarantee those bytes are durably persisted. This is a crucial distinction for a database, and our interface should make that intent explicit with methods like Sync().

Designing the I/O Interfaces

With those goals in mind, I created a set of C++ interfaces that define the contract for all file system interactions in VrootKV. The entire public API is defined in file_manager.h. Let's walk through it piece by piece.

First, we need a contract for a file we can write to.

// From: include/VrootKV/io/file_manager.h

class IWritableFile {
public:
    virtual ~IWritableFile() = default;

    virtual bool Write(std::string_view data) = 0;
    virtual bool Flush() = 0;
    virtual bool Sync() = 0;
    virtual bool Close() = 0;
};

The most important methods here are Flush() and Sync(). They look similar but represent very different guarantees. Flush() typically just tells the operating system to move data from the application's buffer to the OS's buffer. Sync(), on the other hand, is a much stronger promise. It requests that the OS physically write the data to the storage device itself. For a database's Write-Ahead Log (WAL), Sync() is the operation that actually provides durability.

Next, the interface for reading files is simpler, as it's primarily concerned with getting sequential data.

// From: include/VrootKV/io/file_manager.h

class IReadableFile {
public:
    virtual ~IReadableFile() = default;
    virtual size_t Read(size_t n, std::string* result) = 0;
    virtual bool Close() = 0;
};

Finally, the IFileManager interface ties everything together. It acts as a factory for creating file objects and also handles path-level operations like checking for existence, deleting, and renaming.

// From: include/VrootKV/io/file_manager.h

class IFileManager {
public:
    virtual ~IFileManager() = default;

    virtual bool NewWritableFile(const std::string& fname, std::unique_ptr<IWritableFile>& result) = 0;
    virtual bool NewReadableFile(const std::string& fname, std::unique_ptr<IReadableFile>& result) = 0;
    virtual bool FileExists(const std::string& fname) const = 0;
    virtual bool DeleteFile(const std::string& fname) = 0;
    virtual bool RenameFile(const std::string& src, const std::string& target) = 0;
};

Notice the use of std::unique_ptr. This is a modern C++ feature that ensures the file objects are automatically cleaned up when they go out of scope, preventing resource leaks without manual memory management.

The Implementation: Hiding the Messy Details

With the interfaces defined, the implementation in file_manager.cpp can now hide all the platform-specific ugliness. I'm using C++17 std::filesystem for path operations (like exists, rename) as it's now standard and cross-platform. For the actual file I/O, I use preprocessor directives (#ifdef _WIN32) to switch between POSIX and Win32 APIs.

This is where the abstraction pays off. For example, look at the POSIX implementation of Write(). It's not a simple one-liner. It has to be in a loop to handle "partial writes" (where the OS doesn't write all the data you requested at once) and it has to correctly handle being interrupted by a system signal (EINTR).

// Snippet from: src/io/file_manager.cpp

bool PosixWritableFile::Write(std::string_view data) {
    if (fd_ == -1) return false;

    const char* p = data.data();
    size_t remaining = data.size();

    while (remaining > 0) {
        ssize_t n = ::write(fd_, p, remaining);
        if (n < 0) {
            if (errno == EINTR) continue; // Retry write
            return false;
        }
        //... handle partial write...
        p += static_cast<size_t>(n);
        remaining -= static_cast<size_t>(n);
    }
    return true;
}

This is exactly the kind of complex, error-prone logic we want to write once, test thoroughly, and then hide behind our clean IWritableFile interface. The rest of the storage engine will never have to worry about these details.

You can see the full cross-platform implementation in the source file on GitHub: src/io/file_manager.cpp.

Verification: Proving It Works

An abstraction layer is useless if it's not reliable. Rigorous unit testing is non-negotiable for a foundational component like this. Using the Google Test framework, I set up a test fixture that creates a unique temporary directory for each test case, ensuring a clean, isolated environment every time.

The tests cover every aspect of the interface. A key test is WriteAndSyncFile, which validates that data written through the interface is actually persisted durably to disk.

// Snippet from: tests/io/test_file_manager.cpp

TEST_F(FileManagerTest, WriteAndSyncFile) {
    const std::string filename = TestPath("test_write.txt");
    std::unique_ptr<IWritableFile> writable_file;

    // Create/truncate the file for writing.
    ASSERT_TRUE(file_manager_->NewWritableFile(filename, writable_file));

    const std::string data1 = "Hello, ";
    const std::string data2 = "World!";

    EXPECT_TRUE(writable_file->Write(data1));
    EXPECT_TRUE(writable_file->Write(data2));

    // Sync ensures durability beyond the OS page cache.
    EXPECT_TRUE(writable_file->Sync());
    EXPECT_TRUE(writable_file->Close());

    // Verify the file content matches concatenated writes.
    std::ifstream ifs(filename);
    std::stringstream buffer;
    buffer << ifs.rdbuf();
    EXPECT_EQ(buffer.str(), data1 + data2);
}

This test writes some data, calls Sync(), and then reads the file back using standard library tools to verify the contents are exactly as expected. This confirms our core contract of durability.

The full test suite covers many other cases, including chunked reads, error conditions, and file management operations. You can explore it here: tests/io/test_file_manager.cpp.

Conclusion and What's Next

And there we have it! The very first component of VrootKV is complete. We now have a robust, cross-platform, and thoroughly tested I/O abstraction layer. This solid foundation will make everything we build on top of it cleaner and more reliable.

In the next post, we'll use this IFileManager to start defining and implementing the on-disk formats for our Write-Ahead Log (WAL) and SSTables. That's where things start to get really interesting.

Thanks for reading! You can find the full, up-to-date source code for the project on my GitHub. Feel free to star the project, open issues, or leave any questions or feedback in the comments below!

GitHub Repo: https://github.com/dreamvrutik/VrootKV

LinkedIn: https://www.linkedin.com/in/vrutik-halani

#cpp #database #systemdesign #buildinpublic #vrootkv #programming #backend #datastructures