Project Setup and the Supabase CLI

The idea in one sentence

A Supabase project starts as a hosted Postgres instance with two API keys of very different trust levels, and the Supabase CLI is what lets you link a local folder to it and run the entire stack on your own machine with Docker.

Creating a project and its two keys

You create a new hosted project from the Supabase dashboard, or the shortcut database.new. Behind the scenes this provisions a dedicated Postgres instance, an API URL, and two API keys:

• anon key — public, safe to ship in client-side code (a browser bundle, a mobile app). Requests using this key are subject to Row Level Security.
• service_role key — secret, full-access, bypasses Row Level Security entirely. It is meant only for trusted server-side code.

⚡ Never expose the service_role key in client-side code

The service_role key skips every RLS policy on every table. If it ends up in a browser bundle, a mobile app, or any code a user can inspect, anyone can read and write your entire database. Keep it in server-only environment variables, never in code that ships to a client. This is a rule the rest of this course keeps coming back to.

// Server-side only — e.g. an API route, a cron job, an Edge Function.
// process.env.SUPABASE_SERVICE_ROLE_KEY must never be bundled into client code.
import { createClient } from '@supabase/supabase-js';

const supabaseAdmin = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!
);

The Supabase CLI

The CLI is how you manage a project as code instead of only through the dashboard:

# Scaffold a local supabase/ config directory in your project
npx supabase init

# Authenticate the CLI with your Supabase account
supabase login

# Connect this local project folder to a specific hosted project
supabase link --project-ref <project-ref>

supabase link is what tells your local supabase/ folder which hosted project it corresponds to — every later db push or db diff targets that linked project.

Local development with supabase start

supabase start

This spins up the entire Supabase stack locally via Docker — Postgres, Studio, Auth, Storage, Realtime, and the rest, all running as containers on your machine. That means you can develop and test your schema, your RLS policies, and your client code completely offline, with no risk to your hosted project, before ever running supabase db push against it.

flowchart LR
  subgraph local["Local machine (supabase start)"]
    lpg[("Postgres")]
    lstudio["Studio"]
    lauth["Auth"]
    lstorage["Storage"]
  end
  subgraph hosted["Hosted project"]
    hpg[("Postgres")]
    hapi["API URL + anon/service_role keys"]
  end
  local -- "supabase link --project-ref" --> hosted
  local -- "supabase db push" --> hosted

A local Docker-based stack linked to a hosted project

⚡ The one-line takeaway

A hosted project gives you Postgres plus an API URL, an anon key for client code (subject to RLS), and a service_role key for trusted server code (bypasses RLS — never ship it to a client). The CLI’s supabase init, supabase login, and supabase link --project-ref connect a local folder to that project, while supabase start runs the whole stack locally in Docker so you can develop entirely offline.

What is the key difference between the anon key and the service_role key?

There is no difference, they are interchangeable The anon key is subject to Row Level Security; the service_role key bypasses RLS entirely and must stay server-side The anon key is secret and the service_role key is public The service_role key only works in local development

Why must the service_role key never reach client-side code?

It expires after one request It only works with GraphQL, not REST It bypasses Row Level Security, so anyone with it can read and write the entire database It is slower than the anon key

What does `supabase start` do?

Deletes the hosted project Runs the full Supabase stack locally via Docker, including Postgres, Studio, Auth, Storage, and Realtime Pushes local migrations to the hosted project Only starts a Postgres client, nothing else

What does `supabase link --project-ref <ref>` do?

It creates a brand new hosted project It connects your local project folder to a specific existing hosted project It generates the anon and service_role keys It starts the local Docker stack

Submit

Mark as complete