Supabase CLI Kullanımı: Kapsamlı Geliştirici Rehberi (2026)

TL;DR

Supabase CLI, Docker kullanarak makinenizde tam bir Supabase yığını (PostgreSQL, Kimlik Doğrulama, Depolama ve Edge Fonksiyonları) çalıştırır. `brew install supabase/tap/supabase` ile kurun, yerel bir ortam başlatmak için `supabase init` ve `supabase start` komutlarını çalıştırın, ardından üretime göndermek için `supabase db push` ve `supabase functions deploy` komutlarını kullanın. Bulut ortamına dokunmadan Supabase arka uçlarını oluşturmanın ve test etmenin en hızlı yoludur.

Giriş

Arka uç hatalarının %73'ü, geliştiricilerin yerel testi atlaması nedeniyle üretimde yakalanır. Supabase CLI ile, bu artık bir bahane değil. Makinenizde 5 dakikadan daha kısa sürede tam bir üretime eşdeğer bir ortam çalıştırabilirsiniz.

İşte asıl sorun: çoğu geliştirici ya doğrudan üretimde test yapar (riskli) ya da bulut ortamıyla asla tam olarak eşleşmeyen yerel ortamları yapılandırmak için saatler harcar (sinir bozucu). Supabase CLI her ikisini de çözer. Üretimi tam olarak yansıtan Docker tabanlı bir yerel yığın sunar, böylece yerelde çalışan üretimde de çalışır.

Supabase API'lerinizi Apidog ile test edin - ücretsiz

Bu rehberin sonunda şunları yapabileceksiniz:

• Eksiksiz bir yerel Supabase ortamını dakikalar içinde kurmak
• Sürüm kontrollü migrasyonlar ile veritabanı şema değişikliklerini yönetmek
• Edge Fonksiyonlarını dağıtımdan önce yerelde oluşturmak ve test etmek
• Tek bir komutla üretime dağıtım yapmak

CLI olmadan yerel Supabase geliştirmesi neden sorun çıkarır?

CLI olmadan bir Supabase uygulaması oluşturmayı denediyseniz, bu acıyı bilirsiniz. İşte sürekli olarak yaşanan üç senaryo.

"Üretimde test etme" tuzağı. Doğrudan Supabase panosunda bir şema değişikliği yaparsınız. Çalışır. Ön ucunuzu yayınlarsınız. Üç gün sonra, bir ekip arkadaşı depoyu çeker ve veritabanlarında yeni sütun olmadığı için uygulamaları bozulur.

Ortam uyuşmazlığı. Yerel bir PostgreSQL örneği kurar, Supabase şemanızı manuel olarak yeniden oluşturur ve Row Level Security (Satır Seviyesi Güvenliği) politikalarının yerelde neden farklı davrandığını hata ayıklamak için iki saat harcarsınız. Aslında farklı davranmazlar. Bir politikayı kaçırmışsınızdır.

"Benim makinemde çalışıyor" sorunu. Edge Fonksiyonunuz Supabase panosu düzenleyicisinde çalışır ancak gerçek ortam değişkenleri yerine sabit kodlanmış değerlerle test ettiğiniz için üretimde başarısız olur.

Bunlar nadir durumlar değildir. Şema kayması (yerel ve uzaktaki veritabanlarının senkronizasyon dışına çıkması), Supabase kullanan ekipler için bildirilen 1 numaralı sorundur. CLI, bu üç sorunu da çözer:

• Migrasyonlar, şema değişikliklerini sürüm kontrollü ve yeniden üretilebilir tutar
• Yerel Docker yığını, aynı PostgreSQL sürümü, aynı RLS motoru ile üretimi tam olarak yansıtır
• Yerel fonksiyon sunumu, Edge Fonksiyonlarını gerçek ortam değişkenleriyle test eder

Supabase CLI nasıl çalışır

Yerel yığın

`supabase start` komutunu çalıştırdığınızda, CLI bu hizmetlerle bir Docker Compose yığını başlatır:

Bu, Supabase Cloud'da çalışan yığının aynısıdır. Kendi makinenizde.

Kurulum

macOS:

brew install supabase/tap/supabase

Windows (Scoop):

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

Linux / npm:

npm install -g supabase

Çalıştığını doğrulayın:

supabase --version
# supabase 1.x.x

`supabase start` kullanmadan önce Docker Desktop'ın çalışıyor olması gerekir. Bunu atlarsanız, Docker daemon'ın kullanılamadığına dair kafa karıştırıcı bir hata alırsınız.

Proje kurulumu

mkdir my-project && cd my-project
supabase init

Bu şunları oluşturur:

supabase/
├── config.toml       # Portlar, kimlik doğrulama ayarları, depolama yapılandırması
├── seed.sql          # Geliştirme verileri (her veritabanı sıfırlamasında yüklenir)
└── migrations/       # Şema sürüm geçmişi

Yerel yığını başlatma

supabase start

İlk çalıştırma yaklaşık 1GB Docker imajı indirir. Bundan sonra, başlatmalar yaklaşık 10 saniye sürer.

API URL: http://localhost:54321
DB URL:  postgresql://postgres:postgres@localhost:54322/postgres
Studio:  http://localhost:54323
anon key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

`anon key`'i `.env.local` dosyanıza kopyalayın. Ön ucunuz için buna ihtiyacınız olacak.

Migrasyonlar ile veritabanı yönetimi

Migrasyonlar, CLI iş akışının çekirdeğidir. Her şema değişikliği, Git'te izlenen sürüm kontrollü bir SQL dosyası haline gelir. Artık "veritabanını kim, ne zaman değiştirdi" soruları yok.

İlk migrasyonunuzu oluşturma

supabase migration new create_posts_table
# Oluşturur: supabase/migrations/20260324120000_create_posts_table.sql

Dosyayı düzenleyin:

-- RLS'li gönderiler tablosunu baştan oluştur
CREATE TABLE posts (
  id          UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  user_id     UUID REFERENCES auth.users(id) ON DELETE CASCADE NOT NULL,
  title       TEXT NOT NULL,
  content     TEXT,
  published   BOOLEAN DEFAULT false,
  created_at  TIMESTAMPTZ DEFAULT NOW(),
  updated_at  TIMESTAMPTZ DEFAULT NOW()
);

-- Satır Seviyesi Güvenliği etkinleştir
ALTER TABLE posts ENABLE ROW LEVEL SECURITY;

-- Herkes yayınlanmış gönderileri okuyabilir
CREATE POLICY "Anyone can read published posts"
  ON posts FOR SELECT
  USING (published = true);

-- Kullanıcılar kendi gönderilerini yönetir
CREATE POLICY "Users manage own posts"
  ON posts FOR ALL
  USING (auth.uid() = user_id);

-- Her değişiklikte updated_at'i otomatik güncelle
CREATE OR REPLACE FUNCTION update_updated_at()
RETURNS TRIGGER AS $$
BEGIN
  NEW.updated_at = NOW();
  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER posts_updated_at
  BEFORE UPDATE ON posts
  FOR EACH ROW EXECUTE FUNCTION update_updated_at();

Uygulayın:

supabase migration up

TypeScript türlerini oluşturma

Her şema değişikliğinden sonra, türlerinizi yeniden oluşturun:

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

Ön ucunuz tam tür güvenliği elde eder:

import { Database } from '@/types/database'

type Post = Database['public']['Tables']['posts']['Row']
type NewPost = Database['public']['Tables']['posts']['Insert']

// Artık düzenleyiciniz çalışma zamanından önce tür hatalarını yakalar
const createPost = async (post: NewPost) => {
  const { data, error } = await supabase
    .from('posts')
    .insert(post)
    .select()
    .single()
  return data
}

Geliştirme verilerini doldurma

`supabase/seed.sql` dosyasını düzenleyin:

-- Test kullanıcıları (yerel geliştirme için kimlik doğrulamasını atlar)
INSERT INTO auth.users (id, email) VALUES
  ('00000000-0000-0000-0000-000000000001', 'alice@example.com'),
  ('00000000-0000-0000-0000-000000000002', 'bob@example.com');

-- Test gönderileri
INSERT INTO posts (user_id, title, content, published) VALUES
  ('00000000-0000-0000-0000-000000000001', 'Getting started with Supabase', 'Here is what I learned...', true),
  ('00000000-0000-0000-0000-000000000002', 'Draft: API design patterns', 'Work in progress...', false);

İstediğiniz zaman sıfırlayın ve yeniden doldurun:

supabase db reset

Bu, her şeyi siler, tüm migrasyonları yeniden çalıştırır ve başlangıç verilerinizi yükler. Her sabah yeni bir başlangıç yapmak için çalıştırın.

Supabase API'lerini Apidog ile test etme

Yerel Supabase'iniz çalıştığında, `http://localhost:54321` adresinde tam işlevsel bir REST API'niz olur. Supabase, PostgREST aracılığıyla her tablo için otomatik olarak uç noktalar oluşturur. Bunları curl ile manuel olarak test etmek, özellikle farklı kullanıcı jetonlarıyla RLS politikalarını test etmeniz gerektiğinde hızla yorucu hale gelir.

Apidog, yerel Supabase örneğinize doğrudan bağlanır. Şunları yapabilirsiniz:

• İstekleri yeniden kullanılabilir koleksiyonlar olarak kaydetmek
• Ortamları değiştirerek aynı uç noktayı farklı kullanıcılar olarak test etmek
• Onaylamalar ("yanıt en az 1 gönderi içeriyor") eklemek ve bunları bir test paketi olarak çalıştırmak
• API belgelerini ekibinizle otomatik olarak paylaşmak

Apidog'u yerel Supabase ile kurma:

1. Apidog'da yeni bir proje oluşturun
2. Temel URL'yi ayarlayın: `http://localhost:54321`
3. Ortam değişkeni ekleyin: `anon_key = yerel-anon-anahtarınız`
4. Yetkilendirme başlığı ekleyin: `Bearer {{anon_key}}`

Gönderiler uç noktasını test etme:

GET http://localhost:54321/rest/v1/posts?published=eq.true
Authorization: Bearer {{anon_key}}
apikey: {{anon_key}}

Bunu bir istek olarak kaydedin, yanıtın en az bir gönderi içerdiğine dair bir onaylama ekleyin ve RLS politikalarınızı her değiştirdiğinizde çalıştırın. Bozuk politikaları üretime ulaşmadan önce yakalayacaksınız.

Supabase API'lerinizi Apidog ile test etmeye başlayın - ücretsiz

Edge fonksiyonları: yerelde oluşturun ve test edin

Edge Fonksiyonları, Deno üzerinde, kullanıcılarınıza yakın bir konumda (edge) çalışır. Webhook'lar, arka plan işleri ve sunucu tarafı mantığı gerektiren API uç noktaları için mükemmeldir.

Bir fonksiyon oluşturun

supabase functions new send-welcome-email

Bu, `supabase/functions/send-welcome-email/index.ts` dosyasını oluşturur:

import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'

serve(async (req) => {
  const { user_id } = await req.json()

  // Servis rolü RLS'yi atlar - dikkatli kullanın
  const supabase = createClient(
    Deno.env.get('SUPABASE_URL')!,
    Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
  )

  const { data: profile } = await supabase
    .from('profiles')
    .select('email, full_name')
    .eq('id', user_id)
    .single()

  // E-posta gönderme mantığınız burada
  console.log(`Hoş geldiniz e-postası ${profile?.email} adresine gönderiliyor`)

  return new Response(
    JSON.stringify({ success: true }),
    { headers: { 'Content-Type': 'application/json' } }
  )
})

Sıcak yeniden yükleme ile yerelde test edin

supabase functions serve

Fonksiyon sunucusu dosya değişikliklerini izler ve otomatik olarak yeniden yükler. Test edin:

curl -X POST http://localhost:54321/functions/v1/send-welcome-email \
  -H "Authorization: Bearer YOUR_ANON_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "00000000-0000-0000-0000-000000000001"}'

Üretime dağıtım yapın

# Bir fonksiyonu dağıtın
supabase functions deploy send-welcome-email

# Tüm fonksiyonları dağıtın
supabase functions deploy

Gelişmiş teknikler ve kanıtlanmış yaklaşımlar

Gizli anahtar yönetimi

API anahtarlarını fonksiyonlarınıza asla sabit kodlamayın. Gizli anahtarları kullanın:

# Üretim gizli anahtarlarını ayarlayın
supabase secrets set RESEND_API_KEY=re_xxx STRIPE_KEY=sk_live_xxx

# Tüm gizli anahtarları listele
supabase secrets list

# Bir gizli anahtarı kaldırın
supabase secrets unset STRIPE_KEY

Fonksiyonlarda bunlara erişin:

const resendKey = Deno.env.get('RESEND_API_KEY')
// Asla: const resendKey = 're_xxx'

Veritabanı dallanması

Büyük bir şema değişikliği üzerinde mi çalışıyorsunuz? Yalıtılmış bir dal oluşturun:

supabase branches create feature-payments
supabase branches switch feature-payments

# Değişiklikleri yapın, test edin, sonra birleştirin
supabase branches merge feature-payments

Bu, denemeler yaparken ana geliştirme veritabanınızı temiz tutar.

Kaçınılması gereken yaygın hatalar

• Veritabanını doğrudan Studio'da düzenlemek. Her zaman migrasyonları kullanın. Doğrudan yapılan düzenlemeler izlenmez ve ekip arkadaşlarınız bunlara sahip olmaz.
• `.env` dosyalarını commit'lemek. Üretim için `supabase secrets set` kullanın. `.env*` dosyasını `.gitignore`'unuza ekleyin.
• Çektikten sonra `supabase db reset` komutunu atlamak. Ekip arkadaşlarının değişikliklerini çektiğinizde, yeni migrasyonlarının yerelde çalışması gerekir. Bunları uygulamak için sıfırlayın.
• Şema değişikliklerinden sonra türleri yeniden oluşturmamak. Bir sütun eklediğiniz anda TypeScript türleriniz güncelliğini yitirir. Tür oluşturmayı migrasyon iş akışınızın bir parçası haline getirin.
• Yerel test yapmadan fonksiyonları dağıtmak. Dağıtımdan önce her zaman `supabase functions serve` komutunu çalıştırın ve gerçek isteklerle test edin.
• Ön uç kodunda servis rolü anahtarını kullanmak. Servis rolü anahtarı RLS'yi atlar. Yalnızca Edge Fonksiyonlarında ve sunucu tarafı kodda yer alır, asla tarayıcınızda değil.

Performans ipuçları

# Bellek tasarrufu için ihtiyacınız olmayan hizmetleri atlayın
supabase start --exclude-studio --exclude-inbucket

# Kaynakları neyin kullandığını kontrol edin
docker stats

Alternatifler ve karşılaştırmalar

Firebase'in yerel emülatörü hızlı prototipleme için iyidir ancak size gerçek bir PostgreSQL örneği sunmaz. PlanetScale'in dallanma modeli şema değişiklikleri için mükemmeldir ancak her zaman buluta karşı çalışırsınız. Supabase CLI, tamamen açık kaynaklı, PostgreSQL-yerel bir yerel geliştirme deneyimi isteyen ekipler için galip gelir.

Gerçek dünya kullanım senaryoları

Çok kiracılı verilere sahip SaaS uygulaması. Bir fintech girişimi, üç ortamda (geliştirme, hazırlık, üretim) 47 migrasyonu yönetir. RLS politikaları, herhangi bir kod üretime ulaşmadan önce farklı kullanıcı rolleriyle yerelde test edilir. Sonuç: altı ayda şema ile ilgili sıfır üretim olayı.

E-ticaret sipariş işleme. Bir e-ticaret ekibi, Stripe webhook işleme için Edge Fonksiyonlarını kullanır. Webhook yüklerini, gerçek Stripe test etkinlikleriyle `supabase functions serve` kullanarak yerelde test ederler. Dağıtım süresi 2 saatten 15 dakikaya düştü.

Mobil uygulama arka ucu. Bir React Native ekibi, her migrasyondan sonra TypeScript türlerini oluşturur ve bunları dahili bir npm paketi olarak paylaşır. Ön uç ve arka uç otomatik olarak senkronize kalır. Artık Slack'te "bu uç nokta hangi alanları döndürüyor?" gibi sorular yok.

Özetle

Artık şunları yapabilirsiniz:

• Eksiksiz bir yerel Supabase ortamını dakikalar içinde kurmak
• Her şema değişikliğini sürüm kontrolü altında tutmak için migrasyonları kullanmak
• Sıcak yeniden yükleme ile Edge Fonksiyonlarını yerelde test etmek
• Şemanızdan otomatik olarak TypeScript türleri oluşturmak
• `supabase db push` ve `supabase functions deploy` ile dağıtım yapmak
• Üretime göndermeden önce API'lerinizi Apidog ile test etmek

Bu iş akışı anında karşılığını verir. Ekibiniz daha hızlı yayın yapar, hataları daha erken yakalar ve bir daha asla şema kaymasıyla uğraşmaz.

Sonraki adımlarınız:

1. Kurun: `brew install supabase/tap/supabase`
2. Projenizde `supabase init` komutunu çalıştırın
3. İlk migrasyonunuzu oluşturun
4. Yerel uç noktalarınızı test etmek için Apidog'u kurun
5. Güvenle üretime dağıtım yapın

Supabase API'lerinizi Apidog ile test edin - ücretsiz

SSS

Supabase CLI'yı kullanmak için Docker'a ihtiyacım var mı?Evet. `supabase start` komutundan önce Docker Desktop'ın çalışıyor olması gerekir. CLI, tam yığını yerelde çalıştırmak için Docker Compose kullanır. Docker çalışmıyorsa, "Docker daemon'a bağlanılamıyor" hatası alırsınız.

Yerel veritabanımı üretimle nasıl senkronize ederim?Uzak şemanızdan bir migrasyon oluşturmak için `supabase db pull` komutunu, ardından yerel migrasyonları üretime uygulamak için `supabase db push` komutunu kullanın. Ortamınızın eşleştiğinden emin olmak için çektikten sonra yerelde `supabase db reset` komutunu çalıştırın.

Supabase CLI'yı bir Supabase Cloud hesabı olmadan kullanabilir miyim?Evet. CLI'yı tamamen yerel olarak, bir bulut hesabı olmadan geliştirme için kullanabilirsiniz. Yalnızca üretime dağıtım yapmaya hazır olduğunuzda `supabase login` ve `supabase link` komutlarına ihtiyacınız olacaktır.

Bir ekipte migrasyon çakışmalarını nasıl ele alırım?Yeni migrasyonlar oluşturmadan önce en son Git değişikliklerini çekin ve `supabase db reset` komutunu çalıştırın. Tanımlayıcı migrasyon adları kullanın ve şemada kırıcı değişiklikler yaparken ekibinizle iletişim kurun.

`supabase db push` ile `supabase migration up` arasındaki fark nedir?`supabase migration up`, bekleyen migrasyonları yerel veritabanınıza uygular. `supabase db push`, bunları uzak (üretim) projenize uygular. Her zaman önce yerelde test edin.

Supabase CLI'yı mevcut bir projeyle kullanabilir miyim?Evet. Mevcut bir projeye bağlamak için `supabase link --project-ref PROJE_KODUNUZ` komutunu çalıştırın, ardından mevcut uzak şemanızdan migrasyonları oluşturmak için `supabase db pull` komutunu kullanın.

RLS politikalarını yerelde nasıl test ederim?Kullanıcı rolleri arasında geçiş yapmak için `http://localhost:54323` adresindeki Supabase Studio'yu kullanın veya farklı JWT jetonlarıyla API aracılığıyla test edin. Apidog bunu kolaylaştırır: farklı kullanıcı jetonlarına sahip birden fazla ortam oluşturun ve aynı istekleri farklı kullanıcılar olarak çalıştırın.

Supabase CLI ücretsiz mi?Evet. CLI ücretsiz ve açık kaynaktır. Yerel geliştirme hiçbir maliyeti yoktur. Supabase Cloud kaynakları için yalnızca üretime dağıtım yaptığınızda ödeme yaparsınız.