26  Getting Started with Supabase

26.1 Learning Objectives

By the end of this chapter, students will be able to:

  • Create a Supabase account and provision a new PostgreSQL project using the Supabase dashboard.
  • Navigate the Supabase interface to locate the SQL Editor, connection settings, and project credentials.
  • Run a query against a hosted database using the Supabase SQL Editor.
  • Retrieve the connection string for a Supabase project and use it to connect from an external client.
  • Distinguish between a local development database and a hosted cloud database, including the implications for schema changes and data persistence.

The chapters in this section move beyond writing SQL against a local database and into the work of deploying and managing a database in the cloud. That shift introduces questions that local development does not: How do you create and configure a hosted database? How do you push schema changes from your development machine to a remote server without breaking existing data? How do you keep track of what changed, when, and why?

This chapter covers the first step: setting up a Supabase account and learning your way around its interface. The following chapters introduce the Supabase CLI, which brings the deployment workflow into VS Code, and database migrations, which give schema changes a versioned, reproducible history.

26.2 What is Supabase?

Supabase is an open-source backend platform built on PostgreSQL. It provides hosted PostgreSQL databases alongside a web interface, a SQL editor, auto-generated APIs, user authentication, and file storage. For this textbook, the focus is on the database layer: the managed PostgreSQL service, the browser-based SQL editor, and the migration tooling that makes schema changes trackable and reproducible.

Supabase is a good choice for learning deployment because it runs standard PostgreSQL, its free tier is genuinely usable for coursework, and the tooling is designed to work well with local development environments. Everything you learn here transfers directly to other PostgreSQL hosting providers.

The Supabase free tier includes two active projects and 500 MB of database storage per project. Projects on the free plan pause automatically after one week of inactivity and resume when you visit them in the dashboard. For coursework, this means your database will occasionally need a moment to wake up before accepting connections.

26.3 Creating an Account

Go to supabase.com and click Start your project. You can sign up with a GitHub account, which avoids creating a separate password and is the recommended option if you already use GitHub. After signing in for the first time, Supabase will ask you to create an organization.

26.4 Creating an Organization and Project

Supabase organizes work into organizations and projects. An organization is the top-level container for your projects, billing, and team members. A project is a single PostgreSQL database instance with its own connection credentials, storage, and configuration.

Give your organization a name (your name or course name works fine), then create your first project:

  1. Click New project in the dashboard.
  2. Select your organization.
  3. Enter a project name.
  4. Set a strong database password and save it somewhere you can retrieve it later. You will need it to connect external tools.
  5. Choose a region geographically close to you.
  6. Click Create new project.

Provisioning takes about a minute. During this time Supabase is allocating a PostgreSQL instance, configuring networking, and setting up the supporting services. When it finishes, you land on the project dashboard.

26.5 The Dashboard

The left-hand navigation of the Supabase dashboard groups functionality into several areas. You will not use all of them for database work, but it is worth knowing what is there.

Table Editor. A spreadsheet-style view of your tables. You can browse rows, insert data, and filter results without writing SQL. It is convenient for quick inspection but not a substitute for the SQL Editor when you need precision.

SQL Editor. A browser-based interface for writing and running SQL against your database. This is the main tool for schema work in this chapter. It supports full PostgreSQL syntax, saves query history, and lets you save frequently used queries.

Database. Sub-pages for tables, views, functions, triggers, extensions, indexes, and roles. The Tables page lists every table in your database with column details and row counts. The Extensions page lets you enable PostgreSQL extensions such as uuid-ossp or pgcrypto with a toggle rather than a SQL command.

Authentication, Storage, Edge Functions. These are parts of the Supabase platform beyond the database layer and are not covered in this textbook.

Project Settings. Configuration for the project, including API keys, connection strings, and general settings. The Database section under Settings is where you find the credentials needed to connect external tools.

26.6 The SQL Editor

Click SQL Editor in the left navigation to open the query interface. The editor supports the full PostgreSQL dialect. You can write multi-statement scripts, use Ctrl+Enter (or Cmd+Enter on macOS) to run a query, and save named snippets for later use.

To create a table, write a CREATE TABLE statement and run it:

CREATE TABLE students (
    id          SERIAL PRIMARY KEY,
    last_name   TEXT NOT NULL,
    first_name  TEXT NOT NULL,
    enrolled_on DATE DEFAULT CURRENT_DATE
);

The result appears below the editor. Switch to the Table Editor to see the new table listed, or run a query to confirm:

SELECT table_name
FROM information_schema.tables
WHERE table_schema = 'public'
ORDER BY table_name;

Error messages in the SQL Editor include the full PostgreSQL error text, so troubleshooting syntax problems works the same way it does with a local database.

The SQL Editor in Supabase connects to the public schema by default. If you create objects in other schemas, you may need to qualify them with the schema name (for example, analytics.events rather than just events).

26.7 Finding Your Connection String

External tools such as psql, pgAdmin, DBeaver, or the VS Code extensions introduced in the next chapter connect to your Supabase database using a connection string. To find yours:

  1. Click Project Settings in the left navigation.
  2. Click Database under the Settings section.
  3. Scroll to the Connection string section.

Supabase provides the connection string in several formats. The URI format is the most portable:

postgresql://postgres:[YOUR-PASSWORD]@db.[PROJECT-REF].supabase.co:5432/postgres

Replace [YOUR-PASSWORD] with the database password you set during project creation. The [PROJECT-REF] portion is a short alphanumeric string unique to your project; Supabase fills it in automatically when you copy the string from the dashboard.

Keep this connection string available. The next chapter uses it to link your local development environment to this remote database.

26.8 Exercises

  1. Create a Supabase account and project following the steps in this chapter. Note the region you selected and the project reference ID shown in Project Settings.

  2. In the SQL Editor, create a table called courses with columns for a surrogate primary key, a course code (text, not null), a course title (text, not null), and a credit hours value (integer, not null). Verify the table appears in the Table Editor.

  3. Insert two rows into the courses table using INSERT INTO in the SQL Editor. Use the Table Editor to confirm that the rows are visible.

  4. Drop the courses table using DROP TABLE. Confirm in the Table Editor that it no longer appears. Explain why being able to run DDL statements directly in the SQL Editor is both useful and something to be careful about.