Survive Your First Traffic Spike

Don't change any files yet. I'm launching soon and want to find what will break first if a lot of people use my app at once. I'm a beginner, so explain in plain words.

What my app does: [WHAT MY APP DOES]
My stack: [MY STACK]
Expected visitors: [EXPECTED VISITORS]
Busiest pages: [BUSIEST PAGES]

Read the project and check:
1. How my code reaches the database. Is it the supabase-js client (which goes through Supabase's Data API), a Postgres driver or ORM with a connection string (like Prisma, Drizzle, Postgres.js, or pg), or both? For each connection string, which host and port does it use? Don't print any passwords.
2. Where database clients get created. Is a new client or pool created inside a request handler instead of once at the top of the file?
3. Pool size settings. Are any left at the library default, which is usually set for a long-running server, not serverless functions?
4. Queries inside loops (one query per item in a list), and pages that load whole tables with no limit or pagination.
5. Columns my queries and Row Level Security policies filter on, and whether they have an index.
6. Calls to outside services (payments, email, AI, other APIs) that have no timeout.
7. Pages that are the same for every visitor but are rebuilt on every request.

For each check, say "OK", "Risk", or "Not sure", with the file path and one line on why. Then list the risks from most to least likely to take the site down during a spike, with a short fix for each and which prompt type would fix it (connections, slow queries, caching, or timeouts). If you're not sure how Supabase or Vercel behaves today, tell me to check their docs instead of guessing.

My app is struggling under a sudden traffic spike. Help me find the cause and get it back up. Don't change any code until I approve a plan. Keep it calm and step by step.

What I'm seeing: [WHAT I'M SEEING]
Errors from my logs: [ERRORS FROM MY LOGS]
When it started: [WHEN IT STARTED]
What I changed recently: [WHAT I CHANGED RECENTLY]

Some error messages I know about:
- "FATAL: remaining connection slots are reserved for non-replication superuser connections" from Postgres means the database has run out of connections.
- A 504 error with FUNCTION_INVOCATION_TIMEOUT on Vercel means a function ran longer than its maximum duration.
- Supabase's docs say "Connection refused" is usually an IP ban rather than an outage.

Please:
1. Tell me which of these is most likely happening: out of database connections, slow queries piling up, an outside service hanging, or something else. Quote the exact log line that points to it.
2. Tell me where to look to confirm it, step by step: the Database Connections page in my Supabase dashboard, Supabase's reports, and my Vercel project's logs.
3. Give me the fastest safe way to get the site working again, and say what it costs or risks.
4. Then list the proper fixes for after the rush, in order.
If a message isn't one you recognize, say so and tell me to search Supabase's or Vercel's troubleshooting docs instead of guessing.

My server code connects to my Supabase Postgres database from serverless functions on Vercel, and I want to set up connection pooling the right way. Show me the plan before you change anything.

My database library: [MY DATABASE LIBRARY]
Where my server code runs: [WHERE MY SERVER CODE RUNS]
How I run migrations: [HOW I RUN MIGRATIONS]

What I know from Supabase's docs:
- For serverless or edge functions, Supabase recommends the shared pooler in transaction mode. That string comes from the Connect button in the dashboard, under "Transaction pooler", and uses port 6543.
- Transaction mode doesn't support prepared statements, so they must be turned off: prepare: false for Postgres.js and Drizzle, or pgbouncer=true on the connection string for Prisma.
- The database client should be created once at the top of the file (module scope), not inside each request.
- Library defaults are too high for serverless. Postgres.js, for example, defaults to 10 connections per warm instance.
- Migrations and other long single sessions should use the direct connection (port 5432), or session mode (also port 5432) on networks that only support IPv4.

What I know from Vercel's docs:
- With Fluid compute, one function instance can handle several requests at once and shares the same pool.
- Vercel suggests creating the pool once, registering it with attachDatabasePool from @vercel/functions, and using a short idle timeout.

Please:
1. Find every place that creates a database client, and tell me which connection string each one uses (by environment variable name, never the value).
2. Move request-time code to the transaction pooler string, keep migrations on the right connection, and turn off prepared statements for my library.
3. Supabase's guide starts serverless pools at 1 connection per instance, while Vercel's Fluid compute guide warns that a maximum of 1 can hurt concurrency. Explain the tradeoff for my setup and suggest a small starting number.
4. List the environment variables I need to add or change in Vercel and anywhere else I run code, with what each is for.
5. Tell me how to check that it worked.
If my library needs another setting for transaction mode, tell me to check Supabase's guide for that library.

Don't change any files yet. My Supabase database connections stay used up, or some queries hang. Help me find out what's holding them, step by step. I'm a beginner.

What I'm seeing: [WHAT I'M SEEING]
What I pasted: [WHAT I PASTED]

What I know from Supabase's docs:
- pg_stat_activity shows live connections, and its usename column shows which service owns each one (for example, authenticator is the Data API, supabase_auth_admin is Auth, and postgres is the dashboard and outside tools like Prisma).
- "idle in transaction" means a transaction was opened and never committed or rolled back. It holds locks until it closes.
- pg_cancel_backend(pid) cancels a running query but keeps the connection. pg_terminate_backend(pid) closes the whole connection, and it's the only way to end an idle-in-transaction session.

Please:
1. Give me a read-only SQL query I can run in the Supabase SQL editor to see connections grouped by role and state, plus any sessions that are blocked and what is blocking them.
2. When I paste the results, explain them in plain words and say which ones look like a problem.
3. Then search my code for the likely cause: transactions that can end without commit or rollback (for example, an early return or an error inside the transaction), clients that never get released back to the pool, or a new pool created on every request.
4. Suggest a fix for each cause, and tell me whether it's safe to cancel or end any session right now, and which function to use.

Don't change any files yet. I want to find the slowest and busiest queries in my Supabase database and understand them. I'm a beginner.

Slow parts of my app: [SLOW PARTS OF MY APP]
What I pasted: [WHAT I PASTED]

What I know from Supabase's docs:
- The Query Performance report in the Supabase dashboard lists slow queries.
- The pg_stat_statements extension tracks how often each query runs and how long it takes (calls, mean_exec_time, total_exec_time). Its numbers add up from the last time the stats were reset.
- The Supabase CLI has inspection commands like "supabase inspect db outliers", "long-running-queries", and "seq-scans" (after "supabase link").

Please:
1. Tell me how to check whether pg_stat_statements is turned on, and how to turn it on from the dashboard if it isn't.
2. Give me a read-only SQL query that lists the top 10 queries by total time, with calls and average time.
3. When I paste the results, explain the top 3 in plain words: which table they read, roughly what they're doing, and why they might be slow.
4. Match each one to the code in my project that runs it (file path), including queries made through supabase-js or my ORM.
5. For each one, say whether the likely fix is an index, a smaller query (fewer columns or rows, or pagination), or running it less often. Don't write the fix yet.

I want to speed up a slow query in my Supabase database with the right index. Show me the plan before you change anything.

The slow query: [THE SLOW QUERY]
The table and rough size: [THE TABLE AND ROUGH SIZE]
How I change my database: [HOW I CHANGE MY DATABASE]

What I know from Supabase's and Postgres's docs:
- Indexes usually help on columns in where clauses, join columns, and order by columns. A primary key is already indexed.
- Supabase's index_advisor extension suggests indexes for a query, but only single-column B-tree indexes. It's also in the dashboard: open the Query Performance report, pick a query, then the indexes tab.
- "explain" shows how Postgres runs a query. A "Seq Scan" on a big table often means a missing index. If an index doesn't lower the cost, remove it.
- Too many indexes slow down writes, so only add ones that help real queries.
- A normal "create index" blocks writes to the table while it builds. "create index concurrently" doesn't block writes but takes longer, and it can't run inside a transaction block.
- For Row Level Security, Supabase recommends an index on every column a policy filters on (like user_id), and writing auth.uid() as (select auth.uid()) inside policies.

Please:
1. Explain the query plan in plain words, and tell me how to run "explain" on it myself.
2. Suggest the index or indexes that would help, and why. Use index_advisor's idea as a starting point if it fits.
3. Check the RLS policies on this table for unindexed columns and for auth.uid() calls that aren't wrapped in a select.
4. Write the change in the way I change my database. If it uses "concurrently", tell me whether my migration tool runs it inside a transaction, which would make it fail.
5. Tell me how to confirm afterward that the query got faster.

Don't change any files yet. I want to add caching to my app on Vercel, and I must never show one user's data to another user. Review my caching and make a safe plan. I'm a beginner.

Pages I want to cache: [PAGES I WANT TO CACHE]
Pages that are per user: [PAGES THAT ARE PER USER]
My framework: [MY FRAMEWORK]

What I know from Vercel's docs:
- Vercel's CDN caches a function's response only when it sends a Cache-Control header with s-maxage (for example, "public, s-maxage=60, stale-while-revalidate=300").
- It won't cache a response that sets a cookie (Set-Cookie), a request with an Authorization header, or a response marked private, no-cache, or no-store.
- A request that only carries a login cookie isn't on that list, so a per-user page that sends s-maxage could still be cached and shown to others.
- The x-vercel-cache response header shows whether a response came from the cache.

What I know from Next.js's docs:
- Functions marked "use cache" can't read cookies() or headers(). Values passed in as arguments, or used from outside the function, become part of the cache key.

Please:
1. Find every place that sets Cache-Control, s-maxage, revalidate, "use cache", unstable_cache, or any other cache, in code and in vercel.json or next.config.
2. For each one, say "safe" (same for everyone), "leak risk" (depends on who's logged in but could be shared), or "not sure", with the file path and why.
3. Make sure every per-user page and API route sends Cache-Control: private, no-store, and that cached functions never fetch the current user's data unless the user's ID is part of the cache key.
4. Suggest caching for the public pages I listed, with how long, and how updates will show up.
5. Give me a 3-step test with two different accounts and a logged-out browser to prove no one sees someone else's data.

Add timeouts and safe retries to the calls my app makes to outside services. Show me the plan before you change anything.

Outside services I call: [OUTSIDE SERVICES I CALL]
What happens when one is slow: [WHAT HAPPENS WHEN ONE IS SLOW]

What I know:
- fetch can take a timeout signal with AbortSignal.timeout(milliseconds), which stops the request after that long.
- On Vercel, a function that runs past its maximum duration is stopped with a 504 error (FUNCTION_INVOCATION_TIMEOUT). In Next.js App Router, a route can set its own limit with "export const maxDuration".
- On Vercel, waiting for another service doesn't count as active CPU time, but the function's memory time keeps counting while it runs.

Please:
1. List every call to an outside service in my code, with the file path, and whether it has a timeout. Include calls made through an official library, and tell me whether that library has its own timeout or retry setting.
2. Add a sensible timeout to each one, explaining why you chose that number.
3. Add retries only where repeating the call is safe, like reading data. For anything that charges money, sends an email, or creates something, don't retry unless the provider supports an idempotency key or the code can check first whether it already happened.
4. When you retry, wait longer between each try, stop after a few tries, and respect a Retry-After header on 429 or 503 responses.
5. Show the user a clear, friendly message when a service fails, instead of an endless spinner.
6. Set a sensible maxDuration on the routes that call slow services.

Help me plan and write a small, safe load test for my own app using k6. I'm a beginner. Don't run anything for me.

My app's key actions: [MY APP'S KEY ACTIONS]
Where I'll run the test: [WHERE I'LL RUN THE TEST]
My test database: [MY TEST DATABASE]
My Vercel plan: [MY VERCEL PLAN]

Rules I must follow:
- Only test my own app, never someone else's site or a service I don't control.
- Vercel's load testing policy says load testing is only permitted on Enterprise plans, and unannounced tests may get the testing IP addresses blocked. Unless my plan allows it, I'll test a production build running on my own computer instead of my Vercel deployment.
- Supabase's production checklist recommends load testing, preferably on a staging environment. I'll point the test at a separate test project with fake data, never my real users' data.
- Don't send test traffic to real payment, email, or AI services. Use test mode or fake them.

Please:
1. Tell me how to run a production build of my app locally, connected to my test database.
2. Write a k6 script that walks through my key actions with fake test accounts, starting with a smoke test (very few virtual users) and then a slow ramp up and back down, not an instant jump.
3. Add thresholds so the test fails if more than 1% of requests error or responses get too slow, and explain how to pick those numbers.
4. Tell me what to watch while it runs: k6's results, my Supabase project's Database Connections page and reports, and my app's logs.
5. Explain how to read the results and which prompt type (connections, slow queries, caching, or timeouts) fits each kind of failure.
6. Remind me how to stop the test right away if something goes wrong.