DEV Community: Matty Stratton

Don't Give the Model SQL

Matty Stratton — Mon, 17 Aug 2026 14:20:00 +0000

I built a web app to answer questions about my own health data, for a reason that is embarrassingly small. I already had a perfectly good way to ask them: a Claude Code skill that queried the database and reasoned over the results. It worked well. It also can't run on Claude iOS, and the moment I actually want to ask "should I be worried about this" is standing in a kitchen at 6am, not sitting at a desk.

So it lives at a URL, behind Google sign-in allowlisted to exactly one address, with the source public minus the data. It reads the TimescaleDB database I wrote about in The Past Keeps Changing, and it answers two different kinds of question in two deliberately different ways.

(Obligatory: none of this is medical advice, and the thresholds in it are tuned to one person's circumstances. If you copy the rules you will get advice calibrated to somebody else's body.)

Two modes, kept apart on purpose

The coach view is deterministic. Protein adherence, deficit versus the scale, weight trend, overreaching, stalled lifts, data freshness. Each one is a pure function in lib/signals/, unit-tested against fixtures, no LLM involved anywhere. A verdict traces to a rule instead of to a vibe, and unknown is a first-class result distinct from ok, which matters because this dataset produces unknown constantly.

The ask view is an LLM. Claude, server-side, over thirteen read-only tools. It handles the questions nobody wrote a rule for: am I stalling on squat, how big is my deficit actually, what's my VO2max doing.

The interesting design work is all in the second one, and it's mostly about what I refused to build.

The obvious design

Hand the model SQL. Give it the schema, a read-only connection, and let it write queries. It's the design every "chat with your database" demo uses, it takes an afternoon, and for a database this small the query cost is irrelevant.

I rejected it, because there are six traps in this data and every one of them has already produced a wrong answer in this project, on a page I was looking at, at least once.

Today is a Partial Day. Its numbers are still accumulating. Compare it against a completed day and you invent a fast.
A gap is not a zero. An unlogged day is unlogged, not a day I ate nothing.
Apple shadow-copies every Liftosaur session. Query the workouts view naively and training volume roughly doubles.
energy_balance overstates the deficit by about 2.7x. Over the last 30 complete days it reports an average intake of 1,602 kcal against 3,216 burned, a net of −1,614 a day, which predicts losing 3.2 lb a week. The scale over the same window says 1.2. Basal energy is a formula estimate from weight, height and age, and watch-measured active energy runs generous. Both are real numbers whose difference is not a measurement.
A single weigh-in is noise. Day-to-day scale movement is water.
reps: 0 is a set that was attempted and failed, not a set that's missing.

Given SQL, a model walks into all six, which says nothing about the model and everything about the schema. The traps are invisible from it. Nothing about a column called calories tells you today's value is half-formed.

Why the prompt isn't the fix

I could put all six traps in the system prompt, and if I do, the model gets them right most of the time. That's what decided the design, because most of the time is the worse outcome.

A tool that's wrong every time gets caught on day one and thrown away. A tool that's right ninety-something percent of the time gets trusted, and then the rare wrong answer arrives wearing exactly the same confident formatting as the right ones. I have no way to spot it, because the whole reason I'm asking is that I don't already know the answer.

So the traps are foreclosed by the shape of the tools rather than by instructions:

Windowed queries end in AND observed_on < today_local(). The Partial Day isn't excluded by the model remembering to exclude it. It isn't reachable.
Gaps stay absent rows. Nothing zero-fills, so there's no zero to misread.
No tool reaches Apple's workout view at all. The double-counting trap isn't documented for the model's benefit, it's unreachable through the API surface.
energy_balance cannot be fetched without its reality check arriving in the same payload. You can't get the misleading number on its own.

The prompt still describes all six traps, because a model that understands why a window ends where it does gives better answers than one that just gets truncated data. But the prompt is not what's holding them. If the prompt were deleted tomorrow the answers would get worse and they wouldn't get wrong in those six specific ways.

There's also no write tool, and I mean that literally rather than as shorthand for one that's disabled or gated behind a confirmation. There is nothing to disable. Program changes stay in Liftosaur and macro targets stay MacroFactor's call, so the chat has no legitimate reason to mutate anything. The reasoning is in ADR 0006.

The catalog that wasn't the index

Then I nearly shipped a tool that was wrong in a way none of that structure protects against.

The chat needs to know which metrics exist. There's a metric_catalog table holding canonical units and an attention grade per metric, so list_metrics obviously reads from that. It compiled. It typechecked. It returned rows that looked entirely plausible.

in_data  catalogued  uncatalogued
81       38          43

The catalog covers 38 of 81 metrics. The other 43 aren't stale junk: sorted by coverage they start with walking and running distance (3,865 days of it, updated today), flights climbed, walking heart rate average, walking speed, step length, plus the entire micronutrient panel, all of it current because MacroFactor logs micros.

So the tool would have worked exactly as written and made the chat answer "I don't have that" about ten years of walking distance sitting right there in the database.

No test would have caught this. The function did what it said. I caught it by printing .length from a throwaway script against the real database and noticing 38 where I expected 81.

The fix inverts the join. Drive from observations_daily, LEFT JOIN the catalog, and an uncatalogued metric shows up with catalogued: false and a null unit rather than not showing up. It costs one aggregate over the whole continuous aggregate per call, which EXPLAIN ANALYZE puts comfortably under 100ms, and that's fine for something called once a conversation.

The general shape: a lookup table is not an index of reality unless something enforces that it is. Nothing did. Nothing does now either, but at least the absence is visible in the output.

False precision is a real cost

Raw rows out of the views look like this:

observed_on  calories            protein_g
2026-08-08   1370.9033333354562  187.9353333412348

Summing floats does that. Two problems once it reaches a language model. It's false precision, because a scale that reports to a fifth of a pound did not measure thirteen decimal places, and an answer quoting them implies rigour the data doesn't have. And it's pure token cost: eighteen characters where six will do, on every point of every series.

Rounded to two decimals at the tool boundary rather than in the query layer, on the principle that the data layer should return what the database holds and the tool layer is already the thing whose job is shaping output for a model. Done inside the single json() helper every tool return passes through, so a new tool can't forget. It took roughly a third off get_nutrition's payload for a seven-day window, and proportionally more over a ninety-day series.

The counterweight

I want to be careful not to oversell the structural argument, because the model repeatedly did better than the structure asked of it.

Nine deliberately trappy questions, run through a committed probe script so the results are something you can reproduce rather than something I remember. Three of them came back with reasoning the prompt does not contain.

Asked what my VO2max was doing, it reported the upward trend and then warned, unprompted, that Apple derives the figure from outdoor walk and run heart-rate data and that "the estimate is affected by weight dropping as well as by fitness," landing on "suggestive, not conclusive" instead of claiming a fitness gain. Nothing in the prompt mentions VO2max at all.

Asked whether I was stalling on squat, it separated T1 from T2 work by inspecting the weights and set counts. The tier hint that exists elsewhere in this codebase is not exposed to any tool.

And asked about sleep, it read the coverage figures before answering and declined to grade anything on 21 nights. That answer also contained a mistake that was entirely mine, which I didn't spot for another hour. It's the last section of this post.

That last one is my favourite, because it was an accident. I added a days365 field to make the metric index honest about coverage, for the reasons above. The model appropriated it as a generic "is there enough data here to answer this" gate. A field added for one reason got used for a better one, which is worth knowing before you trim a tool payload on token grounds.

Structure constrains the failure modes. It doesn't cap the upside.

The signals I wanted and couldn't build

The obvious next feature is cross-domain: does bad sleep predict missed lifts, does a deep deficit show up in recovery markers. Every signal in the app reads exactly one domain, and a few of them contain advisory copy gesturing at relationships the code never actually checks.

Before writing any of it I checked whether the three most obvious hypotheses hold against real history. They don't get a real test, and why not is the finding.

The only lift the stall rule flags is one it's supposed to ignore. Running stalling() unfiltered across 2,545 sets and 190 sessions returns exactly one hit: triceps pushdown, parked at 47.5lb for two sessions. That's a T3 accessory, and a T3 parking at one weight is the program working as designed rather than a stall. It's precisely the false positive the tier filter exists to suppress, and with the filter on there is nothing left.

The recovery rule has fired once in nine years. I ran the real overreaching() function over every day of history rather than approximating its baseline maths in SQL, because getting a rule subtly wrong by hand is the exact thing this project keeps catching me doing. Out of 2,409 days: ok 2,344 times, unknown 48, watch 16, and act a single time, on 25 April 2022. Nothing has gone past ok since June 2024.

That last paragraph is a correction. My own notes said act had never fired at all, and I believed it for months, because the script that produced that claim was a one-off I never committed and never re-ran. Writing it as npm run verify-signals took fifteen minutes and immediately contradicted the note. Make the check runnable and it will eventually tell you something you didn't want to hear.

And consistent nutrition logging started on 13 July, so four complete weeks is what I'd be correlating against. That's an anecdote wearing a sample's clothes.

So there are no cross-domain signals in this app, and the reason is that the events they'd correlate don't exist in my data yet. Filed as a dated follow-up rather than closed, because the hypotheses aren't rejected, they're just unanswerable with what's on hand.

I find this more satisfying than shipping the feature would have been. The version of me that skipped the check builds four correlation signals, they all sit at unknown forever, and I learn nothing except that the page is noisy.

What's still unverified

Two honest gaps, because a post about verification that ends on a clean note is a post that hasn't looked hard enough.

The ask interface has never been rendered in a browser. The Chrome extension couldn't inject into localhost, so the streaming format is verified via curl and unit tests on the decoder and nothing else. It works when I use it on my phone against production, which is evidence but not a test.

And the unknown signal path is untested against live data, because nothing is currently unknown. The instruction telling the model how to handle it is tested. The behaviour isn't.

Some numbers, since I've spent this whole series insisting on them. Across the nine probes, measured today:

  #  secs  ttft  turns    in    out  cacheR  cacheW     cost
   1   6.9   6.1      2   705     83   14138       0  $0.0127
   3  10.2   6.6      2  3989    299   14138       0  $0.0345
   8  13.6  10.1      3 12119    458   21207       0  $0.0826
   9  16.8   1.7      2 13344    660   14138       0  $0.0903

The cached prefix is 7,069 tokens of system prompt plus thirteen tool definitions, and cacheWrite is zero on every turn after the first, which is the number to watch. If it ever stops being zero, something volatile has crept into the prefix and every turn is paying full freight. A two-turn question reads that prefix twice, hence 14,138.

Nine questions cost 37 cents in total, from 1.3 cents for "how many calories today" to 9 cents for the ones that pull a year of series data. Latency ran 6.9 to 16.8 seconds end to end, with first text arriving anywhere from 1.7 to 10.1 seconds in. That spread is why streaming and a visible status line were not a nicety: ten seconds of blank screen reads as a hang, and the honest fix is to show the thing working rather than to make it faster.

And one gap I didn't know I had

Everything above is a gap I could name. Re-running those probes turned up one I couldn't, and it was sitting in the answer I'd just finished praising.

The sleep response ended with "sleep coverage overall is ~7% of days, so this is informational only." Seven percent is wrong. Over the last thirty days it's seventy, because my watch-wearing changed in July.

The model wasn't guessing and it wasn't reading that from the data. It was reading it from lib/coach/context.ts, where I had written "Sleep has roughly 7% coverage" into the system prompt as a standing fact, months ago, back when it was true.

So the chat told me something false about my own body, sourced from the one component I'd exempted from the argument this entire post makes. The tools compute. The prompt asserts. Assertions rot, and this one had quietly reached the point where the app was contradicting its own database.

Then I went to delete it and found out why it had survived.

test('prompt: carries the remaining data traps', () => {
  assert.match(prompt, /single weigh-in is noise/)
  assert.match(prompt, /7% coverage/)          // <- this line
})

The stale number was under test. That assertion required it to be present, so anyone who spotted the problem and corrected it would have gone red and, quite reasonably, put it back. A wrong fact had acquired a defender.

Two tests below that one sits prompt: forbids numbers that did not come from a tool. Two below that, prompt: hardcodes no target values, with a comment explaining that targets change weekly so the model has to fetch them rather than be told. The principle was already written down. It was already enforced for one kind of number. And for another kind, a test was holding the violation in place.

Chasing the string turned up seven copies, including a live row in the database and the coaching skill I run from my terminal. I had fixed one of them that same morning, in CLAUDE.md, and considered the job done.

The fix isn't to correct the figure. It's to delete it and let list_metrics report coverage, which it already does, and which is how the model knew to be careful about sleep in the first place. The test now asserts the inverse: assert.doesNotMatch(buildSystemPrompt(), /\d+(\.\d+)?%\s*coverage/i), so the next person to write a percentage into that prompt gets stopped instead of protected.

Which is the argument for tool shape over prompt text, arriving as a bug rather than a principle, in the one part of the system I'd decided didn't need it.

The other two in this set: The past keeps changing is why the storage layer under all this is append-only, and every number I didn't measure was wrong is the five figures I had to retract while writing these.

Every Number I Didn't Measure Was Wrong

Matty Stratton — Mon, 17 Aug 2026 14:19:59 +0000

I went to publish something about the database behind my personal health tracker, and fact-checking it took a day. By the end, most of the numbers I had written down to justify that database's design had turned out to be wrong.

Not wildly wrong. Wrong in the quiet way, where the conclusion still holds and the reasoning under it has rotted. Every single one had the same cause: I measured something adjacent to the thing I cared about, wrote the result into a comment, and then the comment outlived my memory of where the number came from.

The setup, briefly. Ten years of Apple Health data plus two and a half years of lifting, on SQLite until it lost data twice and on TimescaleDB since. 73,210 Reports across 81 metrics in a 30 MB database, and the repo is public. That last part is why this was worth a day of anyone's time: a wrong number in a public schema comment is a wrong number somebody else might trust.

Five of them, roughly in order of how badly the arithmetic was wrong. The last one is barely wrong at all and is by some distance the one that should worry you.

1. The segment key, wrong twice in opposite directions

TimescaleDB's columnstore lets you nominate a segmentby column. Rows sharing that value get grouped into a compression batch together, which is where most of the ratio comes from. For a tall, narrow table storing (day, metric, value), metric is the textbook choice, and every guide will tell you so.

I didn't use it. My schema comment explained why: roughly 69 rows per metric per yearly chunk, against a rule of thumb that wants more than 100 rows per segment value per chunk. Below the line, so no segmenting. That comment sat there looking authoritative for months.

Re-running it against the actual table:

yr    rows_per_metric
2019  206
2022  197
2020  174
2021  173
2024  153
2023  152
2026  124
2025   93
2018   92
2016   74
2017   48

Average about 135. Seven of eleven years sit above the guideline, not below. My comment was wrong in the direction that reverses the decision.

The cause is stupid and completely mechanical. I computed it from the 56,000 data points in the export files rather than from the rows that landed. The parser fans out: one heart_rate point becomes three metrics, one sleep_analysis point becomes six. 56,000 points went in, 73,000 rows came out, and I'd done arithmetic on the input file.

So I corrected it, felt good for about four minutes, and then looked at the distribution.

yr    metrics  >=100  <100  <20   median
2016  38        9     29    25     10
2017  40        4     36    27      9
2024  81       34     47     6     69
2025  76       23     53    46      3
2026  77       60     17     6    117

The average is dragged up by a handful of metrics that fire every day. Step count has ten years of unbroken coverage. Vitamin D has whatever MacroFactor felt like logging that week. In most years more metrics fall below the threshold than above it, and in 2025 the median metric has three rows.

Right call, wrong reasoning, twice. And I should be straight about how far the correction actually goes: I have never built the segmented version and compared ratios. What I have is a good argument sitting where a measurement ought to be, which is the exact failure this post is about, showing up inside the section where I'm supposedly fixing it.

The transferable bit is smaller than the story. Compute rows-per-segment-value from the loaded table rather than from whatever you fed it, and look at the spread instead of the mean. An average over a skewed distribution is the one statistic guaranteed to hide the shape of your problem.

2. "About a week," which I appear to have made up

Health Auto Export revises a day after that day has closed. That's the central fact of this whole system, and how long it keeps revising decides the chunk interval: the revision window has to fit inside the chunk that's still uncompressed, or a routine correction has to decompress historical data to land.

My schema comment said "about a week." So did the README. So did two other files.

I never measured it. I picked the figure up somewhere early, it sounded about right, and it hardened into documentation through nothing but repetition across four files.

What the live data says:

days_late  reports  distinct_days
0          1610     6
1          2298     6
2          110      4
3-7        62-69    1 each

Every value change happens at a one-day lag. Nothing at lag two or beyond has changed a value. And that 3-to-7-day tail is a single day, contaminated: it has one hae_backfill row and one live row reported on the same date, which is the migration overlapping itself rather than HealthKit revising anything.

The honest caveat, which matters more than the number: the live pipeline has been running for five days. "No seven-day tail" is weak evidence, not proof. So the position is one day measured, longer assumed, and yearly chunks are absurdly conservative for either.

The decision was never at risk. But "the assumption is safe" and "the assumption is verified" are different claims and I was only ever entitled to one of them. The comments now say which is which, which took ten minutes and should have happened months ago.

3. The watermark, which I diagnosed twice and understood once

The number in this one is INTERVAL '1 hour', and unlike the others it isn't a measurement I got wrong. It's a measurement I never took, because I reasoned my way to a value instead and the reasoning was flawed. It's also the only entry here that reached a user, where user means me, on my phone, in a grocery store.

MacroFactor said I'd eaten 1,556 calories. My own site said 688. Both were reading the same database.

Real-time aggregation unions materialized buckets with raw rows newer than the watermark. It's a very good feature and it's why a dashboard doesn't wait on a refresh job. But once a bucket has been materialized, raw rows for that bucket are never consulted again until something explicitly refreshes it.

Read that sentence again, because I didn't. "Fresh past the watermark" is not the same promise as "always fresh," and I had cheerfully substituted the second. A Report landing later the same day never gets looked at again, so the view goes on serving a stale number with total confidence, which it's entitled to do because I'm the one who configured it that way.

My first fix blamed the backfill, which called refresh_continuous_aggregate(cagg, NULL, NULL) and materialized every bucket including today's. That was a real cause, so I narrowed the refresh, felt clever, and moved on.

It came back, and there were two things I'd had wrong.

The watermark only moves forward. Refreshing a narrower window afterwards doesn't walk it back, so today stayed materialized and the only way to clear it was to rebuild the aggregate.

And my refresh policy was doing it too. I'd set end_offset => INTERVAL '1 hour', reasoning that a bucket ending at midnight tonight can't possibly be older than an hour ago. That reasoning is simply wrong, and the watermark had duly advanced past today.

The fix is belt and braces on purpose. end_offset widened to two days so the current day is never a refresh candidate, and the application reads today straight from the raw log with DISTINCT ON ... ORDER BY reported_at DESC, which computes exactly what last(value, reported_at) computes. Having misjudged the same rule twice, I stopped resting correctness on my ability to reason about it.

For the good version of real-time aggregates rather than my footgun collection, Sven Klemm's original post is still the clearest explanation of the mechanism, and there's a troubleshooting page covering this precise class of problem that would have saved me a week. The behavior isn't a bug. My mental model was.

4. A compression ratio measured against my own test loop

before  after    ratio  chunks
13 MB   1496 kB  8.7    12 (11 compressed)

Eight point seven times, on a database whose entire before state was thirteen megabytes. At this size that's not a benefit and I won't dress it up as one. Compression earns its keep when you're paying to retain hundreds of gigabytes, which is a sentence about somebody else's database.

It's worth showing anyway, because the mechanism is legible here in a way it isn't at scale. Tall, narrow, heavily repeated values in the ordering column. Nothing about that cares how many rows you have.

Two things I got wrong about it.

I measured 11.9x first, locally, and reported it to myself as good news. It was garbage. Re-running an idempotent backfill over and over leaves dead tuples, which inflate the uncompressed "before" without adding any data. I was benchmarking my own test loop and feeling great about it. Measure compression on a freshly loaded table, never on one you've been iterating against.

And I wrote a note promising to re-measure once live restatements had accumulated, which turned out to be more interesting than the ratio. I can't. Every live Restatement lands in the current chunk, chunks are yearly, and the columnstore policy waits 30 days past a chunk's range. That chunk runs to March 2027, so nothing written since going live compresses until roughly April 2027. The follow-up is eight months out rather than pending, and I only worked that out because I went looking instead of promising.

5. One number that was true and misleading at the same time

CLAUDE.md said sleep had "~7% coverage," and concluded that sleep was too sparse to build anything on, which is why the app displays sleep without grading it. Perfectly reasonable inference from the number it had.

window     nights  possible  pct
last 365d  23      365        6.3
last 90d   21      90        23.3
last 30d   21      30        70.0

The year figure was right. It was also concealing that 21 of the 23 recorded nights in the entire year are in the last thirty days. Current coverage is 70%. Something about my watch-wearing changed in July and the annual average will take a year to notice.

Nothing here was ever wrong, exactly. One number was doing the work of three, and the guidance built on it ("basically no sleep data") stopped being true without anything visibly breaking. That's a worse failure mode than a number that's simply incorrect, because there's no moment where it flips.

The pattern, since there is one

Four of these five were caught in a single day, by the same move: run the query against the real artifact instead of trusting the note. None of the queries took more than a minute to write. The expensive part was never the measurement, it was noticing that a measurement was owed.

What they have in common is that a plausible number outlives whatever made it plausible. It gets written down once, in a comment or a doc or a README, in a moment when you have the context to know what it means and what it excludes. Then the context evaporates and the number stays, in the imperative mood, looking like a fact.

And they don't always sit there passively waiting to be caught. The sleep figure above turned out to have seven copies, one of them in the system prompt of the app's chat, where it was being read aloud to me as though it were current. When I went to delete that copy, a unit test went red: it asserted the prompt must contain the string "7% coverage." The wrong number had acquired a defender, and anyone who noticed it before me would have hit the same red test and reasonably concluded they were the ones in error. That's the version of this failure I'd least like to meet again, because diligence doesn't save you from it. Diligence is what puts it back.

Three habits came out of this, and I've actually adopted them rather than merely resolving to.

The first is to write the method next to the number. Not "~69 rows per metric" but "~69 rows per metric, from the export scan." That second version carries its own bug report, visible to anyone who reads it including me six months later. The first version is where I lost months.

The second is to say, in the artifact itself, which side of measured-versus-assumed a figure sits on. My chunk-interval comment now has MEASURED and ASSUMED in capitals, which looks a bit much and has already stopped me re-quoting a guess as a finding twice.

The third is to distrust any single number describing a distribution. Both of my segment-key figures were averages and both were wrong, in opposite directions, because a skewed distribution has no meaningful average. The sleep figure failed identically, except across time rather than across metrics.

It's the engineering equivalent of labelling your leftovers, and the only reason it's worth a post is that I'd have told you I already did all three, right up until the afternoon I checked.

Companion pieces: The past keeps changing is the argument this project exists to make, about data that revises itself and why upsert makes that unfalsifiable. Don't give the model SQL is about the app on top of it.

The Past Keeps Changing

Matty Stratton — Mon, 17 Aug 2026 14:19:58 +0000

I moved my personal health tracker onto a time-series database this month. It holds 69,000 rows in thirty megabytes.

That is not a defensible reason to use one, and I want to be blunt about it before you get there on your own. Nothing I did made anything faster and nothing needed to.

What it replaced was smaller still. An 840 KB SQLite file on my laptop, seventeen metrics, about 280 health observations going back three months, plus two and a half years of lifting history. For what it was doing, that was the right call, and I'd make it again.

I moved because I'd been quietly losing data for months and the schema was built in a way that made it impossible for me to notice.

The whole repo is public at mattstratton/mattstratton-fitness-tracker, schema and decision records included, minus my actual data for reasons I hope are obvious. Every query below runs against the live database, and every number in this post is one query away from you checking it.

What it used to be

There was no server and no app. Health Auto Export wrote JSON files into two iCloud folders. A launchd agent on my MacBook polled those folders every hour, parsed whatever it found, and upserted the results into an 840 KB SQLite file next to it. When I wanted coaching I opened Claude Code on that same laptop and ran a skill that queried it.

That was the entire system. The Mac was the infrastructure, which sounds fine right up until the Mac is closed.

About 150 lines of that code existed for no reason other than surviving iCloud, and every one of them was written in response to something that had already broken. Files under ~/Library/Mobile Documents can exist as metadata-only placeholders that a launchd agent cannot materialise. That one failed with EDEADLK, stranded four days of workouts, and looked exactly like file corruption. Two automations wrote the same data into two different folders, so the winner was whichever sorted last alphabetically, until I changed it to whichever had the later mtime. On files whose mtimes iCloud does not reliably update.

Hold onto that last one. It comes back, and it turns out to be the whole problem.

Losing data twice without noticing

Each hourly run did the obvious thing:

INSERT ... ON CONFLICT DO UPDATE

New value for a day? Overwrite the old one. That is what upsert is for, and it cost me data twice.

The first one was ugly. An iOS update silently dropped Health Auto Export's HealthKit read permission for Weight & Body Mass and Lean Body Mass, while leaving Body Fat % and BMI alone. The exports kept running. They kept succeeding. They contained empty arrays for exactly two metrics, and the sync log wrote status='ok' every hour for five days straight.

Five days of weigh-ins gone, with the monitoring reporting green the entire time.

The second was quieter and I caught it by accident. A midday export made a 1,241 kcal day read as 333, because the export landed at lunchtime and the upsert dutifully replaced a complete day with a partial one.

Two bugs, and if you squint they're the same bug. Upsert answers "did this value change?" by destroying the evidence you would need to answer it. Nothing in that schema could distinguish "never reported" from "reported as empty" from "reported correctly, then clobbered by something worse."

The rule I got out of it: never ask whether the sync ran, ask whether the data is current. Those sound identical right up until a sync succeeds at doing nothing.

The question that dissolved it

I spent an embarrassing amount of time on "should this table upsert or append?" and got nowhere, because it's the wrong question and wrong questions don't have answers.

The right one turned out to be: is the thing I'm storing an observation about a day, or a report that arrived at a time?

Those are different objects. What I burned on August 9th is a fact about August 9th. "My watch told me, on August 10th, that I'd burned 1,834 kcal on August 9th" is a fact about a conversation. The first is stable. The second happens over and over, from multiple sources, with different answers.

The old schema mashed both into one row, which is exactly why both data-loss bugs were invisible. You cannot detect that a report was wrong if you've thrown away the fact that a different report ever existed.

Separate them and the write model stops being a judgement call. Reports append, always. There is no UPDATE statement anywhere in this codebase that touches health data. Current truth is something you derive instead of something you maintain.

It's the difference between a whiteboard and a logbook.

Four words I'll use for the rest of this:

Observation: what a metric was on a given day
Report: a source telling you, at a specific time, what it thinks an Observation was
Observed Day: the calendar day being described, in one fixed timezone
Restatement: a later Report that disagrees with an earlier one about the same Observed Day

Those first two are why I have two row counts and both are correct. 73,210 Reports. 69,613 distinct Observations. The gap is every time something changed its mind, and under the old schema that gap was zero by construction.

Look at where the weight sits in that second definition. At a specific time. That timestamp is what orders Restatements, and ordering Restatements correctly is the entire job. Under the old pipeline it was the file's modification time. A file iCloud had placed there. With an mtime iCloud does not reliably update.

The field the whole model turns on was being inferred from filesystem metadata that lies, and I had already been bitten by that metadata badly enough to rewrite the tie-breaking logic once. It never occurred to me that the same unreliable field was also deciding which version of Tuesday I believed. It's now the HTTP receipt time on the POST, which isn't an approximation of when a source told me something. It's when a source told me something.

Here is what changing its mind looks like

Basal energy for August 9th, every Report in the order it arrived:

value     reported_at (America/Chicago)
718.42    2026-08-09      <- the day, in progress
1746.06   2026-08-09
1817.51   2026-08-09
1842.11   2026-08-10      <- the day is over now
1834.03   2026-08-10         and the number goes DOWN
2319.02   2026-08-10
2319.02   2026-08-11      <- settles, two days later

The transition from 1842.11 to 1834.03 is the one that matters. A day still in progress can only accumulate, so a rising number proves nothing. A number going down on a day that already ended is Apple revising history after the fact.

Almost every time-series database ever built assumes that doesn't happen. Write once, read forever, the past is immutable, timestamps move in one direction only. It's such a load-bearing assumption that plenty of these systems list it as a feature.

My health data has not read the marketing copy.

Where TimescaleDB stops being incidental

What replaced the laptop, before we get to the schema: Health Auto Export now posts straight to a Vercel function on a daily schedule, a scheduled job pulls lifting history from Liftosaur, and both land in TimescaleDB on Tiger Cloud. No files, no iCloud, no Mac. A Next.js app reads it and tells me whether I hit protein, which is a separate post.

That change alone deleted the 150 lines and, more to the point, made Report Time a real measurement instead of an inference.

It also turned up something I hadn't gone looking for. Once nothing was reading files hourly, there was no reason not to ask HealthKit for everything it had, so I did, and it handed back 87 MB of JSON going back to January 2016. Ten years of resting heart rates and step counts and body weights had been sitting on my phone the entire time. The old pipeline could see three months of it, because three months was when I'd set it up, and it had never occurred to me to ask for more. That backfill loaded in 2.2 seconds and quadrupled the useful history of the whole project before I'd written a single interesting query.

Everything past this point is a modeling argument you could implement on any relational database, and for most of this post's length that is exactly what I would tell you to do.

Here it stops being true.

The Reports table is a hypertable partitioned on observed_on, with no primary key and no unique constraint. That's not sloppiness, it's the point: uniqueness would make Restatement an error, and Restatement is the normal path.

Current truth is a continuous aggregate.

CREATE MATERIALIZED VIEW observations_daily
WITH (timescaledb.continuous) AS
SELECT time_bucket(INTERVAL '1 day', observed_on) AS observed_on,
       metric,
       last(value, reported_at)  AS value,
       last(unit,  reported_at)  AS unit,
       max(reported_at)          AS last_reported_at,
       count(*)                  AS report_count      -- >1 means it was Restated
FROM observations
GROUP BY 1, 2;

Sit with last(value, reported_at) for a second. That is last-write-wins. It is precisely the semantics ON CONFLICT DO UPDATE was giving me, expressed as an aggregate instead of as a destructive write, and every losing write is still there to query.

That one line is most of what the migration bought me, and everything else in this post is housekeeping around it.

report_count is the part I didn't expect to lean on. It's just count(*), but it means every row in the view carries whether it has ever been argued about.

How often does this actually happen

I asked three times and got three answers, all correct, spanning two orders of magnitude.

the question I asked                                          answer
of all 69,613 Observations, how many have >1 Report?            0.6%
of Observations on days the live pipeline has touched,
   how many have >1 Report?                                    53.6%
of Observations the pipeline first saw live, how many had
   their VALUE change after that day had already closed?       69.3%

Zero point six percent is junk, diluted by ten years of backfill that loaded once and has never been revised because nothing has looked at it since.

Fifty-three point six is better and still wrong for my purposes, because "more than one Report" counts today's step count ticking upward all afternoon. That's a day accumulating, not history changing.

The third one is the claim. Of the Observations this pipeline has watched land in real time, 69.3% had their value change after the day they describe was already over. That's the majority path, not an edge case I went hunting for.

It needs two caveats and it's going to need them forever. It's 140 of 202 Observations against a pipeline that has been live for five days, so read it as directional rather than as a rate. And it can only climb, because an Observation that hasn't been revised yet can still get revised tomorrow while one that has can't un-revise itself. Any figure here needs its as-of date welded on.

I couldn't have measured any of this before, because the old schema's entire design was "make this unmeasurable."

What that buys you on a bad day

Knowing how often your data revises itself is less interesting than knowing what you can do the day it goes wrong.

One evening in August my food-logging app and this site disagreed about the same day by 868 calories, both of them reading the same database. I've written up what caused that separately, because it's a TimescaleDB footgun with its own set of lessons and I diagnosed it wrong the first time. What belongs here is what the diagnosis cost.

One query. Both Reports were sitting in the log with their timestamps on them, so I could see the number the page was serving, the number that had arrived after the page stopped looking, and the five hours between the two that explained the whole thing.

Under the old schema the later write would have overwritten the earlier one and left nothing behind. I'd have had a wrong number on a page, no way to know it was wrong, and no way to work out when it had become wrong.

Append-only didn't prevent that bug. It made the bug legible, which at 9pm in a grocery store turns out to be worth considerably more.

A thing that was true for two and a half years and invisible

The first Liftosaur sync against the new schema failed on this:

CONSTRAINT lifting_sets_weight_sane CHECK (weight_lbs > 0)

Fifty-two sets across plank, crunch, hanging leg raise, inverted row and bodyweight squat come out of Liftosaur as 0lb. And 0lb means "no external load," which is already what NULL meant in this schema for a set logged as 3x12 with no weight segment at all.

One concept, two representations, sitting in my training history since February 2024.

Relaxing the constraint to >= 0 is the easy fix and the wrong one. Every "did I add weight this week?" query would then need > 0 instead of IS NOT NULL, and AVG(weight_lbs) would quietly average real loads against a pile of zeroes. Normalized in the parser instead.

I want to be clear about the credit: that's a Postgres win, not a TimescaleDB one. A CHECK constraint is about as old-fashioned as database features get. SQLite is typeless and had no constraints, so those rows sat there for two and a half years as an ambiguity nothing in the system was capable of noticing.

The time-series parts of this story are the hypertable and the continuous aggregate. Everything else I got came from moving onto a relational database that has opinions.

What I'd actually ask you to do

It isn't "move your side project to a time-series database." My dataset is a rounding error, the performance argument at my size doesn't exist, and you shouldn't let anyone including me cite my 73,000 rows as evidence that you need anything at all.

My suggestion is smaller than that, and more annoying. Go find out whether your data revises itself.

Most people have never checked, and the reason is that upsert makes it unfalsifiable. If your write path is ON CONFLICT DO UPDATE, a source that quietly restates history looks exactly like a source that doesn't. There is no query you can run. The evidence was destroyed at write time, by you, deliberately, in a line of code that looked completely reasonable.

Count how many of these are true where you work:

Something upstream can restate a value for a day that has already closed
Your only record that a value ever changed is an updated_at column
You cannot answer "what did we think this number was last Tuesday?"
A sync that succeeds and delivers nothing looks identical to one that succeeds and delivers everything
Your dashboard reads from a materialized view and nobody has checked what its watermark is doing

One is fine. Two is worth an afternoon. If you got four, you don't have a data pipeline, you have a very confident rumor.

The fix isn't a migration. It's one question, asked before you design the table: is this an observation about a day, or a report that arrived at a time?

Get it right and most of the rest falls out.

Two follow-ups to this one. Every number I didn't measure was wrong is the confessional: five figures in this project that I never checked against the real thing, and the cheap arithmetic that would have caught each one. Don't give the model SQL is about the app on top, and why its chat interface has thirteen typed tools instead of a query box.

I Contain Multitudes (and Also Three Git Repos)

Matty Stratton — Mon, 06 Jul 2026 01:17:28 +0000

My blog is older than most of the tools I use to run it. The oldest posts started life on LiveJournal sometime in the early 2000s, got dragged through a WordPress import at some point in the mid-2000s, spent the better part of a decade as a Hugo site, and, about a week ago, moved into an Astro 5 site that reproduces every one of those old URLs byte for byte. That's 2,630 posts spanning 2001 to 2020, frozen exactly where they landed.

At the same time, my speaking site (106 talks going back to 2012) moved off Notist and onto something I actually own. And the tool that syncs my dev.to drafts with git finally works the way it was supposed to the whole time, instead of the way it actually did for a while.

All three of those used to be separate repos. As of earlier today, they're one monorepo, with the real git history from all three preserved, not squashed into "initial commit" and called a day. Here's the tour: how the two sites work, how dev.to fits into either of them, and a couple of things that broke in interesting ways along the trip.

The shape of it today

Three systems, one person, now one repo:

mattstratton.com is the personal site. It carries the 2,630-post legacy archive and a newer, general-purpose /writing/ section for anything I want to write that isn't archival.
speaking.mattstratton.com is the talk archive: every deck, every video, every event, self-hosted.
mattstratton-dev-to isn't a website at all. It's a small tool that keeps dev.to drafts and this git repo in sync, and it's the thing that lets a post published on dev.to also show up natively on mattstratton.com, which is what's about to happen to this exact post.

They're merged into one monorepo now, but they're still three genuinely separate concerns underneath, with their own configs and their own reasons for existing. Let's take them one at a time.

mattstratton.com: preserving twenty years of receipts

The current site is Astro 5 and Tailwind v4. The single rule that shaped every other decision in the migration: URL preservation is the prime directive. astro.config.mjs sets trailingSlash: 'always' and builds in directory format specifically to reproduce the old Hugo URLs exactly, which in turn had reproduced the WordPress URLs before that. Old inbound links, whether from a 2009 blog roll or a conference site linking a talk recap from 2014, still resolve. Nobody has to fix a dead link because I decided to rewrite my site in a different framework.

The posts collection is the frozen 2001 to 2020 archive, bulk-converted from Hugo. It doesn't grow. It just needs to keep existing. Everything new goes into writing, and that one's got more going on than I expected when I started writing this post.

The field guide: my own posts plus the good stuff I wrote elsewhere

/writing/ used to be scoped much more narrowly. The working plan before this project had it locked to Postgres-focused, authority-building content, an idea inherited from a content strategy document written for a completely different audience than the one reading my personal blog. The pushback that killed that scoping was simple: I contain multitudes, and a personal site that can only hold one topic isn't really personal anymore.

What's actually interesting about /writing/ now, though, is that it isn't only my own posts. It's a merge of two genuinely different things:

Native entries in src/content/writing/, defined by the schema in content.config.ts: title, description, pubDate, topics, draft, an optional part for a curated four-part Postgres arc, and an optional canonicalUrl for when the real original lives somewhere else entirely.
A hand-maintained list of external links to posts I've written for my employer, Tiger Data, defined in field-guide.ts:

export interface FieldGuideLink {
  title: string;
  description: string;
  part: "mechanics" | "limits" | "traps" | "decision";
  url: string;
}

There are 14 of those right now, all pointing at tigerdata.com, each slotted into one of the same four part buckets native posts can opt into. writing.ts normalizes both shapes into one common GuideItem (title, description, href, external) so the template can render them identically, native entries first within each part, external links after, no interleaving by date. The one visual tell is a small "tigerdata.com ↗" badge next to external titles. No new tab, just an honest label about where you're about to land.

The newsletter: Buttondown does the sending, Astro just serves the pages

/newsletter/ works the same way as most of this site: fetch at build time, serve static files forever. buttondown.ts is an Astro content-layer loader that calls one endpoint, GET /emails?ordering=-publish_date against Buttondown's API, follows pagination until it runs out of pages, and hands the result to Astro as the newsletter collection. Every issue page, the archive index, and the RSS feed are then just static output from a normal getCollection() call, same as any local markdown file.

Two details worth calling out for anyone tempted to do the same thing:

If BUTTONDOWN_API_KEY isn't set, the loader logs a warning and returns an empty collection instead of failing the build. That's not an accident: it means anyone can clone this repo and build it locally without needing my API key.
Buttondown stores each issue's body as Markdown, so the loader runs it through marked.parse() before it ever reaches a template. The site never touches raw HTML from the API.

const key = import.meta.env.BUTTONDOWN_API_KEY ?? process.env.BUTTONDOWN_API_KEY;
if (!key) {
  logger.warn("BUTTONDOWN_API_KEY not set: newsletter archive will build empty.");
  return;
}

speaking.mattstratton.com: getting my slides back from a CDN I don't own

The old speaking site lived on Notist, and Notist had two problems that eventually became one problem: video embeds had already started quietly breaking, and every slide deck was served off Notist's CDN. The day that account lapses, the images and PDFs go with it. A core part of a speaker's professional identity, every talk I've ever given, was living in someone else's database with a thin export option.

So the new site's whole design goal is asset ownership and durability. Plain content in my own repo, on my own domain, that keeps working with no third-party dependency that can be shut off or go quietly stale. Not a redesign. A portability project.

The interesting piece is the slide pipeline, because it runs entirely locally, before a commit ever happens, and never on the deploy host:

originals/{id}.pdf --optimize(gs, 300dpi)--> public/slides/{id}.pdf --rasterize--> public/slides/{id}/{n}.webp
   (gitignored, full-res)          (committed, served, downloadable)     (committed, served, viewer images)

The reason it has to run locally: static hosts don't give you root, and you need root (or at least a real package manager) to run pdftoppm and gs. Trying to shell out to Ghostscript from inside a Netlify build is a fight you will lose. Doing the rasterization on my own machine and committing the output keeps the actual deploy build a boring, fast, host-agnostic astro build.

Video embeds got the same "own it, don't proxy it" treatment. Instead of reproducing Notist's approach (a proxy that, again, had already started breaking), each talk stores a plain provider and video ID in frontmatter, and the page renders a lightweight embed facade that only loads the real player on click.

The current numbers: 106 talks from 2012 to 2026, 93 events, 36 videos, 3,684 slide images. All of it committed, none of it one CDN outage away from disappearing.

Making the talks searchable

Video is the one asset class the speaking site doesn't fully own. It can host the reference, but not the file itself. What it can own is the transcript, and that turned into a genuinely useful feature: full-text search across every talk I've ever given.

Raw transcripts come from YouTube's auto-generated captions, pulled by scripts/transcripts.ts via yt-dlp, cleaned up, and written to public/transcripts/{id}.txt. Auto-generated captions are rough: no punctuation, mangled proper nouns, every "um" and "uh" transcribed faithfully. A transcript-cleanup Claude Code skill handles the cleanup pass, with a strict ruleset: fix punctuation, capitalization, and proper nouns, remove disfluencies, but never reword, paraphrase, or reorder anything actually said. When in doubt, the instruction is to leave the text alone rather than guess.

Search itself runs client-side against two separate JSON payloads, built at deploy time:

search-index.json.ts is small: title, abstract, event, tags, year, per talk. Loaded on first open of the search box.
deep-index.json.ts is the heavy one, concatenating each talk's transcript and slide text into a single searchable blob, fetched lazily only once you actually type a query:

const parts = [readTranscript(talk.id), readSlideText(talk.id)].filter(Boolean);
if (!parts.length) continue;
records.push({ url: talkUrl(talk), text: parts.join(" ").replace(/\s+/g, " ") });

Search.astro builds a Fuse.js fuzzy index over each payload and merges the results, so searching for a phrase I actually said mid-talk, not just a word in the title, finds the right talk. No server, no database, just two static JSON files and a fuzzy-matching library doing all the work in the browser.

Three repos become one

The three-repos-in-one-monorepo move wasn't really about tidiness. Managing three repos independently was mild friction, sure, but the actual trigger was realizing that between a frozen archive and a newly-scoped /writing/ section, there was no home left on my own site for general writing. Once that was the real problem, "merge some repos" turned into "fix the architecture, and while we're in there, get dev.to crossposting actually working."

The mechanism for the merge itself was git subtree add, not a squash and not a filter-repo rewrite. That preserves full commit history from both source repos as real, verifiable ancestry, not just "the files are here now, trust me." Both source repos were young (about 50 and 22 commits respectively), so this wasn't decades of archaeology to protect. It was doing it right on principle, which is its own kind of satisfying.

A few things bit us on the way that are worth flagging if you're ever tempted to merge repos that each bring their own CI:

GitHub Actions workflows are only discovered at the true repo root's .github/workflows/, never in a subdirectory. The dev.to workflows got left nested under the subproject's own .github/workflows/ after the initial merge, which made them completely invisible to GitHub. No error. No warning. gh workflow list just didn't show them, and they silently never ran again.
Netlify doesn't scope rebuilds by subdirectory on its own. Every push rebuilds every connected site unless you add an explicit ignore check in each site's own netlify.toml. And when Netlify skips a build for having no relevant changes, it shows that as "Canceled build due to no content change," which reads exactly like a failure in your inbox even though nothing is actually wrong.
"Base directory" and "Package directory" are different Netlify settings, and the re-link flow for a repo with no npm workspace only shows you Base directory. Package directory just never appears. Worth reading the actual docs instead of assuming, which is a sentence I apparently still need to relearn every few years.
astro check doesn't respect subproject boundaries. Run from the monorepo root, it scanned an unrelated subproject's content collections using the other subproject's generated types and produced over 200 false type errors. One explicit exclude in tsconfig.json took that down to 3, all pre-existing and unrelated.

If two or more of those apply to whatever you're about to merge, budget yourself an extra afternoon.

dev.to: ownership, not direction

The dev.to sync tool is built around one idea I'd genuinely recommend to anyone syncing content between a platform and git: ownership, not direction. The full mental model lives in the repo's CLAUDE.md, but the short version:

It's tempting to think of this as bidirectional sync, keep dev.to and git in lockstep, push changes both ways. Don't do that. It produces an endless phantom-diff loop where each side keeps thinking it's the one with the real version. Instead, a post is dev.to-owned while it's being drafted, and git ignores it entirely. Once a human merges an import PR, it's git-owned forever, marked by the presence of an id field in its frontmatter. Ownership transfers exactly once, at a deliberate moment, and it never automatically flips back.

Two small workflows do the actual work. devto-import.yml runs on a cron, pulls any newly-published dev.to posts, and opens a PR for review, never touching a file that already has an id. devto-publish.yml runs on push to files under posts/, and pushes local edits back to dev.to, writing the id back on a post's very first publish. Their domains never overlap, which is the entire point.

The crosspost pipeline (and yes, this post is going through it)

Once a post is git-owned, I can opt it into crossposting by adding crosspost: true to its frontmatter, which republishes it as a native entry in mattstratton.com's /writing/ collection and rewrites the dev.to post's canonical_url to point back at mattstratton.com, via crosspost-devto.ts. That flag only gets added after a post already has an id, meaning it's already live on dev.to. It's a deliberate, later opt-in, never part of the initial draft template. This post is a good example of the "before":

---
title: "I Contain Multitudes (and Also Three Git Repos)"
published: false
description: "..."
tags: [astro, webdev, showdev]
---

No id, no crosspost, no canonical_url. Once this is published and I decide it belongs on mattstratton.com too, it'll pick up all three, the same way decouple-release-from-deploy.md already has:

id: 4061454
date: "2026-07-03T15:43:16Z"
crosspost: true
canonical_url: "https://www.mattstratton.com/writing/decouple-release-from-deploy/"

The design detail I actually like: this collapses into one atomic commit, not a two-phase publish-then-circle-back dance. mattstratton.com's URL for a crossposted piece is fully deterministic from the filename before any build even happens. dev.to's own article ID is server-assigned and unknowable in advance. So one commit creates the new /writing/ entry and rewrites the dev.to source's canonical_url in the same diff, and one push correctly triggers both the Netlify deploy and dev.to's existing publish workflow, without anyone babysitting a second step.

One trap worth naming because it's the kind of thing that looks obviously fine until it isn't: the writing schema has had an optional canonicalUrl field since the very first Astro migration commit, for a case that had never actually come up: a native /writing/ entry that's really a copy of something whose true original lives elsewhere, like a mirrored Tiger Data post. Before the crosspost script existed, the only place that field showed up at all was a commented-out line in the placeholder template file, # canonicalUrl: ... # set when cross-posted. Nobody had ever actually set it on a real post. For a dev.to crosspost, though, mattstratton.com is becoming the canonical source, the opposite of what that field was reserved for, so the crosspost script has to know to leave it unset on the entries it generates instead of reaching for an already-named field out of habit.

A few weird-ass bugs, for flavor

This post is meant to be "here's how it's set up," not "here's a bug report," but a couple of the failures along the way are too good not to mention briefly.

The best one: the publish workflow started failing with a 422 on any post whose canonical_url changed after the first publish, with the error body {"error":"Tried to load unspecified class: Time","status":422}. Root cause was a full YAML round-trip silently dropping quotes from a timestamp that doesn't strictly need them under the JS YAML library's own rules:

# before the fix (breaks dev.to's Ruby backend)
date: 2026-07-03T15:43:16Z
# after (quoted, parses fine on both sides)
date: "2026-07-03T15:43:16Z"

Perfectly legal YAML either way, by the JS library's rules. But dev.to's backend is Ruby, and Ruby's YAML parser auto-detects that now-unquoted, ISO-8601-shaped scalar as a native Time object, which its safe loader then refuses to instantiate. Two implementations of "the same" file format, quietly disagreeing about what a bare string is allowed to become. Fixed by doing a targeted single-line replace on just the canonical_url line instead of re-serializing the whole file.

A few smaller ones, quickly:

Two files edited in a different tool picked up Windows line endings, and crosspost: true\r parses as the string "true\r", not the boolean true. Those two posts just silently never showed up as eligible.
A 7-part series had dev.to's actual Series feature turned on for exactly 2 of the 7 posts, predating any of this tooling.
Rewriting internal links across that same series hit a substring-replace bug where a typo'd slug happened to be a literal prefix of a different, correct slug. Fixed by sorting replacements longest-slug-first.

The fun stuff: memory and gains

Two smaller pieces worth a callout because they're genuinely neat and don't fit anywhere else in this tour.

The speaking site's Claude Code skills (adding a new talk, cleaning up a transcript, resyncing talk memory) don't need memory.build to work. They ran fine without it. But they now also include it, a permanent memory layer for AI agents, so that when I'm working with an agent on content, it can pull up what it already knows about a talk or a previous session instead of me re-explaining context every single time. Nice to have, not load-bearing.

And /fitness pulls my workout history straight from Liftosaur's API at build time. The reason it exists at all: Liftosaur's own public profile page just didn't show as much as I wanted, no real trend view, nothing I could link people to that told the whole story. Liftosaur doesn't hand back tidy JSON for a workout either; it returns a compact Liftoscript-text blob, so a small parser extracts the date, program, exercises, and sets from that text. Personal records and trend sparklines get computed from that parsed data at render time, not fetched as a separate call.

What's still on my plate

The crosspost trigger right now is a manual CLI command I have to remember to run. The fix I actually want: since the dev.to workflow is already entirely PR-centric (import arrives as a PR, id gets written back as an auto-commit on that same push, never a second spawned PR), the crosspost step should follow the exact same shape. A GitHub Action on pull_request that detects crosspost: true, generates the /writing/ entry, and pushes it as an additional commit onto the same PR, instead of a manual script run or a redundant second PR. I filed an issue for it while writing this post, because I'd apparently been assuming for a while that one already existed and it hadn't.

A couple of others I'm actually looking forward to: a map of everywhere I've spoken on the speaking site (the event data already has lat/lng, so this should be a fun afternoon, not a project), and real hero and thumbnail image design for /writing/ and the legacy archive, since the crosspost script currently papers over that gap by embedding the cover image inline in the post body instead of rendering it properly. There's also the usual pile of housekeeping (a master to main rename, a Node 24 upgrade) that's real but not exactly a fun read.

None of it was urgent enough to hold up shipping the parts that already work. That's usually how the good list gets built anyway.

Your Agent Didn't Break Prod. Your Pipeline Did.

Matty Stratton — Fri, 03 Jul 2026 15:43:16 +0000

Picture a pipeline that looks pretty reasonable on paper. An agent opens pull requests. CI gates the merge to main: lint, tests, build, all green or it doesn't land. A scheduled job periodically promotes whatever's sitting in staging straight to production. No individual approval per feature. Just a batch cutover on a timer.

That pipeline will absolutely, eventually, wreck your week.

Not because the agent did anything malicious. Because two very different questions got quietly collapsed into one gate: "did this pass CI" and "is this safe for a real person to see right now." Those have never been the same question, not for humans and not for robots. We just used to have enough friction in the deploy process that the gap between them rarely mattered.

I've written before about the scaffolding that lets a non-engineer safely drive a coding agent against a real codebase. Rules, skills, hooks. Three layers of paranoia built into the system instead of relying on any one person's vigilance on a random Friday. That post was about the merge gate: what stops garbage from landing on main.

Part of that merge gate is worth calling out on its own: a second pass on the same PR, same harness, different system prompt, catches things the first pass missed. You don't need a different vendor or a different model for that to work, just a fresh set of eyes that didn't write the code. I wrote more about why that works here.

This post is about the gate after that one. Passing CI and landing on main solves exactly one problem, and it is not the problem of "will my users see something half-finished this afternoon."

I've been talking about shifting things left in the pipeline for the better part of a decade, usually about security. Same instinct, one checkpoint further down the line: not just "is this code safe to merge," but "is deploying this code, right now, safe."

Continuous delivery is not continuous deployment

This isn't a new idea. It's an old one that a lot of teams politely ignored for a decade, mostly because deploys used to be scary enough that nobody wanted to do more than one a sprint.

Continuous delivery means every merge is releasable. It does not mean every merge is released. Continuous deployment collapses those two things into the same action, and that's a choice you make on purpose, not a default you inherit by moving fast.

If your pipeline treats "merged" and "live" as synonyms, you've opted into continuous deployment without ever deciding to. The fix isn't slowing the pipeline down. It's separating the two decisions so a merge event and a "customers can see this" event stop being the same button.

Feature flags are one popular way to do that separation, and if you already run one, great, keep running it. But a flag is a mechanism, not the point. I don't run a feature-flag system myself, and I still get the same separation. What matters is the decoupling, not the specific tool you use to get it.

In case it's not obvious what one even looks like: a feature flag, at its most embarrassingly simple, is a boolean and an if statement.

if (flags.newInvoiceExport) {
  renderNewExport()
} else {
  renderOldExport()
}

You do not need a vendor with a pricing page to get started. A config value, an environment variable, a column on a settings table, all of that counts as day one. Upgrade to something like LaunchDarkly or Unleash once the dumb version is the thing slowing you down, not before.

Put a gate on the release event, not just the merge event

My own setup looks like this: PRs merge to main, but main isn't what's live. A separate release step promotes main to a production branch, and that promotion only happens after I explicitly say go. Nothing gets pushed to production on a timer, and nothing gets pushed because a batch of unrelated changes happened to be sitting around.

Once that promotion kicks off, it isn't done just because Vercel says "build succeeded." The release process waits until Vercel confirms the new build is actually the one serving traffic, then runs an automated check against production itself: hit a handful of endpoints that have to work, confirm they do, and only then call the release finished. If that check fails, I find out. A user does not.

There's a second, slower layer after that: a manual pass through the specific things that changed in this release, because an automated check can tell you the server responds, not that the feature behaves the way you meant it to.

None of that requires a flag anywhere. The gate isn't "does this code know how to hide itself." The gate is "does a human, and then a machine, and then a human again, all get a chance to say no before this reaches a real user." Feature flags earn you a fourth layer, an inside-the-code one, on top of that. Nice to have. Not the load-bearing part.

An automated check is monitoring with a head start

I've spent a lot of years on the incident response and observability side of this industry, enough to have given entire talks on it. The lesson that refuses to go out of style: an automated check after a release doesn't exist to catch every possible bad deploy. It exists to catch the slow discovery of a bad deploy.

A user hitting your bug is monitoring too. It's just the worst possible kind, because you find out from a support ticket instead of a dashboard, and by the time the ticket lands, it's already been somebody's bad afternoon for a while.

A post-deploy check that hits the handful of things that actually matter isn't a replacement for real observability: dashboards, alerts, tracing, whatever you've already built. It's a compressed version of the same instinct, aimed at the exact moment you're most likely to have broken something, which is right after you changed something.

The fallback: revert fast, and don't paint yourself into a corner

A release gate handles the "I'm not ready" case. It doesn't handle the "I was wrong" case, where the promotion went through, real users saw it, and it turns out there's a bug that only shows up under actual traffic. For that you need the other half: the ability to revert fast, which mostly comes down to one boring rule.

Don't ship a database migration that the previous version of your code can't survive.

This is the expand/contract pattern, and if you've been doing this long enough you've relearned it under a new name roughly every three years. Add the new column nullable. Backfill it. Write to both the old and new column. Read from the new one once you trust it. Only then, in a later release, drop the old column. Every step in that sequence is safe to roll back from, because the previous version of the app never depends on something that doesn't exist yet.

Skip that discipline and your revert button becomes decorative. You can git revert the code in about four seconds. If the migration already ran and already dropped a column the old code expects, reverting the code just gives you a fancier way to be down.

This is also, not coincidentally, incident response 101. Effective incident response runs on having a small number of pre-agreed moves you can execute without a meeting: revert, roll back, page someone, whatever applies. The worst possible moment to invent your rollback plan is during the incident it's supposed to fix. If reverting requires an engineer to reason live about which of three interdependent migrations is safe to undo, you don't have a rollback plan. You have a discussion topic, and discussion topics don't resolve outages.

Someone still has to own saying "go"

None of the automation above changes who's accountable for a release. It changes what that person is accountable with.

I've talked before, on stages instead of on a blog, about how the lifecycle of a service doesn't end the moment something reaches production, and ownership doesn't evaporate the second it ships. Somebody owns a service in production the same way somebody owns the decision to promote a build to it. If your team can't answer "who decided to release this" for a given deploy, an agent that opens PRs quickly is not actually your biggest problem.

In my setup, that person is me, for now. It might be someone else on my team next month, and the gate doesn't care which name is attached, only that a name is. The promotion step has an owner. It is never "whichever cron job happened to fire at 3am."

Same guardrails, new reason to need them

None of this is agent-specific. Gated promotions, expand/contract migrations, decoupling deploy from release: this is stuff engineering orgs have known for well over a decade. It got treated as optional at a lot of small teams because a human was in the loop on every deploy, and a human noticing "wait, this doesn't feel done yet" was doing the job the gate should have been doing.

Take that human out of the loop, or just make them faster and more numerous by handing them an agent, and the discipline you skipped stops being optional. It was never really optional. It was just being covered for by somebody's judgment call at 4:58pm on a Thursday.

The agent didn't create this problem. It just removed the friction that used to hide it.

Same as last time: if you want the receipts on how the merge-side guardrails work, that's here. This one's the other half.

What's Actually in My .zshrc (and Why)

Matty Stratton — Wed, 01 Jul 2026 15:39:44 +0000

Your shell config is mostly a graveyard. A line you added in 2019 to fix a problem you don't remember having. An alias you're afraid to remove because what if you need it. Mine is no different, but there are a handful of pieces in there that are worth explaining, not because they're clever, but because most people have never thought about why they'd want them.

This isn't a full dump of my config. If you want that, it's all on GitHub at matty-dotfiles. This post is about the config itself: the logic, the functions, the stuff that changes how the shell behaves depending on who, or what, is actually running it. (There's a quick note at the bottom on how the files are actually organized, if you're wondering why I keep saying "files" instead of "file.")

The part that actually matters: AGENT_MODE

Here's the thing that made me want to write this post in the first place.

if [[ -n "$npm_config_yes" ]] || [[ -n "$CI" ]] || [[ "$-" != *i* ]]; then
  export AGENT_MODE=true
else
  export AGENT_MODE=false
fi

Your shell used to have one audience: you. That's not true anymore. If you're running Claude Code, or any other coding agent that shells out to run commands on your behalf, your shell now has a second audience that doesn't want the same things you do. It doesn't want thefuck to interactively suggest a correction. It doesn't want a confirmation prompt before rm deletes something. It doesn't want your fancy multi-line prompt burning tokens or confusing a parser.

So I detect it. If npm_config_yes is set, or CI is set, or the shell isn't interactive ($- doesn't contain i), I flip AGENT_MODE on. Later in .zshrc_shared, that flag does real work:

if [[ "$AGENT_MODE" == "true" ]]; then
  export EDITOR='nvim'
  PROMPT='%n@%m:%~%# '
  RPROMPT=''
  unsetopt CORRECT
  unsetopt CORRECT_ALL
  setopt NO_BEEP
  setopt NO_HIST_BEEP
  setopt NO_LIST_BEEP
  alias rm='rm -f'
  alias cp='cp -f'
  alias mv='mv -f'
  alias npm='npm --no-fund --no-audit'
  alias yarn='yarn --non-interactive'
  alias pip='pip --quiet'
  alias git='git -c advice.detachedHead=false'
fi

No beeps, no interactive confirmations, a boring flat prompt instead of starship, and force flags on the destructive file commands so an agent doesn't get stuck at a prompt it can't answer. EDITOR switches to plain nvim instead of code --wait, because a headless agent trying to wait on VS Code to close a file is not a fun afternoon.

I'd bet a decent chunk of you reading this have never thought about the fact that your interactive shell defaults are actively hostile to a non-interactive process. Worth fixing before it bites you.

Secrets that don't live in plaintext

source ~/keychain-environment-variables.sh

export GITHUB_TOKEN=$(keychain-environment-variable GITHUB_TOKEN)
export CHANGELOG_GITHUB_TOKEN=$(keychain-environment-variable GITHUB_TOKEN)
export BOWIE_GITHUB_TOKEN=$(keychain-environment-variable GITHUB_TOKEN)
export HOMEBREW_GITHUB_API_TOKEN=$(keychain-environment-variable GITHUB_TOKEN)
export GITHUB_PERSONAL_ACCESS_TOKEN=$(keychain-environment-variable GITHUB_TOKEN)
export BUTTONDOWN_API_KEY=$(keychain-environment-variable BUTTONDOWN_API_KEY)

keychain-environment-variable is a function that pulls a secret out of macOS's Keychain at shell startup instead of having it sit around in plaintext in a dotfile that's synced to GitHub. I did not write this myself, I adapted it from a blog post, and I only know that because the comment at the top of the file still says so. It just shells out to security find-generic-password under the hood, nothing exotic, but it means the thing I git push never has a credential in it.

It's worth calling out that this function has to live somewhere. It's not in .zshrc_shared itself, it's a separate file (keychain-environment-variables.sh) that gets sourced, and yes, it's yadm-alternated too (##os.Darwin and ##os.Linux versions, same symlink dance as the zshrc files). If you go copy the alias/export lines above without also grabbing that script, none of this works. Ask me how I know.

The `gh` alias that fixes a dumb problem

alias gh="GITHUB_TOKEN= command gh"

Small, but it earns its place. The gh CLI has its own auth flow, and it checks GITHUB_TOKEN first if it's set, which it is, everywhere, because half my other tools need it exported. Without this alias, gh quietly uses that token instead of my actual gh auth login session, and I get weird permission mismatches that take way too long to debug. This alias just unsets the variable for the one command that has opinions about it.

A shortcut for working an issue with Claude Code

issue() { claude --permission-mode plan -w "issue-$1" "/implement issue #$1" }

Type issue 412 and it spins up Claude Code in plan mode, in its own worktree named issue-412, already pointed at a slash command that implements GitHub issue #412. It's a one-liner, but it's the kind of one-liner that removes enough friction that I actually use it instead of doing the same five commands by hand every time.

atuin and starship deserve more than a name-drop

I mentioned in My Brewfile that I install both of these, but I glossed over why, so let's fix that.

eval "$(atuin init zsh)"

atuin replaces your plain old shell history file with a searchable SQLite database, and it hooks into your shell so every command gets logged with context: what directory you were in, how long it ran, whether it exited cleanly. The part that actually changed how I work is the search. Instead of mashing the up arrow forty times or grepping through .zsh_history and hoping, I hit a keybinding and fuzzy-search across every command I've ever run, filtered by directory if I want. If you sync it, that history follows you across machines too. I didn't realize how much time I spent reconstructing commands from memory until I stopped having to.

eval "$(starship init zsh)"

starship is the prompt. That's it, that's the whole job, but it does that job well: git branch and status, language versions, command duration, all rendered fast and only when relevant, so it doesn't clutter the prompt with things that don't apply to the directory you're in. The reason it matters more than "cosmetic" makes it sound is that a good prompt answers questions before you have to ask them. Am I in a dirty git tree? Which Node version is active here? Starship tells me before I type anything.

Also notice that starship shows back up in the AGENT_MODE block from earlier, sort of. When agent mode is on, I explicitly override PROMPT to something flat and boring instead of letting starship render. Fancy prompts are a UX win for a human; they're just noise (or worse, a parsing hazard) for a process reading your terminal output.

Aliases are underrated, actually

People treat aliases like a beginner's trick, something you graduate out of once you "really" know the shell. That's backwards. An alias is just muscle memory you get to define yourself, for the commands you actually run, not the ones a tutorial thinks you should run. A few from my shared config:

alias c='clear'
alias sz='source ~/.zshrc'
alias zshconfig="nvim ~/.zshrc"
alias gpom="git push origin main"
alias gitmain="git checkout main && git pull origin main"
alias cpenv='cp ~/src/github.com/timescale/tiger-den/.env ./'

c has been in my shell configs for so many decades at this point that I genuinely forget, in the moment, that c isn't actually a real command. It's clear. It has always been clear. I have simply stopped knowing that.

sz and zshconfig exist because I edit and reload this file constantly, and typing nvim ~/.zshrc##os.Darwin correctly every time is not a skill I've bothered to develop. gpom and gitmain are the ones I'd actually recommend you steal: they encode the exact git incantations you run dozens of times a day into something you can type without thinking. cpenv is hyper-specific to one project of mine, and that's fine too. Aliases don't need to be generalizable to be worth having.

The stuff I'll just mention

A few plugins and settings that do work but don't need a full section: thefuck for command correction, autojump for directory jumping, oh-my-zsh plugins like git-extras and history-substring-search, and a couple of bindkeys so option+arrow jumps by word instead of doing nothing useful:

bindkey "^[[1;3C" forward-word
bindkey "^[[1;3D" backward-word

All small. All the kind of thing you only notice once it's gone.

Bonus: why there are three files, not one

I manage my dotfiles with yadm, which supports "alternate files" keyed on things like OS. So instead of one .zshrc, I actually have .zshrc##os.Darwin and .zshrc##os.Linux, and yadm symlinks the right one to .zshrc depending on the machine. Both of those source a third file, .zshrc_shared, which holds everything that doesn't care what kernel it's running on. Same setup applies to the keychain script above.

That's really it. It's a small mechanism, not a deep one, which is exactly why it's a bonus section and not its own post. If enough people want the full "how yadm alternates work" writeup, say so in the comments and I'll do it properly.

Go poke around

The full files are in matty-dotfiles if you want the parts I skipped. If you've got a shell trick worth stealing, I want to hear about it in the comments.

Postgres Extensions Cheat Sheet: Replace 7 Databases With SQL

Matty Stratton — Sat, 02 May 2026 20:47:24 +0000

This post is a practical companion to It's 2026, Just Use Postgres. That post makes the architectural case for consolidating on Postgres. This one shows you how.

Below are working SQL examples for each use case. Every extension listed here is available on Tiger Cloud with no additional setup. If you're self-hosting, each section links to the extension's repo.

What you'll be able to do after reading this: Set up Postgres extensions for full-text search, vector search, time-series, caching, message queues, document storage, geospatial queries, and scheduled jobs. Each section is self-contained, so you can skip to what you need.

Enable Everything

Here's the full set. You probably don't need all of them. Pick the ones that match your workload.

CREATE EXTENSION pg_textsearch; -- BM25 full-text search
CREATE EXTENSION vector; -- Vector search (pgvector)
CREATE EXTENSION vectorscale; -- DiskANN index for vectors
CREATE EXTENSION ai; -- AI embeddings and RAG workflows
CREATE EXTENSION timescaledb; -- Time-series
CREATE EXTENSION pgmq; -- Message queues
CREATE EXTENSION pg_cron; -- Scheduled jobs
CREATE EXTENSION postgis; -- Geospatial

Full-Text Search (Replace Elasticsearch)

Extension: pg_textsearch (true BM25 ranking)

What you're replacing: Elasticsearch (separate JVM cluster, complex mappings, sync pipelines), Solr, or Algolia ($1 per 1,000 searches).

What you get: The same BM25 algorithm that powers Elasticsearch, running natively in Postgres. No separate cluster. No sync jobs. No data drift.

CREATE TABLE articles (
  id SERIAL PRIMARY KEY,
  title TEXT,
  content TEXT
);

-- Create a BM25 index
CREATE INDEX idx_articles_bm25 ON articles USING bm25(content)
  WITH (text_config = 'english');

-- Search with BM25 scoring
SELECT title, -(content <@> 'database optimization') AS score
FROM articles
ORDER BY content <@> 'database optimization'
LIMIT 10;

Deep dive: You Don't Need Elasticsearch: BM25 is Now in Postgres

Vector Search (Replace Pinecone)

Extensions: pgvector + pgvectorscale

What you're replacing: Pinecone ($70/month minimum, separate infrastructure, data sync), Qdrant, Milvus, or Weaviate.

What you get: pgvectorscale uses the DiskANN algorithm (from Microsoft Research). On a 50M vector benchmark, it achieved 28x lower p95 latency and 16x higher throughput than Pinecone at 99% recall.

CREATE EXTENSION vector;
CREATE EXTENSION vectorscale CASCADE;

CREATE TABLE documents (
  id SERIAL PRIMARY KEY,
  content TEXT,
  embedding vector(1536)
);

-- High-performance DiskANN index
CREATE INDEX idx_docs_embedding ON documents USING diskann(embedding);

-- Find similar documents
SELECT content, embedding <=> '[0.1, 0.2, ...]'::vector AS distance
FROM documents
ORDER BY embedding <=> '[0.1, 0.2, ...]'::vector
LIMIT 10;

Auto-sync embeddings with pgai

No more manual embedding pipelines. pgai regenerates embeddings automatically on every INSERT and UPDATE.

SELECT ai.create_vectorizer(
  'documents'::regclass,
  loading => ai.loading_column(column_name => 'content'),
  embedding => ai.embedding_openai(
    model => 'text-embedding-3-small',
    dimensions => '1536'
  )
);

Every row stays in sync. No batch jobs. No drift.

Hybrid Search: BM25 + Vectors in One Query

This is where Postgres consolidation pays off immediately. Combining keyword search and semantic search in other stacks requires two API calls, result merging, failure handling, and double the latency. In Postgres, it's one query.

Simple weighted hybrid

SELECT
  title,
  -(content <@> 'database optimization') AS bm25_score,
  embedding <=> query_embedding AS vector_distance,
  0.7 * (-(content <@> 'database optimization')) +
  0.3 * (1 - (embedding <=> query_embedding)) AS hybrid_score
FROM articles
ORDER BY hybrid_score DESC
LIMIT 10;

Reciprocal Rank Fusion (for RAG applications)

WITH bm25 AS (
  SELECT id, ROW_NUMBER() OVER (ORDER BY content <@> $1) AS rank
  FROM documents LIMIT 20
),
vectors AS (
  SELECT id, ROW_NUMBER() OVER (ORDER BY embedding <=> $2) AS rank
  FROM documents LIMIT 20
)
SELECT d.*,
  1.0 / (60 + COALESCE(b.rank, 1000)) +
  1.0 / (60 + COALESCE(v.rank, 1000)) AS score
FROM documents d
LEFT JOIN bm25 b ON d.id = b.id
LEFT JOIN vectors v ON d.id = v.id
WHERE b.id IS NOT NULL OR v.id IS NOT NULL
ORDER BY score DESC LIMIT 10;

One query. One transaction. One result set.

Time-Series (Replace InfluxDB)

Extension: TimescaleDB (21K+ GitHub stars)

What you're replacing: InfluxDB (separate database, Flux or limited SQL), Prometheus (metrics only, not application data).

What you get: Automatic time-based partitioning, compression up to 95%, continuous aggregates for fast dashboards, and full SQL. Your time-series data lives alongside your relational data with JOINs and ACID guarantees.

CREATE EXTENSION timescaledb;

CREATE TABLE metrics (
  time TIMESTAMPTZ NOT NULL,
  device_id TEXT,
  temperature DOUBLE PRECISION
);

-- Convert to a hypertable (automatic time partitioning)
SELECT create_hypertable('metrics', 'time');

-- Query with time buckets
SELECT time_bucket('1 hour', time) AS hour,
       AVG(temperature)
FROM metrics
WHERE time > NOW() - INTERVAL '24 hours'
GROUP BY hour;

Lifecycle automation

TimescaleDB handles retention and compression policies so you don't have to build cron jobs for data management.

-- Automatically drop data older than 30 days
SELECT add_retention_policy('metrics', INTERVAL '30 days');

-- Compress data older than 7 days (up to 95% storage reduction)
ALTER TABLE metrics SET (timescaledb.compress);
SELECT add_compression_policy('metrics', INTERVAL '7 days');

Case study: Plexigrid went from 4 databases to 1 and got 350x faster queries.

Caching (Replace Redis)

Feature: UNLOGGED tables + JSONB (built into Postgres, no extension needed)

What you're replacing: Redis for simple key-value caching scenarios.

What you get: In-memory-speed storage without WAL overhead. Good for session data, temporary lookups, and simple caches. No separate service to operate.

When to keep Redis: If you need pub/sub, sorted sets, Lua scripting, or complex data structures, Redis is still the better tool for those specific jobs.

-- UNLOGGED = no WAL overhead, faster writes
CREATE UNLOGGED TABLE cache (
  key TEXT PRIMARY KEY,
  value JSONB,
  expires_at TIMESTAMPTZ
);

-- Set with expiration
INSERT INTO cache (key, value, expires_at)
VALUES ('user:123', '{"name": "Alice"}', NOW() + INTERVAL '1 hour')
ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value;

-- Get
SELECT value FROM cache
WHERE key = 'user:123' AND expires_at > NOW();

-- Schedule cleanup with pg_cron
SELECT cron.schedule('cache_cleanup', '0 * * * *',
  $$DELETE FROM cache WHERE expires_at < NOW()$$);

Message Queues (Replace Kafka)

Extension: pgmq

What you're replacing: Kafka or RabbitMQ for task queues and simple event processing.

What you get: A lightweight message queue inside Postgres. Send, receive with visibility timeouts, and delete after processing. Transactional with the rest of your data.

When to keep Kafka: If you need high-throughput event streaming across dozens of services, consumer groups, exactly-once semantics, or multi-datacenter replication, Kafka is purpose-built for that.

CREATE EXTENSION pgmq;
SELECT pgmq.create('my_queue');

-- Send a message
SELECT pgmq.send('my_queue', '{"event": "signup", "user_id": 123}');

-- Receive (with 30-second visibility timeout)
SELECT * FROM pgmq.read('my_queue', 30, 5);

-- Delete after processing
SELECT pgmq.delete('my_queue', msg_id);

Alternative: SKIP LOCKED pattern (no extension needed)

For simple job queues, Postgres has a built-in pattern using FOR UPDATE SKIP LOCKED:

CREATE TABLE jobs (
  id SERIAL PRIMARY KEY,
  payload JSONB,
  status TEXT DEFAULT 'pending'
);

-- Worker claims a job atomically
UPDATE jobs SET status = 'processing'
WHERE id = (
  SELECT id FROM jobs WHERE status = 'pending'
  FOR UPDATE SKIP LOCKED LIMIT 1
) RETURNING *;

Documents (Replace MongoDB)

Feature: Native JSONB (built into Postgres since 2014)

What you're replacing: MongoDB for document storage.

What you get: Schemaless document storage with GIN indexing, plus everything Postgres gives you: ACID transactions, relational JOINs, and SQL. No separate database for your "document-shaped" data.

CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  data JSONB
);

-- Insert a nested document
INSERT INTO users (data) VALUES ('{
  "name": "Alice",
  "profile": {"bio": "Developer", "links": ["github.com/alice"]}
}');

-- Query nested fields
SELECT data->>'name', data->'profile'->>'bio'
FROM users
WHERE data->'profile'->>'bio' LIKE '%Developer%';

-- Index specific JSON fields for fast lookups
CREATE INDEX idx_users_email ON users ((data->>'email'));

Geospatial (Replace Specialized GIS)

Extension: PostGIS (the industry standard since 2001)

What you're replacing: Nothing, really. PostGIS is what most specialized GIS tools are built on. It powers OpenStreetMap and has been in production for 24 years.

CREATE EXTENSION postgis;

CREATE TABLE stores (
  id SERIAL PRIMARY KEY,
  name TEXT,
  location GEOGRAPHY(POINT, 4326)
);

-- Find stores within 5km
SELECT name,
  ST_Distance(location, ST_MakePoint(-122.4, 37.78)::geography) AS meters
FROM stores
WHERE ST_DWithin(location, ST_MakePoint(-122.4, 37.78)::geography, 5000);

Scheduled Jobs (Replace External Cron)

Extension: pg_cron

What you're replacing: External cron jobs, Kubernetes CronJobs, or Lambda scheduled triggers for database maintenance tasks.

What you get: Cron scheduling inside Postgres. Useful for cache cleanup, materialized view refreshes, data retention, and periodic aggregation.

CREATE EXTENSION pg_cron;

-- Run cache cleanup every hour
SELECT cron.schedule('cleanup', '0 * * * *',
  $$DELETE FROM cache WHERE expires_at < NOW()$$);

-- Refresh a materialized view every night at 2 AM
SELECT cron.schedule('rollup', '0 2 * * *',
  $$REFRESH MATERIALIZED VIEW CONCURRENTLY daily_stats$$);

Fuzzy Search (Typo Tolerance)

Extension: pg_trgm (built into Postgres)

CREATE EXTENSION pg_trgm;

CREATE INDEX idx_name_trgm ON products USING GIN (name gin_trgm_ops);

-- Finds "PostgreSQL" even when typed as "posgresql"
SELECT name FROM products
WHERE name % 'posgresql'
ORDER BY similarity(name, 'posgresql') DESC;

What's Next

If you want the architectural argument for why consolidating on Postgres matters (especially in the AI era), read It's 2026, Just Use Postgres.

All of these extensions come pre-configured on Tiger Cloud. Create a free database and start building.

Further reading:

Why I'm Learning ROS 2 as a Database Person

Matty Stratton — Fri, 01 May 2026 21:46:47 +0000

There's a moment that happens in every robotics company that makes it to production. The pilot worked. The robot does the thing. Now there are twenty on the floor, then fifty, then a fleet, and somebody asks: "What did the sensors look like on unit 17 during those three anomalies last quarter?"

That's when the data infrastructure question gets real. As robotics moves from lab to warehouse floor to factory line, that question is going to come up a lot more often. The default answers aren't really built for it.

I'm not a robotics engineer. Never built a robot. Never written a ROS 2 node or had an argument about MCAP vs. SQLite3 (though I'm about to). What I am is someone who's spent 20+ years watching what happens when storage decisions get made before the questions are fully understood. Log files are the classic version: great for appending, bad for answering "show me the error pattern across 200 servers from three weeks ago." The data exists. It's just not queryable. That's the shape of regret I'm talking about.

I work at Tiger Data doing developer relations for TimescaleDB. Time-series data is literally my job. When I started looking at how ROS 2 handles recorded telemetry at scale, I saw something familiar: high-frequency sequential writes, stable append rates, a recording format optimized for replay rather than analysis, no real query story for "compare behavior across 200 runs without loading everything into memory."

Oof.

rosbag2 is good at what it does. Record, replay, done. That's the right scope for it. If you've been running ROS 2 long enough to think about what happens after the bag file, you've probably felt the edge of that scope. The problem is that "done recording" is the beginning of a different problem when you're trying to understand what's happening across a fleet, over time, at scale. There's an open feature request in the rosbag2 repo that names TimescaleDB and InfluxDB by name as candidate options for exactly this. It's been open since July 2024. Zero comments.

The community noticed the gap. Nobody filled it.

So that's what I'm going to try to figure out, in public. I'm going to build a ROS 2 node that writes telemetry directly to TimescaleDB and actually query it. All of it in a public GitHub repo, commit by commit, so the decisions are visible as they get made. Document everything that breaks. The database side I know. The ROS 2 side I'm learning from scratch, and I'll be honest about that difference in real time. And to be clear: I don't actually know what any of this looks like at fleet scale. That's not false modesty. That's the whole point.

What's coming next: getting the local environment set up (TurtleBot3 is basically the hello world of ROS 2 simulation: it's what the official tutorials use, it publishes the standard topics I care about, and Gazebo runs the whole thing without me needing actual hardware*) and a post on what rosbag2 actually stores and why the format question matters once you're past replay. After that, the actual build: schema decisions, type mapping headaches, and a Grafana dashboard over live robot telemetry. The full tutorial comes last, once I've learned enough to actually teach it.

If you've ever wanted to weigh in on that rosbag2 feature request, now's a good time. And if you're working on this problem (fleet telemetry pipelines, robot data at scale, the gap between recording and understanding), I want to hear what you're running into.

* - that said, I am not opposed to asking my boss to buy me a robot

How My Coworker Who Didn't Know 'cd' Shipped to Production

Matty Stratton — Thu, 23 Apr 2026 20:30:39 +0000

This morning, our Design Lead asked me how to get her terminal into the right folder.

Tanya [6:57 AM]
my ghost isnt in tiger den anymore! GAH do i do /tiger-den
or what was the command to make it work 
in tiger den

Matty [7:14 AM]
What what?

Tanya [7:14 AM]
sorry lol
you know when i go into terminal/or ghostie
and i need to type the thing to make it so im
working in tiger den

Matty [7:14 AM]
Yes type cd tiger-den

Tanya [7:15 AM]
YES
OK CD
thank you

Tanya has been here at Tiger Data for about two weeks. In that time, she shipped a feature to our production Next.js app.

I'm not going to pretend that's a normal sentence to write.

Tanya is our Design Lead. She runs brand. She's the reason our designs look the way they do and our blog thumbnails don't look like a high school yearbook. She is not a software engineer. She had not, as far as I know, previously planned on becoming one.

She didn't become one. She just started shipping.

The feature she shipped is an internal brand hub: a searchable index of every Tiger Data brand asset (logos, typography, colors, whatever you need) plus an interactive image builder that works like Canva (if Canva had been written specifically for our team). You can upload your own images, pick from our logo library, layer in backgrounds and icons, and drop text on top. Drag everything around, resize it, line it up. Export a PNG. (The thumbnail on this post was made with it.)

The downside of teaching a designer to use the terminal is that she will want hers to look like yours. Tanya saw my Ghostty theme and my catppuccin Starship theme over a screen share and decided she wanted both. Her Claude Code statusline came next. That's an entire other post.

Hold both of these facts in your brain at the same time: Tanya is asking me what cd does this morning. Tanya shipped a real feature to a real codebase last week.

If you read my last post on coding agents and internal tooling, you know where I ended it. The caveat was that I was a solo contributor to a real codebase, and the first comment on the post called out exactly the right thing. Who owns this when you leave? That's a reasonable question. In March, my answer was "me, and that's a problem."

My answer in April is "...and also Tanya."

That's only true because of what got built alongside the agent. The agent is the interesting part of the demo. The boring part is what made it safe to hand a Next.js codebase to a designer who's still learning cd.

Here's that boring part.

The agent is not the hard part

Coding agents are very good at a lot of things. Being trustworthy is...not one of them.

I don't mean malicious. I mean if you ask an agent to fix a bug, it will often fix the bug. It will also sometimes decide the failing test is "probably flaky" and move on. Or notice a test it doesn't understand and quietly skip it. Or hit an error, try a second approach, fail, try a third approach, fail again, and by the time you look up it has deleted the function you were trying to fix. Or my favorite one: "These test failures are unrelated to my changes".

This is catchable. I catch a lot of it. I've been doing ops since before the Seinfeld finale aired, and I have been running DevOpsDays since before most of the current DevOps job descriptions existed. I read every diff before it leaves my machine and I have strong opinions about what a normal-looking CI run is supposed to contain.

I still miss things, everyone does. I rubber-stamp, I push tired, I get three levels deep on a task and stop reading carefully. Even with the paranoia cranked up, I am not reliably the last line of defense for my own work, let alone anyone else's.

And the paranoia itself is not transferable. "Notice when an agent silently dropped a test case" is not a skill you pick up in two weeks. It is not a skill most of the engineers I know pick up in two weeks, because most of them never had to. I cannot hand it to Tanya by writing a memo.

So the question is not how do I make Tanya as paranoid as I am. The question is: how do I make the system so paranoid that it doesn't matter how paranoid any of us are on a given Friday afternoon?

You build the paranoia into the system. (If this sounds familiar, it should.)

Rules are a suggestion

The first place everyone reaches is CLAUDE.md. Some people call theirs AGENTS.md if they want the file to be portable across agents that aren't Claude. Same idea. You write down the rules you want the agent to follow, drop it at the root of the repo, and the agent reads it every session.

Ours has a section called "Golden Rules". A handful of the actual rules from the actual file:

Diagnose before fixing. Read errors, trace code, explain your hypothesis before writing any fix. No guess-and-deploy.

Never dismiss failures. Test failures, CI failures, lint warnings. Investigate every one. Never call them "pre-existing" or "not my problem."

Never destructive without permission. No DROP, TRUNCATE, DELETE without WHERE.

Always use /pr to push. Never raw git push.

These are not theoretical. Each one is on the list because the agent did the thing I didn't want it to do, often enough that I eventually wrote it down. (Sometimes from running /insights in Claude Code.)

Does the agent follow them? Mostly. Does the agent ignore them when convenient? Also yes.

The failure mode is an exchange you have probably already had:

Me: "Wait, you just pushed to main."

Claude: "Oh shoot, you're right. The CLAUDE.md says to use /pr. I just... didn't."

It apologizes. It means it. It will still do it again on Tuesday.

CLAUDE.md is training; it shapes the default behavior. It does not enforce anything. Treat it like training and it is useful. Treat it like a wall and something is going to walk through the wall.

That was the first thing I had to learn. It might have take a few times.

Skills are a habit

If rules are what you write down when you want an agent to know something, skills are what you write down when you want the agent (or the human) to do something the same way every time.

A Claude Code skill is roughly: a folder with instructions, some scripts, and a slash command. Type /setup and it walks through our dev environment setup. Type /debug and it starts a structured investigation instead of letting the agent flail. Type /release and it runs the release process in the right order.

The one that matters most is /pr.

Our repo has a preflight checklist you have to pass to open a pull request. It runs lint. It runs the typechecker. It runs the tests. It runs the build. It runs a code review subagent. If any changed files touch rendered output, it runs a UI verification step. If any touched docs, it runs a docs-drift check. If any touched security-sensitive paths, it runs a security review. Only then does it actually open the PR, and even then it opens it as a draft.

All of that is one command. Tanya does not have to remember any of it. She types /pr.

This is still not enforcement. Skills are suggestions. A motivated human (or a tired agent, or a confused agent, or an agent being nudged by a tired human) can skip /pr and push directly, and nothing in the skill itself will stop them (note: the skill does try to tell the agent when it should try to run it, and it usually gets it right...but not always).

The job of a skill is to make the right way the easy way. /pr is one command. Running all of those checks by hand is eight. If typing /pr is easier than doing the alternative, the alternative stops happening. That is most of the game.

Tanya used /pr for the brand hub. She did not run lint, typecheck, tests, and build in sequence. She would not have known to! She typed a slash and a word. Everything ran.

The rest is between her and the agent.

Hooks are a wall

The rule "never push to main" lives in CLAUDE.md. The skill /pr is easier to type than the alternative. Neither of those is enforcement.

The enforcement is a pre-push git hook.

If you (or a coding agent) run git push from a machine with our repo checked out, the hook fires before the push leaves your laptop. If the branch you are on is main or production, the hook exits 1 and prints the error message I wrote specifically for the version of me that is about to do a dumb thing. The push does not happen.

If the branch is anything else, the hook runs lint, typecheck, tests, and build locally. If any of them fail, the push does not happen.

There is a flag to skip hooks, yes. If the agent tries to use it, a separate PreToolUse hook catches the command before it runs and blocks it on protected branches. And if a push somehow lands on the remote anyway, GitHub branch protection rejects it on the server side.

I did not build all three layers on day one. I built them in the order I needed them, which is to say I built each one the first time something got past the layer before it.

There is also a SessionStart hook that runs before the agent does anything. It checks that the Node version is the one the app expects, that the environment file exists, that dependencies are up to date, that the database the session is about to touch is the development database and not production. If any of that is wrong, the session opens with a warning, and the agent is told to act on the warning before doing anything else.

None of this requires the agent to cooperate. None of it requires the human to remember.

CI is the outer wall. Six jobs, parallel, on every pull request. Lint. Typecheck. Frontend tests. Backend tests across three shards. Build. Doc drift check. If any job fails, the PR cannot merge. If the PR does not have a label, a seventh job fails. Zero warnings allowed.

This is the only layer that does not care how tired anyone is, how confused the agent is, or what quiet thing got dropped on the way through. It just says no.

Tanya has never pushed to main. She could not push to main if she tried. Neither can I. We have confirmed.

The scaffolding is the product

Here is the funny thing about all of this: none of it is new.

Linters. CI. Pre-commit hooks. Code review. Required labels. Branch protection. Engineering teams have been writing these guardrails for the humans on the team for two decades. What changed is that the same guardrails now work on the agent. And because the agent does most of the typing, they work for the non-engineer driving the agent too.

The three layers are just discipline given shape. Rules tell the agent what you want, skills make the right thing the easiest thing, hooks enforce the non-negotiables. That stack is not new. It is what engineering has been doing for twenty years, and it works.

What did change is the cost. A CLAUDE.md is an afternoon. A skill is another afternoon. A git hook is an hour. A SessionStart script is an hour. Most of them I wrote in a single week, when the alternative was cleaning up after a mistake the agent had already made twice.

The agent isn't the product, the scaffolding is. The agent is really good at working inside it without stepping on anything important.

There is one piece of scaffolding I have not been able to write.

It is the call on my calendar every few days where Tanya and I hop on a screen share and work through something hand-in-hand. We have a name for these. It is "make Tanya an engineer." Sometimes we are making her Claude Code statusline look cool. Sometimes we are picking out a new text editor and making it hers. Sometimes we are walking through how the app is put together so we can figure out how to make it even more awesome.

They are still happening. They will probably still be happening in six months. I am not trying to automate them away.

There is something about a real person on the other side of a screen share that makes the work feel survivable. A CLAUDE.md will not do that. A slash command will not do that. The hooks definitely will not do that.

That is also part of the system.

Two things I owe you

First, a callback to Guilherme on the last post. You were right that Retool is bus-factor insurance. You can also roll your own. It's called a CLAUDE.md, a pre-push hook that exits 1, and an hour-long call called "make Tanya an engineer."

Second, a correction on the opener. Tanya is not the only other person shipping code to Tiger Den. A few other folks have been committing too. I made her the hero because her two-week arc was the cleanest story. Apologies to the rest of the team for the dramatic license.

Airtable, it's been real. Tiger Den is better. Tanya is proof.

Follow-up, July 2026: everything above is the merge gate; what keeps garbage off main. There's a second gate after it, between "merged" and "live," and skipping that one will wreck your week in an entirely different way. That's the other half.

This post was reviewed and approved by Tanya before publishing. Zero AI agent skills involved.

How Do PostgreSQL Indices Work, Anyways?

Matty Stratton — Wed, 18 Mar 2026 14:35:21 +0000

You've probably created a hundred indexes in your career. Maybe a thousand. You ran EXPLAIN ANALYZE, saw "Index Scan" instead of "Seq Scan," pumped your fist, and moved on.

But do you actually know what's happening underneath? Because once you do, a lot of things about PostgreSQL performance start to make a lot more sense. And some of the pain points you've been fighting start to feel less like mysteries and more like, well, physics.

It's a tree. Obviously.

The default index type in PostgreSQL is a B-tree. You knew that. But let's talk about what that actually means for your data.

When you create an index on, say, a timestamp column, PostgreSQL builds a balanced tree structure where each node contains keys and pointers. The leaf nodes point to actual heap tuples (your rows on disk). The internal nodes just help you navigate. Think of it like a phone book. (Do people still know what phone books are? I'm aging myself.)

The key thing to understand: the index is a separate data structure from your table. It lives in its own pages on disk. When you insert a row, PostgreSQL doesn't just write your row. It also has to update every index on that table. Every. Single. One.

So if you have a table with five indexes and you're doing 50,000 inserts per second, that's not 50K write operations. That's 250K+ B-tree insertions per second, plus the heap write. Oof.

You can see exactly how much space each index is consuming with \di+ in psql:

\di+ public.*

-- Or if you want programmatic access:
SELECT indexrelid::regclass AS index_name,
       pg_size_pretty(pg_relation_size(indexrelid)) AS index_size,
       idx_scan AS times_used,
       idx_tup_read AS tuples_read
FROM   pg_stat_user_indexes
WHERE  schemaname = 'public'
ORDER  BY pg_relation_size(indexrelid) DESC;

Run that on your biggest table. If you see indexes measured in gigabytes that have idx_scan = 0, those indexes are costing you writes and giving you nothing back. They're dead weight.

Pages, not rows

Here's where it gets interesting. PostgreSQL doesn't read individual rows from disk. It reads 8KB pages. Always. Even if you only want one tiny row, you're pulling in a full 8KB page.

Your B-tree is also organized into 8KB pages. Each page holds as many index entries as it can fit. For a simple index on a bigint column, you can fit a few hundred entries per page. For a compound index on (tenant_id, event_type, created_at), you're fitting fewer because each entry is wider.

When PostgreSQL traverses your B-tree, it starts at the root page, reads it, follows a pointer to the right internal page, reads that, and eventually gets to a leaf page that tells it where your actual row lives on the heap. For a table with a million rows, that's maybe three or four page reads. For a billion rows, it might be five or six. Logarithmic scaling is your friend here.

You can see this in action with EXPLAIN (ANALYZE, BUFFERS):

EXPLAIN (ANALYZE, BUFFERS) SELECT * FROM events WHERE created_at > now() - interval '1 hour';

-- Look for lines like:
--   Index Scan using events_created_at_idx on events
--     Buffers: shared hit=4 read=2

The shared hit count tells you how many pages came from the buffer cache. The read count tells you how many had to come from disk. If you're seeing high read values on a query you run frequently, your working set has outgrown your shared_buffers.

But. (There's always a but.)

The part nobody thinks about

Those leaf pages need to stay ordered. When you insert a new value that belongs in the middle of a page that's already full, PostgreSQL has to split that page. Page splits are expensive. They cause write amplification and can fragment your index over time.

For time-series data (timestamps always increasing), you mostly dodge this problem because new values go to the rightmost leaf. That's nice. But it creates a different problem: hot-page contention. Every concurrent insert is fighting to write to the same leaf page at the end of the tree.

And then there's the part that really gets you: MVCC overhead.

PostgreSQL's multiversion concurrency control means that even your index has to deal with tuple visibility. Index entries don't get removed immediately when a row is deleted or updated. They stick around until VACUUM cleans them up. So your index isn't just tracking live rows. It's tracking all the versions of your rows until the cleanup crew gets around to it.

For a high-churn table, your index can be significantly larger than you'd expect just from the row count. I've seen cases where the index is effectively 2-3x the "expected" size because of dead tuple bloat.

Here's how to check if bloat is eating your indexes alive:

SELECT relname,
       n_dead_tup,
       n_live_tup,
       round(n_dead_tup * 100.0 / nullif(n_live_tup + n_dead_tup, 0), 1) AS dead_pct,
       last_autovacuum
FROM   pg_stat_user_tables
WHERE  n_dead_tup > 10000
ORDER  BY n_dead_tup DESC;

If dead_pct is climbing above 10-20% and last_autovacuum was hours ago (or null), autovacuum is falling behind. That bloat isn't just wasting space. It's making every index scan touch more pages than it should.

Index-only scans (and why they're worth understanding)

There's one more behavior worth knowing about, because it changes how you think about index design.

Normally, PostgreSQL uses the index to find where a row lives on the heap, then goes and reads the actual row. That's two separate lookups: the index, then the heap.

But if every column your query needs is already in the index, PostgreSQL can skip the heap entirely. That's an index-only scan, and it's significantly faster.

-- This index covers both the WHERE clause and the SELECT list:
CREATE INDEX idx_events_covering ON events (created_at) INCLUDE (event_type, value);

-- Now this query never touches the heap:
EXPLAIN (ANALYZE, BUFFERS)
SELECT event_type, value FROM events WHERE created_at > now() - interval '1 hour';

-- Look for:
--   Index Only Scan using idx_events_covering on events
--     Heap Fetches: 0

The Heap Fetches: 0 is what you want. That means PostgreSQL answered the entire query from the index alone.

The catch: index-only scans only work well when the visibility map is up to date, which brings us right back to VACUUM. If VACUUM hasn't visited a page recently, PostgreSQL can't trust the index alone and has to check the heap anyway. So even this optimization depends on keeping autovacuum healthy.

Partial indexes (less is more)

One more tool that's underused: partial indexes. If you only query a subset of your data most of the time, you can index just that subset.

-- Instead of indexing every row:
CREATE INDEX idx_events_status ON events (status);

-- Index only the rows that matter:
CREATE INDEX idx_events_active ON events (status) WHERE status = 'active';

The partial index is smaller, faster to scan, and cheaper to maintain on writes. For high-churn tables where most queries filter to a small slice of data, this is free performance.

So why does this matter?

Understanding this stuff isn't just academic. It explains real problems you hit in production:

Why adding indexes slows down writes. Every index is another B-tree that needs to be maintained on every insert. It's not free. It's never been free. The cost just hides until you're at scale.

Why your queries get slower over time even though nothing changed. Index bloat from dead tuples. Pages that used to be tightly packed are now half-empty after splits and vacuuming. Your three-page-read query is now a six-page-read query.

Why VACUUM matters so much. It's not just reclaiming table space. It's keeping your indexes healthy. If autovacuum can't keep up, your indexes degrade. And if you're inserting fast enough, autovacuum can fall behind. That's not a bug. That's just the architecture working as designed.

Why partitioning helps (and then stops helping). Smaller partitions mean smaller indexes mean fewer tree levels. Great. But now your query planner has to evaluate all those partitions to figure out which ones to scan. And that planning cost scales linearly with partition count. You're trading one bottleneck for another.

The bigger picture

I wrote about this cycle more extensively in a piece about the PostgreSQL optimization treadmill. The short version: there's a pretty predictable progression that teams go through. Optimize indexes. Partition tables. Tune autovacuum. Scale vertically. Add read replicas. Each phase buys you a few months.

That's not a criticism of PostgreSQL. Postgres is an incredible database. But it's a general-purpose relational database, and its architecture reflects that. The heap storage model, MVCC, the query planner, B-trees. They're all designed to handle a wide range of workloads really well. The tradeoff is that for very specific access patterns (like time-series data at scale), those general-purpose design choices start working against you instead of for you.

Understanding how your indexes work is the first step to understanding when they stop being enough. And knowing when you're fighting the architecture instead of optimizing within it can save you months of whack-a-mole performance tuning.

But that's a topic for another day. For now, go run these queries on your biggest table:

-- How big are your indexes, really?
SELECT indexrelid::regclass AS index_name,
       pg_size_pretty(pg_relation_size(indexrelid)) AS size,
       idx_scan AS scans
FROM   pg_stat_user_indexes
WHERE  relname = 'your_table_here'
ORDER  BY pg_relation_size(indexrelid) DESC;

-- Are any of them unused?
SELECT indexrelid::regclass AS index_name,
       idx_scan
FROM   pg_stat_user_indexes
WHERE  idx_scan = 0
  AND  schemaname = 'public'
ORDER  BY pg_relation_size(indexrelid) DESC;

You might be surprised.

Coding Agents Are Actually Good at This One Thing

Matty Stratton — Sun, 01 Mar 2026 20:31:28 +0000

The discourse around AI coding tools tends to collapse into two camps: people who think they're going to replace developers, and people dunking on "vibe coding" demos that fall apart the moment you look at them sideways.

Both camps are mostly arguing about the wrong thing.

I've been using coding agents heavily for the past few months, and the use case where they've actually changed how I work isn't production applications or greenfield SaaS ideas. It's internal tooling. And that distinction matters more than people are giving it credit for.

The Airtable Problem

For years, I built internal tools the way most of us did: I found something close enough and made it work. Airtable was great for this. I built conference talk trackers, content inventories, planning dashboards... all kinds of things. The spreadsheet-meets-database model was genuinely useful, and for a while, it was the right call.

But you're always fighting two things with tools like Airtable or Notion or even Asana when you're bending them to a purpose they weren't built for. First, you fight the constraints of the tool itself: the data model it has, the views it supports, the automations it allows. Second, you fight the cost and friction of giving your whole team access to yet another SaaS platform.

At some point the juice stops being worth the squeeze. You're not building what you actually need, you're building the closest approximation that fits inside someone else's product.

Just Build the Thing

What coding agents have unlocked for me is the ability to just build the thing.

The project I've been heads-down on is called Tiger Den: an internal content management system for our Marketing team at Tiger Data. It's a Next.js app, Drizzle ORM, tRPC, Postgres (running on Tiger Data, natch). A real web app with a real database, exactly structured for how we actually work.

Tiger Den manages our content library, tracks blog posts and videos, stores voice profiles for different authors so we can make sure our content matches our voices, generates UTM links, and surfaces the right content for the right workflow. It's not a product. It's not trying to be. It's a tool that fits our team's exact needs because we built it for our team's exact needs.

A few folks on the team are starting to use it. Workflows that used to involve a bunch of spreadsheet wrangling and web search gymnastics are getting simpler. It's not fully baked (it's somewhere between "mostly works for me" and "the team is starting to play with it") but it's already more useful than what it replaced (a combination of "nothing" plus "not very updated spreadsheet"), and I've been iterating on it continuously.

That iteration speed is the point.

Why Internal Tooling Specifically

The reason coding agents shine here, and why I keep coming back to this use case, is the risk profile.

When you're building a public-facing application, you have to worry about edge cases at scale, security hardening, performance under load, what happens when a user does something unexpected, what happens when a thousand users do something unexpected. The cost of getting it wrong is high.

Internal tools have a completely different calculus. The user population is small and known. The stakes for any individual bug are low. You can ship something that's 80% right and fix the other 20% next week. You can move fast and it's actually fine.

This is the Microsoft Access model, honestly. In the 90s and early 2000s, people built remarkably functional internal tools in Access (forms, reports, relational data, real logic) because the barrier was low enough that you could actually do it. Then the web happened, the complexity went way up, and that era of "just build the thing" basically ended for most people.

Coding agents are bringing it back. The barrier is low again. You can describe what you want, iterate in a tight loop, and end up with something that actually fits your use case instead of something that almost fits someone else's template.

What About Retool?

When I posted about this, someone brought up Retool — fair question. Isn't that exactly what Retool is for?

Maybe. But my reaction was: isn't that just trading one set of constraints for another? Now I'm stuck on how Retool thinks about the world instead of how Airtable thinks about the world. I haven't dug deep into Retool, so I'm not going to trash it, but the pattern is the same: you're building inside someone else's model of what your tool should be.

The thing I actually want is to build the thing I want. That's what "just use Next.js and a database" gives me.

Some Honest Caveats

I want to be careful not to oversell this, because the context matters a lot.

I'm a systems guy. Infrastructure, security, DevOps, that's my background. I could build Tiger Den without a coding agent; it would just take a lot longer because I'm coming at software development somewhat sideways. The agent collapses that time gap significantly. But I'm still making real architectural decisions, reviewing what gets generated, and understanding the codebase well enough to maintain it. This isn't "describe what you want and walk away."

Someone also asked about maintenance (a reasonable concern!). My answer: for Tiger Den specifically, I'm only writing to my own database. I'm not doing write operations against external systems, I'm not touching production data, and the blast radius of any given bug is small. That's a deliberate choice, and it's part of why internal tooling is the right framing. If I were building something that talked to our customers' data or integrated deeply with critical external systems, I'd be a lot more careful.

The low-stakes calculus stops applying the moment you have real users, real consequences for downtime, or data you can't afford to mess up. Keep that boundary clear and this approach works really well. Blur it and you're asking for trouble.

But for "my team needs a thing and the existing tools don't quite fit"? This is legitimately transformative. I've wanted to be able to build internal tools this easily for a long time. Now I can.

Airtable, it's been real. Tiger Den is better.

Product 101: Your Secret Weapon for Understanding the Business

Matty Stratton — Tue, 04 Nov 2025 14:58:55 +0000

This is Part 5 of my 7-part series on business literacy for DevRel. Start with Part 1 if you missed it.

We've covered sales, marketing, and finance. But there's one group we haven't talked about yet - and they might be your most valuable partnership in the entire company: Product.

Not because product managers are inherently better than anyone else (though the good ones are pretty great). But because strategic product leaders sit at the intersection of everything. They see the business from a unique vantage point that can be incredibly valuable to DevRel.

A good product partner is worth their weight in gold. They're your early warning system, your business intelligence source, and your reality check all rolled into one.

What Product Actually Does

At the most basic level, product management is about figuring out what to build, why to build it, and making sure it actually gets built.

But that simple description hides a ton of complexity:

Product managers (PMs) are responsible for:

Deciding what features/capabilities to prioritize
Understanding user needs and market opportunities
Working with engineering to build the right things
Collaborating with go-to-market teams (sales, marketing) to position and launch features
Measuring whether what they built is actually working
Saying "no" to a lot of things (this is actually most of the job)

Product sits at the center of a bunch of competing pressures:

Sales wants features that will close deals
Marketing wants things that will generate buzz
Engineering wants to build technically interesting things
Finance wants efficient use of resources
Customers want their specific problems solved
Executives want the product to support business strategy

The PM's job is to synthesize all of this and make decisions about what the product should become.

Meet the Product Team: Roles You Need to Know

Chief Product Officer (CPO) / VP of Product: Sets the overall product vision and strategy. They're thinking about where the product needs to be in 2-3 years, not just next quarter. They usually report directly to the CEO.

Director of Product / Senior PM: Usually owns a major product area or domain. They're thinking strategically about their area while managing other PMs.

Product Manager (PM): Owns a specific product or feature area. They work day-to-day with engineering teams to ship features. This is who you'll probably work with most.

Technical Product Manager (TPM): Like a PM but more technical. Often owns platform, API, or developer-facing products. If you work at a developer tools company, TPMs are your people.

Product Marketing Manager (PMM): We talked about these folks in the marketing post, but they sit between product and marketing. They take what product builds and figure out how to position and message it.

Product Operations / Product Ops: Help PMs be more effective by managing tools, processes, and data. They're the behind-the-scenes folks making product teams run smoothly.

How Product Thinks About the World

Product managers live in a few key frameworks. Understanding these helps you speak their language:

The Product Roadmap

This is the plan for what gets built when. Roadmaps are usually organized by quarters or releases, and they're always wrong (because priorities change).

Roadmaps are political documents as much as planning documents. What makes it onto the roadmap and what doesn't tells you a lot about what the business values.

User Stories and Jobs to Be Done

PMs think about user needs in terms of "user stories" (as a [role], I want to [do something] so that [outcome]) or "jobs to be done" (when [situation], I want to [motivation], so I can [expected outcome]).

This is useful for DevRel because it's how you can frame developer feedback. Instead of "developers want feature X," try "when developers are trying to debug production issues, they want observability into what the system is doing, so they can identify root causes faster."

Prioritization Frameworks

PMs are always prioritizing. Common frameworks:

RICE: Reach, Impact, Confidence, Effort
Value vs. Effort: Classic 2x2 matrix
Kano Model: Basic needs vs. performance needs vs. delighters

Understanding how your product team prioritizes helps you frame feedback effectively.

Success Metrics

Good PMs are all about metrics:

Activation: Did users do the key action that shows they "get" the product?
Engagement: Are users coming back? How often?
Retention: Are users sticking around over time?
Feature adoption: Are users actually using the new thing we built?
Time to value: How quickly can users get value from the product?

Notice how some of these overlap with PLG metrics? That's not an accident.

Why Product Matters So Much to DevRel

Here's where it gets interesting. Product is uniquely positioned to give you intelligence about the business that you can't get anywhere else.

They See Across Functions

A strategic PM talks to:

Sales (what's blocking deals?)
Marketing (what's resonating in the market?)
Customer success (what are customers struggling with?)
Engineering (what's technically feasible?)
Finance (what can we afford?)
Executives (what's the strategy?)

They're synthesizing information from everywhere. If you have a good relationship with product leadership, they can give you context on what's really happening across the business that you'd never get from any single function.

They Know What's Coming

Product knows what's on the roadmap before it's public. This is incredibly valuable for DevRel:

You can prep content in advance
You can understand strategic direction
You can give early feedback on how developers will react
You can plan your activities around major releases

They Need What You Have

As a devrel, you're sitting on a goldmine of information that product desperately needs:

What developers are actually struggling with
What features developers are asking for (and why)
How developers talk about problems in their own language
What the competition is doing (you see it at conferences and in communities)
Which parts of your product confuse people

This creates natural reciprocity. You help them, they help you.

They Fight Similar Battles

Good PMs face the same challenge you do: they have to translate between technical reality and business objectives. They have to advocate for what's right while acknowledging business constraints.

You're natural allies.

The Product/DevRel Partnership

When done right, the Product/DevRel partnership is incredibly powerful:

DevRel provides Product:

Raw, unfiltered user feedback from communities
Market intelligence from conferences and events
Early signals about what developers care about
Reality checks on how features will be received
Developer perspective on product decisions

Product provides DevRel:

Early access to roadmap and upcoming features
Context on why decisions were made
Understanding of strategic priorities
Cross-functional intelligence
Air cover when you need to push back on requests

The Feedback Loop

One of DevRel's most valuable contributions is being a structured feedback channel from developers to product. But this only works if you do it right:

Bad feedback: "Developers want dark mode"

Good feedback: "I'm seeing consistent requests for dark mode from developers who code at night. The specific pain point is eye strain during long coding sessions. This came up in 15+ community conversations last month, and competitors X and Y both shipped this recently."

Bad feedback: "This new feature is confusing"

Good feedback: "In office hours, 3 out of 5 developers got stuck at the same step in the new onboarding flow. The confusion is around [specific thing]. Here's a recording of where they got stuck."

Strategic product leaders eat this stuff up because it's specific, actionable, and helps them make better decisions.

Not All PMs Are Created Equal

That said, not every PM is strategic. Some are just feature factories, cranking out roadmap items without understanding the broader context.

A comment that inspired this post mentioned this perfectly: not every product leader can "get their heads out of the sands of features/roadmap, nor are they all observant of business value themselves."

Look for PMs who:

Understand the business model, not just the feature list
Can articulate why something is being built, not just what
Talk to customers and users regularly
Have opinions about strategy, not just execution
Are curious about the market and competition
Actually understand the technical implications of their decisions

These are the ones worth partnering closely with. The others... well, you can still work with them, but don't expect the strategic partnership.

How Product Decisions Happen (And Where You Fit In)

Understanding how product decisions get made helps you influence them:

Input gathering: PMs collect input from sales, customers, community, market research, executives, etc.

Prioritization: PMs use frameworks to decide what's most important

Roadmap planning: Decisions get formalized into "we're building X in Q2"

Execution: Engineering builds it

Launch: Product goes to market with help from marketing, sales, and (hopefully) DevRel

Measurement: Did it work?

DevRel can influence at almost every stage:

Input: Share developer feedback
Prioritization: Provide market context
Roadmap: React to plans, suggest adjustments
Execution: Give technical feedback during development
Launch: Create content, drive awareness
Measurement: Share qualitative feedback on how it's landing

But you have to be in the conversation to have influence. Which means building relationships.

The DevRel Seat at the Product Table

Some DevRel teams are deeply integrated with product. Others are completely disconnected. If you're in the latter camp, here's how to change that:

Start small: Ask to sit in on a product planning meeting as an observer
Provide value first: Share useful feedback before asking for anything
Speak their language: Frame things in terms of user problems and business impact
Be consistent: Show up regularly with valuable input
Don't be precious: Accept that you won't always get what you want
Understand constraints: Product is making trade-offs; understand what they are

Regular Touchpoints That Work

Consider establishing:

Monthly sync with product leadership: Share what you're hearing, get context on roadmap
Feedback review sessions: Present synthesized developer feedback quarterly
Early access to betas: Get hands-on with features before launch
Launch planning collaboration: Work together on go-to-market for major features
Roadmap input sessions: Provide perspective on upcoming priorities

Product Gives You Business Intelligence

Here's something nobody talks about: a good product partner can be your best source of business intelligence.

They'll tell you things like:

"Sales is really struggling in the enterprise segment right now"
"We're shifting strategy toward [market] next year"
"The exec team is worried about [competitive threat]"
"Marketing's campaigns aren't converting well"
"There might be budget cuts coming"

Why do they know this? Because they're in all the meetings. They see the cross-functional dynamics. They hear what's really going on.

And if they trust you, they'll share it. This is incredibly valuable for planning your DevRel strategy and seeing what's coming.

Essential Product Terminology

Let me give you the vocabulary:

MVP (Minimum Viable Product): The smallest version of something that delivers value. Often used as an excuse to ship incomplete things, but the concept is sound.

Product-Market Fit: The magical moment when you've built something that a market actually wants. Most products never achieve this.

Feature parity: Having the same features as competitors. Often overvalued by sales, undervalued by product.

Technical debt: The accumulated cost of quick-and-dirty technical decisions. Always more than you think.

Dogfooding: Using your own product internally. Good PMs do this religiously.

Beta / Alpha: Early versions for testing. Alpha is usually internal, beta is usually external but limited.

GA (General Availability): The feature is fully launched and available to everyone.

Sunset / Deprecation: Retiring a feature or product. Always painful, usually necessary.

OKRs (Objectives and Key Results): How many product teams set goals. Objectives are qualitative, key results are measurable.

What This Means For Your Work

Understanding product doesn't mean becoming a PM. It means:

You can provide product with valuable, actionable feedback
You can anticipate what's coming and plan accordingly
You can understand why certain decisions are made (even when you disagree)
You can be a strategic partner instead of just a feedback conduit
You have access to cross-functional intelligence that helps you navigate the business

Product is your window into how the whole business is working - the headwinds, the tailwinds, the tensions, the priorities. Use it.

Finding Your Product Partner

Not sure who to connect with in product? Start here:

Identify the PM who owns your developer-facing products (API, SDK, CLI, etc.)
Reach out with value: "Hey, I'm hearing a lot of feedback about [thing]. Want to chat?"
Be low-maintenance: Respect their time, be organized, come prepared
Look for strategic thinkers: Find the PMs who see the bigger picture
Build the relationship over time: This is a long game

And if you find a great product partner? Hold onto them. They're rare and incredibly valuable.

Next up: we'll talk about Product-Led Growth and how it changes everything about the relationship between product, DevRel, and go-to-market. Spoiler: in PLG companies, product and DevRel become deeply intertwined.

Questions about working with product? War stories about great (or terrible) product partnerships? Let's hear them in the comments!

Previously: Part 4: Finance 101

Next up: Product-Led Growth