Supabase connection prompt writer

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 goes in and out

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

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

How the task works

• Check what you have. Your coding AI looks for your project, .env.local and the two packages.
• Write the client. It writes lib/supabase/admin.ts, which reads the URL and the service role key and stops with a clear message if one is missing.
• Write the test. It writes a script that reads up to 5 rows from agent_jobs and counts the rows in agent_activity_log.
• Explain and run. It explains the key in plain words. You run the test and check for the two result lines.

Full instructions

• Open your project in Claude Code. This prompt creates files, so it needs an AI that can write to your project.
• Install the two packages it needs: npm install @supabase/supabase-js and npm install -D tsx. The prompt asks before it installs them.
• 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.
• Paste the prompt from the download and let it create the two files.
• Run npx tsx scripts/test-db-connection.ts in your terminal.
• Check that you see the two lines about agent_jobs and the activity log. Zero rows is fine on new tables.
• If you see an error, check the key names in .env.local and that both tables exist.

Full instruction file

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

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

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. 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.