TürkDB Kullanım Kılavuzu TürkDB kullanım kılavuzu — buradaki akışlar hedeflenen ürün deneyimini, kapsamı ve doğrulama noktalarını anlatır.

🔗 Uygulamanızı Bağlayın

TürkDB’nin hedef bağlantı deneyimi, uygulamanın kullanabileceği standart bir DSN/bağlantı bilgisini açıkça göstermektir. Pilot sırasında bu bilginin TLS, izin listesi ve uygulama ayarlarıyla birlikte doğrulanması gerekir.

Bağlantı bilgisini nereden alırsınız?

turkdb cluster get my-cluster --output connection-string

GET https://api.turkdb.io/v1/clusters/{id}/connection
Authorization: Bearer <api-key>

Özel ağ ve WireGuard ile erişim

Cluster → Bağlantı sekmesinde Bağlantı Bilgilerini Göster düğmesini kullanın. Gösterilen erişim türüne göre ilerleyin:

• Özel ağ: Uygulamanızın veritabanının özel ağına erişebildiğinden emin olun; DSN tek başına ağ erişimi sağlamaz.
• WireGuard: WireGuard Yapılandırması kartındaki dosyayı wg0.conf olarak indirin, WireGuard istemcinize aktarın ve tüneli etkinleştirin. Linux'ta WireGuard kuruluysa sudo wg-quick up wg0 kullanılabilir. Ardından gösterilen DSN ile bağlanın.
• Yapılandırma hazır değil: Ekrandaki durum mesajını kontrol edip bağlantı bilgilerini yenileyin. Sorun sürerse destek ekibine cluster kimliğini ve durum mesajını iletin.

IP izin listesine kural eklemek, özel ağdaki veritabanına public adres açmaz. Erişim türüne uygun ağ bağlantısı ve TLS ayarları birlikte sağlanmalıdır. DSN ve WireGuard dosyası hassas bilgiler içerir; bunları herkese açık depolarda veya destek mesajlarında paylaşmayın.

PostgreSQL: çalışan sürüm ve bağlantı havuzu

Cluster özetindeki Çalışan PostgreSQL sürümü ve Son SQL gözlemi alanlarını kontrol edin. Sipariş edilen sürüm ile çalışan sürümün eşleşmesi doğrulanmamışsa veya gözlem güncel değilse ekran uyarı gösterir.

Pooler istendiğinde Direct Bağlantı — Migration ve Yönetim adresi doğrudan veritabanına gider. Pooler Bağlantısı — Uygulama Trafiği yalnız çalışma durumu doğrulandığında gösterilir. Pooler adresi görünmüyorsa kurulumu tamamlanmış varsaymayın; bağlantı bilgilerini yenileyip durum uyarısını inceleyin.

Bağlantı formatları

Şifre değişirse ne olur?

Cluster detayında Erişim Yönetimi sekmesinden şifreyi sıfırlayabilirsiniz. Yeni şifreyi uygulamanızın ortam değişkenlerine yazmanız yeterlidir.

📊 Cluster Durumları

🌐 Web UI

app.turkdb.io — Cluster oluşturma, izleme, yedekleme ve hesap yönetimi için tek ekran.

⌨️ CLI — turkdb

Web UI'deki her işlemi terminal üzerinden yapan tek binary. Scripting ve CI/CD için idealdir.

Kurulum

# macOS / Linux
curl -sSfL https://get.turkdb.io | sh

# Shell tamamlaması (opsiyonel)
turkdb completion bash > /etc/bash_completion.d/turkdb   # bash
turkdb completion zsh  > "${fpath[1]}/_turkdb"            # zsh

Giriş

# Tarayıcı açar, hesabınızla giriş yapın
turkdb login

# CI/CD için API key ile
turkdb login --api-key turkdb_xxxxxxxxxxxx

# Cluster oluştur — tier ile boyut seçin (turkdb cluster tiers ile listeleyin)
turkdb cluster create \
  --name my-pg --type postgres --version 16 \
  --tier p9200-h-4 --region ist1

# Yüksek erişilebilirlik ile
turkdb cluster create \
  --name my-pg-ha --type postgres \
  --tier p9200-h-8 --ha

# Listele / detay / DSN
turkdb cluster list
turkdb cluster get    my-pg
turkdb cluster get    my-pg --output connection-string

# Kullanılabilir makine boyutları
turkdb cluster tiers

# HA cluster düğüm durumu
turkdb cluster ha-status my-pg

# Etiket ekle (ortam, takım vb.)
turkdb cluster tag my-pg --set env=prod --set team=backend

# Sil (KVKK gereği 30 gün bekleme başlar)
turkdb cluster delete my-pg --confirm

# Manuel yedek al
turkdb backup create my-pg

# Yedek listesi
turkdb backup list my-pg

# Otomatik yedekleme zamanlaması (cron)
turkdb backup schedule set my-pg \
  --cron "0 3 * * *" --retention-days 14

turkdb backup schedule get my-pg

# PITR'ı etkinleştir (WAL/binlog arşivleme başlar)
turkdb cluster pitr enable  my-pg --retention 168  # 168 saat = 7 gün

# Kurtarma penceresini göster
turkdb cluster pitr window  my-pg

# Belirli bir noktaya geri yükle → yeni cluster açılır
turkdb cluster pitr restore my-pg \
  --to   "2026-05-20T14:30:00Z" \
  --name my-pg-recovered

# Restore geçmişi
turkdb cluster pitr history my-pg

# PITR'ı kapat
turkdb cluster pitr disable my-pg

# Mevcut cluster'dan yeni cluster aç (altyapı kopyası — veri taşınmaz)
turkdb cluster fork my-pg --name my-pg-staging

# Farklı boyut ve bölge ile
turkdb cluster fork my-pg \
  --name   my-pg-test \
  --tier   p9200-h-2

# Konfigürasyon parametrelerini de kopyala
turkdb cluster fork my-pg \
  --name           my-pg-copy \
  --include-config

# Fork tamamlanana kadar bekle
turkdb cluster fork my-pg --name my-pg-preview --wait

# DB kullanıcılarını listele
turkdb cluster users list my-pg

# Yeni kullanıcı oluştur (şifre interaktif sorulur)
turkdb cluster users create my-pg \
  --username appuser \
  --role     readwrite

# Salt okunur kullanıcı
turkdb cluster users create my-pg \
  --username reporter \
  --role     readonly

# Kullanıcı sil
turkdb cluster users delete my-pg <user-id>

# İzinli IP'leri listele
turkdb cluster allowlist list my-pg

# IP veya CIDR bloğu ekle
turkdb cluster allowlist add my-pg 203.0.113.0/24 \
  --desc "Ofis ağı"

# Kural kaldır
turkdb cluster allowlist remove my-pg <rule-id>

# Tüm kuralları temizle
turkdb cluster allowlist clear my-pg --force

# Son 100 log satırı
turkdb cluster logs my-pg

# Son N satır
turkdb cluster logs my-pg --tail 500

# Canlı log akışı (Ctrl+C ile çıkış)
turkdb cluster logs my-pg --follow

# Webhook oluştur — cluster olaylarında sizin URL'nize POST gönderilir
turkdb webhook create \
  --url    https://hooks.sirket.com/turkdb \
  --secret gizli-anahtar

# Belirli olaylar için (yoksa tüm olaylar)
turkdb webhook create \
  --url    https://hooks.sirket.com/turkdb \
  --events cluster.ready,cluster.failed

# Listele / test / sil
turkdb webhook list
turkdb webhook test       <webhook-id>
turkdb webhook deliveries <webhook-id>
turkdb webhook delete     <webhook-id>

# KVKK uyum özeti
turkdb compliance summary

# Bekleyen veri silme kuyruğu (KVKK Md. 7)
turkdb compliance deletion-status

# Veri erişim talebi (KVKK Md. 11)
turkdb compliance export request
turkdb compliance export list
turkdb compliance export get <export-id>

# Veri ihlali kaydı — 72 saat Kurul bildirim geri sayımı başlar (Md. 12)
turkdb compliance breach report \
  --title       "Yetkisiz Erişim" \
  --description "Detaylı açıklama..." \
  --severity    high \
  --affected    150
turkdb compliance breach list
turkdb compliance breach close <breach-id>

# Plan ve tüm seçenekler
turkdb billing plan

# Bu dönemin kullanımı ve tahmini fatura
turkdb billing usage

# Fatura geçmişi
turkdb billing invoices
turkdb billing get <invoice-id>

# Ekip üyelerini listele
turkdb member list

# Yeni üye davet et
turkdb member invite [email protected] --role admin

# Rolü değiştir
turkdb member role <member-id> readonly

# Üyeyi kaldır
turkdb member remove <member-id>

🔗 REST API

Tüm işlemler REST API üzerinden de yapılabilir. CI/CD scriptleri, özel yönetim araçları ve üçüncü taraf entegrasyonlar için kullanın.

Base URL: https://api.turkdb.io/v1
Auth: Authorization: Bearer <api-key>

# Cluster oluştur
curl -s -X POST https://api.turkdb.io/v1/clusters \
  -H "Authorization: Bearer turkdb_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-pg","type":"postgresql","tier":"p9200-h-4","region":"ist1","engine_profile":"geo-postgis","enabled_capabilities":["postgis"]}'

# Bağlantı bilgisini al
curl -s https://api.turkdb.io/v1/clusters/{id}/connection \
  -H "Authorization: Bearer turkdb_xxx"

Temel Endpoint'ler

Tam OpenAPI 3.1 spec: api.turkdb.io/openapi.yaml

🏗️ Terraform Provider

Infrastructure as Code ile cluster'larınızı Terraform state'inde yönetin.

# versions.tf
terraform {
  required_providers {
    turkdb = {
      source  = "turkdb/turkdb"
      version = "~> 0.4"
    }
  }
}

provider "turkdb" {
  api_key = var.turkdb_api_key
}

# PostgreSQL cluster
resource "turkdb_cluster" "main" {
  name            = "my-app-db"
  type            = "postgresql"
  provider_id     = "plusclouds"
  machine_tier_id = "p9200-h-4"
  region          = "tr-ist-1"

  postgresql_version = "16"
  storage_gb         = 50
  replicas           = 2
  engine_profile     = "geo-postgis"
  enabled_capabilities = ["postgis"]

  tags = {
    env  = "production"
    team = "backend"
  }
}

data "turkdb_cluster_connection" "main" {
  cluster_id = turkdb_cluster.main.id
}

output "dsn" {
  value     = data.turkdb_cluster_connection.main.dsn
  sensitive = true
}

☸️ Kubernetes Operator

Kubernetes kullanıyorsanız TürkDB cluster'ını bir K8s kaynağı gibi yönetin. Bağlantı bilgisi otomatik olarak bir Secret'a yazılır — uygulamanız doğrudan bu Secret'ı okuyabilir.

# Cluster tanımı (GitOps'a commit edebilirsiniz)
apiVersion: database.turkdb.io/v1alpha1
kind: PostgreSQLCluster
metadata:
  name: my-app-db
  namespace: production
spec:
  forProvider:
    tier:   p9200-h-4
    region: ist1
    backup:
      enabled:       true
      retentionDays: 14
  writeConnectionSecretToRef:
    namespace: production
    name:      my-app-db-conn   # bu Secret otomatik doldurulur

🗄️ Hangi Veritabanını Seçmeli?

🧩 Motor Profilleri ve Sonradan Açılan Özellikler

Her motor özelliği aynı riskte değildir. Bu yüzden TürkDB’de özellikler ikiye ayrılır: cluster açılışında seçilen motor profilleri ve mevcut cluster üstünde preflight/onay/doğrulama ile açılan capability değişiklikleri.

Cluster açılışında seçilen profiller

Mevcut cluster üstünde yapılabilecekler

⚡ Yüksek Erişilebilirlik (HA)

HA seçeneğinde asıl değer, primary düşüşü olduğunda replikanın devralma süresi, uygulama reconnect davranışı ve veri kaybı riskinin açıkça ölçülebilmesidir. Üretim kapsamı bu ölçümler ve seçilen paketle birlikte netleştirilir.

💰 Makine Boyutları ve Fiyatlandırma

TürkDB, PlusClouds Leo One Hybrid Value serisi üzerinde çalışır. Uygulamanızın ihtiyacına göre doğru boyutu seçin.

Tüm tier listesi için: turkdb cluster tiers veya app.turkdb.io/pricing

💾 Yedekleme & Point-in-Time Recovery

Otomatik yedekleme

Otomatik yedekleme için Yedekleme sekmesindeki zamanlamanın etkin olduğunu ve saklama süresini kontrol edin. Yedeklerin başarıyla tamamlandığını ayrıca doğrulayın; zamanlama tanımı tek başına alınmış bir yedek değildir.

Yedek ve geri yükleme durumunu takip etme

Yedekleme sekmesinde zamanlama ve saklama ayarlarını kontrol edebilir, manuel yedek başlatabilir ve yedek durumunu izleyebilirsiniz. Uzun süren veya başarısız bir yedekte önce durum mesajını, ardından olay ve log kayıtlarını inceleyin. Ekran yalnız ilgili yedek için kullanılabilir işlemleri gösterir; iptal, temizleme veya yeniden deneme seçeneği her durumda açık olmayabilir.

Geri yükleme öncesinde hedef cluster adı ve seçilen yedek için ön kontrol çalışır. Engelleyici bir sonuç varsa açıklanan koşulu giderin. İşlemi başlatmak, geri yüklemenin tamamlandığı anlamına gelmez; geri yükleme işini ve hedef cluster durumunu takip edin, verileri doğruladıktan sonra uygulamanın bağlantısını değiştirin.

PITR ekranında en erken ve en geç kurtarma zamanı hazır olmadan tarih seçilemez. Arşiv akışı gecikmiş, çalışma durumu doğrulanmamış veya kurtarma penceresi hazır değilse ekrandaki sonraki adımı uygulayın. PITR'ı açmak tek başına kullanılabilir bir kurtarma noktası oluştuğunu göstermez.

Point-in-Time Recovery (PITR)

PostgreSQL ve MySQL cluster'larında PITR etkinleştirirseniz sürekli WAL/binlog arşivleme başlar. Yanlış silinen veriler veya başarısız migration sonrası saniye hassasiyetiyle geri dönebilirsiniz.

🍴 Cluster Fork

Var olan bir cluster'ın altyapı yapılandırmasını kopyalayarak yeni bir cluster açar. Veri taşınmaz — yalnızca aynı tip, versiyon ve parametreler kopyalanır.

# Staging: aynı konfigürasyon, daha küçük boyut
turkdb cluster fork prod-db \
  --name staging-db --tier p9200-h-2

# Veriyle birlikte kopyalamak için önce fork, sonra migration başlatın

🚚 Veri Taşıma

Başka bir kaynaktan TürkDB'ye veri taşımak için Web UI'deki Migration Wizard'ı kullanın. Arka planda çalışan bir iş olarak başlar — bağlantınızı kesmenize gerek yok.

👤 Veritabanı Kullanıcıları

Her cluster'a birden fazla veritabanı kullanıcısı ekleyebilirsiniz. Her servis veya takım için ayrı kullanıcı oluşturmak güvenlik açısından önerilir.

🛡️ IP İzin Listesi

IP izin listesiyle erişim kurallarını yönetin. Özel ağ veya WireGuard kullanan cluster’larda önce ilgili ağ erişimini kurmanız gerekir; IP/CIDR eklemek public veritabanı portu açmaz.

📋 Loglar

Cluster'ın veritabanı log satırlarını Web UI'den veya CLI'dan görüntüleyebilirsiniz. Yavaş sorgular, bağlantı hataları ve uyarılar burada yer alır.

turkdb cluster logs my-pg               # son 100 satır
turkdb cluster logs my-pg --tail 500  # son N satır
turkdb cluster logs my-pg --follow    # canlı akış

📈 Metrikler

Nerede bulunur?

Metrikler sekmesinde ne görürsünüz?

Yavaş Sorgular sekmesi

Cluster Detay sayfasında Yavaş Sorgular sekmesi ayrı bir performans aracıdır. Hangi sorgularınızın yavaş çalıştığını görüp optimizasyon yapabilirsiniz.

API ile metrik okuma

GET https://api.turkdb.io/v1/clusters/{id}/metrics
Authorization: Bearer <api-key>

Yanıtta şu alanlar gelir: queries_per_second, avg_query_latency_ms, replication_lag_seconds, active_connections, max_connections, storage_used_bytes, storage_total_bytes, backup_status, last_backup_at, timestamp.

🔔 Webhook

Cluster olayları gerçekleştiğinde belirlediğiniz URL'e otomatik POST isteği gönderilir. Slack bildirimi, PagerDuty alarmı veya kendi otomasyon sistemleriniz için kullanın.

💳 Faturalama

TürkDB abonelik tabanlı çalışır. Her cluster, oluşturulurken seçtiğiniz makine tier'ına bağlı bir iyzico (BDDK lisanslı) aboneliğiyle ilişkilendirilir. Aboneliğin ilk ödemesi onaylanana kadar cluster kaynakları başlatılmaz; sonraki dönemler otomatik yenilenir.

Ücret nasıl hesaplanır?

Abonelik yaşam döngüsü

Fatura ve planları görüntüleme

turkdb billing plan              # aktif plan + tüm tier seçenekleri
turkdb billing usage             # dönem kullanımı + tahmini fatura
turkdb billing invoices          # fatura geçmişi
turkdb billing get <invoice-id>   # tek fatura detayı

Sayaç ve mutabakat görünürlüğü

Fatura & Kullanım ekranında dönem sayaçları, meter bazlı subtotal değerleri ve billing metering mutabakatı görünür. Reconciliation temiz değilse panel açık kalan veya eksik sayaçları ayrı ayrı listeler.

• GET /v1/billing/metered-usage: dönem rating satırları, meter type, reason code, billable quantity ve USD cent subtotal.
• GET /v1/billing/metering-reconciliation: eksik compute/storage/backup/data-plane sayaçları, açık kalan backup storage ve eksik price_key kontrolü.

Fatura kalemlerini inceleme

Fatura & Kullanım ekranındaki fatura listesinde Fatura dökümü düğmesini açın. USD faturalarında kalem açıklaması, miktar × birim fiyat, kalem toplamı, ara toplam, vergi ve genel toplam gösterilir. Kalem tutarları cent'e yuvarlanır; bu döküm kaydedilmiş fatura tutarlarını gösterir.

Dönem kullanım tahmini ile kaydedilmiş fatura aynı görünüm değildir. Eski bir kayıt için USD dökümü bulunmadığı belirtiliyorsa para birimini USD kabul etmeyin. Döküm yüklenemezse kapatıp yeniden açın.

👥 Ekip Yönetimi

Birden fazla kişinin aynı tenant üzerinde çalışması için üye ekleyebilir ve rol atayabilirsiniz.

🏛️ KVKK Uyumu

TürkDB’nin uyum tarafındaki hedefi veri yerleşimi, erişim kaydı, silme talebi ve export gibi süreçleri görünür kılmaktır. KVKK yükümlülükleri pilot kapsamı, sözleşme ve hukuki değerlendirmeyle birlikte netleştirilmelidir.

Aylık KVKK kontrol rutini

• Web UI → Uyum → Özet: açık ihlal veya bekleyen silme var mı?
• Bekleyen silmelerde kalan gün < 5 ise imha yaklaşıyor
• Audit Log'u gözden geçirin: beklenmedik erişim var mı?
• Gelen veri export taleplerini yanıtlayın

❓ Sık Sorulan Sorular

Uygulamam hangi adrese bağlanmalı?

Web UI veya CLI'dan bağlantı bilgisini alın. Bu adres bağlantı yönetimi içerir — doğrudan veritabanı sunucusuna bağlanmıyorsunuz, bağlantı katmanı üzerinden geçiyorsunuz.

Sildiğim cluster'ın verisi ne zaman tamamen yok edilir?

KVKK Md. 7 gereği silme talebinden 30 gün sonra kalıcı imha gerçekleşir. Bu süre içinde destek birimiyle iletişime geçerek kurtarma talep edebilirsiniz.

Bağlantı limitine ulaştım, ne yapmalıyım?

İki seçenek: (1) Daha büyük bir tier'a geçin. (2) Uygulama tarafında connection pool kütüphanesi kullanın (PgBouncer, HikariCP, vb.).

Hangi veritabanını seçmeliyim?

Genel web uygulamaları için PostgreSQL, mevcut MySQL altyapısıyla uyumluluk için MySQL, esnek döküman modeli için MongoDB, büyük ölçekli analitik için ClickHouse, önbellek ve oturum için Redis.

Migration'da kaynak DB şifrem güvende mi?

Kimlik bilgileriniz yalnızca migration işi süresince şifreli olarak tutulur ve iş tamamlandıktan sonra silinir. Veritabanımıza yazılmaz.

HA cluster ile standart cluster arasındaki fark?

HA cluster birden fazla düğüm çalıştırır. Primary düştüğünde replika otomatik devreye girer — uygulamanız kısa bir yeniden bağlanma süresinin ardından çalışmaya devam eder. Standart cluster'da ise Primary düştüğünde sizden manuel müdahale gerekebilir.

Tier'ı sonradan değiştirebilir miyim?

Evet. Web UI'de Cluster → Ayarlar → Tier Değiştir. Küçük bir kesinti (genellikle < 30 sn) oluşabilir.

API key'im sızdı, ne yapmalıyım?

Hemen Web UI → API Keys veya turkdb api-key delete <id> ile iptal edin. Ardından yeni bir key oluşturun ve sistemlerinize güncelleyin.

🆘 Destek