Symptom: pasting a docs migration into Supabase SQL Editor returns
something like ERROR: 42P01: relation "searchable" does not exist,
where "searchable" is just a word inside a markdown content block — not
a real table.
Root cause
Supabase SQL Editor pre-processes queries differently depending on the
"Enforce RLS" toggle. With it on, the wrapper interferes with Postgres
dollar-quoted string parsing ($tag$...$tag$). If your migration's
content includes a $NAME sequence that looks like a partial
dollar-quote tag (e.g. $WEEK_AGO in a bash example), the parser gets
confused and treats subsequent markdown words as relation names.
Fix
Two options, in order of preference:
Option 1 — disable "Enforce RLS" in the SQL Editor for that one run. The toggle is at the top of the editor. Disabling it sends raw SQL to Postgres, which handles dollar-quoting correctly.
Option 2 — avoid bare $IDENT patterns inside $md$ blocks.
Wrap shell vars in braces: $WEEK_AGO → ${WEEK_AGO}. Same shell
semantics, parser-safe. Also avoid inline ; semicolons inside
markdown (use em-dashes instead).
Generalized lesson
When writing docs that ship as SQL migrations:
- Keep
$IDENT$patterns out of markdown — even safe-looking ones can collide with PG's dollar-quote tokenizer in some SQL clients. - Use
${IDENT}syntax in shell examples. - Use em-dashes (
—) instead of;for in-sentence pauses.
The mnueron docs migrations (003, 005, 006, 008) follow these rules now.