Supabase

If you've never heard of Supabase, that's fine. Most people haven't. By the end of this page, you'll know exactly what it is, why your app needs it, and how to set it up in about five minutes.

The 30-second version

• What it is: a free online service that holds your app's stuff: its users, the things they save, the photos they upload.
• Why you need it: every real app needs a place to remember things between sessions. Supabase is that place.
• How hard: five minutes, once. Sign up on supabase.com, copy a few short strings, paste them into Appsanic, done.
• What it costs: free, no credit card. You'd only start paying once your app has thousands of active users, and then it's $25/month.
• Where it lives: in your name, in your own Supabase account. Not ours. You own it.

If that's enough for you, skip to How to connect Supabase below. Otherwise, keep reading. The next sections explain why apps need this kind of thing in the first place.

Why apps need something like Supabase (the no-jargon version)

Imagine the simplest possible app: a button that, when you tap it, shows the time. That app is just screens. It doesn't have to remember anything between uses. Close it, open it tomorrow. Same buttons, same behaviour. No external services needed.

Now imagine a real app. Say, a habit tracker. The moment you tap "I drank water today," your app has to remember that. Tomorrow when you open the app, that tick has to still be there. Next week, when you check your streak, the app has to look back at the last seven days.

That memory has to live somewhere. It can't just live on your phone, because:

• If your phone dies, the memory dies with it.
• If you sign in from your tablet, the tablet doesn't know your phone's history.
• If you have friends who share the app, your habits have to be visible to them, and they're not on your phone.

So the memory has to live somewhere on the internet: somewhere your phone can reach, your friends' phones can reach, your tablet can reach. Some shared place every copy of the app can look at.

Supabase is that place. It's a free service that, once you sign up, gives your app a private spot on the internet where it can write down anything it needs to remember.

Without Supabase (or something like it), your app is a brochure: pretty screens, no real memory. With Supabase, your app is a real app, with users, with their data, with a history.

The four things Supabase gives you

It's not just memory. Supabase actually rolls up four useful things into one service:

1. A place to remember stuff (a database)

The main thing. Every kind of thing your app remembers (users, posts, messages, settings, anything) has a spot here.

What's "a database"? It's just a fancy word for a place that holds organised information. Picture a giant, very tidy filing cabinet. One drawer for users, one drawer for posts, one drawer for orders. Each drawer holds cards (rows) with the same kind of information on each. That's it.

2. Sign-in (also called "authentication")

The whole sign-up, sign-in, "forgot my password," "sign in with Google" experience. Supabase handles all of this. You don't build any of it from scratch. Appsanic taps into Supabase's sign-in system and your app gets a complete sign-in flow.

3. A place for files (file storage)

Photos, videos, voice notes, PDFs, anything users upload. They go into Supabase's file storage. Each user only has access to their own files, by default.

4. Live updates (also called "realtime")

When something changes (a new message, a friend ticks off a habit), every phone using your app sees it instantly. No "tap refresh to see new messages."

All four of those things, one service, one account. That's what makes Supabase special. Every other option requires you to plug in three or four different things.

Picture it this way

If your app is a coffee shop, Supabase is the back room:

• The front of house (your app): the counter, the menu boards, the chairs, the lighting. That's what customers see.
• The back room (Supabase): where the till records every transaction, where the staff sign in for their shifts, where the stock is stored, where the manager looks at yesterday's numbers.

Customers never go in the back room. They don't need to know it exists. But without it, the shop doesn't actually function. It's just a room with chairs.

You design what the front of house looks like in Appsanic. Supabase quietly runs the back room.

Why does Appsanic use Supabase specifically?

Reasonable question, since there are other options. The short version:

• It's free for ages. Most apps stay free until they have tens of thousands of users.
• It does four things in one. Other options cover one thing each. You'd have to plug in three or four separate services and remember which is which.
• You own it, and it's based on Postgres - the same database that powers some of the world's most serious products. Your project lives in your account, so you can move to any other Postgres tool any time. The next section covers this in full.

You own everything

This is worth saying twice because it's the most important thing about Supabase + Appsanic:

Your Supabase project lives in your own Supabase account. Not ours.

You sign up for Supabase yourself, in your name. Their bills come to you (which is free at the start). Appsanic gets a set of keys that lets it operate the project (open it, create things in it, save and read data), but the project itself is yours forever.

That means:

• If you cancel Appsanic tomorrow, your Supabase project keeps running.
• Your users keep using your app even if you stop using Appsanic.
• You can sign in to supabase.com directly any time and see exactly what's there.
• You can export everything to a file you control (Supabase has a one-click export).
• You can move to any other tool that speaks Postgres if you want.

No lock-in. No data ransom. You hold the keys.

How Appsanic and Supabase actually work together

When you describe a feature to the agent (say, "let users save favourite recipes", "add sign-in with email and password", or "let users upload a profile photo"), the agent does two things at once:

1. Writes the app code: the screens, the buttons, the lists.
2. Reaches into your Supabase project and sets things up there (once you've switched on Account access - more below): creates a place to store favourite recipes, sets the rules so each user only sees their own, makes a spot for profile photos.

The agent says up front when it's about to work inside your account, and every action it takes there is listed in the Activity feed at the bottom of the Supabase connector page. You read what the agent did, you see it working on your phone, you move on.

If you ever want to peek behind the scenes, click Supabase dashboard from inside your Appsanic project. You'll land in your Supabase project, already signed in, with everything visible.

What the AI can do for you, in Supabase

Once you've connected Supabase and switched on Account access - a toggle on the connector page, off until you opt in - the agent can do all of this without you ever signing into Supabase yourself, and every action lands in the Activity feed described above. (With the toggle off, the agent still writes all the app code; it just hands you step-by-step setup instructions instead of running them for you. Toggle changes take effect on the next build.)

With Account access on, the AI can:

• Build the tables your app needs: every "kind of thing" your app remembers (users, posts, orders, anything).
• Set the privacy rules so each user only sees their own stuff (more on this in a moment).
• Set up file storage for photos and uploads.
• Create and manage user accounts: sign-up, sign-in, password reset, email verification.
• Add starter data so your app works on day one (sample posts, default settings).
• Run automatic actions when data changes (like sending a notification when someone gets a new comment).
• Update the data setup as the app grows: add a column, link tables together, add a new "kind of thing."

If you add one extra optional thing (an "admin token", three clicks):

• Add "Sign in with Google", "Sign in with Apple", "Sign in with GitHub": these require admin permission on your Supabase project.
• Tune email and security settings: sender domain, session length, password rules.
• Run small scripts on the server: for webhooks, scheduled tasks, anything that runs without a user touching the app.

The optional admin token is genuinely optional. Most apps work perfectly without it. You can always add it later.

What the AI sees vs what stays server-side

This is the part people get wrong, so it's worth being precise. "Connected" doesn't mean the AI has all your keys - it means the AI can ask our server to do things on your behalf with the keys you gave us, once Account access is on.

What the AI sees in its working context (and embeds in your app's code):

• Your Supabase project URL (the https://abcd1234.supabase.co address).
• Your Supabase public key (also called the anon key). This one is safe to bundle into your app's JavaScript bundle - Supabase designed it that way. Your data is protected by the privacy rules you set on each table, not by hiding this key. The AI bakes this value as a string directly into your lib/supabase.ts (or equivalent) so the app boots and connects without any extra setup on your side.

What stays encrypted on our servers and never touches the AI:

• Your admin key (also called the service-role key). This one bypasses every privacy rule. We hold it under AES-256-GCM encryption and only our internal tools use it - when the AI says "set up a table" or "configure auth," our server runs the operation with this key. The AI never sees the value itself.
• Your token signing secret (JWT secret), if you provided one.
• Your account admin token, if you provided one. Same handling - encrypted, used only by our server-side tools when the AI requests an account-level operation.

Why this split matters:

If you ever wonder why the AI sometimes says "I'll set up the database for you" but sometimes asks you for a specific value: that's the line above. Anything below the line, the AI runs through our server-side tools using your saved keys (every such action is recorded in the Activity feed). Anything above the line, the AI can use directly in the code it generates for you.

There is no failure mode where the AI is missing a value it needs but you've "already connected" Supabase. If you ever see the AI struggle with credentials, that's a bug on our side and we want to know about it.

Connecting Supabase to your account

This is the one-time setup. About five minutes total. You do it once per account - every project in the account shares the connection.

The quick way, when you see it: open Dashboard → Connectors → Supabase and look for a Connect with Supabase button. Click it, approve in the window that opens, then confirm which Supabase project to connect (pre-selected if you only have one). Done - no key copying. The paste-keys form is always available beneath the button, and the steps below walk through that path. Don't skip a step; it's only five.

Step 1: Sign up for Supabase (free, no credit card)

Go to supabase.com and click Start your project. You can sign in with GitHub, or just an email + password.

Once you're in, click New project. You'll see a small form:

• Name: anything. Call it "My App" or "Habit Forge"; only you ever see this name.
• Database password: Supabase generates a strong one for you. Copy it and write it somewhere safe (a password manager, a note app). You probably only need it once, but Supabase cannot recover it for you if you lose it.
• Region: pick the one closest to your users. If your users are in North America, pick a US one. Europe? Frankfurt or Dublin. Asia-Pacific? Sydney or Singapore. This makes your app feel faster for people in that area.
• Plan: Free.

Click Create project. Supabase takes about a minute to spin everything up. While it's loading, you can read the next step.

Step 2: Find Supabase's settings page

When your project is ready, look at the left sidebar in the Supabase dashboard. At the bottom, click the ⚙️ gear icon ("Project Settings").

You're now on the settings page. Two sub-pages from here have what you need:

• "Data API": has your project's web address.
• "API Keys": has the two keys you'll paste in.

Step 3: Copy three things into Appsanic

Open Appsanic in a separate browser tab. Go to Dashboard → Connectors → Supabase. You'll see a form with three required fields.

Here's exactly where to find each one in Supabase:

Copy each one carefully. The #1 reason connections fail is an accidental space when you copy. Click into the field, copy, click into Appsanic's matching field, paste. Don't paste anywhere else first.

A note on the difference between the two keys, since this confuses everyone:

• The public key is meant to be in your app. Phones get a copy of it. It's safe because Supabase only lets it do what your privacy rules allow. Think of it as the "shop's front door key". Everyone has it, but the front door only lets you into the public area.
• The admin key is the keys to everything. It bypasses every rule. It never leaves Appsanic's server. Phones never see it. We encrypt it before saving. The agent uses it only when it needs to set things up (creating tables, configuring sign-in).

Step 4 (optional): Get an admin token for extra power

Skip this if you just want the basics working. Add it later if you find you need it.

If you want the agent to also configure social sign-in (Google, Apple, etc.) or tune email settings:

1. Go to supabase.com/dashboard/account/tokens.
2. Click Generate new token.
3. Name it "Appsanic".
4. Copy it right away (Supabase only shows it once).
5. Paste it into the Account admin token field in Appsanic.

Step 5: Click Connect

Appsanic now runs a quick test to make sure your keys work. Three possible results:

• ✅ Connected: you're done. The agent can use Supabase whenever you ask it to.
• ❌ "Invalid keys": almost always a copy-paste issue. Usually:
• An accidental space at the start or end of one of the keys (most common).
• The public key and admin key swapped (each goes in a specific field).
• The admin key copied while it was still hidden (you copied dots, not the real key).

Re-copy carefully, paste, click Connect again.

• ⚠️ "Connection works but admin token is invalid": your basic setup is fine; just the optional token is wrong. Save with the basics and skip the admin token for now.

That's it. Supabase is connected. From now on, every prompt you write that touches data automatically uses your Supabase project. One more switch worth knowing: if you want the agent to set things up inside the project for you (tables, privacy rules, auth settings), flip on Account access on the same page - it's off until you do.

Looking at what's in your Supabase project

You don't have to. But if you want to peek:

From Appsanic, click Supabase dashboard at any time and you land in your Supabase project, already signed in.

Most useful Supabase tabs:

• Table Editor: every drawer of your filing cabinet. Click a table to see what's inside.
• Authentication → Users: every user who's signed up for your app. You can invite, ban, or delete users here if you ever need to.
• Storage: where uploaded files (photos, etc.) live.
• Logs: if something's not working, errors show up here.

Privacy: the most important thing happening invisibly

Every time the agent creates a table for user data, it also writes a rule that says:

"Only the user this row belongs to can see or edit it."

This rule lives in Supabase itself, not just in your app's code. Which means: even if there's a bug in your app, even if a hacker tried to ask for someone else's data, Supabase itself refuses.

It's a second locked door, deeper than the front door. The technical name is "Row Level Security"; you don't need to remember that. You just need to know it's on, and that the agent sets it up automatically every time it creates a table.

You can verify this in the Supabase dashboard under Authentication → Policies. Every user-facing table should have at least one policy. If you ever create a table by hand in Supabase (rather than through Appsanic), you'd have to remember to add the policy yourself. The agent does this automatically.

What it costs

The free tier covers a lot. As of mid-2026:

• 500 MB of data: that's roughly 100,000 to 1,000,000 typical user records. Most small apps never come close.
• 1 GB of file storage: plenty for thousands of profile photos.
• 5 GB of bandwidth per month.
• 50,000 monthly active users.
• Generous limits on realtime connections and messages.

<a id="free-tier-pause"></a> One quirk of the free plan worth knowing up front: a free-tier project auto-pauses after a week of no activity (Supabase does this to save money on idle projects). A paused project can't answer your app, so connections and queries fail until it wakes. To wake it, open the Supabase dashboard for that project and click Restore; it's back in about a minute. To stop it pausing at all, upgrade to the Pro plan ($25 USD/month), which never pauses. The rest of this page refers back to this when it comes up.

You'd pay when:

• Your app has lots of users (above 50k monthly active).
• You're storing lots of files (above 1 GB).
• You need the project to never pause.
• You want automatic backups beyond the default.

The Pro plan is $25 USD/month per Supabase project and covers most production apps for a long time.

Common scenarios

"I'm starting my second project. Do I need a new Supabase account?"

No - and you may not need to connect anything at all. Connections are account-wide: connect Supabase once and every project in the account uses it. If you'd rather keep each app's data fully separate, create a new Supabase project at supabase.com (one Supabase account holds many) and either switch the connection when you switch focus, or keep the apps in separate Appsanic accounts.

"I want to wipe everything and start over"

Two options in the Supabase dashboard, both under Settings → General:

• Reset database: wipes the data, keeps the project and its connection.
• Delete project: wipes everything irreversibly for a fresh slate (you confirm by typing the project name). Export anything you want to keep first, then click Disconnect in Appsanic → Dashboard → Connectors → Supabase before connecting a new project.

After a reset, ask the agent: "Reset complete. Rebuild the data structure for the app, recreate the tables, privacy rules, and any starter data."

"I need to change the region"

Once a Supabase project is created in a region, you can't move it. To change:

1. Create a new Supabase project in the new region.
2. For a brand-new app: just connect the new project to Appsanic.
3. For an app with users already: export the data from the old project (Supabase dashboard → Database → Backups), create the new project, restore the backup, then update the connection in Appsanic.

The agent can walk you through this if you ask.

"Separate environments for development and production"

For more serious projects, you usually want separate Supabase projects for development, staging, and production. That way, you can experiment in development without affecting real users.

"Give me three environments: development, staging, production. Each has its own Supabase project."

The agent sets up the separate configurations. See Environment Variables.

"I accidentally shared my admin key publicly"

Bad day, but fixable.

1. In the Supabase dashboard, go to Project Settings → API Keys.
2. Click Reset service_role key. The old one stops working immediately.
3. In Appsanic, go to Dashboard → Connectors → Supabase, paste the new admin key, click Save.
4. Look at the Logs tab in Supabase for any suspicious activity in the time the old key was exposed.

If you also used the optional admin token, rotate it at supabase.com/dashboard/account/tokens.

Things that go wrong

"Invalid keys" when I try to connect

Almost always a copy-paste issue. In order of how often we see it:

1. An accidental space at the start or end of one of the keys. The fix: re-copy, paste carefully.
2. Public and admin key swapped. Each goes in a specific field. Double-check you put the right one in each.
3. Copied while the key was still hidden. Supabase masks the admin key by default. Make sure you clicked Reveal before copying.
4. Project is paused. A paused free-tier project can't answer the connection test. Open its Supabase dashboard to wake it, then retry.

"My users can sign up but can't see any data"

This is the privacy rules doing their job, but too aggressively for the current case. Usually:

1. You added data manually in the Supabase dashboard and forgot to set the user. The agent sets user_id automatically when creating data through code, but manual rows often forget. Edit those rows and fill in the correct user_id.
2. The user just signed up and there's no data linked to them yet. That's the expected empty state.
3. A bug in the privacy rules. Open Supabase → Authentication → Policies and check each table has a sensible rule.

If you're stuck, paste it into the chat: "Users can sign in but their data screen is empty even though there's data in the table." The agent looks at the policies and explains.

"A query is slow"

Free-tier Supabase usually has no performance issues for small apps. If a query gets slow, usually one of:

• The table has lots of rows and the query has no index.
• The query is asking for too much when it could ask for less.
• The app is making the same query repeatedly when it could cache the result.

Ask Sanic AI to review the slow query - it'll usually point right at the cause and propose an index or a tighter select.

"My app suddenly can't reach Supabase"

If your app was working and now every query fails, the most common cause is a paused free-tier project. Open its Supabase dashboard to wake it, or move to the Pro plan so it never pauses.

Under the hood (for engineers)

What's actually in your project after the agent wires Supabase up:

• Client: the @supabase/supabase-js SDK, initialised once and exposed from a small lib/supabase.ts. Your project URL and anon key are inlined there as strings - an exported project has no .env file, and the anon key is safe to bundle. Auth state lives in a Zustand store that the navigator (React Navigation v7) reads to fork between the signed-in and signed-out stacks.
• Server-side work: anything that must bypass RLS (admin operations, webhooks, scheduled jobs) runs with the service-role key, which never reaches the app. Appsanic runs those server-side, or the agent deploys a Supabase Edge Function as a small relay.
• Schema changes: applied to your project directly through Appsanic's server-side tools, each with RLS enabled and at least one policy on every user-scoped table. An exported project does not carry a local supabase/migrations/ folder.
• Realtime: subscriptions via supabase.channel(...).on('postgres_changes', ..., handler).subscribe(), cleaned up on unmount with removeChannel.
• Storage: buckets with RLS policies that namespace by auth.uid() in the path (<bucket>/<user_id>/<filename>).

What Appsanic itself stores: the credentials you pasted in, encrypted at rest with envelope encryption, read only server-side when dispatching tools that touch your project. The anon key is inlined into the app's code; the service-role key and admin token never leave the server. Both key formats are accepted in the form - the new-style sb_publishable_* / sb_secret_* and the legacy eyJ* JWTs - and the validator normalises both.

Next

Read Database & Data for how the data side works in detail, or Authentication for the sign-in flow. Or just go build something. Every doc in the Building features section assumes Supabase is connected.