Supabase CLI, Supabase projelerini tarayıcıdaki panelden bağımsız olarak terminal üzerinden yönetmenizi sağlayan resmi bir komut satırı aracıdır. Veritabanı şemasını migration dosyalarına dönüştürmek, yerel ortamda Supabase servislerini ayağa kaldırmak, Edge Functions deploy etmek ve gizli değişkenleri yönetmek gibi işleri tekrar çalıştırılabilir komutlara indirger. Bu yönüyle özellikle ekip çalışmalarında, test süreçlerinde ve CI/CD hatlarında ciddi bir düzen sağlar. Aşağıdaki yazımızda Supabase CLI'nın ne işe yaradığını, nasıl kurulduğunu, migration ve deploy süreçlerinin nasıl yönetildiğini bulacaksınız.
Supabase CLI Ne İşe Yarar?
Supabase CLI, adından da anlaşılacağı gibi komut satırı arayüzü sunar; yani Dashboard'un yerini tamamen almaz, onu tamamlayan bir araçtır. Projenizi yerel makinenizde Docker üzerinden çalıştırabilir, şema değişikliklerini SQL dosyalarına dönüştürebilir ve bu dosyaları üretim projesine kontrollü biçimde gönderebilirsiniz. Komutlar terminalde çalıştığı için aynı adımları ekip arkadaşlarınızla paylaşmak, dokümana yazmak ve otomasyona bağlamak kolaylaşır. Dashboard üzerinden tıklayarak yapılan işlemlerin tekrarlanabilir olmaması, özellikle kalabalık ekiplerde ciddi tutarsızlıklara yol açabilir. CLI bu noktada devreye girerek herkesin aynı komutları aynı sırayla çalıştırmasını sağlar. Yine de hangi komutun yerel ortamda, hangisinin uzak projede çalıştığını baştan bilmek gerekir. Örneğin db push ve db reset gibi komutlar yanlış ortamda kullanıldığında geri dönüşü zor sonuçlar doğurabilir. Bu nedenle CLI kullanmaya başlamadan önce yerel ve uzak ortam ayrımını netleştirmek faydalı olur.
- Yerel Supabase servislerini başlatabilir ve durdurabilirsiniz.
- SQL migration dosyaları oluşturup bunları yerelde test edebilirsiniz.
- Uzak projeye bağlanarak şema değişikliklerini kontrollü biçimde gönderebilirsiniz.
- Edge Functions oluşturabilir, yerelde çalıştırabilir ve deploy edebilirsiniz.
- Gizli ortam değişkenlerini yani secret'ları güvenli biçimde yönetebilirsiniz.
- Veritabanı şemasından TypeScript tipleri üretebilirsiniz.
- CI/CD hatlarında otomatik test ve dağıtım adımları kurabilirsiniz.
Yerel Geliştirme ve Migration Disiplini Nedir?
Supabase CLI'nın en güçlü taraflarından biri, yerel geliştirme ortamını Docker üzerinde ayağa kaldırabilmesidir. supabase start komutuyla Postgres, Auth, Storage, Edge Functions ve Studio gibi bileşenler kendi makinenizde çalışmaya başlar. Böylece üretim veritabanına dokunmadan şema değişikliklerini deneyebilir, migration dosyalarını test edebilir ve ekip için ortak bir çalışma zemini oluşturabilirsiniz. Migration yaklaşımı, veritabanı değişikliklerinin SQL dosyaları halinde versiyonlanması anlamına gelir. Bu dosyalar Git ile saklanır ve farklı ortamlara aynı sırayla uygulanır. Yerel ortamda supabase db reset komutu veritabanını sıfırlar ve migration'ları baştan uygular; bu, geliştirme sırasında beklenen bir davranıştır. Ancak aynı komutu uzak veya üretim veritabanında rastgele çalıştırmak ciddi veri kaybına yol açabilir. Bu yüzden komutları çalıştırmadan önce bağlı olduğunuz ortamı her zaman kontrol etmekte yarar var.
Hangi Durumlarda CLI Tercih Edilmelidir?
Tek kişilik ve küçük ölçekli bir projede Dashboard başlangıç için yeterli görünebilir. Fakat şema değişiklikleri çoğaldığında, birden fazla ortam oluştuğunda veya ekip üyeleri aynı veritabanı üzerinde çalıştığında CLI belirgin biçimde öne çıkar. GitHub Actions, GitLab CI ya da benzeri sistemlerde otomatik test ve deploy yapmak istiyorsanız Supabase CLI pratikte zorunlu hale gelir. Migration dosyalarını kod gibi inceleyebilmek, geri alma ve yeniden uygulama süreçlerini yönetmek açısından da önemlidir. İlk bakışta öğrenme eğrisi dik görünse de temel komutlar oturduğunda günlük geliştirme akışı belirgin biçimde hızlanır.
Supabase CLI Nasıl Kurulur?
Supabase CLI kurulumuna geçmeden önce yerel geliştirme için Docker'ın çalışıyor olması gerekir; çünkü CLI, yerel Supabase servislerini Docker container'ları üzerinde başlatır. Node.js ve npm kullanacaksanız güncel bir sürüm kurmanız önerilir. Uzak projeye bağlanmak için Supabase hesabınıza ait erişim token'ına ve proje referans kimliğine ihtiyacınız olur. Windows, macOS ve Linux için farklı kurulum yöntemleri bulunur; ekipte ortak bir yöntem seçmek komutların dokümantasyonla uyumlu kalmasını sağlar. Docker Desktop veya Docker Engine kapalıyken supabase start komutu başarısız olur. Bu nedenle kurulum sonrası ilk kontrolünüz Docker'ın açık olduğundan emin olmak olmalıdır.
- Docker Desktop veya Docker Engine kurulu ve çalışır durumda olmalıdır.
- Node.js ve npm ya da Homebrew, Scoop gibi bir paket yöneticisi hazırlanmalıdır.
- Supabase hesabı açılmalı ve erişim token'ı alınmalıdır.
- Uzak proje için project-ref değeri not edilmelidir.
- Terminal kullanımına temel düzeyde aşina olunmalıdır.
Supabase CLI Kurulum Ayarları Nasıl Yapılır?
Proje bazlı kurulum için Supabase CLI'yı npm ile geliştirme bağımlılığı olarak ekleyebilirsiniz. Bu yöntem, CLI sürümünün proje içinde sabitlenmesine yardımcı olur ve komutları npx supabase üzerinden çalıştırmanızı sağlar. macOS'ta Homebrew, Windows'ta Scoop veya doğrudan binary indirme gibi alternatifler de mevcuttur. Kurulumun ardından supabase --version komutuyla aracın doğru kurulduğunu kontrol edin. Global kurulum ile proje içi kurulum arasındaki farkı bilmek önemlidir; ekipte herkesin aynı yöntemi kullanması sürüm farklılıklarını azaltır.
- Proje içinde yerel bağımlılık olarak kurulum: npm install supabase --save-dev
- Sürüm kontrolü: npx supabase --version
- macOS Homebrew alternatifi: brew install supabase/tap/supabase
- Windows Scoop alternatifi: scoop bucket add supabase https://github.com/supabase/scoop-bucket.git scoop install supabase
Başlatma ve Projeye Bağlanma Nasıl Yapılır?
Kurulum tamamlandıktan sonra supabase login komutuyla hesabınıza giriş yapın; bu işlem erişim token'ını yerel makinenizde saklar. Proje klasörünüzde supabase init çalıştırarak yerel yapılandırmayı oluşturun; bu adım supabase/config.toml dosyasını ve temel klasör yapısını hazırlar. Yerel servisleri başlatmak için supabase start, durum bilgisini görmek için supabase status komutunu kullanın. Uzak projeye bağlanmak için supabase link --project-ref <proje-ref> komutunu çalıştırın; böylece yerel proje belirtilen Supabase projesiyle ilişkilendirilir. Erişim token'ını, veritabanı şifresini veya .env dosyalarını Git deposuna commit etmeyin. Bu bilgiler CI/CD ortamlarında secret olarak saklanmalı ve yalnızca güvenli kanallar üzerinden paylaşılmalıdır.
- supabase login
- supabase init
- supabase start
- supabase status
- supabase link --project-ref <proje-ref>
Supabase CLI İle Yerel Geliştirme ve Migration Nasıl Yapılır?
Günlük geliştirmede önce Docker'ın çalıştığından emin olun, ardından supabase start ile yerel Supabase stack'ini başlatın. supabase status komutu yerel API adresi, veritabanı portu ve Studio bağlantısı gibi bilgileri gösterir; bu bilgileri uygulamanızın yerel ortam değişkenlerine yazabilirsiniz. Yerel Studio üzerinden veritabanını inceleyebilir, Auth kullanıcılarını test edebilir ve Storage bucket'larını deneyebilirsiniz. Yeni migration dosyalarını uyguladıktan sonra yerel veritabanını baştan kurmak için supabase db reset kullanılır; bu komut yerel veriyi siler ve migration'ları yeniden uygular. Bu komutun yalnızca yerel geliştirme ortamına ait olduğunu unutmamak gerekir. Uzak projede aynı etkiyi beklemek ve komutu orada çalıştırmak doğru değildir.
Migration Dosyalarının Oluşturulması
Şema değişikliği yapacağınızda önce supabase migration new <migration_adi> komutuyla boş bir SQL dosyası oluşturun. Oluşan dosyaya tablo, index, policy veya fonksiyon değişikliklerinizi SQL olarak yazın. Yerelde test etmek için supabase db reset veya supabase migration up gibi komutlarla migration'ları uygulayın. Yerel veritabanında yaptığınız değişiklikleri migration dosyasına dönüştürmek için supabase db diff -f <migration_adi> kullanabilirsiniz. Uzak projeye göndermeden önce migration dosyalarını kod incelemesinden geçirmek iyi bir alışkanlıktır. supabase db push komutu bekleyen migration'ları uzak veritabanına uygular. Bu komutu çalıştırmadan önce yedekleme ve önizleme yapmak, destekleniyorsa --dry-run ile hangi migration'ların uygulanacağını görmek riski azaltır.
- supabase migration new create_profiles komutuyla yeni bir migration dosyası oluşturun.
- SQL dosyasını tablo ve policy değişiklikleriyle düzenleyin.
- supabase db reset ile değişiklikleri yerelde test edin.
- Dosyaları Git'e commit edin ve kod incelemesine gönderin.
- İnceleme sonrası supabase db push ile uzak ortama uygulayın.
- Uygulama sonrası şema ve logları kontrol edin.
Yerel geliştirmede başlangıç verisi gerekiyorsa supabase/seed.sql dosyasını kullanabilirsiniz; db reset sonrası seed verisi otomatik uygulanır. Veritabanı şemasından TypeScript tipleri üretmek için supabase gen types typescript --local > types/supabase.ts komutundan yararlanabilirsiniz. Bu tipler, uygulama kodunda tablo ve kolon adlarının yanlış yazılmasını azaltır. Yerel testlerde Auth, Storage ve Edge Functions davranışlarını gerçek Supabase servislerine yakın biçimde deneyebilirsiniz. Üretim şeması değiştiğinde tipleri yeniden üretmeyi unutmamak gerekir; eski tiplerle çalışan uygulama kodunda sessiz hatalar oluşabilir.
Supabase CLI İle Edge Functions, Secret'lar ve Üretim Dağıtımı Nasıl Yönetilir?
Supabase Edge Functions, Deno tabanlı sunucusuz fonksiyonlardır ve CLI ile kolayca oluşturulabilir. supabase functions new <fonksiyon_adi> komutuyla yeni bir fonksiyon iskeleti oluşturun. Yerelde çalıştırmak için supabase functions serve <fonksiyon_adi> --env-file ./supabase/.env.local benzeri bir komut kullanabilirsiniz; ortam dosyası gizli değişkenleri yerel test için sağlar. Fonksiyon kodunu değiştirdikçe yerel sunucu üzerinden test edin ve hata loglarını takip edin. Secret değerlerini fonksiyon kodunun içine yazmayın; hem yerelde hem üretimde ortam değişkenleri üzerinden yönetin.
Secret'ların Güvenli Yönetimi
Uzak projedeki Edge Functions için secret eklemek üzere supabase secrets set MY_SECRET=deger komutunu kullanın. Mevcut secret'ları listelemek için supabase secrets list, kaldırmak için supabase secrets unset MY_SECRET komutlarından yararlanabilirsiniz. Yerel geliştirmede ayrı bir .env.local dosyası kullanmak, üretim secret'ları ile yerel test değerlerini ayrı tutmanızı sağlar. Secret'lar deploy sırasında fonksiyonlara ortam değişkeni olarak aktarılır; bu nedenle isimlendirmeyi tutarlı yapmak önemlidir. Secret dosyalarını .gitignore içine ekleyin ve CI/CD ortamlarında yalnızca platformun secret yönetim özelliğini kullanın.
Üretim Dağıtım Yönetimi
Edge Function'ı üretime göndermek için supabase functions deploy <fonksiyon_adi> komutunu çalıştırın. Veritabanı migration'larını uygulamak için supabase db push, TypeScript tiplerini uzak projeden üretmek için supabase gen types typescript --project-id <proje-ref> --schema public > types/supabase.ts gibi komutlar kullanabilirsiniz. Deploy sonrası fonksiyon loglarını, hata oranlarını ve veritabanı şemasını kontrol edin. Üretim dağıtımı öncesinde staging ortamı kullanmak, geri dönüş planı hazırlamak ve migration'ları küçük parçalara bölmek riski azaltır. Üretimde doğrudan Dashboard üzerinden şema değiştirmek migration geçmişiyle çelişki yaratabilir; şema değişikliklerini mümkün olduğunca migration dosyaları üzerinden yönetin.
Supabase CLI CI/CD ve Ekip Çalışmasında Nasıl Kullanılır?
CI/CD hatlarında Supabase CLI kullanmak için SUPABASE_ACCESS_TOKEN, SUPABASE_DB_PASSWORD ve proje referansı gibi değerleri ortam değişkeni olarak tanımlayın. Bu değerleri GitHub Actions Secrets, GitLab CI Variables veya benzeri güvenli alanlarda saklayın. Pipeline içinde önce CLI'yı kurun, ardından supabase link --project-ref $PROJECT_REF ile projeye bağlanın. Migration'ları uygulamak için supabase db push, fonksiyonları deploy etmek için supabase functions deploy komutlarını kullanın. Üretim deploy'unu otomatik tetikliyorsanız onay adımı, korumalı branch ve geri alma planı ekleyin; yanlış bir migration'ın üretime gitmesi ciddi kesintiye yol açabilir.
Örnek CI/CD Akışı
- Kod deposunu checkout edin.
- Node.js ve Supabase CLI kurulumunu tamamlayın.
- Bağımlılıkları npm ci ile yükleyin.
- supabase link --project-ref $PROJECT_REF ile projeye bağlanın.
- supabase db push ile migration'ları uygulayın.
- supabase functions deploy <fonksiyon_adi> ile fonksiyonları dağıtın.
- supabase gen types typescript ile tipleri üretin veya doğrulayın.
- Deploy sonrası sağlık kontrolü ve log incelemesi yapın.
Ekipte herkesin aynı migration disiplinini izlemesi gerekir; şema değişiklikleri PR üzerinden incelenmeli ve yerelde db reset ile test edilmelidir. Dashboard'dan yapılan manuel değişiklikler migration geçmişini bozabilir; bu nedenle üretim şeması için tek doğruluk kaynağı migration dosyaları olmalıdır. Yerel .env dosyaları kişisel kalmalı, örnek değişkenler .env.example içinde paylaşılmalıdır. Sık yapılan hatalar arasında yanlış projeye db push çalıştırmak, Docker'ı başlatmadan supabase start denemek ve secret'ları koda gömmek yer alır. supabase link sonrası hangi projeye bağlı olduğunuzu kontrol edin; terminalde yanlış proje referansıyla çalışmak geri dönüşü zor sonuçlar doğurabilir.
Yorumlar
Yorum Gönder
1.Görüşleriniz bizim için önemlidir.
2. Konu dışı sorularınız için İletişim sayfasından ulaşabilirsiniz.