There is an official nixpkgs#surrealdb. It works. It builds the entire Rust codebase from source. Every dependency, every crate, the full database engine — all of it compiled on your machine.
For SurrealDB, that means an hour or more of CPU time. To get a CLI binary you could download in seconds. And there is no Cachix cache for it either — no prebuilt binary waiting on a cache server to skip the build. You compile it yourself, every time.
I put up with this for years. I wrote about the pain of running SurrealDB on NixOS before — the friction is real. Every time I needed a specific version of surreal, I’d either wait for the build or work around Nix entirely. Eventually I asked myself: how hard can it be to just wrap the precompiled binary?
Turns out, not hard at all.
The edge
The compile time is annoying. But the actual problem that pushed me over the edge is version compatibility.
SurrealDB exports and imports are version-sensitive. If you run surreal import with a CLI version that doesn’t match the database instance, you get partial imports. Or silent data corruption. Or nothing at all — just an error and a half-migrated dataset.
This means you need the exact right version of the CLI for every database you touch. Not “latest.” Not “close enough.” The exact version.
With the official nixpkg, you get whatever version nixpkgs currently pins. One version. Want an older one? Good luck pinning a specific nixpkgs commit, waiting an hour for it to build, and hoping the derivation still works.
The flake
A Nix flake that packages every stable SurrealDB release as a precompiled binary.
You can run any version directly:
nix run github:dariuscorvus/surrealdb-nix#surreal-2.1.0Install it to your profile:
nix profile install github:dariuscorvus/surrealdb-nix#surreal-2.1.0Or use it in your NixOS configuration like you would any other package.
No compilation. No waiting. Just the binary, wrapped in a proper Nix derivation with all the right metadata.
The URL trick
SurrealDB doesn’t advertise a public download URL pattern in their docs. What they do provide is install.surrealdb.com — a shell script you curl and pipe into bash. The classic “just trust us” installer.
I didn’t want to run their script. I wanted the URL. So I bisected it.
The install script does a lot — OS detection, CPU detection, version resolution, file placement. But buried in all of that is the one thing I actually needed: the URL pattern.
https://download.surrealdb.com/v${VERSION}/surreal-v${VERSION}.${ARCH}.tgzWhere ARCH is one of linux-amd64, linux-arm64, darwin-amd64, darwin-arm64. That’s it. A predictable URL for every version and platform combination.
Once I had that, the rest was mechanical. The update script hits the GitHub releases API for all stable SurrealDB versions, downloads each tarball, hashes it, and writes the result into versions.json. The flake reads that file and builds a derivation for each version using fetchurl with the known hash.
No install script. No curl-pipe-bash. Just a direct download with a verified hash — which is exactly how Nix is supposed to work.
The philosophy
The official nixpkg builds from source because that’s the Nix way. Source builds are reproducible, auditable, and trustworthy. That philosophy is correct — in general.
But for a CLI tool where you need five different versions pinned across projects, and each one takes an hour to compile, the philosophy breaks down. You don’t need to audit the SurrealDB source on every version bump. You need surreal import to work with the right version right now.
Wrapping a precompiled binary in a Nix derivation is trivially simple. Fetch the tarball, unpack it, put the binary in $out/bin. That’s it. The hard part was not the packaging — it was deciding that the “proper” approach wasn’t worth the cost.
When to use this
- You work with multiple SurrealDB versions across projects
- You need to match CLI and instance versions for safe imports/exports
- You don’t want to wait an hour for a build you’ll use for five minutes
- You’re on NixOS or use Nix for dev environments and want SurrealDB to just work
If you only ever use the latest version and don’t mind the compile time, the official nixpkg is fine. This flake exists for everyone else.
The code is at github.com/dariuscorvus/surrealdb-nix.