PostgreSQL Row-Level Security Reference Guide

Problem Description

An engineering team is building a multi-tenant SaaS application on PostgreSQL 16. Each tenant's data must be isolated so that users from one tenant can never read or modify another tenant's rows — even if they share the same database. The team has heard that PostgreSQL has a native mechanism to enforce this at the database layer rather than in application code, but is unsure how to set it up correctly or what pitfalls to watch out for.

The team includes both developers who are new to PostgreSQL security features and experienced DBAs who will maintain the system. They need a thorough technical guide they can embed in the team wiki. The guide should explain the core mechanism, show complete working examples, and cover operational gotchas — including what to expect from different deployment environments (self-hosted vs. managed cloud).

Output Specification

Write a single markdown file named rls_guide.md that serves as a self-contained reference guide.

The guide should include:

• A conceptual explanation of how the mechanism works
• Working SQL examples demonstrating setup for a multi-tenant use case, including policy creation and testing
• Notes on common pitfalls and edge cases to watch out for
• Guidance on which PostgreSQL versions the features are available in, with inline version notes where behavior differs
• Links to the relevant official documentation pages

The SQL examples must be complete and runnable.