Supabase Drops postgres-best-practices: The Agent Skills Guide PostgreSQL Developers Have Been Waiting For

Published on ClawList.io | Category: Development

---

If you've ever spun up a Supabase project and wondered whether you're actually doing PostgreSQL the right way — you're not alone. This week, Supabase co-founder Paul Copplestone (@kiwicopple) announced the release of postgres-best-practices, an open-source guide documenting the exact Agent Skills and PostgreSQL patterns the Supabase team uses internally on their own platform.

Think of it as the PostgreSQL equivalent of Vercel's beloved react-best-practices — battle-tested, production-grade patterns that have been refined by running one of the world's most popular developer platforms at scale. For developers building AI automation pipelines, OpenClaw skills, or data-heavy backend systems, this release is more than just documentation — it's a blueprint.

---

What Is postgres-best-practices and Why Does It Matter?

The concept is straightforward but powerful: instead of scattering tribal knowledge across Slack threads, internal wikis, and engineers' heads, Supabase has codified the Agent Skills they rely on every day into a single, versioned, open-source repository.

Inspired directly by Vercel's approach to React, the philosophy here is that best practices should be shareable, forkable, and improvable by the community. This matters enormously for several reasons:

• Consistency at scale — whether you're a solo developer or a team of fifty, your PostgreSQL patterns should be reproducible
• AI agent compatibility — as more developers use LLMs and AI agents to write or review database code, having an authoritative reference makes AI-assisted development significantly more accurate
• Onboarding speed — new engineers (or new AI tools) can immediately understand why certain patterns exist, not just what they are
• Production-readiness — these aren't academic examples; they're the same patterns keeping Supabase's infrastructure running for millions of users

For builders working with AI automation workflows and OpenClaw skills in particular, having a well-defined PostgreSQL skill layer is critical. Your agents are only as reliable as the database patterns they're operating on.

---

Core PostgreSQL Agent Skills You'll Find in the Guide

While the full repository is the authoritative source, the postgres-best-practices guide covers several categories of Agent Skills that are especially relevant for modern application development and AI-driven data workflows.

1. Schema Design and Naming Conventions

One of the most impactful areas the guide addresses is consistent schema design. Inconsistent naming is a silent killer in automated systems — an AI agent querying user_id in one table and userId in another will introduce bugs that are notoriously hard to trace.

The Supabase team recommends patterns like:

-- Preferred: snake_case for all identifiers
CREATE TABLE public.user_profiles (
  id          uuid DEFAULT gen_random_uuid() PRIMARY KEY,
  user_id     uuid REFERENCES auth.users(id) ON DELETE CASCADE,
  display_name text NOT NULL,
  created_at  timestamptz DEFAULT now() NOT NULL,
  updated_at  timestamptz DEFAULT now() NOT NULL
);

-- Use Row Level Security consistently
ALTER TABLE public.user_profiles ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Users can view their own profile"
  ON public.user_profiles
  FOR SELECT
  USING (auth.uid() = user_id);

This kind of standardized scaffolding is exactly what AI automation tools and OpenClaw skills need to generate reliable, predictable database interactions without manual correction.

2. Performance Patterns for Agent-Driven Queries

AI agents often generate queries that work perfectly in development but collapse under production load. The guide specifically addresses indexing strategies, query optimization, and connection pooling — the three horsemen of PostgreSQL performance at scale.

Key patterns include:

• Partial indexes for filtering active or recent records, dramatically reducing index size
• Covering indexes to eliminate table heap lookups on hot query paths
• EXPLAIN ANALYZE as a first-class workflow step, not an afterthought
• PgBouncer-aware query patterns that avoid session-level state when using connection poolers

-- Partial index: only index active subscriptions
CREATE INDEX idx_subscriptions_active_user
  ON public.subscriptions (user_id)
  WHERE status = 'active';

-- Covering index: include frequently selected columns
CREATE INDEX idx_posts_user_published
  ON public.posts (user_id, published_at DESC)
  INCLUDE (title, slug);

For AI automation pipelines where agents may be executing hundreds of queries per minute, these patterns aren't optional — they're survival skills.

3. Security Patterns and Row Level Security (RLS)

Perhaps the most critical section for any developer shipping a multi-tenant application or exposing database logic to AI agents is the Row Level Security (RLS) patterns. Supabase has become synonymous with RLS as a first-class security model, and the guide reflects years of hard-won experience.

The guide covers:

• Defining policies that are index-friendly (poorly written RLS policies can disable your indexes entirely)
• Using security definer functions carefully to avoid privilege escalation
• Testing RLS policies systematically before deploying to production

-- Example: tenant-scoped RLS policy that plays well with indexes
CREATE POLICY "tenant_isolation"
  ON public.documents
  FOR ALL
  USING (
    tenant_id = (
      SELECT tenant_id
      FROM public.memberships
      WHERE user_id = auth.uid()
      LIMIT 1
    )
  );

When OpenClaw skills or AI agents are given database access, RLS becomes your last line of defense. Getting these patterns right isn't just a best practice — it's a security imperative.

---

Why This Is a Game-Changer for AI Automation Developers

The timing of this release isn't accidental. We're living through a period where AI agents are increasingly writing, reviewing, and executing database code — and the quality of that code is only as good as the reference material those agents were trained on or are given as context.

By open-sourcing their internal Agent Skills as postgres-best-practices, Supabase has effectively created a high-quality grounding document that developers can:

1. Feed directly into their AI coding assistants as system context or RAG documents
2. Use as a validation checklist for AI-generated SQL migrations
3. Reference in OpenClaw skills to ensure database interactions meet production standards
4. Contribute back to, making it a living, community-maintained standard over time

This mirrors exactly what made Vercel's react-best-practices so valuable — not just as reading material, but as a machine-readable source of truth for how modern applications should be built.

---

Getting Started with postgres-best-practices

The release is available as an open-source repository from the Supabase team. Here's how to start integrating it into your workflow immediately:

• Bookmark and read the full guide — even experienced PostgreSQL developers will find patterns worth adopting
• Add it to your AI assistant's context — reference the guide when asking LLMs to write database migrations or RLS policies
• Audit your existing schemas against the naming and security conventions documented
• Contribute — the guide is explicitly designed to evolve with community input, just like Vercel's React equivalent

---

Conclusion

postgres-best-practices is exactly the kind of resource the developer community has needed for a long time: opinionated, production-tested, and open. By framing PostgreSQL patterns as Agent Skills — discrete, composable, and shareable — Supabase has given developers a vocabulary and a toolkit that works equally well for human engineers and AI automation systems.

Whether you're building on Supabase directly, running your own PostgreSQL infrastructure, or designing OpenClaw skills that interact with relational data, this guide deserves a place in your reference stack. The age of AI-assisted database development is here, and having a canonical best practices document is no longer a nice-to-have — it's a foundation.

---

Follow @kiwicopple for updates, and check the original announcement at x.com/kiwicopple/status/2014359058652745800. Stay tuned to ClawList.io for more developer resources, AI automation guides, and OpenClaw skill breakdowns.