DEV Community

Cover image for Supabase CLI Kullanımı: Kapsamlı Geliştirici Rehberi (2026)
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

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

#backend #cli #tooling #tutorial

TL;DR

Supabase CLI, Docker ile makinenizde eksiksiz bir Supabase yığını (PostgreSQL, Kimlik Doğrulama, Depolama ve Edge Fonksiyonları) çalıştırır. Kurulum için brew install supabase/tap/supabase, ortam başlatmak için supabase init ve supabase start, üretime göndermek için ise supabase db push ve supabase functions deploy komutlarını kullanın. Buluta ihtiyaç duymadan Supabase arka uçlarını hızlıca oluşturup test edebilirsiniz.

Apidog'u hemen deneyin

Giriş

Arka uç hatalarının %73'ü, geliştiricilerin yerel testi atlaması nedeniyle üretimde ortaya çıkar. Supabase CLI ile, 5 dakikadan kısa sürede makinenizde üretime eşdeğer bir ortam kurabilirsiniz.

Sorun şu: Çoğu geliştirici ya doğrudan üretimde test yapıyor (riskli), ya da bulut ortamıyla birebir aynı olmayan yerel ortamları el ile kurmaya saatler harcıyor (verimsiz). Supabase CLI, bu iki problemi çözer: Docker tabanlı bir yerel yığın ile üretimi birebir yansıtır; yerelde çalışan, üretimde de çalışır.

💡 Supabase üzerinde API geliştiriyorsanız, uç noktalarınızı tasarlamak, test etmek ve belgelemek için bir araca ihtiyacınız olacak. Apidog, Supabase'in REST ve GraphQL API'lerine doğrudan bağlanarak arka ucu yerelde geliştirirken test etmenizi sağlar.

Supabase API'lerinizi Apidog ile test edin - ücretsiz

Bu rehberi bitirdiğinizde şunları yapabileceksiniz:

  • Dakikalar içinde eksiksiz yerel Supabase ortamı kurmak
  • Sürüm kontrollü migrasyonlarla veritabanı şema değişikliklerini yönetmek
  • Edge Fonksiyonlarını dağıtımdan önce yerelde oluşturup test etmek
  • Tek komutla üretime dağıtım yapmak

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

CLI olmadan bir Supabase uygulaması kurmayı denediyseniz, aşağıdaki klasik acıları bilirsiniz:

  • "Üretimde test etme" tuzağı: Şemayı doğrudan Supabase panelinde değiştirirsiniz; çalışır. Frontend deploy edilir. Ekip arkadaşınız depoyu çeker, yeni sütun olmadığı için uygulama bozulur.
  • Ortam uyuşmazlığı: Yerel PostgreSQL örneği kurar, şemayı elle oluşturur, RLS politikalarını yerelde iki saat debug edersiniz. Aslında bir RLS politikasını atlamışsınızdır.
  • "Benim makinemde çalışıyor" problemi: Edge Fonksiyonunuz panelde çalışır; ama üretimde, sabit kodlu değerlerle test ettiğiniz için hata verir.

Bu problemler yaygındır. Şema kayması, Supabase ekiplerinde 1 numaralı sorundur. CLI ile:

  • Migrasyonlar, şema değişikliklerini sürüm kontrollü ve tekrar üretilebilir kılar
  • Yerel Docker yığını, üretimle aynı PostgreSQL ve RLS motorunu çalıştırır
  • Fonksiyonlar, yerelde gerçek ortam değişkenleriyle test edilir

Supabase CLI nasıl çalışır?

Yerel yığın

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

Hizmet Port Amaç
PostgreSQL 54322 Veritabanınız
PostgREST 54321 Otomatik oluşturulan REST API
GoTrue 54321/auth Kimlik doğrulama hizmeti
Realtime 54321/realtime WebSocket abonelikleri
Storage 54321/storage Dosya depolama
Studio 54323 Görsel kontrol paneli
Inbucket 54324 E-posta testi (tüm e-postaları yerelde yakalar)
Edge Runtime 54321/functions Deno tabanlı fonksiyon çalıştırıcı

Bu, Supabase Cloud ile birebir aynıdır; tamamen kendi makinenizde.

Kurulum

macOS:

brew install supabase/tap/supabase
Enter fullscreen mode Exit fullscreen mode

Windows (Scoop):

scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
scoop install supabase
Enter fullscreen mode Exit fullscreen mode

Linux / npm:

npm install -g supabase
Enter fullscreen mode Exit fullscreen mode

Kurulumu doğrulayın:

supabase --version
# supabase 1.x.x
Enter fullscreen mode Exit fullscreen mode

supabase start öncesi Docker Desktop çalışıyor olmalı. Aksi halde Docker daemon hatası alırsınız.

Proje kurulumu 

mkdir my-project && cd my-project
supabase init
Enter fullscreen mode Exit fullscreen mode

Şu dosya/dizinler oluşur:

supabase/
├── config.toml       # Portlar, kimlik doğrulama, depolama ayarları
├── seed.sql          # Geliştirme verileri
└── migrations/       # Şema sürüm geçmişi
Enter fullscreen mode Exit fullscreen mode

Yerel yığını başlatma 

supabase start
Enter fullscreen mode Exit fullscreen mode

İlk çalıştırma ~1GB Docker imajı indirir. Sonraki başlatmalar ~10 saniye sürer.

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

anon key'i .env.local dosyanıza ekleyin; frontend için gerekli.

Migrasyonlar ile veritabanı yönetimi

Migrasyonlar, CLI iş akışının temelidir. Her şema değişikliği, Git ile izlenen bir SQL dosyasına dönüşür.

İlk migrasyonunuzu oluşturma 

supabase migration new create_posts_table
# supabase/migrations/20260324120000_create_posts_table.sql oluşur
Enter fullscreen mode Exit fullscreen mode

Dosyayı düzenleyin:

-- RLS'li gönderiler tablosu
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()
);

ALTER TABLE posts ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Anyone can read published posts"
  ON posts FOR SELECT
  USING (published = true);

CREATE POLICY "Users manage own posts"
  ON posts FOR ALL
  USING (auth.uid() = user_id);

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();
Enter fullscreen mode Exit fullscreen mode

Uygulayın:

supabase migration up
Enter fullscreen mode Exit fullscreen mode

TypeScript türlerini oluşturma

Her şema değişikliğinden sonra türlerinizi güncelleyin:

supabase gen types typescript --local > src/types/database.ts
Enter fullscreen mode Exit fullscreen mode

Örnek kullanım:

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

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

const createPost = async (post: NewPost) => {
  const { data, error } = await supabase
    .from('posts')
    .insert(post)
    .select()
    .single()
  return data
}
Enter fullscreen mode Exit fullscreen mode

Geliştirme verilerini doldurma

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

-- Test kullanıcıları
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);
Enter fullscreen mode Exit fullscreen mode

Her zaman sıfırlayın ve doldurun:

supabase db reset
Enter fullscreen mode Exit fullscreen mode

Bu komut: her şeyi siler, migrasyonları tekrar çalıştırır ve seed verisini yükler.

Supabase API'lerini Apidog ile test etme

Yerel Supabase'iniz çalışıyorsa, http://localhost:54321 adresinde tam bir REST API'niz vardır. Supabase, PostgREST ile her tabloya otomatik endpoint sağlar. Ancak curl ile manuel test zahmetli ve hataya açıktır, özellikle RLS'yi farklı kullanıcılarla test etmek gerektiğinde.

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

  • İstekleri koleksiyon olarak kaydetmek
  • Farklı ortamlarla aynı endpoint'i farklı kullanıcılar olarak test etmek
  • Yanıt doğrulamaları eklemek ve bir test paketi olarak çalıştırmak
  • API dokümantasyonunu ekibinizle paylaşmak

Apidog'u yerel Supabase ile kurma:

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

Gönderiler endpoint'ini test edin:

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

Bunu kaydedip, yanıtın en az 1 gönderi içerdiğine dair doğrulama ekleyin. RLS politikanızı değiştirdikçe otomatik test edin.

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ıya yakın edge konumlarında çalışır. Webhook, arka plan işi ve sunucu tarafı mantık için idealdir.

Bir fonksiyon oluşturun 

supabase functions new send-welcome-email
Enter fullscreen mode Exit fullscreen mode

supabase/functions/send-welcome-email/index.ts dosyası oluşur:

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 olun
  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 burada
  console.log(`Hoş geldiniz e-postası ${profile?.email} adresine gönderiliyor`)

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

Sıcak yeniden yükleme ile yerelde test 

supabase functions serve
Enter fullscreen mode Exit fullscreen mode

Sunucu dosya değişikliklerini izler ve otomatik 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"}'
Enter fullscreen mode Exit fullscreen mode

Üretime dağıtım 

# Tek fonksiyon dağıt
supabase functions deploy send-welcome-email

# Tüm fonksiyonları dağıt
supabase functions deploy
Enter fullscreen mode Exit fullscreen mode

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

Gizli anahtar yönetimi

API anahtarlarını asla kodda sabit tutmayın. Supabase secrets kullanın:

supabase secrets set RESEND_API_KEY=re_xxx STRIPE_KEY=sk_live_xxx
supabase secrets list
supabase secrets unset STRIPE_KEY
Enter fullscreen mode Exit fullscreen mode

Fonksiyonlarda:

const resendKey = Deno.env.get('RESEND_API_KEY')
// Yanlış: const resendKey = 're_xxx'
Enter fullscreen mode Exit fullscreen mode

Veritabanı dallanması

Büyük şema değişiklikleri için yalıtılmış dal oluşturun:

supabase branches create feature-payments
supabase branches switch feature-payments
# Değişiklikleri yap, test et, sonra birleştir:
supabase branches merge feature-payments
Enter fullscreen mode Exit fullscreen mode

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

  • Veritabanını doğrudan Studio'da düzenlemek: Daima migrasyon kullanın.
  • .env dosyalarını commit etmek: Üretim için supabase secrets set kullanın. .env* dosyalarını .gitignore'a ekleyin.
  • Çektikten sonra supabase db reset çalıştırmamak: Ekip değişikliklerini çektiğinizde, yeni migrasyonları uygulamak için sıfırlama yapın.
  • Şema değişikliklerinden sonra türleri yeniden oluşturmamak: TypeScript türlerini migrasyon sonrası güncelleyin.
  • Yerel test olmadan fonksiyonları dağıtmak: Daima önce supabase functions serve ile test edin.
  • Frontend'de servis rolü anahtarı kullanmak: Servis rolü anahtarı sadece sunucu tarafında kullanılmalı, frontend'de asla.

Performans ipuçları 

# Bellekten tasarruf için gereksiz servisleri atla
supabase start --exclude-studio --exclude-inbucket

# Kaynak kullanımını izle
docker stats
Enter fullscreen mode Exit fullscreen mode

Alternatifler ve karşılaştırmalar

Özellik Supabase CLI Firebase CLI PlanetScale CLI
Yerel veritabanı Tam PostgreSQL Yalnızca Emülatör Yalnızca Bulut
Migrasyonlar Git'te SQL dosyaları Yerel destek yok Dallanma
Edge Fonksiyonları Deno çalışma zamanı Cloud Fonksiyonları Dahil değil
Yerelde Kimlik Doğrulama Tam GoTrue Emülatör Dahil değil
Açık kaynak Tamamen açık Tescilli Tescilli
Tür oluşturma Dahili Manuel Manuel

Firebase emülatörü hızlı prototipleme için iyidir fakat gerçek PostgreSQL sunmaz. PlanetScale dallanma modeliyle güçlüdür fakat her zaman buluta bağlısınız. Supabase CLI, açık kaynak ve PostgreSQL-odaklı yerel geliştirme isteyenler için öne çıkar.

Gerçek dünya kullanım senaryoları

Çok kiracılı SaaS: Bir fintech girişimi, üç ortamda (dev, staging, prod) 47 migrasyonu yönetiyor. RLS politikalarını farklı kullanıcılarla yerelde test ederek 6 ayda sıfır şema problemi yaşıyor.

E-ticaret sipariş işleme: Stripe webhook'larını Edge Fonksiyonları ile yönetiyorlar. Webhook yüklerini supabase functions serve ile yerelde test ediyorlar. Dağıtım süresi 2 saatten 15 dakikaya düştü.

Mobil uygulama arka ucu: React Native ekibi, her migrasyondan sonra TypeScript türlerini oluşturup npm paketi olarak dağıtıyor. Frontend ve backend otomatik senkronize, iletişim maliyeti sıfır.

Özetle

Artık şunları yapabilirsiniz:

  • Eksiksiz yerel Supabase ortamı kurmak
  • Her şema değişikliğini migrasyonla sürüm kontrolünde tutmak
  • Edge Fonksiyonlarını sıcak yeniden yükleme ile yerelde test etmek
  • Şemadan otomatik TypeScript türleri üretmek
  • supabase db push ve supabase functions deploy ile kolayca dağıtım yapmak
  • Üretime göndermeden önce API'lerinizi Apidog ile test etmek

Bu iş akışı ekibinize hız, güven ve sürdürülebilirlik kazandırır. Hataları erken yakalar, şema kaymasıyla uğraşmazsınız.

Sonraki adımlarınız:

  1. Kurulum: brew install supabase/tap/supabase
  2. Projede supabase init ç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 öncesi Docker Desktop çalışıyor olmalı. CLI, tüm yığını yerelde başlatmak için Docker Compose kullanır.

Yerel veritabanımı üretimle nasıl senkronize ederim?

supabase db pull ile uzak şemadan migrasyon oluşturun, supabase db push ile migrasyonları üretime uygulayın. Eşleşme için çektikten sonra supabase db reset çalıştırın.

Supabase CLI'yı Supabase Cloud hesabı olmadan kullanabilir miyim?

Evet. Tamamen yerelde kullanabilirsiniz. Üretime dağıtım için sadece supabase login ve supabase link gereklidir.

Bir ekipte migrasyon çakışmaları nasıl yönetilir?

Yeni migrasyonlar öncesi git pull yapıp supabase db reset çalıştırın. Anlamlı migrasyon isimleri kullanın, kırıcı şema değişikliklerinde ekiple iletişim kurun.

supabase db push ile supabase migration up farkı nedir?

supabase migration up yerel veritabanına uygular; supabase db push üretime gönderir. Daima önce yerelde test edin.

Supabase CLI'yı mevcut bir projede kullanabilir miyim?

Evet. supabase link --project-ref PROJE_KODUNUZ ile bağlayın, supabase db pull ile mevcut şemadan migrasyon oluşturun.

RLS politikalarını yerelde nasıl test ederim?

http://localhost:54323 üzerindeki Studio'dan veya farklı JWT ile API'dan test edin. Apidog ile farklı kullanıcı jetonları içeren ortamlar oluşturup kolayca test edebilirsiniz.

Supabase CLI ücretsiz mi?

Evet. CLI açık kaynak ve ücretsizdir. Yerel geliştirme ücretsizdir; yalnızca Supabase Cloud kaynakları için ödeme yaparsınız.

Top comments (0)