Netlify Database ile Serverless Postgres Nasıl Kullanılır?

Netlify Database, Netlify projesine entegre edilen tam yönetilen Postgres veritabanıdır. Provisioning, deploy lifecycle içindeki migration uygulaması ve Deploy Preview database branch’leri platform tarafından yönetilir; schema, query, index, constraint ve uygulama güvenliği geliştirici tarafından tasarlanır. İlk kurulum için Netlify CLI ile netlify database init komutu çalıştırılır, ardından migration dosyaları oluşturulur ve uygulama @netlify/database üzerinden doğru environment branch’ine otomatik bağlanır.

Bu rehberde küçük bir “tasks” tablosu kurup migration, CRUD, local development, Deploy Preview izolasyonu ve production yayın akışını birlikte ele alacağız. Kod örnekleri yayın öncesinde gerçek proje ve güncel package sürümleriyle çalıştırılmalıdır.

Öne Çıkanlar

• Netlify Database yalnız kredi tabanlı planlarda sunulan yönetilen Postgres hizmetidir.
• netlify database init, paketleri ve başlangıç migration’ını hazırlayan önerilen kurulum yoludur.
• Drizzle ORM veya direct SQL ile çalışılabilir.
• Migration dosyaları repository’de netlify/database/migrations altında tutulur.
• Local database gerçek Postgres uyumlu bir ortamdır ve netlify dev veya Vite plugin ile başlatılabilir.
• Production ve Deploy Preview migration’ları deploy lifecycle içinde otomatik uygulanır.
• Deploy Preview kendi database branch’ine bağlanır; production deploy yalnız main database’e erişir.
• Rollback kodu geri alabilir, uygulanmış schema değişikliğini otomatik olarak tersine çevirmeyebilir.

Netlify Database Nedir?

Netlify Database, uygulamaya ayrı Postgres hesabı, connection proxy ve preview database otomasyonu kurmadan ilişkisel veri katmanı eklemeyi amaçlar. Normal Postgres kavramları korunur:

• Table ve schema,
• Primary/foreign key,
• Index,
• Unique ve check constraint,
• Transaction,
• SQL query,
• Postgres-compatible driver ve tooling.

Platform entegrasyonu ise şu katmanlarda devreye girer:

• İlk deploy’da database provisioning,
• Environment’a göre doğru connection string,
• Deploy Preview başına izole database branch,
• Repository’deki migration’ların deploy sırasında uygulanması,
• Dashboard’da branch ve kullanım görünümü,
• Auto-scale compute,
• Inactivity sonrası sleep/scale-to-zero,
• Backup, snapshot ve access control özellikleri.

Bu yaklaşım serverless uygulamada connection yönetimini kolaylaştırabilir. Yine de kötü tasarlanmış query, eksik index, destructive migration veya aşırı veri transferi otomatik olarak düzeltilmez.

Başlamadan Önce Gerekenler

Kurulum için tipik gereksinimler:

• Kredi tabanlı Netlify hesabı,
• Git repository’ye bağlı Netlify projesi,
• Güncel Netlify CLI,
• Node.js ve package manager,
• TypeScript veya JavaScript projesi,
• Production ve preview veri politikasının belirlenmiş olması.

CLI kontrolü:

``bash netlify --version netlify status ``

Proje bağlı değilse:

``bash netlify link ``

Database’i başlatın:

``bash netlify database init ``

Komut güncel sürüme göre:

• @netlify/database paketini yükler,
• Drizzle veya direct SQL seçimi sunar,
• Başlangıç migration’ı oluşturur,
• Database erişiminin yapılandırılmasını başlatır.

Interactive komutun seçenekleri sürümle değişebilir. Ekip içinde CLI sürümünü ve seçilen query yaklaşımını README’de kaydedin.

Direct SQL mi, Drizzle ORM mi?

İki yaklaşım da geçerlidir.

Direct SQL

Avantajları:

• Postgres özelliklerine doğrudan erişim,
• Migration ve query’nin açık olması,
• Küçük projede az abstraction,
• SQL bilgisi olan ekip için kolay debug.

Trade-off’ları:

• Type mapping ve result shape elle yönetilir,
• Dinamik query’de parameterization disiplini gerekir,
• Büyük projede tekrar eden query code oluşabilir.

Drizzle ORM

Avantajları:

• Type-safe schema ve query,
• TypeScript workflow’a yakınlık,
• Migration üretme yardımcıları,
• Refactor sırasında compile-time geri bildirim.

Trade-off’ları:

• ORM API ve version değişimleri,
• Karmaşık SQL’de abstraction sınırları,
• Generated migration’ın yine insan tarafından review edilmesi gereği.

Bu rehber direct SQL örnekleri kullanıyor. Ekip mevcut ORM standardına sahipse getConnectionString() ile Postgres uyumlu client da bağlanabilir.

Schema ve Migration Nasıl Oluşturulur?

Migration, database schema değişikliğini version control altında tutan SQL dosyasıdır. Dosya yolu:

``text netlify/database/migrations/ ``

Yeni migration:

``bash netlify database migrations new --description "create tasks table" ``

Dosya adı sıralanabilir bir numara ve slug içerir:

``text netlify/database/migrations/001_create_tasks_table.sql ``

Örnek migration:

```sql CREATE TABLE tasks ( id BIGSERIAL PRIMARY KEY, title TEXT NOT NULL CHECK (char_length(title) BETWEEN 1 AND 200), status TEXT NOT NULL DEFAULT 'open' CHECK (status IN ('open', 'in_progress', 'done')), priority INTEGER NOT NULL DEFAULT 0 CHECK (priority BETWEEN 0 AND 5), created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW() );

CREATE INDEX tasks_status_created_at_idx ON tasks (status, created_at DESC); ```

Migration tasarımında:

• Database constraint ile business invariant’ı koruyun.
• Sık filtrelenen alan için ölçüme dayalı index ekleyin.
• Time zone için TIMESTAMPTZ tercih edin.
• Yüksek trafik tabloda uzun lock yaratacak değişiklikleri planlayın.
• DROP COLUMN, type değişimi veya NOT NULL ekleme gibi destructive adımları tek release’e sıkıştırmayın.

Netlify migration’ları lexicographic sırayla uygular. Dosya adlarını sonradan yeniden adlandırmak veya uygulanmış migration’ı silmek remote state ile repository’yi uyumsuz hâle getirebilir.

Local Database Nasıl Başlatılır?

Netlify CLI ile:

``bash netlify dev ``

CLI uygulama dev server’ıyla birlikte local Postgres-compatible database başlatır. Process kapanınca local database service durur; data local geliştirme state’inde korunabilir.

Vite projesinde @netlify/vite-plugin ile normal npm run dev akışında aynı database emulator kullanılabilir.

Migration’ı local database’e uygulayın:

``bash netlify database migrations apply ``

Durumu görün:

``bash netlify database status ``

Interactive SQL:

``bash netlify database connect ``

Tek query:

``bash netlify database connect --query "SELECT * FROM tasks LIMIT 10" ``

Local database’i sıfırlamak için:

``bash netlify database reset ``

Bu komut local schema ve table’ları siler; production veya preview branch’lerini etkilemez. Yine de destructive komut çalıştırmadan önce netlify database status ile hedefi doğrulayın.

Local environment production’ın network, compute, sleep, branch ve access özelliklerinin birebir kopyası değildir. Query doğruluğu için güçlüdür; gerçek latency ve scaling production’da ayrıca test edilmelidir.

Uygulama Kodundan Database’e Nasıl Bağlanılır?

@netlify/database paketi environment’a uygun connection’ı seçer:

```ts import { getDatabase } from "@netlify/database";

const db = getDatabase(); ```

Kendi Postgres driver veya ORM’inizi kullanacaksanız:

```ts import { getConnectionString } from "@netlify/database"; import pg from "pg";

const pool = new pg. Pool({ connectionString: getConnectionString(), max: 5 }); ```

getConnectionString() production’da main database, Deploy Preview’da ilgili izole branch için doğru URL’yi döndürür. Connection string’i browser’a, response’a veya log’a yazmayın.

Pool ayarı serverless runtime’da dikkat gerektirir. Her invocation’da sınırsız connection açmak yerine package’ın optimize edilmiş client’ını veya provider’ın önerdiği pool davranışını kullanın. Memory ve concurrency arttıkça toplam connection sayısını hesaplayın.

CRUD Endpoint’i Nasıl Yazılır?

Basit Netlify Function:

```ts import type { Config } from "@netlify/functions"; import { getDatabase } from "@netlify/database";

export default async (request: Request) => { const db = getDatabase();

if (request. method === "GET") { const { rows } = await db. pool. query( SELECT id, title, status, priority, created_at, updated_at FROM tasks ORDER BY created_at DESC LIMIT 50 );

return Response. json({ tasks: rows }); }

if (request. method === "POST") { let body: unknown;

try { body = await request. json(); } catch { return Response. json({ error: "Geçersiz JSON" }, { status: 400 }); }

if ( typeof body ! == "object" || body === null || ! ("title" in body) || typeof body. title ! == "string" ) { return Response. json({ error: "title gerekli" }, { status: 422 }); }

const title = body. title. trim();

if (! title || title. length > 200) { return Response. json({ error: "title uzunluğu geçersiz" }, { status: 422 }); }

const { rows } = await db. pool. query( INSERT INTO tasks (title) VALUES ($1) RETURNING id, title, status, priority, created_at, updated_at, [title] );

return Response. json({ task: rows[0] }, { status: 201 }); }

return Response. json( { error: "Method not allowed" }, { status: 405, headers: { Allow: "GET, POST" } } ); };

export const config: Config = { path: "/api/tasks" }; ```

Parameter placeholder ($1) SQL injection riskini azaltır. Kullanıcı girdisini string interpolation ile query’ye eklemeyin:

``ts // Yanlış INSERT INTO tasks (title) VALUES ('${title}') ``

Authorization örnekte yoktur; production’da task’ın hangi kullanıcıya ait olduğu ve bu kullanıcının read/write yetkisi ayrıca kontrol edilmelidir.

Update ve Delete Nasıl Yapılır?

Update örneği:

``ts const { rows } = await db.pool.query( UPDATE tasks SET status = $1, updated_at = NOW() WHERE id = $2 RETURNING id, title, status, priority, updated_at`, [status, taskId] );

if (rows. length === 0) { return Response. json({ error: "Task bulunamadı" }, { status: 404 }); } ```

Optimistic concurrency gerekiyorsa updated_at veya version kolonu kullanın:

``sql UPDATE tasks SET status = $1, version = version + 1, updated_at = NOW() WHERE id = $2 AND version = $3; ``

Affected row 0 ise başka bir işlem kaydı değiştirmiş olabilir. Kullanıcıya conflict response (409) döndürün.

Delete işlemi için soft delete veya audit gereksinimini düşünün. DELETE FROM tasks WHERE id = $1 geri dönüşsüz olabilir. Regülasyon ve kullanıcı beklentisine göre deleted_at yaklaşımı daha uygun olabilir; ancak retention dolunca gerçek silme süreci yine gerekir.

Transaction Ne Zaman Kullanılır?

Birden fazla değişiklik ya hep ya hiç uygulanmalıysa transaction gerekir:

```ts const client = await db.pool.connect();

try { await client. query("BEGIN");

const taskResult = await client. query( INSERT INTO tasks (title) VALUES ($1) RETURNING id, [title] );

await client. query( INSERT INTO task_events (task_id, event_type) VALUES ($1, 'created'), [taskResult. rows[0]. id] );

await client. query("COMMIT"); } catch (error) { await client. query("ROLLBACK"); throw error; } finally { client. release(); } ```

Transaction’ı uzun dış API çağrısı boyunca açık tutmayın. Önce database transaction’ını kısa tamamlayın; dış side effect için outbox/queue/idempotency pattern düşünün.

Deploy Preview Database Branch Nasıl Çalışır?

Pull request açıldığında Netlify Deploy Preview oluşturur. Netlify Database bu preview için production data’nın branch copy’sini oluşturur ve preview code’unu otomatik olarak bu branch’e bağlar. Preview süresince schema veya data değişikliği main database’i etkilemez.

Akış:

``text Production database ↓ branch copy Deploy Preview database branch ↓ Preview migration ve sentetik test ↓ PR review ↓ merge Production migration + publish ``

Preview branch testinde:

1. Production’da bilinen bir sentinel row seçin. 2. Pull request’te yeni migration ekleyin. 3. Preview deploy logunda branch creation ve migration adımını görün. 4. Preview’da 10 sentetik row ekleyin. 5. Production endpoint’inde bu row’ların görünmediğini doğrulayın. 6. Preview row update/delete işlemlerini test edin. 7. PR kapatıldığında branch lifecycle’ını kontrol edin.

Production verisinin branch’e kopyalanması, preview reviewer’larının gerçek data görmesine yol açabilir. PII erişimi olan preview’ı public bırakmayın. Team access, data masking ve minimum privilege uygulanmalıdır.

Migration Production’da Ne Zaman Uygulanır?

Production deploy sürecinde migration publish öncesi uygulanır. Migration başarısızsa yeni deploy yayınlanmaz. Bu mekanizma code ile schema drift’ini azaltır.

Riskli durum:

1. Migration eski code ile uyumsuz schema değişikliği yapar. 2. Migration başarıyla uygulanır. 3. Yeni code deploy son adımda başka nedenle başarısız olur. 4. Eski production code yeni schema ile çalışmak zorunda kalır.

Bu nedenle migration’lar backward compatible olmalıdır.

Expand–migrate–contract örneği

Bir kolonu yeniden adlandırmak yerine:

Release 1 — Expand

``sql ALTER TABLE tasks ADD COLUMN summary TEXT; ``

Code hem eski hem yeni alanla çalışır; data backfill edilir.

Release 2 — Migrate

Read/write yeni kolona geçer ve eski field artık kullanılmaz.

Release 3 — Contract

``sql ALTER TABLE tasks DROP COLUMN old_summary; ``

Bu yaklaşım daha yavaştır fakat rollback sırasında eski code’un kırılma riskini azaltır.

Uygulanmış migration dosyasını değiştirmek yerine yeni migration ekleyin. Remote branch’lerde kayıtlı migration history repository ile eşleşmelidir.

Rollback Nasıl Planlanır?

Netlify deploy rollback, önceki application/Function sürümünü yeniden yayınlayabilir. Database schema ve data otomatik olarak önceki ana dönmez.

Rollback öncesinde:

• Eski code yeni schema ile çalışıyor mu?
• Yeni kolon nullable/default mı?
• Migration destructive data kaybı yarattı mı?
• Data backfill geri çevrilebilir mi?
• Snapshot/backup hangi noktaya ait?
• Third-party side effect var mı?

Database rollback için bazen forward fix daha güvenlidir. Örneğin yanlış index veya constraint yeni migration ile düzeltilebilir. Data restore kullanıcıların son değişikliklerini kaybettirebilir; incident owner ve kabul kriteri önceden belirlenmelidir.

Auto-Scale ve Sleep on Inactivity

Netlify Database trafik hacmine göre compute’u belirlenen aralıkta otomatik ölçekleyebilir. Minimum ve maksimum değer plan ve proje ayarına göre dashboard’dan yapılandırılabilir.

Inactivity sonrası sleep, database’in kullanılmadığı dönemde compute tüketimini azaltır. Sonraki query database’i uyandırır ve ilk request’te ek latency oluşturabilir.

Test edilmesi gerekenler:

• Sleep timeout,
• İlk wake query süresi,
• p50/p95 normal query,
• Yoğunlukta auto-scale davranışı,
• Connection pool recovery,
• Function timeout ile wake latency uyumu.

Scale-to-zero düşük trafikli uygulamada maliyet avantajı sağlayabilir; sürekli düşük latency gereken iş yükünde minimum compute ayarı daha uygun olabilir.

Güvenlik ve Access Control

Production checklist:

• Browser’a connection string açılmıyor.
• Parameterized query kullanılıyor.
• Function authentication ve row ownership kontrolü var.
• Team/database role minimum yetkili.
• Deploy Preview public değil veya PII maskeli.
• Migration review zorunlu.
• DROP, mass update/delete ayrı approval gerektiriyor.
• Query logları secret/PII içermiyor.
• Backup ve restore düzenli test ediliyor.
• Data retention ve silme akışı tanımlı.
• Database dashboard’daki manuel değişiklikler audit ediliyor.

Dashboard’dan production row edit etmek hızlı olabilir; version control dışında state değiştirir. Acil müdahale prosedürü, iki kişi review ve değişiklik kaydı kullanın.

Fiyatlandırma ve Limitlerde Güncel Uyarı

Netlify Database aktifken compute ve bandwidth kredi tüketir. Database dokümanı hâlâ storage alanının 1 Temmuz 2026’ya kadar ücretsiz olduğunu söylüyor; bu tarih 23 Ağustos 2026 itibarıyla geçmiştir ve sayfa güncel storage oranını açıkça belirtmemektedir. Production bütçesi hazırlarken dashboard ve Netlify Support üzerinden gerçek storage fiyatını teyit edin.

Ayrıca:

• Planın minimum/maksimum compute aralığı,
• Branch/snapshot/retention limitleri,
• Connection ve query sınırları,
• Backup/recovery kapsamı,
• Compliance destekleri

yayın tarihinde resmî billing/limits sayfasından kontrol edilmelidir.

Zorunlu Uygulama Testi

Küçük tasks tablosunda:

• 10 insert,
• 3 query,
• 2 update,
• 1 migration,
• 1 Deploy Preview branch izolasyon testi

yapılmalıdır.

Adım	İşlem	Beklenen kanıt	Sonuç
1	Local migration apply	tasks table	Uygulanmadı
2	10 sentetik insert	Row ID ve count	Uygulanmadı
3	Status filter	Doğru subset	Uygulanmadı
4	Priority sort	Doğru order	Uygulanmadı
5	Aggregate count	Group sonucu	Uygulanmadı
6	2 update	Version/timestamp	Uygulanmadı
7	Preview migration	Yeni kolon yalnız branch’te	Uygulanmadı
8	Production isolation	Preview row görünmüyor	Uygulanmadı
9	Merge/publish	Migration + endpoint	Uygulanmadı
10	Rollback smoke test	Eski code uyumu	Uygulanmadı

Kaydedilecekler:

• Netlify CLI, Node, package ve Postgres sürümü,
• Migration filename/hash,
• Commit SHA ve PR numarası,
• Local/preview/production branch kimliği,
• Query ve result count,
• HTTP status ve Function logu,
• Migration başlangıç/bitiş zamanı,
• PII içermeyen ekran görüntüleri.

> Editör notu — zorunlu özgün kanıt: Bu taslak hazırlanırken Netlify Database oluşturulmadı; 10 insert, 3 query, 2 update veya Preview migration testi yapılmadı. Yayından önce yalnız sentetik tasks verisi kullanılmalı; migration, query sonuçları ve production izolasyonu gerçek deploy loglarıyla doğrulanmalıdır. Ölçülmeyen latency veya migration süresi yazıya eklenmemelidir.

> Görsel notu: Repository migration → local Postgres → Deploy Preview branch → production database akışını gösteren özgün şema; redakte CLI status, branch dashboard ve query sonuç ekranları hazırlanmalıdır.

> İç link editör notu: Netlify Storage, Functions, Deploy Previews ve environment variables yazıları yayımlandığında setup, API ve güvenlik bölümlerine doğal bağlantı eklenmelidir.

Sık Sorulan Sorular

Netlify Database gerçek Postgres mi?

Postgres-compatible tam yönetilen database’tir. SQL, Postgres driver ve tooling kullanılabilir; platform bağlantı, branch ve migration lifecycle’ını entegre eder.

Local geliştirme için Docker gerekir mi?

Netlify CLI veya Vite plugin gerçek Postgres-compatible local database başlatabilir. Docker zorunlu değildir; ekip standardı gerektiriyorsa ayrıca kullanılabilir.

Deploy Preview production verisini değiştirir mi?

Netlify Database preview için izole branch oluşturur ve preview code’u buna bağlar. Yanlış harici connection string veya production API kullanılıyorsa izolasyon bozulabilir; gerçek test gerekir.

Migration başarısız olursa ne olur?

Preview’da deploy başarısız olur; production’da migration başarısızsa yeni deploy yayınlanmaz. Eski code ile kısmen uygulanmış schema riski için backward-compatible migration tasarlayın.

Deploy rollback database’i geri alır mı?

Hayır. Kod deploy’u geri dönebilir; schema ve data değişiklikleri ayrı migration, restore veya forward fix gerektirebilir.

Storage fiyatı nedir?

Resmî sayfa 1 Temmuz 2026’ya kadar ücretsiz dönemden söz ediyor ancak bu tarih geçmiştir. 23 Ağustos 2026 itibarıyla güncel storage oranı sayfada açık değildir; dashboard ve Netlify desteğinden teyit edilmelidir.

Kaynaklar

• Netlify Database overview
• Getting started
• Migrations
• Local development
• API reference
• Database branching
• Billing, limits, and compliance

Sonuç

Netlify Database, Postgres’un relational gücünü Netlify deploy lifecycle’ıyla birleştirir. Sağlam başlangıç için CLI ile kurulum yapın, schema’yı versioned migration’larla yönetin, local database’te CRUD ve constraint’leri test edin ve her pull request’te preview branch izolasyonunu doğrulayın. Production migration’larını backward compatible tasarlayın; çünkü code rollback schema’yı otomatik geri almaz. Connection string’i yalnız server-side tutun ve fiyatlandırmada geçmiş tarihli storage ifadesini güncel oran gibi kabul etmeyin.

İlk serverless Postgres projenizi kurmak için [ücretsiz Netlify hesabı oluşturabilirsiniz](https://join. netlify. com/wmkqymu1heo2). Bu bir iş ortaklığı bağlantısıdır; bağlantı üzerinden kayıt olmanız veya ücretli plana geçmeniz halinde Ortak Alan komisyon kazanabilir.