Merhaba Arkadaşlar. Bu yazımda sizlere Couchbase ile nasıl başlayabileceğinizi adım adım göstereceğim. .NET geliştiricisi olarak SQL Server tarafına alışkın olabilirsiniz. Ama Couchbase biraz farklı çalışıyor. Özellikle Cluster → Bucket → Scope → Collection yapısı ilk başta kafa karıştırabiliyor. Ben de kendi deneyimlerim üzerinden sıfırdan kurulumdan başlayıp, ilk verimizi ekleyip .NET uygulamasından sorgulamaya kadar göstereceğim. 

---

1. Kurulum (Windows ve Docker)

1.1 Windows Server Üzerine Kurulum

Öncelikle Couchbase downloads sayfasından Windows için Couchbase Server MSI dosyasını indiriyoruz. Kurulum sihirbazını çalıştırdıktan sonra tarayıcıdan http://localhost:8091 adresine giderek Cluster kurulumu yapıyoruz.

• Cluster adı belirleyin (ör: DevCluster)
• Admin kullanıcı oluşturun
• Servislerden Data, Query, Index, Search seçin
• RAM kotalarını ayarlayın (ör: Data için 1GB)

# Firewall kuralları (PowerShell)
netsh advfirewall firewall add rule name="Couchbase WebUI" dir=in action=allow protocol=TCP localport=8091-8096
netsh advfirewall firewall add rule name="Couchbase KV" dir=in action=allow protocol=TCP localport=11210

1.2 Docker Üzerinden Kurulum

Eğer Docker kullanıyorsanız tek bir komut yeterli 👇

docker run -d --name couchbase `
  -p 8091-8097:8091-8097 `
  -p 11210-11211:11210-11211 `
  couchbase:community

Ardından yine http://localhost:8091 üzerinden kurulum sihirbazı çıkacak.

---

2. Cluster, Bucket, Scope ve Collection

Buralar SQL Server geçmişi olanlara tanıdık gelecek:

• Cluster → SQL Server Instance
• Bucket → Database
• Scope → Schema
• Collection → Table

-- Scope ve collection oluşturma
CREATE SCOPE `Commerce`.`app`;
CREATE COLLECTION `Commerce`.`app`.`users`;
CREATE COLLECTION `Commerce`.`app`.`products`;
CREATE COLLECTION `Commerce`.`app`.`orders`;

---

3. Index Oluşturma

Sorguların çalışabilmesi için index gerekli. Geliştirme için Primary Index açıyoruz. Performans için ayrıca secondary index’ler tanımlıyoruz.

-- Primary Index
CREATE PRIMARY INDEX ON `Commerce`.`app`.`users`;
CREATE PRIMARY INDEX ON `Commerce`.`app`.`products`;
CREATE PRIMARY INDEX ON `Commerce`.`app`.`orders`;

-- Secondary Index
CREATE INDEX idx_orders_userId
ON `Commerce`.`app`.`orders`(userId);

CREATE INDEX idx_orders_status_createdAt
ON `Commerce`.`app`.`orders`(status, createdAt);

CREATE INDEX idx_orders_items_productId
ON `Commerce`.`app`.`orders`(DISTINCT ARRAY i.productId FOR i IN items END);

---

4. İlk Verilerimizi Ekleyelim

Couchbase’te otomatik artan ID yok. O yüzden GUID kullanıyoruz. Document key’leri user::GUID, product::GUID şeklinde isimlendirmek en sağlıklı yöntem.

INSERT INTO `Commerce`.`app`.`users` (KEY, VALUE) VALUES
("user::b3f6a8e3-68cb-4f17-b0a8-69c4a8f52290",
{
  "Id": "b3f6a8e3-68cb-4f17-b0a8-69c4a8f52290",
  "Name": "Ekrem Özer",
  "Email": "ekrem@example.com",
  "Age": 36,
  "IsActive": true,
  "CreatedAt": "2025-09-15T19:00:00Z"
});

INSERT INTO `Commerce`.`app`.`products` (KEY, VALUE) VALUES
("product::d52c1f5e-5c44-41c9-9a32-2be6f7a0a9f0",
{
  "Id": "d52c1f5e-5c44-41c9-9a32-2be6f7a0a9f0",
  "Name": "Laptop",
  "Price": 1500,
  "Currency": "USD",
  "Stock": 25,
  "Tags": ["electronics", "computer"],
  "CreatedAt": "2025-09-15T19:05:00Z"
});

-- Çok ürünlü sipariş örneği
INSERT INTO `Commerce`.`app`.`orders` (KEY, VALUE) VALUES
("order::e7d1a3f4-90ad-4b7d-9d57-1a2b3c4d5e6f",
{
  "Id": "e7d1a3f4-90ad-4b7d-9d57-1a2b3c4d5e6f",
  "UserId": "b3f6a8e3-68cb-4f17-b0a8-69c4a8f52290",
  "Items": [
    { "ProductId": "d52c1f5e-5c44-41c9-9a32-2be6f7a0a9f0", "Quantity": 1, "UnitPrice": 1500 },
    { "ProductId": "a8a93f6b-1e1a-4d1d-9c4e-0f5d19d9f0b2", "Quantity": 3, "UnitPrice": 25 }
  ],
  "Total": 1575,
  "Status": "Processing",
  "CreatedAt": "2025-09-16T21:00:00Z"
});

---

5. İlk SELECT ve JOIN Sorguları

-- Tüm kullanıcılar
SELECT * FROM `Commerce`.`app`.`users`;

-- Orders JOIN Users
SELECT o.Total, o.Status, u.Name, u.Email
FROM `Commerce`.`app`.`orders` o
JOIN `Commerce`.`app`.`users` u
     ON o.UserId = u.Id;

-- Orders → Items (UNNEST) → Products
SELECT META(o).id AS OrderId,
       u.Name     AS UserName,
       p.Name     AS ProductName,
       i.Quantity,
       i.UnitPrice,
       (i.Quantity * i.UnitPrice) AS LineTotal,
       o.Total    AS OrderTotal,
       o.Status
FROM `Commerce`.`app`.`orders` o
JOIN `Commerce`.`app`.`users` u
     ON o.UserId = u.Id
UNNEST o.Items AS i
JOIN `Commerce`.`app`.`products` p
     ON i.ProductId = p.Id;

---

6. .NET Console Uygulaması

6.1 NuGet Kurulumu

dotnet add package CouchbaseNetClient

6.2 Bağlantı

var cluster = await Cluster.ConnectAsync(
    "couchbase://<sunucu-ip>",
    "Administrator",
    "Parola"
);

var bucket = await cluster.BucketAsync("Commerce");
var scope = bucket.Scope("app");
var users = scope.Collection("users");

6.3 POCO Model

public class User {
    public Guid Id { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }
    public int Age { get; set; }
    public bool IsActive { get; set; }
    public DateTime CreatedAt { get; set; }
}

6.4 Insert

var u = new User {
    Id = Guid.NewGuid(),
    Name = "Yeni Kullanıcı",
    Email = "yeni@example.com",
    Age = 29,
    IsActive = true,
    CreatedAt = DateTime.UtcNow
};
await users.UpsertAsync($"user::{u.Id}", u);

6.5 Select (KV Get)

var get = await users.GetAsync($"user::{u.Id}");
var userDoc = get.ContentAs<User>();
Console.WriteLine($"{userDoc.Name} - {userDoc.Email}");

6.6 Select (N1QL Query)

var q = "SELECT u.* FROM `Commerce`.`app`.`users` u WHERE u.IsActive = TRUE";
var qr = await cluster.QueryAsync<User>(q);

await foreach (var row in qr)
    Console.WriteLine($"{row.Name} - {row.Email}");

---

Sonuç 🎯

Bu yazıda sizlerle Couchbase’i Windows ve Docker üzerinde kurduk, Cluster → Bucket → Scope → Collection hiyerarşisini öğrendik, indexleri ekledik, GUID ID’lerle veriler ekledik ve sorguladık. Son olarak da .NET Console uygulaması üzerinden hem Insert hem de Select işlemlerini gerçekleştirdik. 🎉

Bir sonraki yazımda Couchbase tarafında Index optimizasyonu ve performans best practices konularına değineceğim. Takipte kalın 👋