--- title: "Supabase connection prompt writer" type: "prompt" url: "https://useaiblocks.com/prompts/connect-code-to-supabase-builder-prompt" updated: "2026-11-03" first_published: "2026-10-25" job: "Build and ship software" tested: true instructions: "https://useaiblocks.com/skills/connect-code-to-supabase-builder-prompt/SKILL.md" --- # Supabase connection prompt writer > Paste one prompt into Claude Code to connect your app to Supabase from the server, keep the secret key safe and run a first read check. Get a coding brief to connect your app to Supabase, with scoped access, safe secrets and a read check. Free prompt for the job "Build and ship software" · Level: intermediate · Thinking: medium · Tested · Updated 2026-11-03 ## Links - Page: https://useaiblocks.com/prompts/connect-code-to-supabase-builder-prompt - Instructions (SKILL.md): https://useaiblocks.com/skills/connect-code-to-supabase-builder-prompt/SKILL.md - All files (zip): https://useaiblocks.com/skills/connect-code-to-supabase-builder-prompt.zip - JSON version: https://useaiblocks.com/prompts/connect-code-to-supabase-builder-prompt.json - In your AI: connect https://useaiblocks.com/mcp and ask "Use AI Blocks to get connect-code-to-supabase-builder-prompt" ## What it does Before an app can save or read anything, it needs a safe link to its database. This prompt sets that up for Supabase. It writes a server-only client that reads your URL and service role key from .env.local, and a small test script that counts rows in two tables. You paste the prompt into Claude Code in your project. It also explains the service role key and Row Level Security in plain words. The test only reads data. ## What you give it - Your code project, open in Claude Code - Your Supabase URL and service role key, saved in .env.local - The agent_jobs and agent_activity_log tables in your Supabase project ## What you get - A server-only Supabase client file (lib/supabase/admin.ts) - A test script (scripts/test-db-connection.ts) - A plain explanation of the service role key, and what the test should print ## Example: what goes in and what comes out ### What goes in - Your code project, open in Claude Code - Your Supabase project URL - Your Supabase service role key, saved in .env.local - Your agent_jobs and agent_activity_log tables ### Before you start - Claude Code, or an AI that can create files in your project - A Supabase project with the two tables already made - A Node or Next.js server project ### What comes out - **lib/supabase/admin.ts**: A server-only Supabase client called supabaseAdmin that stops with a clear error if a key is missing. - **scripts/test-db-connection.ts**: A script that reads up to 5 rows from agent_jobs and counts the rows in agent_activity_log. - **Plain-English explanation**: Short notes on the service role key, why it stays out of browser code, and the data and error pattern. - **Test result**: The lines you should see when you run the script, where zero rows is fine on new tables. ## Use it when - You are building an app with a Next.js or Node server and want it to talk to Supabase. - You want a first read test that proves the link works. - You are new to coding and want each part explained simply. ## Skip it when - You are building browser code or a client-side app: this prompt makes a server-only client, so use the Supabase docs for your framework. - You use a framework other than Next.js or Node: follow the Supabase docs for that framework instead. - You have not made the agent_jobs and agent_activity_log tables yet: create them in Supabase first, or the test will fail. ## How to use it 1. Open your project in Claude Code. This prompt creates files, so it needs an AI that can write to your project. 2. Install the two packages it needs: npm install @supabase/supabase-js and npm install -D tsx. The prompt asks before it installs them. 3. Save your Supabase URL and service role key in .env.local. Keep that file out of git, because the service role key skips Row Level Security. 4. Paste the prompt from the download and let it create the two files. 5. Run npx tsx scripts/test-db-connection.ts in your terminal. 6. Check that you see the two lines about agent_jobs and the activity log. Zero rows is fine on new tables. 7. If you see an error, check the key names in .env.local and that both tables exist. ## What to do next - [Postgres performance tuner](https://useaiblocks.com/skills/postgres-performance-tuner): Build it ## Instructions (SKILL.md) ## Connect Code to Supabase prompt ### Before you start Use the material below to do this job. If facts or tool access are missing, explain what you can finish and what must wait. **What you need** (use your own material or the linked skill): - **A codebase** (yours): a project's code, in a folder or repo the AI can open. How to start: 1. **Look first.** Use what they've already attached, pasted or put in their about-me note. In a coding assistant with file access, look in the project too for these by name. 2. **Check what's missing.** Look for a codebase. They can attach files, paste the details, or share a file path your assistant can read. Ask only for missing facts that change the result. If they ask you to start with what they have, complete the parts you can and mark the gaps. 3. **Do the job.** Follow the method with the facts and tools you have. Mark each gap with `MISSING:` where it belongs and never invent a fact to fill it. Keep the answer tight: say each point once and merge steps that give the same thing. In CHECKS MISSED, list checks that failed or could not run. If every required check ran and passed, write “none”. ### Before you run it - You need these ready: your Supabase URL, your service role key and the two tables below. - This prompt needs a Supabase project, with the URL and the service role key in `.env.local`. Keep that file out of git. The service role key skips Row Level Security, so it stays on the server and never goes in browser code. - It needs two tables in your Supabase project: `agent_jobs` and `agent_activity_log`. Any columns work, because the test only reads and counts rows. Create them in the Supabase dashboard (Table Editor or SQL editor). See https://supabase.com/docs/guides/database/tables. - It needs two packages: `@supabase/supabase-js` and `tsx`. Install them with `npm install @supabase/supabase-js` and `npm install -D tsx`. Ask the user before you install. - It reads data only. It does not change your database. ### Method Copy this into Claude Code to wire up the database connection and run your first query from code. --- ``` I need to connect my code to Supabase. Do these things in order: 0. Before you install any package, ask me. The packages are @supabase/supabase-js and tsx (as a dev dependency). Then check that .env.local is listed in .gitignore. If it is not, tell me and ask before you change .gitignore. 1. Create lib/supabase/admin.ts: - Import createClient from @supabase/supabase-js - Read SUPABASE_URL from process.env (fall back to NEXT_PUBLIC_SUPABASE_URL) - Read SUPABASE_SERVICE_ROLE_KEY from process.env (fall back to SUPABASE_SERVICE_KEY) - If either is missing, throw a clear error message saying which one is missing - Export the client as "supabaseAdmin" - Add a comment at the top: "Server-side only. Never import this in browser code." 2. Create scripts/test-db-connection.ts: - Import supabaseAdmin from lib/supabase/admin - Query the agent_jobs table: select all rows, limit 5 - Print: "Connected to Supabase. Found X rows in agent_jobs." - If error, print the error message - Query agent_activity_log: count all rows - Print: "Activity log has X entries." 3. After creating both files, explain: - What "service role key" means and why it bypasses Row Level Security - Why we never use this client in browser code - What { data, error } destructuring means (the Supabase return pattern) Keep the explanation simple. I'm a business owner learning to build. ``` --- ### How to Test ```bash npx tsx scripts/test-db-connection.ts ``` You should see: ``` Connected to Supabase. Found 0 rows in agent_jobs. Activity log has 0 entries. ``` Zero rows is correct if you just set up the tables. The important thing is no errors. ### Common Errors | Error | Fix | |-------|-----| | "SUPABASE_URL is not defined" | Check `.env.local` has `SUPABASE_URL` or `NEXT_PUBLIC_SUPABASE_URL` | | "SUPABASE_SERVICE_ROLE_KEY is not defined" | Check `.env.local` has the service role key from Supabase dashboard | | "relation agent_jobs does not exist" | The tables are not there yet. Create `agent_jobs` and `agent_activity_log` in the Supabase dashboard (Table Editor or SQL editor), then run the test again. | | "Invalid API key" | Your service role key is wrong. Recopy from Supabase > Settings > API | ### Next Step Once this works, every agent you build will use `supabaseAdmin` to read and write data. This is the foundation. ### Final check Give the requested deliverables, evidence used, assumptions, missing inputs, and the smallest useful next step. Distinguish an idea, a calculation, a proposed action and a completed tool action. ### After this When you've handed it back, suggest what they could do next in one short question. It's a suggestion: if they're done, that's fine. Offer these, and say they can type their own: - The [Postgres performance tuner](https://useaiblocks.com/skills/postgres-performance-tuner). It takes the code change. If they pick one and that skill is added here, carry straight on with what you just made. If not, give the link and say what to bring.