Как поднять Supabase локально — полное руководство для вайбкодеров

Работать с облачным Supabase удобно, пока проект маленький и интернет стабильный. Но как только начинаются реальные итерации — частые правки схемы, тест авторизации, отладка Storage — облако превращается в тормоз: долгие запросы, случайный лимит на бесплатном плане, невозможность работать офлайн.

Локальный Supabase решает это полностью. Вы получаете точную копию всего стека — PostgreSQL, Auth, Storage, Realtime, Studio — прямо на своей машине. Это стандартный способ разработки в 2026 году, и в этой статье я покажу, как это сделать правильно, с нуля до первого рабочего запроса.

1. Что именно запускается локально

Supabase — это не одна программа, а набор сервисов, скреплённых Docker Compose. Когда вы поднимаете его локально, запускаются:

• PostgreSQL 15 — основная база данных.
• PostgREST — автоматически генерирует REST API из вашей схемы БД.
• GoTrue — сервис авторизации (email, OAuth, magic link).
• Realtime — WebSocket-сервер для подписок на изменения в таблицах.
• Storage API — S3-совместимое хранилище файлов.
• Kong — API-шлюз, через который проходят все запросы.
• Supabase Studio — веб-интерфейс для управления всем стеком (на порту 54323).
• Inbucket — локальный почтовый сервер для тестирования писем (на порту 54324).

Всё это поднимается одной командой и работает идентично облаку. Миграции, которые вы пишете локально, применяются в облаке без изменений.

2. Требования перед началом

Убедитесь, что установлено:

• Docker Desktop (или Docker Engine + Docker Compose на Linux). Версия 20.10+.
• Node.js 18+ — нужен для установки Supabase CLI через npm.
• Свободно ~4 ГБ RAM (все контейнеры вместе потребляют 2–3 ГБ).
• ~3 ГБ на диске для образов.

Проверить можно так:

docker --version

# Docker version 26.1.0 или выше

node --version

# v20.x.x или выше

## 3. Установка Supabase CLI

Supabase CLI — это единственная утилита, которая вам нужна. Она управляет локальным стеком, миграциями и связью с облаком.

macOS / Linux (через npm)

npm install -g supabase

macOS (через Homebrew)

brew install supabase/tap/supabase

Windows

# Через Scoop

scoop bucket add supabase https://github.com/supabase/scoop-bucket.git

scoop install supabase

Проверяем установку:

supabase --version

# 1.200.x или выше

4. Инициализация проекта

Перейдите в папку вашего проекта и инициализируйте Supabase:

cd my-project

supabase init

Команда создаёт папку supabase/ со следующей структурой:

supabase/

├── config.toml # конфигурация локального стека

├── migrations/ # SQL-миграции

└── seed.sql # начальные данные (опционально)

Файл config.toml — это главный конфиг. По умолчанию он уже рабочий, но вы можете изменить порты, если что-то конфликтует:

[api]

port = 54321 # PostgREST + Kong

[db]

port = 54322 # PostgreSQL

[studio]

port = 54323 # Supabase Studio

[inbucket]

port = 54324 # Тестовая почта

[storage]

file_size_limit = "50MiB"

5. Запуск локального стека

supabase start

Первый запуск займёт 3–7 минут — Docker скачает все образы (~2 ГБ). Последующие запуски — 15–30 секунд.

После успешного старта в терминале появится вывод с ключами:

Started supabase local development setup.

API URL: http://127.0.0.1:54321

GraphQL URL: http://127.0.0.1:54321/graphql/v1

S3 Storage URL: http://127.0.0.1:54321/storage/v1/s3

DB URL: postgresql://postgres:postgres@127.0.0.1:54322/postgres

Studio URL: http://127.0.0.1:54323

Inbucket URL: http://127.0.0.1:54324

anon key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

service_role key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Сохраните эти значения — они понадобятся для подключения из вашего приложения.

Если забыли — можно получить снова:

supabase status

6. Supabase Studio — локальный дашборд

Откройте в браузере http://127.0.0.1:54323.

Вы увидите полноценный Supabase Studio — тот же интерфейс, что и в облаке. Здесь можно:

• Просматривать и редактировать таблицы через Table Editor.
• Писать SQL-запросы через SQL Editor.
• Управлять пользователями через Authentication.
• Загружать файлы через Storage.
• Просматривать логи всех сервисов.

Inbucket (тестовая почта) доступен на http://127.0.0.1:54324. Все письма от Auth (подтверждение email, magic link, сброс пароля) приходят сюда — не нужно настраивать SMTP для разработки.

7. Подключение к проекту из кода

Переменные окружения (.env)

NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321

NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Инициализация клиента (JS/TS)

import { createClient } from '@supabase/supabase-js'

const supabase = createClient(

process.env.NEXT_PUBLIC_SUPABASE_URL!,

process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!

)

Если используете Next.js с серверными компонентами, добавьте SUPABASE_SERVICE_ROLE_KEY для серверных операций:

// Только на сервере — никогда не передавайте в браузер

const supabaseAdmin = createClient(

process.env.NEXT_PUBLIC_SUPABASE_URL!,

process.env.SUPABASE_SERVICE_ROLE_KEY!

)

8. Миграции — правильный способ менять схему

Никогда не меняйте схему базы напрямую через Studio в долгосрочных проектах — изменения потеряются при сбросе или не попадут в облако. Используйте миграции.

Создать новую миграцию

supabase migration new create_posts_table

Создаётся файл supabase/migrations/20260527120000_create_posts_table.sql. Напишите в нём SQL:

create table posts (

id uuid default gen_random_uuid() primary key,

title text not null,

content text,

user_id uuid references auth.users(id) on delete cascade,

created_at timestamptz default now()

);

-- Включаем Row Level Security

alter table posts enable row level security;

-- Политика: пользователь видит только свои посты

create policy "Users can view own posts"

on posts for select

using (auth.uid() = user_id);

-- Политика: пользователь может создавать посты

create policy "Users can insert own posts"

on posts for insert

with check (auth.uid() = user_id);

Применить миграции

supabase db reset

Эта команда сбрасывает локальную БД и применяет все миграции заново + seed.sql. Используйте её когда нужно получить чистое состояние.

Применить только новые миграции без сброса:

supabase migration up

Сгенерировать TypeScript-типы из схемы

supabase gen types typescript --local > src/types/database.types.ts

После этого у вас будут полные типы для всех таблиц — ИИ-ассистент будет работать с ними значительно точнее.

9. Seed-данные — тестовое наполнение базы

Файл supabase/seed.sql выполняется при каждом supabase db reset. Добавьте туда тестовые данные:

-- Создаём тестового пользователя (только для локальной разработки)

insert into auth.users (id, email, encrypted_password, email_confirmed_at)

values (

'00000000-0000-0000-0000-000000000001',

'test@example.com',

crypt('password123', gen_salt('bf')),

now()

);

-- Тестовые посты

insert into posts (title, content, user_id) values

('Первый пост', 'Привет, мир!', '00000000-0000-0000-0000-000000000001'),

('Второй пост', 'Supabase локально — это просто.', '00000000-0000-0000-0000-000000000001');

10. Остановка и управление стеком

# Остановить (данные сохраняются)

supabase stop

# Остановить и удалить все данные (полный сброс)

supabase stop --no-backup

# Посмотреть статус всех сервисов

supabase status

# Логи конкретного сервиса

supabase logs db # PostgreSQL

supabase logs auth # GoTrue

supabase logs realtime # Realtime

supabase logs storage # Storage

11. Синхронизация с облачным проектом

Когда локальная разработка готова, можно связать локальный проект с облаком:

# Авторизоваться в Supabase

supabase login

# Связать с облачным проектом

supabase link --project-ref ваш-project-ref

# Применить все локальные миграции в облаке

supabase db push

project-ref можно найти в URL вашего проекта на supabase.com: https://app.supabase.com/project/ваш-project-ref.

Важно: supabase db push применяет только новые миграции. Уже применённые в облаке миграции он не трогает.

12. Типичные проблемы и решения

Docker не запускается

# Убедитесь, что Docker Desktop запущен

docker info

# Если ошибка "port already in use" — найдите и остановите процесс

lsof -i :54321

kill -9

Studio не открывается

Подождите 30–60 секунд после supabase start — Studio запускается последним. Если не помогло:

supabase stop && supabase start

Ошибка при миграции

Если миграция сломала схему — сбросьте базу:

supabase db reset

Auth не отправляет письма

Письма в локальной среде не отправляются на реальный email. Откройте Inbucket: http://127.0.0.1:54324 — все письма там.

Конфликт портов на Windows/Mac

Измените порты в supabase/config.toml и перезапустите стек.

13. Советы для работы с ИИ-ассистентом

Если вы используете Cursor, Claude Code или аналогичный инструмент — добавьте в AGENTS.md или системный промпт:

## Supabase

- Локальный стек запущен через `supabase start`

- URL: http://127.0.0.1:54321

- Все изменения схемы — только через миграции в `supabase/migrations/`

- Типы сгенерированы в `src/types/database.types.ts`

- RLS включён на всех таблицах — всегда добавляй политики при создании таблицы

- Для сброса базы: `supabase db reset`

ИИ будет понимать структуру проекта и не будет предлагать менять схему напрямую через Studio.

Заключение

Локальный Supabase — это не «сложная настройка», а стандартный рабочий процесс, который занимает 10 минут при первом запуске и ускоряет разработку в разы. Вы получаете полный контроль над стеком, работаете офлайн, тестируете миграции без страха сломать облачную базу и применяете всё в прод одной командой.

Краткий маршрут:

1. npm install -g supabase — установить CLI.
2. supabase init — инициализировать проект.
3. supabase start — запустить стек.
4. Studio на http://127.0.0.1:54323 — управлять данными.
5. Миграции через supabase migration new — менять схему.
6. supabase db push — выкатить в облако.

Если у вас уже есть облачный проект и вы хотите подтянуть его схему локально — пишите в комментариях, разберём этот сценарий отдельно.