Node.js İle Çevrim Dışı Veri Senkronizasyonu Nasıl Yapılır?

Gereksinimler ve Ön Hazırlık

Uygulamamızı geliştirmek için modern bir Node.js ortamına ihtiyacımız var. 2026 standartlarına uygun olarak Node.js 22+ sürümünü kullanmanızı öneririm. Projenizi başlatmak için aşağıdaki araçların yüklü olduğundan emin olun:

• Node.js (LTS sürümü)
• npm veya pnpm paket yöneticisi
• PouchDB (İstemci tarafı için) ve CouchDB (Sunucu tarafı veritabanı)

Proje dizininizi oluşturun ve gerekli bağımlılıkları yükleyin:

mkdir offline-sync-app
cd offline-sync-app
npm init -y
npm install pouchdb pouchdb-adapter-indexeddb

Bu komutlar, tarayıcı tabanlı yerel veritabanı yönetimini sağlayan PouchDB kütüphanesini projenize dahil eder.

Yerel Veritabanı Kurulumu ve Veri Yönetimi

Çevrim dışı çalışmanın ilk adımı, verileri kullanıcının cihazında güvenli bir şekilde saklamaktır. PouchDB, IndexedDB kullanarak tarayıcıda kalıcı bir depolama alanı oluşturur. Aşağıdaki kod ile yerel veritabanınızı başlatabilirsiniz.

const PouchDB = require('pouchdb');

// Yerel veritabanını oluşturma
const localDB = new PouchDB('my_local_db');

// Veri ekleme fonksiyonu
async function saveLocalData(doc) {
    try {
        const response = await localDB.put(doc);
        console.log('Veri başarıyla yerel veritabanına kaydedildi:', response);
    } catch (err) {
        console.error('Kayıt hatası:', err);
    }
}

saveLocalData({ _id: 'task_001', title: 'Çevrim dışı görev', completed: false });

Bu kod, _id alanı ile benzersiz bir doküman oluşturur. CouchDB ile uyumluluk için _id kullanımı zorunludur.

Node.js ile Senkronizasyon Stratejileri

Senkronizasyon, yerel veritabanı ile uzak veritabanı arasındaki farkların giderilmesidir. PouchDB'nin sync metodu, çift yönlü veri akışını otomatik olarak yönetir. Bağlantı koptuğunda senkronizasyon durur, bağlantı geldiğinde kaldığı yerden devam eder.

const remoteDB = new PouchDB('http://admin:password@localhost:5984/remote_db');

function startSync() {
    localDB.sync(remoteDB, {
        live: true,
        retry: true
    }).on('change', (info) => {
        console.log('Veri senkronize edildi:', info);
    }).on('error', (err) => {
        console.error('Senkronizasyon hatası:', err);
    });
}

startSync();

live: true parametresi, değişikliklerin anlık olarak yansıtılmasını sağlar. retry: true ise ağ koptuğunda otomatik yeniden bağlanma denemelerini aktif eder.

Çakışma Çözümü (Conflict Resolution)

Aynı veri hem çevrim dışı hem de sunucuda güncellendiğinde çakışmalar oluşur. PouchDB, her doküman için bir _rev (revizyon) numarası tutar. Çakışma durumunda en son yapılan değişikliği veya özel bir mantığı uygulamalısınız.

localDB.get('task_001', { conflicts: true }).then(doc => {
    if (doc._conflicts) {
        console.log('Çakışma tespit edildi, otomatik çözülüyor...');
        // Burada iş mantığınıza göre en son veriyi seçin veya birleştirin
    }
});

Kritik Uyarı: Çakışma çözümü sırasında veri kaybını önlemek için her zaman sunucudaki "timestamp" (zaman damgası) değerlerini karşılaştırın. Asla kullanıcı verisini kullanıcıya sormadan doğrudan üzerine yazmayın.

Senkronizasyon Yöntemleri Karşılaştırması

Güvenlik ve Veri Bütünlüğü

Node.js tarafında verileri sunucuya gönderirken mutlaka doğrulama yapmalısınız. İstemciden gelen verinin manipüle edilmediğinden emin olmak için "Validation Schema" kullanın.

const Joi = require('joi');

const schema = Joi.object({
    _id: Joi.string().required(),
    title: Joi.string().min(3).required(),
    completed: Joi.boolean()
});

function validateData(data) {
    return schema.validate(data);
}

Bu yapı, veritabanına hatalı veya kötü niyetli veri girişini engeller. Her zaman sunucu tarafında Joi veya Zod gibi kütüphanelerle gelen veriyi kontrol edin.

Sıkça Sorulan Sorular

Senkronizasyon sırasında internet koparsa ne olur?

PouchDB, değişiklikleri yerel veritabanında kuyruğa alır. İnternet bağlantısı geri geldiğinde, sync metodu otomatik olarak tüm birikmiş değişiklikleri sunucuya iletir.

Çok büyük verilerde performans sorunu yaşar mıyım?

Evet, IndexedDB limitleri ve tarayıcı belleği sınırlıdır. Büyük verilerde "paginated sync" (sayfalı senkronizasyon) veya sadece aktif verilerin senkronize edilmesi önerilir.

CouchDB kullanmak zorunda mıyım?

PouchDB'nin en iyi çalıştığı ortam CouchDB'dir. Ancak, farklı bir veritabanı kullanıyorsanız, pouchdb-adapter-http kullanarak kendi REST API'niz üzerinden senkronizasyon mantığını manuel yazabilirsiniz.

Veri güvenliğini nasıl sağlarım?

İstemci ve sunucu arasındaki iletişimde mutlaka HTTPS kullanın ve CouchDB üzerinde "Database per user" (her kullanıcıya özel veritabanı) mimarisini uygulayın.

Çakışmalar neden oluşur?

Aynı dokümanın farklı kopyalarının aynı anda veya farklı zamanlarda değiştirilip sunucuya gönderilmesi sonucu revizyon numaralarının uyuşmaması ile oluşur.

Sorumluluk Reddi: Bu rehberdeki kod örnekleri eğitim amaçlıdır. Üretim ortamında (production) veritabanı erişim bilgilerini asla kod içerisinde tutmayın, çevresel değişkenleri (env) kullanın ve tüm API uç noktalarınızı JWT (JSON Web Token) ile koruyun.

İleri Seviye Senkronizasyon Senaryosu: "Batch" İşlemler ve Delta Güncellemeleri

Uygulamanız büyüdükçe, her bir dokümanı tek tek senkronize etmek ağ trafiğini gereksiz yere artıracaktır. Bunun yerine, "delta" (fark) tabanlı güncellemeler ve toplu (batch) gönderim stratejileri kullanarak bant genişliğini optimize etmelisiniz. PouchDB'nin bulkDocs metodu, yerel veritabanındaki değişiklikleri tek bir HTTP isteği ile sunucuya iletmenize olanak tanır.

Aşağıdaki örnek, yerel veritabanında biriken tüm güncellemeleri tek seferde sunucuya nasıl göndereceğinizi göstermektedir:

async function syncBatchUpdates(localDB, remoteDB) {
  try {
    // Sadece henüz senkronize edilmemiş veya güncellenmiş kayıtları al
    const changes = await localDB.allDocs({
      include_docs: true,
      attachments: true
    });

    const docsToSync = changes.rows.map(row => row.doc);

    // Toplu gönderim
    const response = await remoteDB.bulkDocs(docsToSync);
    console.log("Toplu senkronizasyon başarılı:", response);
  } catch (err) {
    console.error("Toplu senkronizasyon hatası:", err);
  }
}

Senkronizasyon Süreçlerinde Hata Ayıklama ve İzleme

Çevrim dışı uygulamalarda karşılaşılan en büyük zorluk, senkronizasyonun arka planda sessizce başarısız olmasıdır. Kullanıcıya net bir geri bildirim sağlamak için senkronizasyon olaylarını (events) dinlemek ve hata loglarını merkezi bir yapıda toplamak gerekir.

Senkronizasyon Durumlarını Takip Etme

PouchDB replikasyon nesnesi, senkronizasyonun o anki durumunu anlamanız için çeşitli olay dinleyicileri sunar. Bu dinleyicileri kullanarak bir "Sync Monitor" mekanizması kurabilirsiniz:

const sync = localDB.sync(remoteDB, {
  live: true,
  retry: true
}).on('change', (info) => {
  console.log("Veri değişikliği algılandı:", info);
}).on('paused', (err) => {
  console.log("Senkronizasyon duraklatıldı (ağ bağlantısı yok veya güncel).");
}).on('active', () => {
  console.log("Senkronizasyon devam ediyor...");
}).on('denied', (err) => {
  console.error("Sunucu erişimi reddetti:", err);
}).on('error', (err) => {
  console.error("Kritik senkronizasyon hatası:", err);
});

Hata Ayıklama İpuçları

• Network Tabı: Tarayıcı geliştirici araçlarında "Network" sekmesini kullanarak, senkronizasyon isteklerinin 401 (Unauthorized) veya 403 (Forbidden) hataları döndürüp döndürmediğini kontrol edin.
• Replication Logları: PouchDB.debug.enable('*') komutunu kullanarak konsolda tüm senkronizasyon trafiğini detaylıca görüntüleyebilirsiniz.
• Veri Boyutu: Eğer senkronizasyon çok yavaşsa, yerel veritabanınızdaki "tombstone" (silinmiş doküman izleri) kayıtlarını temizlemek için compact() metodunu kullanın.

İpucu: Üretim ortamında PouchDB.debug modunu asla açık bırakmayın; bu, uygulamanızın performansını ciddi oranda düşürebilir ve hassas veri bilgilerini konsola sızdırabilir.

Sonuç

Node.js ile çevrim dışı veri senkronizasyonu, kullanıcı deneyimini bir üst seviyeye taşıyan kritik bir yetenektir. PouchDB ve CouchDB ikilisi, bu karmaşık süreci yönetmek için en sağlam standartları sunar. Bu rehberde öğrendiğiniz yerel depolama, çift yönlü senkronizasyon ve çakışma yönetimi temellerini kullanarak, bağlantı kopsa bile çalışan uygulamalar geliştirebilirsiniz.

Bir sonraki adım olarak, uygulamanıza "Sync Status" göstergesi ekleyerek kullanıcıyı ağ durumu hakkında bilgilendiren bir arayüz bileşeni geliştirmeyi deneyebilirsiniz.