DEV Community: Eitamos Ring

Why Regex Sucks in a Hot Loop

Eitamos Ring — Wed, 17 Jun 2026 13:41:49 +0000

A while back I ripped a regex out of my SQL parser and replaced it with twenty lines of hand-written string scanning. Then I got nervous. Hand-rolling a scanner because you assume regex is slow is exactly the kind of premature optimization I make fun of other people for. So I filed an issue against myself: prove the hand-rolled version is actually faster, or delete it and go back to the regex.

Months later I sat down to settle it. The honest regex came back about ninety times slower. And the reason had nothing to do with raw matching speed.

What the code does

The function answers one small question: does a specific table alias appear in this piece of SQL, followed by a dot? That's how the parser notices a subquery reaching out to an outer table, like o.id pointing at an orders o defined outside it.

func containsWordDot(text, word string) bool {
    if word == "" {
        return false
    }
    needle := word + "."
    idx := 0
    for {
        pos := strings.Index(text[idx:], needle)
        if pos < 0 {
            return false
        }
        absPos := idx + pos
        // the char before the alias must not be part of a longer identifier,
        // so alias "a" doesn't match "data."
        if absPos > 0 {
            prev := rune(text[absPos-1])
            if unicode.IsLetter(prev) || unicode.IsDigit(prev) || prev == '_' {
                idx = absPos + 1
                continue
            }
        }
        return true
    }
}

It's not pretty. The boundary check is the only reason it exists, because a plain strings.Contains would happily match a. inside data. and invent a correlation that was never there.

The case for going back to regex

My own argument against the code was simple. Go's regex engine is RE2: deterministic, no catastrophic backtracking, genuinely fast. Compile one pattern once at startup and reuse it everywhere:

var wordDotPattern = regexp.MustCompile(`\b\w+\.\w+`)

Less code. No manual boundary handling to get wrong. If it benchmarked even close to the hand-rolled version, deleting twenty fiddly lines was the right move. I expected to delete them.

Where the plan fell apart

That regex matches any word-dot-word. My function answers a narrower question: does this specific alias appear? And the alias is different on every call, because the parser walks every table in the query and asks about each one in turn.

So the precompiled pattern can't replace the function. It's answering a question nobody asked. The only regex that does the same job has to bake the specific alias into the pattern, which means compiling a fresh regex every single call:

regexp.MustCompile(`\b` + regexp.QuoteMeta(word) + `\.`).MatchString(text)

That line is the whole story. You can't compile a pattern once when the pattern changes every time you run it. "Compile once, reuse forever" quietly dies the moment you notice the thing it depends on isn't a constant. And compiling a regex is not cheap. Doing it in a loop, once per table per query, is a bill you pay on every parse for the rest of the program's life.

The numbers

I ran the matrix I'd written into the issue: short input (~20 bytes), medium (~200), long (~2000), each as a match, a miss, and a near-miss. Ten runs each, medians:

input        scanner      regex (compiled per call)
short/miss     21 ns          1,972 ns
short/hit      24 ns          1,990 ns
medium/hit    195 ns          6,252 ns
long/hit    1,566 ns         46,600 ns

Six to ninety times slower depending on size, and the scanner did it with zero allocations while the regex allocated on every call.

For a sanity check I also benchmarked the precompiled regex, the one that can't actually do the job. The scanner still won at every size, because strings.Index is SIMD-accelerated and allocates nothing, while even a warm MatchString carries per-call overhead. There was no input length where regex caught up. No crossover at all.

So does regex suck?

Not really.
The title is a little unfair, and I'll own that, I needed to catch your eye a bit :)

Regex is the right tool sometimes, and a state machine I wrote by hand is often the thing that deserves to be deleted

What actually sucks is reaching for regex without noticing that your pattern isn't constant.
The cost of a regex is split in two: compiling it, and matching with it. Everyone remembers matching is fast.

People forget compiling is the expensive half, and that you only get to skip it when the pattern is fixed. Put a per-call variable in the pattern and you've moved the expensive half into your hot path without realizing it.

The benchmark earned its place, but not the way I thought it would. It didn't just tell me which option was faster. Forcing myself to write the genuinely equivalent regex is what revealed there was no equivalent precompiled regex in the first place. Making the comparison fair was where the real answer was hiding.

I kept the twenty lines and left the benchmark numbers in a comment on top, so the next person who thinks "this should just be a regex" can read the receipts instead of arguing with me about it. Which is exactly what past-me wanted when I filed the issue.

Measure the thing you'd actually ship. Not the thing that's easy to type into a benchmark.

This came out of issue #59 on postgresparser, a pure-Go PostgreSQL parser I work on. The full benchmark and verdict live in the issue.

Parse, Don’t Guess

Eitamos Ring — Thu, 11 Jun 2026 22:24:01 +0000

Three days before going open source, I deleted my parser's smartest feature.

333 lines. 6 functions. 12 passing tests. All green, all clever, all gone.

The feature worked. That was the problem.

The feature that knew too much

My PostgreSQL parser (valk-postgres-parser) extracts structure from SQL text: tables, columns, joins, filters. One of its analysis functions did something more ambitious. Give it a query like this:

SELECT * FROM orders o
JOIN customers c ON o.customer_id = c.id

and it would tell you the foreign key relationship: orders.customer_id is a child pointing at parent customers.id.

No schema. No catalog access. Just the query text. It felt like magic, and users love magic.

Here is how the magic worked:

func isForeignKeyColumn(column, targetTable string) bool {
    // ...
    if strings.HasSuffix(column, "_id") {
        prefix := strings.TrimSuffix(column, "_id")
        if strings.HasPrefix(targetTable, prefix) {
            return true
        }
        // Also check if table contains the prefix (handles prefixed
        // tables like fk_customers). This allows customer_id to match
        // fk_customers, e2e_customers, etc.
        // ...

Naming conventions. customer_id next to a table called customers? Must be a foreign key. Ship it.

The comment that aged badly

The real problem was further down, in the fallback. What happens when neither column matches a naming pattern? The function did this:

// If we can't determine from FK naming conventions, return a default
// relationship based on table order (left table = parent by convention
// in SQL JOINs). This is still a heuristic but is consistent with how
// JOINs are typically written.
return &JoinRelationship{
    ChildTable:  rightTable,
    ParentTable: leftTable,
    // ...
}

Read that again. When the function had no idea, it did not say "I have no idea." It returned an answer anyway, based on which table appeared first in the query.

Every JOIN got an answer. That was the bug. Not a crash, not a parse error. A function that is sometimes right, sometimes wrong, and gives the caller no way to tell which.

Wrong is worse than empty

Think about what downstream code does with a foreign key relationship. In our case it generated test data: parent rows first, then children referencing them. Flip parent and child and you get foreign key violations, or worse, data that inserts fine but means the wrong thing.

An empty result fails loudly. The caller sees nothing came back and handles it. A wrong result fails quietly, three layers up, a week later, in a system that trusted the library.

And the heuristic had plenty of ways to be wrong:

customer_id happily matched tables named fk_customers and e2e_customers, because of a prefix check added for one test environment
Self-referencing tables (employees.manager_id) confused the direction logic
Junction tables, where both joined columns are primary keys, got an arbitrary winner
And the table-order fallback was a coin flip dressed up as a convention

Each bug was fixable. Another pattern, another special case, another test. That is exactly how the function grew to be the smartest 333 lines in the codebase. The line count was not the cost. The confidence was.

The replacement: facts or nothing

The fix was not a better heuristic. It was a contract change:

schema := map[string][]analysis.ColumnSchema{
    "customers": {{Name: "id", PGType: "bigint", IsPrimaryKey: true}},
    "orders":    {{Name: "id", IsPrimaryKey: true}, {Name: "customer_id"}},
}

joins, _ := analysis.ExtractJoinRelationshipsWithSchema(query, schema)
// orders.customer_id -> customers.id, because the schema says id is a PK.

You pass schema metadata, you get relationships derived from actual primary keys. You do not pass schema, you get nothing. If the metadata cannot settle a case (both sides are primary keys), the answer is nil, not a guess.

Deleting the no-schema path meant deleting tested, working, green code. The 12 tests I removed were not failing. They were carefully asserting that the guesses came out the way the guesses come out. Tests that lock in behavior nobody should rely on are not coverage. They are a fence around a landmine.

The migration cost turned out to be near zero: every production caller already had schema metadata sitting right there. They had just never been asked for it.

The part I did not expect

Last week a stranger opened an issue on the repo. He was analyzing hundreds of queries and hit a case where a WHERE clause column was not qualified by a table name, so the parser left the table field empty.

He did not ask the parser to guess. He asked for ExtractWhereConditionsWithSchema, by name, with the same schema-map shape the JOIN function uses. The design had taught him what to ask for.

That is the moment you find out an API decision was right: when users start requesting extensions to the constraint instead of exceptions from it.

The rule

You probably know "Parse, don't validate": make illegal states unrepresentable by parsing input into types that carry proof. This is the next clause of the same contract. Parsing tells the truth about what the input is. It must also tell the truth about what it cannot know.

If your library cannot know, it must say so. An empty result is an answer. A guess is a liability with good marketing.

We are currently spending billions of dollars teaching language models to say "I don't know" instead of hallucinating a confident answer. Your API can do it for free, in the type system, today: take the inputs that make the answer knowable, and return nothing when it is not.

The smartest code I ever deleted is the reason people trust what is left.

The parser is open source at github.com/ValkDB/postgresparser, 260 stars and counting. Issues and PRs welcome, especially the ones that ask for facts instead of guesses.

The Microsecond Lie: Why your Go timers are lying about the GPU

Eitamos Ring — Sat, 23 May 2026 19:12:52 +0000

TL;DR: I thought my CUDA kernel was running in 160 microseconds. I was wrong. Here is how I used CUDA Events in pure Go to find the real hardware time, and why CPU-side timers are the wrong tool for GPU forensics.

I wrapped my kernel launch in a standard Go time.Since(start) block and saw 162 microseconds.

I thought I had built a speed demon. Then I implemented real GPU Events and found the truth.

The Misleading Metric

When you launch a CUDA kernel, it is completely asynchronous. The CPU doesn't wait for the GPU to finish; it just puts the task in a queue (a Stream) and returns control to your Go program immediately.

My 162-microsecond measurement wasn't measuring the math. It was only measuring how long it took the Go runtime to talk to the NVIDIA driver and enqueue the job.

The GPU hadn't even finished the first row of the matrix before my timer stopped.

The Hardware Truth (RTX 4070 Ti)

To find the real numbers, I had to implement CUDA Events. These are markers you place directly into the hardware stream. The GPU itself records a timestamp when it reaches the marker, bypassing the CPU clock entirely.

I ran a 10M element vector addition on an RTX 4070 Ti. Here is what the hardware actually said:

Measurement Method	Reported Time	What it actually measured
CPU `time.Since` (Async)	~160 µs	Time to enqueue the work
GPU `cuda.Event` (Actual)	~434 µs	Actual compute time on Silicon
CPU `time.Since` (with Sync)	~404 µs	Enqueue + Execution + Runtime overhead

The hardware compute time was 2.7x slower than what my CPU timers led me to believe.

Implementation in Pure Go

Measuring this accurately required adding NewEvent, Record, and ElapsedTime to the gocudrv package. Since we aren't using cgo, I had to bind the cuEventElapsedTime symbols manually and handle the C-to-Go float32 conversion.

Here is what the "truth-telling" code looks like now:

// 1. Create the hardware stopwatches
start, _ := ctx.NewEvent()
stop, _ := ctx.NewEvent()

// 2. Place markers in the stream
start.Record(stream)
fn.LaunchOn(ctx, stream, cfg, args...)
stop.Record(stream)

// 3. Wait for the STOP marker to be reached
stop.Synchronize(ctx)

// 4. Get the hardware duration
duration, _ := start.Elapsed(stop)
fmt.Printf("Actual GPU time: %v\n", duration)

The Lesson for AI Infrastructure

As we move toward Go-based AI infrastructure, we have to be careful about "Measurement Drift."

If you are building an inference gateway or a real-time image processor in Go, using CPU timers will make your P99s look incredible on paper while your users experience mysterious latency.

You can't optimize what you can't measure. If you aren't using hardware events, you are just measuring the speed of your request queue, not the speed of your product.

What's Next?

Now that I have a microsecond-accurate stopwatch, I can finally start optimizing the data path. I'm currently working on CUDA Graphs to reduce that 160µs enqueuing overhead by bundling complex task topologies into a single hardware command.

If you're interested in the forensics of low-level Go or want to help build the cgo-free bridge, check out the progress on GitHub.

https://github.com/eitamring/gocudrv

Deleting the 8.4GB Python Sidecar: Pure Go + CUDA with `CGO_ENABLED=0`

Eitamos Ring — Wed, 20 May 2026 04:47:04 +0000

TL;DR: I built gocudrv so Go services can talk directly to NVIDIA GPUs — no cgo, no CUDA toolkit, no bloated Python dependencies. One static binary.

Last month I was reviewing a production AI service. The core business logic was clean, efficient Go (15MB binary), but GPU access was routed through a Python sidecar.

The results were painful:

8.4GB Docker images — bloated with unused CUDA toolkits and PyTorch dependencies
4-minute cold starts during autoscaling
Extra serialization + network hops between Go → Python → GPU

We had accepted this because “GPUs belong to Python.” I decided to challenge that assumption.

The Impossible Build: `CGO_ENABLED=0`

Most Go developers assume you need cgo for CUDA. Instead, I used the CUDA Driver API (already present wherever an NVIDIA driver is installed) together with purego to bypass the C compiler entirely.

// internal/platform/platform_linux.go
func LibraryCandidates() []string {
    return []string{
        "libcuda.so.1",
        "/usr/lib/x86_64-linux-gnu/libcuda.so.1",
        "/usr/lib/wsl/lib/libcuda.so.1", // Works seamlessly in WSL2
    }
}

gocudrv loads libcuda.so at runtime. Standard go build works — even when building on a Mac targeting Linux.

The Receipts: Size & Build Comparison

Metric	Python Sidecar Approach	gocudrv (Pure Go)
Artifact Size	~8,400 MB	2.4 MB
Build Time	5–10 minutes (Docker)	< 2 seconds
External Dependencies	Python + PyTorch + CUDA Toolkit	NVIDIA Driver only
Deployment Simplicity	Multiple processes + networking	Single static binary

Low-Level Kernel Performance (10M element vector add on RTX 4070 Ti)

For a simple vector addition (~114 MB data):

H→D Copy: 19.3 ms
Kernel Launch: 3.4 ms
D→H Copy: 25.6 ms
Total GPU Pipeline: 48.3 ms

These numbers represent the raw GPU work. In the previous Python sidecar setup, we also paid extra for:

JSON/Protobuf serialization
Local network socket transfer (Go → Python)
Python interpreter + PyTorch overhead

The real win is not necessarily beating PyTorch on micro-benchmarks, but removing the entire sidecar layer and its operational complexity.

Beyond a Simple Wrapper

Pure Go doesn’t mean slow. I focused on asynchronous overlap from the beginning to hide PCIe transfer latency:

stream, _ := ctx.NewStream()

// Start DMA transfer — returns immediately
err := buf.CopyFromHostAsync(ctx, stream, hostBuffer)

// Go can do useful work while the GPU is computing
// ...

// Synchronize only when needed
err = stream.Synchronize(ctx)

Why This Matters in 2026

AI is shifting from research demos to critical infrastructure. Go excels at stability, concurrency, observability, and operational predictability — exactly what production model serving demands.

Removing the Python sidecar gives you:

Dramatically smaller images and faster deploys.
Much better cold start times.
Single language and single binary (much simpler observability and debugging).
No GIL, better P99 tail latencies.

Current State (Honest)

gocudrv is still early and experimental. Core functionality works today (device management, memory management, PTX loading, streams, async copies), but it is not yet ready for complex high-performance inference serving.

I’m actively working on CUDA Graphs, Events & Timing, and multi-GPU support.

If you’re a Go engineer tired of carrying heavy Python AI runtimes in production, I’d love your feedback and contributions.

→ link

Why LLMs Run on GPUs, Not CPUs

Eitamos Ring — Mon, 18 May 2026 07:15:03 +0000

It’s not because GPUs are magic AI chips

I used to think GPUs were used for LLMs because they were special hardware built for AI.

That is close, but not really the useful answer.

The better answer is:

LLMs became GPU-shaped.

A GPU does not understand language.
It does not reason.
It does not know what your prompt means.

It is just very good at doing the same numeric work across a massive amount of data.

And that is mostly what modern LLM inference is.

From text to numbers

When you send a prompt to an LLM, the model is not reading it like a person.

Your prompt becomes tokens.
Tokens become numbers.
Those numbers move through many layers.

At a very simplified level, the model keeps doing this:

output = input @ weights

That is matrix multiplication.

For a tiny model, a CPU is fine.

For a 7B, 70B, or 405B parameter model, this becomes a ridiculous amount of repeated numeric work.

That is where GPUs win.

A CPU is great at flexible logic:

if user.IsAdmin {
    loadDashboard()
} else {
    loadLimitedView()
}

A GPU is great at repeated parallel work:

Do the same operation across millions of values.

Not because the work is smart.

Because there is a lot of it.

The bottleneck most developers feel: memory

Raw math is only part of the story.

The bigger issue is often memory movement.

A 70B model in FP16 is roughly:

70B parameters × 2 bytes = 140GB

That is just the weights.

So when the model generates text, it is not only “doing math.”
It also has to keep moving a huge amount of model data fast enough to produce the next token.

That is why normal developers hit questions like:

Why do I need so much VRAM?
Why is CPU offload so slow?
Why does quantization help?
Why does long context get expensive?
Why does my big GPU look underused with one request?

The answer is usually data movement.

Not just compute.

If the model fits in GPU memory, life is better.

If parts of it spill to CPU memory, every generated token can get slower.

If you reduce the model size with quantization, there is less data to move.

That is why quantized models often feel faster.

Why quantization helps

Quantization reduces how much data the system has to store and move.

Roughly:

FP16 = 2 bytes per parameter
INT8 = 1 byte per parameter
INT4 = 0.5 bytes per parameter

So a 70B model looks roughly like this:

FP16  → 140GB
INT8  → 70GB
INT4  → 35GB

Same basic model shape.

Much less data to push through memory.

That is the practical reason quantization matters.

It is not just “smaller model file.”

It can change whether the model fits in VRAM at all.

And fitting in VRAM is often the difference between usable and painful.

Prefill vs decode

LLM inference has two very different phases.

Prefill is when the model processes your prompt.

The prompt is already available, so the GPU can do a lot of work in parallel.

This phase fits GPUs well.

Decode is when the model generates the response.

This happens one token at a time.

Token 1.
Then token 2.
Then token 3.

The model cannot fully generate token 50 before token 49 exists.

That is why a powerful GPU can still look underused when serving one request.

The GPU is huge.

The work is arriving in small steps.

Why batching matters

Batching is how serving systems keep GPUs busy.

One request:

model.Generate(prompt)

Many requests together:

batch := []Prompt{
    promptA,
    promptB,
    promptC,
    promptD,
}

model.GenerateBatch(batch)

Now the GPU can process many next-token steps together.

The same model weights can be reused across more work.

That is the real reason batching matters.

It is not just:

More work means busier GPU.

It is:

Use every expensive memory read for as much useful math as possible.

This is why LLM serving is not just “put model on GPU.”

It is batching, scheduling, memory layout, and keeping the hardware fed.

A bad serving system wastes expensive GPU time.

A good one keeps the GPU busy.

So why GPUs?

We use GPUs for LLMs because the workload is:

huge
numeric
repetitive
parallel enough
very sensitive to memory movement

The GPU is not the brain.

The model is the brain.

The GPU is the engine that makes the brain fast enough to use.

LLMs do not run on GPUs because GPUs are magic AI machines.

They run there because the workload matches what GPUs are good at.

Once that clicks, a lot of practical things make more sense:

Why VRAM matters.
Why batching matters.
Why quantization helps.
Why CPU offload hurts.
Why long context is expensive.
Why “just use a bigger GPU” is not always the full answer.

Calling CUDA from Go without cgo

Eitamos Ring — Sat, 16 May 2026 14:37:43 +0000

I started gocudrv with one constraint:

I wanted Go code to call CUDA without making every build depend on CUDA headers, a C compiler, or cgo.

That means loading the NVIDIA driver at runtime instead of linking against CUDA at build time.

Why avoid cgo?

cgo is the normal way to call C from Go, and often the right tool. But it also makes builds heavier.

A package that uses cgo needs:

a C compiler
platform-specific toolchains
cross-compilers for cross-platform builds

For this project, that was exactly the setup I wanted to avoid.

The goal was a normal Go build:

CGO_ENABLED=0 go build ./...

The binary still requires an NVIDIA driver on the machine where it runs.

It just does not require the CUDA toolkit on the machine where it is built.

Why the Driver API?

CUDA exposes two major APIs:

the higher-level Runtime API
the lower-level Driver API

gocudrv uses the Driver API because it is exposed directly by the NVIDIA driver itself:

libcuda.so.1 on Linux/WSL
nvcuda.dll on Windows

That allows the program to:

load the driver dynamically at startup
bind only the symbols it needs
fail gracefully if the driver is missing

The Driver API is also backward compatible, which makes it a better fit for a thin binding layer.

Where purego fits

gocudrv uses purego to open shared libraries and bind native functions without cgo.

At the top level, initialization looks pretty ordinary:

package main

import (
    "fmt"
    "log"

    "github.com/eitamring/gocudrv/cuda"
)

func main() {
    if err := cuda.Init(); err != nil {
        log.Fatal(err)
    }

    v, err := cuda.DriverVersion()
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("CUDA driver: %d.%d\n", v/1000, (v%1000)/10)
}

Underneath that small API, the package:

locates the driver library
binds functions like cuInit and cuDriverGetVersion
calls cuInit(0)
maps CUDA result codes into Go errors

What this does not buy

Skipping cgo does not remove the C boundary.

It just makes the boundary more manual.

The library still has to define:

function signatures
pointer types
struct layouts
alignment and padding

exactly as the CUDA ABI expects them.

If a native function expects a pointer to a struct, the Go side must pass memory with the exact same layout. The compiler will not rescue a bad binding.

That tradeoff is worth it for this project, but it is still a tradeoff.

Next steps

Loading the driver is only the first step.

A machine may have:

zero GPUs
one GPU
several GPUs

The next step is handling devices, contexts, memory, and eventually streams and async execution cleanly from Go.

The project is still very early, but the vector-add example already works.

gocudrv on GitHub

Three Rules for Designing a Go SDK Other People Will Actually Use

Eitamos Ring — Thu, 07 May 2026 18:00:00 +0000

I publish open-source Go libraries.
Not many people use most of them, and I've spent a fair amount of time trying to figure out why. Some of it is distribution. Some of it is the unsexy truth that nobody needed the thing I built. But a real chunk of it — bigger than I want to admit — is that the API was designed for me, the author, and not for the developer arriving cold from a Google search at 2am with a deadline.

This post is three rules I now apply when designing a Go SDK. They come from publishing postgresparser — a pure-Go PostgreSQL parser — and watching where new users got stuck. The examples are from that library, but the rules aren't about parsers. They're about what the surface of a Go package should look like if you want strangers to use it.

I'll also flag one place I broke my own rule, because the post would be dishonest without it.

Rule 1: Expose answers, not nodes

The single biggest mistake I see in Go SDKs (and that I've made myself) is shipping the internal data model as the public API. The author has built an AST, or a state machine, or a config tree, and they think: "great, I'll let the caller walk it." The caller does not want to walk it. The caller wants an answer to a specific question.

Here's what "expose the nodes" looks like in a SQL parsing context:

// What other Go SQL parsers tend to give you
tree, _ := parser.Parse(sql)
for _, stmt := range tree.Statements {
    if sel, ok := stmt.(*ast.SelectStmt); ok {
        for _, from := range sel.From {
            if rv, ok := from.(*ast.RangeVar); ok {
                tables = append(tables, rv.Relname)
            }
            // ...also handle JoinExpr, Subquery, RangeFunction,
            // RangeTableSample, RangeTableFunc, CTERef...
        }
    }
}

The user came to your library to find out which tables a query touches. You handed them a tree-walking exercise and a list of node types they have to learn. Every caller of your library now has to write — and maintain — the same boilerplate, with the same bugs, in slightly different ways.

Compare:

// What postgresparser gives you
result, _ := postgresparser.ParseSQL(sql)
fmt.Println(result.Tables)

That's it. Two lines. CTEs, subqueries, set operations, joins — all flattened into the same field, with aliases preserved. The IR (the actual AST-equivalent) still exists internally, but it's not what the caller binds to.

The principle: for every question your SDK answers, there should be a single field or function whose name is the question. "Which tables?" → Tables. "Which columns are filtered?" → ExtractWhereConditions. "How is each column used?" → ColumnUsage. If a user has to traverse three levels of struct to get an answer, the answer wasn't really exposed.

The objection I hear: but what if the caller wants something custom that we didn't anticipate? Fine — keep the IR public for the 5% case. But default to answering the 95% case in one line, and only fall back to the IR when the typed accessor doesn't cover the question.

Rule 2: Name the common case after the common case, and mark the variants

Most Go SDKs I see treat all of their entry points as peers. Parse, ParseStrict, ParseAll, ParseWithOptions, ParseFromReader — all listed in pkg.go.dev with the same visual weight, and the user has to read every one to figure out which they want.

This is the "tyranny of options" failure. The author thought of every variant; the user has to think about it too.

The fix is sequencing. Pick the version 80% of users want. Give that the short name. Make the other variants explicitly named after the thing that makes them different.

postgresparser's parsing entry points:

// 80% case — parses one statement, gives you a result.
result, _ := postgresparser.ParseSQL(sql)

// "I might pass multiple statements and want all of them."
batch, _ := postgresparser.ParseSQLAll(sql)

// "I want an error if more than one statement was passed."
result, _ := postgresparser.ParseSQLStrict(sql)

ParseSQL is the default. ParseSQLAll and ParseSQLStrict are explicitly named after the property that makes them different (handling all statements, strict-on-multi). A user reading the package docs sees ParseSQL first, tries it, and only goes looking for the variants if they hit a case it doesn't cover.

The wrong version of the same API:

// Don't do this
postgresparser.ParseSQL(sql, ParseOptions{Strict: true, AllStatements: false})
postgresparser.ParseSQL(sql, ParseOptions{Strict: false, AllStatements: true})

You've moved the decision from the function name (where it's documented and grep-able) to a config struct (where it's not). New users have to read the options struct just to call the function. Existing code has to be re-read every time someone wants to know what mode it's in.

The principle: the most common call should be the shortest call. Variants get names that describe how they differ. Config structs are for things that don't fit in a name, not for things that do.

Rule 3: Return structured data, not strings the caller has to re-parse

This one I see less often in writing about SDK design, but it's the one that bites users hardest in practice.

If your SDK has done work to extract structured information from unstructured input, don't throw the structure away on the way out. Returning []string when you could have returned []struct{...} is a tax you charge every caller forever.

postgresparser extracts WHERE conditions. The naive return type would be:

// Bad: caller has to re-parse what you already parsed
conditions, _ := analysis.ExtractWhereConditions(sql)
// returns: ["status = 'active'", "total > 100"]

// Now every caller writes a regex. They get it wrong.
// They handle = and != but forget IS NULL. They miss BETWEEN.
// They re-introduce the bug your library was built to solve.

What it actually returns:

type Condition struct {
    Column   string
    Operator string
    Value    interface{}
}

conditions, _ := analysis.ExtractWhereConditions(
    "SELECT * FROM orders WHERE status = 'active' AND total > 100",
)
for _, c := range conditions {
    fmt.Printf("%s %s %v\n", c.Column, c.Operator, c.Value)
}
// status = active
// total > 100

Now the caller can ask c.Column == "tenant_id" directly. They can switch on c.Operator. They can type-assert c.Value. None of them have to write a regex, and none of them re-introduce parsing bugs at the boundary of your library.

The principle: if the structure exists internally, expose the structure. Strings are for things that have no structure, or for things the user is going to print. Stringly-typed return values are how libraries become impossible to use correctly at scale.

The reverse also holds: if you find yourself writing a long regex inside a library you depend on, that library failed Rule 3.

Where I broke my own rule

In the spirit of not pretending I have all this figured out: postgresparser violates Rule 2 with ParseSQLWithOptions(sql, opts). It exists alongside ParseSQL(sql), takes a config struct with extraction flags like IncludeCreateTableFieldComments, and is exactly the "tyranny of options" pattern I just told you to avoid.

The honest reason it exists: comment extraction is expensive and most callers don't need it, but I didn't want to design a separate ParseSQLWithComments function because the option might evolve. So I shipped a WithOptions escape hatch and told myself it was fine. It's not fine — it's a slow leak that will get bigger as more options accrete. The right move would have been a separate named function for the one option that exists today, and a real opt-in API design when the second option arrives.

I'm flagging it so you can see what the wrong choice looks like even when the author knew the rule.

The point of including this isn't self-deprecation. It's that you will violate your own rules. The goal isn't a perfect API on day one; it's noticing the violation, naming it, and fixing it before the wrong shape hardens into a public contract you can't change.

TLDR;

If you can't remember three rules, remember the question they all answer: what does the user have to learn before they can use this library?

Rule 1 says: don't make them learn your AST.
Rule 2 says: don't make them learn your option matrix.
Rule 3 says: don't make them re-parse what you already parsed.

Every line of documentation a user has to read before their first successful call is friction. Some of it is unavoidable. A lot of it isn't, and that's where the design work is.

postgresparser is on GitHub at github.com/ValkDB/postgresparser if you want to see what these rules look like applied (and, per the section above, where they aren't yet). Issues and PRs welcome — particularly the kind that point out a rule I missed.

What I Learned Building a Pure Go PostgreSQL Parser

Eitamos Ring — Tue, 05 May 2026 06:19:05 +0000

Why I built it

I needed a PostgreSQL parser that could run inside Go tooling without CGO, external binaries, or runtime dependencies.

What made PostgreSQL parsing harder than expected

SQL is not one grammar
PostgreSQL has a lot of dialect-specific edge cases
AST shape matters more than “can it parse”
Error handling becomes a product feature
Real-world SQL is uglier than examples

Why pure Go mattered

No CGO, easy installation, works in CI, easy to embed in linters and developer tools.

What 200+ GitHub stars taught me

Developers care about boring installation
Parser APIs need to be simple
Good examples matter more than perfect docs
People want tooling, not academic grammar dumps

Where it’s going

This parser is becoming the foundation for Valk Guard, a local-first static analyzer for SQL and ORM usage. No LLM required. It works from ASTs and deterministic rules.

GitHub repo: GitHub repo: https://github.com/ValkDB/postgresparser

What every `?` in your SQL is hiding

Eitamos Ring — Mon, 04 May 2026 18:48:09 +0000

Take a query that comes out of pg_stat_statements:

SELECT date_trunc(?, o.created_at) AS week,
       count(*) AS total
FROM orders o
INNER JOIN customers c ON c.id = o.customer_id
WHERE o.created_at >= ?
  AND o.amount > ?
  AND c.plan = ?
GROUP BY ?
ORDER BY 2 DESC
LIMIT ?

Six question marks. Each one means something completely different.

The first, inside date_trunc, expects a string like 'week' — it's telling the function which time bucket to use. The second is a timestamp comparing against created_at. The third is a number comparing against amount. The fourth is a string joined through to the customers table — it has to match a plan value over there. The fifth, sitting bare inside GROUP BY, is a positional integer like 1, pointing back at the first column in the SELECT list. It's not a value, it's an index. The sixth, after LIMIT, is a page-size integer.

Six placeholders, four different value types, two completely different kinds of integer. There isn't a regex that gets all six right — not without re-implementing a SQL parser inside it.

postgresparser is the open-source Go/ANTLR PostgreSQL parser we maintain at ValkDB. Until this release, when you got back an AST, every ? was just a leaf node with positional information and nothing else. The parser knew exactly what each ? meant — it had to, in order to parse — but it never told you. So everyone downstream fell back to regular expressions, string scanning, and increasingly elaborate guesswork.

This week's release tells you what every ? actually is.

The new API

result, _ := analysis.AnalyzeSQL(querySQL)

for _, p := range result.Placeholders {
    fmt.Printf("placeholder %d: role=%s column=%s\n",
        p.Index, p.Role, p.ColumnRef)
}

placeholder 1: role=function_arg     column=         (date_trunc, arg 0)
placeholder 2: role=where_value      column=created_at
placeholder 3: role=where_value      column=amount
placeholder 4: role=where_value      column=plan
placeholder 5: role=group_by_ordinal column=
placeholder 6: role=limit            column=

Six placeholders, six correct classifications, no string scanning. Switch on the role, fill in the right value.

How the old way failed

Without role information, this is the pipeline most tools end up with:

┌─────────────────────┐
│  Normalized SQL     │
│  with ? placeholders│
└──────────┬──────────┘
           │
           ▼
┌─────────────────────────────────┐
│   Regex sweep for "?"           │
│                                 │
│   finds ? in string literals    │
│   finds ? in comments           │
│   can't see GROUP BY context    │
│   mis-IDs JSONB ? operator      │
│   picks same value twice for    │
│   same column on >= and <       │
└──────────┬──────────────────────┘
           │
           ▼
┌─────────────────────┐
│  Hand-written       │
│  per-position guess │
│  (fragile)          │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  Substituted SQL    │
│  often broken       │
└─────────────────────┘

The role-aware version skips all of that by walking the parse tree the parser already built. String literals are leaves of their own kind, so question marks inside them are never seen as placeholders. Comments are stripped before tree construction. The JSONB operator is parsed as an operator node, not a placeholder leaf, so it never enters the placeholder list. GROUP BY and ORDER BY ordinals carry their own dedicated role. And every placeholder's syntactic role — its actual position in the grammar — comes back attached.

The five footguns this release closes

1. The JSONB `?` operator is not a placeholder

PostgreSQL has three jsonb operators that look like placeholder tokens:

WHERE data ? 'key'                  -- "does jsonb contain top-level key?"
WHERE data ?| array['a','b']        -- "any of these keys?"
WHERE data ?& array['a','b']        -- "all of these keys?"

A regex sweep can't tell these apart from real placeholders. The new placeholder list excludes JSONB operator tokens by construction.

2. `INTERVAL ?` actually parses

Before this release, INTERVAL ? was rejected with a syntax error — a real problem if you consume pg_stat_statements, because every query that uses an interval literal gets normalized to that form. The grammar now accepts a parameter token in interval-operand position.

3. `?` inside string literals stays inside string literals

WHERE notes = 'has a ?'
WHERE notes = 'don''t mark me ?'

The collector walks the parse tree, never the raw SQL — so string-literal ? and comment ? simply don't appear in the placeholder list.

4. `GROUP BY ?` is an ordinal, not a value

pg_stat_statements rewrites GROUP BY 1, 2 to GROUP BY ?, ?. These placeholders need to be substituted with positional integers referring to SELECT-list slots — not with arbitrary values. A dedicated role makes this explicit.

5. Function-argument placeholders need to know their function

SELECT date_trunc(?, created_at), extract(? FROM created_at) FROM t

The first ? must be a string like 'week'. The second must be a string like 'year'. Both are function-args, but the function differs — so the right substitution differs. Each placeholder of this kind now carries its parent function name and argument index.

Who this is for

If you build an ORM or query builder and you've ever wanted to type-check a placeholder before binding to it, this is for you. If you build a SQL linter, a migration tool that rewrites queries between dialects, a monitoring agent that ingests pg_stat_statements, an AI-assisted SQL generator that emits parameterized queries — same. The common thread is that you have a normalized SQL string with ? placeholders in it, and you need to know what each one means before you can do anything useful.

If that sounds like work you've done, you've probably written a private placeholder classifier already. With this release, you don't have to.

Closing

The parser tells you what the SQL says; type inference belongs a layer up. The API stays narrow on purpose — roles, positions, and the structural context needed to make sense of them. Function-wrapper exposure on column usage is next on the roadmap; lateral-join and recursive-CTE refinements after that.

The parser knew. Now it tells you.

postgresparser — open-source PostgreSQL parser. Go, ANTLR-based. Contributions welcome.

A Protobuf for Database Schemas

Eitamos Ring — Wed, 18 Mar 2026 07:52:54 +0000

Every serious system has an interface definition for its wire format. gRPC has protobuf. REST has OpenAPI. GraphQL has its SDL. But databases -- the thing everything else is built on top of -- have nothing.

Your database schema is one of the most important artifacts in your system. It defines every table, column, type, constraint, relationship, and index. It encodes years of domain decisions. And yet there is no standard, portable, machine-readable format for it.

We built one. We call it ctxexport.json.

The problem is older than LLMs

Before you assume this is an AI-context story, consider how many times you have needed your schema outside the database itself:

Onboarding a new engineer who needs to understand the data model.
Diffing staging against production to catch drift before a deploy.
Running a linter in CI to enforce naming conventions or catch missing indexes.
Generating documentation that is not immediately stale.

Every time, you end up writing a bespoke script that queries information_schema or pg_catalog, parses the output, and feeds it into whatever tool you need. The script is Postgres-specific. It breaks when you add a second schema. Nobody maintains it.

pg_dump --schema-only exists, but it is a restore format, not a consumption format. It is Postgres-specific SQL with SET statements, ownership clauses, and an ordering designed for replay, not reading. Try parsing it reliably. Try feeding it to a linter. Try diffing two of them without drowning in noise.

MongoDB is worse. There is no mongodump --schema-only. Your schema lives in the shape of whatever documents happen to exist. Good luck extracting that into something a tool can reason about.

Extract once, use many ways

The core insight behind ctxexport.json is the same one behind protobuf: separate the definition from the consumption.

A protobuf .proto file is written once and compiled to Go structs, Python classes, TypeScript types, gRPC stubs, or REST gateways. The definition is the single source of truth. The consumers are many and varied.

ctxexport.json works the same way. You extract your schema once -- from Postgres, MongoDB, or whatever backend -- and produce a single canonical JSON file. That file contains entities (tables, views, collections), fields (columns with types, nullability, defaults), edges (foreign keys and inferred references), and access paths (indexes). Everything a tool needs to understand your data model, nothing it does not.

From that single artifact, you can:

Compile to a lighthouse map -- a compact table-and-relationship summary that fits in an LLM prompt.
Compile to full SQL DDL -- standard CREATE TABLE statements for any subset of tables.
Serve over MCP -- give an AI agent schema awareness without database credentials.
Diff across environments -- compare staging and production schemas as structured data, not text.
Lint offline -- check naming conventions, missing indexes, or orphaned foreign keys in CI.
Validate in CI -- catch schema regressions before they reach production.
Commit to git -- your schema becomes a versioned artifact with a real history.

None of these consumers need to know whether the source was Postgres or MongoDB. None of them need a live database connection. The extraction happened once, upstream, and everything downstream reads the same contract.

The sidecar pattern

Databases have never been good at carrying human knowledge alongside the schema. Your users.deleted_at column is a soft-delete flag, but the database only knows it is a timestamp with time zone. Your orders.payload column is JSONB with a specific structure, but the database sees an opaque blob.

A sidecar file (dbdense.yaml) layers descriptions and value annotations onto the extracted schema:

entities:
  payments:
    fields:
      status:
        values: ["pending", "authorized", "paid", "failed", "refunded"]
  users:
    fields:
      deleted_at:
        description: "Soft delete timestamp. NULL = active."

This merges at export time. The compiled DDL gets inline comments like -- Values: pending, authorized, paid, failed, refunded. Every downstream consumer -- linter, LLM, documentation generator -- picks it up automatically. Write it once in a YAML file committed to the repo.

Why JSON, not SQL

SQL DDL is human-readable but machine-hostile. Parsing CREATE TABLE statements reliably across dialects is a nightmare. Defaults are quoted differently. Constraints can be inline or out-of-band. Comments use different syntax. There is no standard way to represent a foreign key relationship as structured data.

JSON is boring and that is the point. It is a declarative state representation -- you look up a table by name, not by parsing DDL statement order. Every language has a JSON parser. The schema is simple: a version string, an array of entities, and an array of edges. You can validate it with a JSON Schema. You can diff it with jq. You can read it in any language without a SQL parser.

A minimal entity looks like this:

{
  "name": "payments",
  "type": "table",
  "fields": [
    {"name": "id", "type": "uuid", "is_pk": true},
    {"name": "status", "type": "text", "not_null": true, "values": ["pending", "paid", "failed"]}
  ]
}

Flat, predictable, zero ambiguity.

Stop treating your schema like a black box

The immediate use case is LLM context -- giving AI agents schema awareness without live database access. But the format is deliberately general. If your tool can read JSON, it can read a database schema. That was not true before.

The project is at github.com/valkdb/dbdense. The contract is documented in docs/ctxexport-contract.md. It supports Postgres and MongoDB today. The extractor interface is small enough that adding a new backend is a single file.

Your database schema is too important to be locked inside the database. Export it. Version it. Build on it.

Stop Sending 93K Tokens of Schema to Your LLM Agent!

Eitamos Ring — Wed, 18 Mar 2026 07:52:06 +0000

I've watched agents query information_schema over and over, spending 4-6 turns just to figure out which tables exist, what columns they have, and how they join. On a 500-table database, the full DDL is around 93,000 tokens. Most questions touch 3-5 tables. On a complex multi-table join, I measured a 64% token reduction by just giving the agent the schema upfront.

That's what dbdense does.

I built dbdense to fix this.

What it does

dbdense is a three-step offline pipeline: extract, compile, serve.

Extract connects to your database once and snapshots the schema into a portable JSON file (ctxexport.json). Tables, columns, types, primary keys, foreign keys, indexes -- everything an LLM needs to write correct queries.
Compile turns that snapshot into two artifacts:
- A lighthouse -- a compact table map (~4K tokens for 500 tables). It looks like this:
```
 T:users|J:orders,sessions
 T:orders|E:payload,shipping|J:payments,shipments,users
 T:payments|J:orders
```
Every table, its FK neighbors, and embedded docs. 23x smaller than full DDL. This stays in the agent's context so it always knows what's available.
- Full DDL -- standard CREATE TABLE statements with constraints, rendered on demand only for the specific tables the agent asks about.
Serve (optional) exposes the lighthouse as an MCP resource and the DDL via an MCP slice tool. The agent reads the map, picks the tables it needs, and gets back just those definitions.

After the extract, everything runs locally. The compiled artifacts are plain text you can commit to your repo. No database connection needed at runtime.

No credentials in the agent runtime

The export step is the only step that touches the database. After that, compile and serve work from the local snapshot. Your production database credentials never need to be in the agent's environment. The tool works offline and air-gapped.

The numbers

I ran an agentic benchmark: n=3, same 5 questions, same seeded Postgres database (20K+ rows, 8 tables), same model (Claude Sonnet 4). One arm had only a Postgres MCP tool. The other had the same tool plus dbdense schema context injected into the prompt.

Metric	Without schema context	With dbdense	Delta
Correct answers	13/15	13/15	equal
Avg turns	4.1	2.2	-46%
Tokens per run	285,922	187,603	-34%

Same accuracy. 34% fewer tokens. 46% fewer turns.

The savings scale with query complexity. On simple single-table filters, both arms performed about the same. On a complex multi-table join, the baseline agent spent 6+ turns querying information_schema to discover the schema. dbdense answered in 2 turns, using 64% fewer tokens for that query.

The two wrong answers (both on the same question, in both arms) returned identical incorrect results, pointing to question ambiguity rather than a schema context issue.

Sidecar enrichment

Databases lie by omission. A column named status with type text tells the LLM nothing about what values are valid. The agent either guesses or wastes a SELECT DISTINCT turn to find out.

dbdense supports a dbdense.yaml sidecar file where you annotate columns with descriptions and enum values:

entities:
  payments:
    fields:
      status:
        values: ["pending", "authorized", "paid", "failed", "refunded"]
  orders:
    fields:
      status:
        description: "Order lifecycle status."
        values: ["pending", "confirmed", "shipped", "delivered", "cancelled"]

These annotations merge into the compiled DDL as inline SQL comments. The LLM sees -- Values: pending, authorized, paid, failed, refunded right next to the column definition. No extra queries needed.

This also works for documenting JSONB structures, MongoDB embedded documents, or anything else the raw schema doesn't capture.

What it doesn't do

The snapshot is static. If your schema changes, re-run export. This is intentional -- schemas are stable; questions change.

The slice tool still depends on the LLM picking the right tables from the lighthouse. dbdense reduces the context problem; it doesn't solve table selection for the model.

It's not a pg_dump --schema-only replacement. The renderer covers columns, PKs, FKs, NOT NULL, defaults, unique constraints, and indexes, but skips triggers, RLS policies, and custom types.

Try it

go install github.com/valkdb/dbdense/cmd/dbdense@latest
dbdense export --driver postgres --db "postgres://user:pass@localhost:5432/mydb" --schemas public
dbdense compile --mode lighthouse --in ctxexport.json --out lighthouse.txt
dbdense compile --in ctxexport.json --out schema.sql

You now have two files: a lighthouse map and full DDL. Point your agent at them. If you use Claude Code, dbdense init-claude writes the MCP config for you.

The project is open source at github.com/valkdb/dbdense.

How does a linter know your column doesn't exist

Eitamos Ring — Mon, 09 Mar 2026 08:40:04 +0000

You write a query that SELECTs ghost_status from the orders table. Your code compiles. Your tests pass. But ghost_status was never created in any migration. In production, that query crashes.
Valk Guard catches this at PR time - with no database connection.
This post walks through exactly how. Not hand-waving. The actual code path, from source file to finding.
The setup
Here's a Go file using Goqu to build a query:
func ListBrokenUserOrderStatus(ctx context.Context) error {
_, _, err := goqu.From("users").
LeftJoin(
goqu.T("orders"),
goqu.On(goqu.I("orders.user_id").Eq(goqu.I("users.id"))),
).
Select("users.id", "users.email", "orders.ghost_status").
Where(goqu.I("orders.missing_flag").Eq("pending")).
ToSQL()
return err
}
And here's the migration that created the orders table:
CREATE TABLE orders (
id SERIAL PRIMARY KEY,
user_id INTEGER NOT NULL REFERENCES users(id),
total NUMERIC(10,2) NOT NULL,
status TEXT NOT NULL DEFAULT 'pending',
created_at TIMESTAMP DEFAULT now()
);
Notice: the query references orders.ghost_status. The migration never created that column. There is no ghost_status. Valk Guard reports:
VG105: projection column "ghost_status" not found in table "orders" schema; check SELECT list and schema/model mappings
How does it know?
Let's walk through each phase.
Phase 1: Query extraction
The Goqu scanner doesn't look for SQL strings. It walks the Go AST looking for method chains rooted in goqu.From().
When it finds one, it flattens the chain into a list of method calls: From("users") → LeftJoin(...) → Select(...) → Where(...). Each method gets parsed: From gives the base table, LeftJoin gives the join target, Select gives the projection columns, Where gives the predicates.
From these parts, the scanner synthesizes a SQL statement:
SELECT users.id, users.email, orders.ghost_status
FROM users LEFT JOIN orders ON orders.user_id = users.id
WHERE orders.missing_flag = 'pending'
This SQL never existed in your source code. Valk Guard constructed it from the AST of your Go code. That's the key difference from regex-based tools - regex can't walk a method chain and reconstruct what the query builder will produce.
Phase 2: Schema snapshot
Separately, Valk Guard finds all .sql files under your migration paths. Each file gets parsed through postgresparser, and every DDL statement gets applied to a Snapshot - an in-memory representation of your schema's current state.
The snapshot builder processes DDL actions in order:
CREATE TABLE orders (id, user_id, total, status, created_at) → registers the table with five columns
ALTER TABLE orders ADD COLUMN shipped_at TIMESTAMP → adds a sixth column
ALTER TABLE orders DROP COLUMN shipped_at → removes it

The end result is a map of table names to column definitions. For orders, that's: id, user_id, total, status, created_at. Five columns. No ghost_status.
This is the same principle as running all your migrations on an empty database - except it happens in memory, with no database, in microseconds.
Phase 3: Rule evaluation
Now VG105 runs. It takes the synthesized SQL (already parsed into a structured IR by postgresparser) and the schema snapshot, and does a straightforward lookup:
For each column in the SELECT list with usage type "projection", resolve which table it belongs to (using the alias or the single-table shortcut)
Look up that table in the snapshot
Check if the column exists in the table's column map
If not → finding

For ghost_status, the column usage says it belongs to orders (from the orders.ghost_status qualifier). The snapshot has an orders table. But orders.ghost_status is not in the column map. Finding.
The same logic powers VG106 (unknown filter column - catches WHERE orders.missing_flag = 'pending' from the same query) and VG107 (unknown table reference).
It also works with ORM models
The same snapshot system powers schema-drift rules (VG101–VG104). Instead of checking queries against migrations, these rules check ORM models against migrations.
Say you have a Go struct:
type Order struct {
ID int db:"id"
UserID int db:"user_id"
Total string db:"total"
Status string db:"status"
GhostStatus string db:"ghost_status"
}
Valk Guard's Go model extractor walks the AST, reads the db struct tags, and produces a ModelDef with columns: id, user_id, total, status, ghost_status.
VG101 then compares each model column against the migration snapshot. ghost_status isn't in the orders table → finding:
VG101: model "orders" references column "ghost_status" not found in table "orders" schema; check migration DDL or update model mapping
Two different rules, two different input paths (query vs. model), same schema snapshot, same answer.
What this means in practice
You don't need a running database. You don't need to run migrations. You don't need to connect to staging. Valk Guard reads your source code and your migration files, builds everything in memory, and cross-references them statically.
This runs in CI in seconds. It catches the kind of bug that usually shows up as a column "ghost_status" does not exist error in your logs at 2am - and moves it to a PR comment at 2pm instead.
go install github.com/valkdb/valk-guard/cmd/valk-guard@latest
valk-guard scan .
Repo: github.com/ValkDB/valk-guard

DEV Community: Eitamos Ring

Why Regex Sucks in a Hot Loop

What the code does

The case for going back to regex

Where the plan fell apart

The numbers

So does regex suck?

Parse, Don’t Guess

The feature that knew too much

The comment that aged badly

Wrong is worse than empty

The replacement: facts or nothing

The part I did not expect

The rule

The Microsecond Lie: Why your Go timers are lying about the GPU

The Misleading Metric

The Hardware Truth (RTX 4070 Ti)

Implementation in Pure Go

The Lesson for AI Infrastructure

What's Next?

Deleting the 8.4GB Python Sidecar: Pure Go + CUDA with `CGO_ENABLED=0`

The Impossible Build: CGO_ENABLED=0

The Receipts: Size & Build Comparison

Low-Level Kernel Performance (10M element vector add on RTX 4070 Ti)

Beyond a Simple Wrapper

Why This Matters in 2026

Current State (Honest)

Why LLMs Run on GPUs, Not CPUs

It’s not because GPUs are magic AI chips

From text to numbers

The bottleneck most developers feel: memory

Why quantization helps

Prefill vs decode

Why batching matters

So why GPUs?

Calling CUDA from Go without cgo

Why avoid cgo?

Why the Driver API?

Where purego fits

What this does not buy

Next steps

Three Rules for Designing a Go SDK Other People Will Actually Use

Rule 1: Expose answers, not nodes

Rule 2: Name the common case after the common case, and mark the variants

Rule 3: Return structured data, not strings the caller has to re-parse

Where I broke my own rule

TLDR;

What I Learned Building a Pure Go PostgreSQL Parser

Why I built it

What made PostgreSQL parsing harder than expected

Why pure Go mattered

What 200+ GitHub stars taught me

Where it’s going

What every `?` in your SQL is hiding

The new API

How the old way failed

The five footguns this release closes

1. The JSONB ? operator is not a placeholder

2. INTERVAL ? actually parses

3. ? inside string literals stays inside string literals

4. GROUP BY ? is an ordinal, not a value

5. Function-argument placeholders need to know their function

Who this is for

Closing

A Protobuf for Database Schemas

The problem is older than LLMs

Extract once, use many ways

The sidecar pattern

Why JSON, not SQL

Stop treating your schema like a black box

Stop Sending 93K Tokens of Schema to Your LLM Agent!

What it does

No credentials in the agent runtime

The numbers

Sidecar enrichment

What it doesn't do

Try it

How does a linter know your column doesn't exist

The Impossible Build: `CGO_ENABLED=0`

1. The JSONB `?` operator is not a placeholder

2. `INTERVAL ?` actually parses

3. `?` inside string literals stays inside string literals

4. `GROUP BY ?` is an ordinal, not a value