mongodump ve mongorestore: MongoDB Yedek Alma ve Geri Yükleme Rehberi

Araçlar nereden gelir?

MongoDB 4.4'ten itibaren Database Tools sunucudan ayrı yayımlanır ve 100.0.0 ile başlayan kendi sürüm numarasını kullanır. Linux'ta resmî depodan kurulumda mongodb-database-tools paketi mongodump, mongorestore, bsondump, mongoimport, mongoexport, mongostat, mongotop ve mongofiles araçlarını içerir. mongodb-org meta paketi, mongodb-org-tools üzerinden bu paketi de kurar; yani Ubuntu kurulum yazısındaki gibi mongodb-org kurduysanız araçlar zaten sistemdedir.

MongoDB 9.0 kullanıyorsanız bir sürüm ayrıntısına dikkat edin: belgelere göre 9.0 dağıtımındaki time series koleksiyonlarını dökmek için Database Tools 100.16.0 veya üstü gerekir. Daha eski sürümler time series bucket ad alanlarını doğrudan okumaya çalışır, 9.0 buna izin vermez ve mongodump CommandNotSupportedOnLegacyTimeseriesBucketsNamespace hatasıyla durur. Çözüm araçları güncellemektir. Time series koleksiyonlarının kendisi için time series yazısına bakın.

mongodump ile yedek alma

Seçeneksiz çalıştırılan mongodump, yerel makinede 27017 portundaki sunucuya bağlanır ve tüm veritabanlarını dump/ dizinine yazar. Çıktı dizinini --out (kısaca -o), belirli bir veritabanını --db, belirli bir koleksiyonu --collection ile seçersiniz:

mongodump --out=/opt/backup/mongodump-1
mongodump --db=magaza --out=/opt/backup/magaza
mongodump --db=magaza --collection=siparisler
mongodump --db=magaza --excludeCollection=loglar --excludeCollection=oturumlar

Dizin çıktısında her veritabanı için bir alt dizin, her koleksiyon için bir .bson veri dosyası ve bir .metadata.json dosyası oluşur. Metadata dosyası koleksiyon adı, türü, seçenekleri, UUID ve indeks tanımlarını taşır; görünümler (view) için yalnızca metadata dosyası yazılır, BSON dosyası olmaz. Metadata dosyaları Extended JSON v2.0 (Canonical) biçimindedir.

--query seçeneği yalnızca --collection ile çalışır ve sorgu Extended JSON v2 biçiminde, alan adları ve operatörler tırnak içinde yazılmalıdır. Kabuk tarafında sorguyu tek tırnakla sarmak, içteki çift tırnakların ve $ karakterinin kabuk tarafından yorumlanmasını önler:

mongodump -d=magaza -c=siparisler -q='{ "durum": "tamamlandi", "tarih": { "$gte": { "$date": "2026-01-01T00:00:00.000Z" } } }'

Sıkıştırma ve arşiv dosyası

--gzip dizin çıktısında her dosyayı ayrı ayrı sıkıştırır; dosya adları .bson.gz ve .metadata.json.gz ile biter. --archive ise çok sayıda BSON dosyası yerine tek bir dosya üretir; belgelere göre arşiv biçimi disk G/Ç'sini iyileştirir ve performansı artırabilir. İkisini birlikte kullanarak tek, sıkıştırılmış bir dosya elde edersiniz. --archive ile --out birlikte kullanılamaz.

mongodump --archive=/opt/backup/magaza.archive --db=magaza
mongodump --archive=/opt/backup/magaza.gz --gzip --db=magaza

Arşiv dosyası, Windows veya macOS gibi büyük-küçük harf duyarsız dosya sistemlerinde de önerilen biçimdir. Belgelere göre dizin çıktısında yalnızca harf büyüklüğüyle ayrışan koleksiyon adları (Users ve users gibi) bu dosya sistemlerinde birbirinin üzerine yazılır. --archive değer verilmeden kullanılırsa veri standart çıktıya akar; bu sayede iki sunucu arasında diske yazmadan kopyalama yapılabilir:

mongodump --archive | mongorestore --archive

Kimlik doğrulamalı sunucudan yedek

Erişim denetimi açık bir sunucuda mongodump çalıştıran kullanıcının, yedeklenecek her veritabanında find eylemine sahip olması gerekir. Yerleşik backup rolü tüm veritabanlarını yedeklemeye yetecek ayrıcalıkları sağlar; bu yüzden yedekleme için admin veritabanında yalnızca backup rolü olan ayrı bir kullanıcı açmak mantıklıdır (rol yönetimi yazısında örneği var). --password vermezseniz araç parolayı sorar; böylece parola kabuk geçmişine düşmez.

mongodump --host=localhost --port=27017 --username=yedekci --authenticationDatabase=admin --out=/opt/backup/tam
mongodump --uri="mongodb://yedekci@localhost:27017/?authSource=admin" --db=magaza

Kimlik doğrulama veritabanıyla ilgili bir tuzak var: bağlantı dizesinde authSource belirtilmezse, --db ile verdiğiniz veritabanı hem dökülecek veritabanı hem de kimlik doğrulama veritabanı olarak kullanılır. Kullanıcınız admin'de tanımlıysa --authenticationDatabase=admin veya authSource=admin eklemezseniz doğrulama başarısız olur. Bağlantı dizesi ayrıntıları için connection string yazısına bakın.

Yedeğe neler girer, neler girmez?

Belgelerin "veri hariç tutma" kuralları, özellikle tam sunucu yedeği alırken önemlidir:

• --db vermezseniz local veritabanı yedeğe girmez; config veritabanından yalnızca chunks, collections, databases, settings, shards, tags ve version koleksiyonları alınır.
• Sıradan bir veritabanını --db ile dökerken system. ile başlayan koleksiyonlar, system.js hariç, dışarıda kalır.
• --db=admin ile dökümde system.keys koleksiyonu hariç tutulur.
• Yedek belgeleri ve indeks tanımlarını içerir, indeks verisini içermez; indeksler geri yüklemede yeniden oluşturulur.
• Görünümlerin varsayılan olarak yalnızca tanımı alınır; içerik için --viewsAsCollections gerekir.
• Tüm sunucu dökülürken kullanıcı ve rol tanımları her zaman dahil edilir; tek veritabanı dökümünde bunları almak için --dumpDbUsersAndRoles kullanılır.

Bunlara ek olarak mongodump, Queryable Encryption veya istemci tarafı alan düzeyi şifreleme kullanan koleksiyonlarla çalışmaz. Ayrıca koleksiyon seçeneklerinde $ ile başlayan alan adları varsa mongodump ve mongorestore bunları işleyemez.

Tutarlı yedek: --oplog ve --oplogReplay

mongodump çalışırken yazma işlemleri devam ederse yedek tek bir zaman anını temsil etmeyebilir. Belgeler bunun için üç yol sunar: uygulama düzeyinde yazmaları durdurmak (tek koleksiyon yedekleri için önerilir), fsync kilidiyle tüm yazmaları duraklatmak ya da tam replica set dökümlerinde --oplog kullanmak. --oplog, döküm süresince oluşan yazmaları çıktı dizininin en üstünde oplog.bson dosyasına (arşiv kullanıyorsanız arşivin içine) yazar. Geri yüklerken mongorestore --oplogReplay bu kayıtları uygular ve veri, dökümün bittiği ana getirilir.

mongodump --oplog --archive=/opt/backup/rs-tam.gz --gzip
mongorestore --oplogReplay --archive=/opt/backup/rs-tam.gz --gzip

--oplog yalnızca oplog tutan düğümlerde, yani replica set üyelerinde çalışır; tek başına çalışan bir mongod'da oplog yoktur. Tam bir döküm şarttır: --db, --collection, --query veya --dumpDbUsersAndRoles ile birlikte kullanılırsa başarısız olur. Döküm sırasında biri renameCollection, $out içeren bir aggregation, mapReduce, kullanıcı veya rol değiştiren bir işlem ya da küme çapında ayar değiştiren bir komut çalıştırırsa da işlem başarısız olur. Sharded cluster'da --oplog kullanılamaz. Belgeler ayrıca time series koleksiyonu olan bir dağıtımda mongodump --oplog çalışırken feature compatibility version (FCV) değerini 8.x ile 9.0 arasında değiştirmemenizi ister. Replica set kavramı için replica set kurulumu yazısına bakın.

mongorestore ile geri yükleme

mongorestore bir dizin yolu, tek bir BSON dosyası ya da --archive ile bir arşiv alır. Hedef veritabanı ve koleksiyonlar yoksa oluşturulur. Belirli ad alanlarını seçmek için --nsInclude, dışarıda bırakmak için --nsExclude kullanılır; ikisi de * joker karakterini kabul eder ve birden çok kez verilebilir. Arşivden geri yüklemede --db ve --collection kullanımdan kaldırılmıştır, yerine --nsInclude önerilir.

mongorestore /opt/backup/mongodump-1
mongorestore --nsInclude=magaza.siparisler /opt/backup/mongodump-1
mongorestore --nsInclude='magaza.*' --nsExclude='magaza.*_test' /opt/backup/mongodump-1
mongorestore --gzip --archive=/opt/backup/magaza.gz --nsInclude='magaza.*'

Yedeği farklı bir adla geri yüklemek için --nsFrom ve --nsTo birlikte kullanılır. Bu, MongoDB 4.2'de kaldırılan copydb ve clone komutlarının yerine belgelerin önerdiği yöntemdir. Örneğin canlı veritabanını test için kopyalamak:

mongodump --archive=/opt/backup/magaza.archive --db=magaza
mongorestore --archive=/opt/backup/magaza.archive --nsFrom='magaza.*' --nsTo='magaza_test.*'

Önemli bir davranış: mongorestore yalnızca ekleme (insert) yapar, güncelleme yapmaz. Hedef koleksiyonda aynı _id değerine sahip belgeler varsa bunların üzerine yazılmaz. Koleksiyonu yedekteki haline tam olarak döndürmek istiyorsanız --drop ile önce hedef koleksiyonu düşürmeniz gerekir. --drop yalnızca yedekte bulunan koleksiyonları düşürür; yedekte olmayan koleksiyonlara dokunmaz.

Geri yüklemede belge sırası varsayılan olarak garanti edilmez; sıra önemliyse --maintainInsertionOrder kullanın. system.profile koleksiyonunun verisi hiçbir zaman geri yüklenmez. mongorestore çökerse sistem yalnızca bir kısmı yüklenmiş tutarsız bir durumda kalabilir; belgeler bu durumda yüklenen veriyi silip işlemi baştan çalıştırmanızı söyler. Aynı koleksiyona birden çok mongorestore'u eşzamanlı çalıştırmak desteklenmez.

Geri yükleme için gereken yetkiler

Erişim denetimi açık bir hedefte yerleşik restore rolü, yedek system.profile verisi içermiyorsa ve --oplogReplay kullanılmıyorsa yeterlidir. Yedekte system.profile verisi varsa ek olarak dbAdmin veya dbAdminAnyDatabase rolünün sağladığı ayrıcalıklar gerekir. --oplogReplay için ise belgeler anyResource üzerinde anyAction veren özel bir rol tanımlamanızı ve bunu yalnızca bu işi yapması gereken kullanıcılara vermenizi ister.

Sürüm uyumluluğu kuralı

Belgelere göre mongodump ile alınan bir yedeği mongorestore ile yüklerken kaynak ve hedef dağıtım aynı ana sürümde ya da aynı feature compatibility version değerinde olmalıdır. BSON veri dosyalarını aynı veya daha yeni sürüme yüklemek mümkündür, ancak bu yükseltme yöntemi olarak önerilmez; metadata, arşiv ve oplog dosyaları için bu garanti yoktur ve farklı sürümler arasında geri yükleme başarısız olabilir, sessizce hatalı sonuç verebilir veya metadata'yı bozabilir. Ayrıca yedeği hangi mongodump sürümüyle aldıysanız aynı sürüm mongorestore ile yüklemeniz istenir. Sürüm yükseltme planı için MongoDB 9.0 yenilikleri yazısına bakın.

Uygulamalı örnek: gece yedeği betiği

Aşağıdaki küçük betik, belgelerdeki "yedek dosyalarını içerik ve zamanla etiketleyin" önerisine uygun olarak her çalıştığında tarihli, sıkıştırılmış tek bir arşiv üretir. mongodump mevcut çıktı dosyalarının üzerine yazdığı için tarihli ad kullanmak eski yedeği korur. Betik çalışırken parola soramayacağı için parolayı --config seçeneğiyle verilen bir YAML dosyasında tutabilirsiniz. Database Tools 100.3.0 ile gelen bu seçenek, belgelere göre parola istemi dışında parola vermenin önerilen yoludur; dosya password, uri ve sslPEMKeyPassword alanlarını içerebilir ve uygun dosya sistemi izinleriyle korunmalıdır. Aynı değeri komut satırında da verirseniz komut satırındaki değer geçerli olur.

password: <parola>

#!/bin/bash
TARIH=$(date +%F)
mongodump --uri="mongodb://yedekci@localhost:27017/?authSource=admin" \
  --config=/etc/mongodump-yedek.yaml \
  --archive=/opt/backup/tam-$TARIH.gz --gzip

Dosyayı chmod 600 ile yalnızca betiği çalıştıran kullanıcının okuyabileceği hale getirin. Betiği cron veya bir systemd birimiyle her gece çalıştırabilirsiniz; servis yönetimi temelleri için systemd servis yönetimi yazısına bakabilirsiniz. Yedeğin işe yaradığını anlamanın tek yolu, belgelerin de önerdiği gibi yedeği bir test dağıtımına geri yükleyip doğrulamaktır.

Performans ve yöntem seçimi

Belgelere göre mongodump ve mongorestore çalışan bir mongod ile konuştukları için veritabanı performansını etkileyebilir: tüm veriyi bellekten geçirmeye zorlarlar ve veri sistem belleğinden büyükse sık kullanılan çalışma kümesini bellekten iter. Bu etki kabul edilemezse dosya sistemi anlık görüntüleri alternatif olarak önerilir. Doğru anlık görüntü için journaling açık olmalı ve journal, diğer veri dosyalarıyla aynı mantıksal birimde bulunmalıdır.

Sharded cluster'ların mongodump ile yedeklenmesi için belgeler ayrı bir öğretici sunar ve sırasında dengeleyicinin (balancer), shard'lar arası transaction'ların ve DDL işlemlerinin durdurulmasını ister; ayrıntı için sharding yazısına bakın.

Sık yapılan hatalar

• mongodump'ı mongosh içinde çalıştırmaya çalışmak: Araç sistem komut satırında çalışır.
• Aynı çıktı dizinine tekrar tekrar yazmak: Eski dosyaların üzerine yazılır; tarihli dizin veya arşiv adı kullanın.
• Yedeği hiç geri yüklememek: Test edilmemiş yedek, işe yarayacağı kanıtlanmamış yedektir.
• --drop olmadan "tam geri yükleme" beklemek: Aynı _id'li mevcut belgeler değişmez.
• JSON dışa aktarımını yedek sanmak: mongoexport yedekleme aracı değildir; farkı mongoexport ve mongoimport yazısında.
• Farklı ana sürüme metadata ve arşivle geri yüklemek: Sonuç başarısız veya bozuk olabilir.

Sık Sorulan Sorular

Tek bir koleksiyonu nasıl geri yüklerim?

Dizin yedeği için mongorestore --nsInclude=veritabani.koleksiyon dump/, arşiv için aynı seçeneği --archive ile birlikte kullanın. Desen hiçbir dosyayla eşleşmezse hiçbir veri yüklenmez.

Yedeği sıkıştırmak geri yüklemeyi yavaşlatır mı?

Belgeler sıkıştırmanın hıza etkisi için bir değer vermez. Bilinen şey, mongorestore --gzip seçeneğinin tam olarak mongodump --gzip ile üretilmiş dosyaları veya akışı okumak için var olduğudur; sıkıştırılmış bir yedeği geri yüklerken bu seçeneği, arşivse --archive ile birlikte vermeniz gerekir.

Kullanıcılar ve roller yedeğe girer mi?

Tüm sunucu dökümünde kullanıcı ve rol tanımları her zaman dahildir. Tek bir veritabanı için --dumpDbUsersAndRoles ile alınabilir ve --restoreDbUsersAndRoles ile geri yüklenir; ikinci seçenek admin veritabanında kullanılamaz.

Döküm alırken uygulamayı durdurmam gerekir mi?

Zorunlu değildir, ancak yazmalar devam ederse yedek tek bir anı yansıtmayabilir. Replica set'te tam döküm için --oplog, tek koleksiyon yedeğinde uygulama düzeyinde yazma durdurma önerilir.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: MongoDB öğrenme rehberi · mongoexport ve mongoimport · MongoDB kullanıcı ve rol yönetimi · MongoDB replica set kurulumu · MongoDB production notları · Veritabanı yedekleme stratejileri