Most Supabase Bugs Aren't Supabase Bugs

I've debugged enough Supabase applications — my own and other people's — to have an opinion about where they go wrong.

It's almost never the library. Supabase is well-built. The client is well-documented. The errors are usually clear.

The problems are in how developers compose queries. Not because developers don't know Postgres, but because the patterns that produce performance problems in Supabase applications are specific to Supabase's architecture in ways that generic database knowledge doesn't cover.

That's what the Supabase Postgres Best Practices skill from supabase/agent-skills is for.

The Patterns That Actually Break Things

The skill documents the failure modes the Supabase team sees repeatedly in production applications. A few of them are worth naming directly.

N+1 queries through the client API. The Supabase JS client makes it easy to chain queries — fetch a list of items, then for each item fetch related data. The syntax is clean. The performance is catastrophic. Every item in the list generates a new round-trip to the database. Applications that work fine at 20 rows start timing out at 2,000.

The fix — using select with nested relations to join in a single query — is well-documented, but it requires knowing to look for it. An agent without the skill will write the clean-looking version. An agent with the skill knows to use the join.

Missing indexes on columns that appear in where clauses and order by clauses. This one is particular to how Supabase applications evolve. You start with a table, you add filtering later, you add sorting later, you never add the indexes because the data set is small and it's fast enough. Then it isn't. The skill encodes: when you add a filter, add the index.

Realtime subscriptions without row filtering. Subscribing to a table with channel().on('postgres_changes', ...) without a filter option sends every change to every connected client. This works fine in development. In production, with concurrent users and frequent updates, it becomes a firehose. The skill encodes: always filter realtime subscriptions.

Why Skills Beat Documentation for This

All of these patterns are documented. The Supabase docs are good. The guides cover these topics.

The problem isn't documentation access — it's documentation timing. A developer reads the best practices section once, during initial setup, before they know which parts will be relevant to their specific application. By the time they hit the performance problem, they've forgotten the relevant section, or they're so deep in debugging mode that they're Googling symptoms rather than consulting architecture docs.

An agent with the Supabase Postgres Best Practices skill loaded doesn't have a timing problem. The rules are active every time it writes a query. The N+1 guard fires when the N+1 pattern is about to be generated, not after the production incident.

That's the core argument for skills in any domain where the knowledge exists but doesn't get applied at the right moment.

The 130K Number

130,600 installs means this is being used at meaningful scale. What that tells me is that the patterns it addresses are genuinely common — this isn't a skill for advanced database optimization, it's a skill that prevents the mistakes that hurt ordinary applications.

The Supabase team seeing the same mistakes across enough customer applications to write them down is itself useful information. These aren't theoretical anti-patterns. They're what actually happens when developers who know Supabase build applications at production scale.

That provenance matters. The skill isn't a community wiki assembled from Stack Overflow. It's a codification of what the people who maintain the platform have seen actually break things, in real applications, with real users.

When the source of a best practices set is "the team that sees production incidents across thousands of applications," the best practices are worth following.

Part of the AI Skill Daily series — skills worth understanding, one at a time.