MongoDB Connection String: mongodb:// ve mongodb+srv:// Biçimi

Standart biçimin parçaları

Sunucu kısmına kurulumun türüne göre farklı adresler yazılır. Tek bir sunucu (standalone) için o mongod'un adresi, replica set için replica set yapılandırmasında listelenen üye adları, sharded cluster için ise mongos yönlendiricilerinin adresleri verilir. Örnekler:

mongodb://uygulama:Gizli%40Parola1@localhost:27017/magaza
mongodb://uygulama:Gizli%40Parola1@db1.ornek.com:27017,db2.ornek.com:27017,db3.ornek.com:27017/magaza?replicaSet=rs0&authSource=admin
mongodb://uygulama:Gizli%40Parola1@mongos1.ornek.com:27017,mongos2.ornek.com:27017/

İlk satır yerel bir sunucuya, ikincisi üç üyeli rs0 replica set'ine, üçüncüsü iki mongos üzerinden bir sharded cluster'a bağlanır. Veritabanı adı vermediğiniz hâlde seçenek yazacaksanız, son sunucuyla seçenekleri başlatan soru işareti arasına bölü işareti koymanız gerekir: ...:27017/?replicaSet=rs0.

Kimlik doğrulama veritabanı nasıl belirlenir?

Bir kullanıcı belirli bir veritabanında tanımlanır ve bağlanırken o veritabanına karşı doğrulanır. İstemci bu veritabanını şu sırayla seçer:

• authSource seçeneği verilmişse o veritabanı kullanılır.
• authSource yoksa adresteki /defaultauthdb kullanılır.
• İkisi de yoksa admin veritabanı kullanılır.

Bu kural en sık yaşanan karışıklığın kaynağıdır: kullanıcınızı admin veritabanında oluşturduysanız ve adrese /magaza yazdıysanız, istemci kullanıcıyı magaza veritabanında arar. Bu durumda adrese ?authSource=admin eklemeniz gerekir:

mongodb://uygulama:Gizli%40Parola1@db1.ornek.com:27017/magaza?authSource=admin

mongosh'ta /defaultauthdb parçası aynı zamanda varsayılan veritabanını belirler; yazılmazsa mongosh test veritabanını kullanır. Sürücüler bu alanı farklı yorumlayabilir. Kullanıcıların nerede oluşturulacağı kullanıcı ve rol yönetimi yazısında anlatılıyor. Adreste kullanıcı adı yoksa (veya --username verilmemişse) MongoDB authSource değerini yok sayar.

Paroladaki özel karakterler: yüzde kodlama

Kullanıcı adı veya parola şu karakterlerden birini içeriyorsa, bu karakterler yüzde kodlamayla (percent encoding) yazılmalıdır: $ : / ? # [ ] @. Aksi halde istemci adresi yanlış parçalara ayırır. Örneğin @ karakteri %40 olur; bu yüzden yukarıdaki örneklerde Gizli@Parola1 parolası Gizli%40Parola1 olarak yazıldı.

UNIX alan soketine bağlanırken soket yolu da kodlanır. Örneğin /tmp/mongodb-27017.sock yolu adreste %2Ftmp%2Fmongodb-27017.sock olarak yazılır:

mongodb://uygulama:Gizli%40Parola1@%2Ftmp%2Fmongodb-27017.sock

mongodb+srv:// biçimi ve DNS kayıtları

SRV biçiminde adrese tek bir ana makine adı yazarsınız; sürücü veya mongosh, bu ada karşılık gelen DNS SRV kaydını sorgulayarak hangi sunucuların çalıştığını öğrenir. Böylece sunucuları değiştirdiğinizde istemcilerin yapılandırmasına dokunmanız gerekmez. Genel kalıp mongodb+srv://[kullanıcı:parola@]sunucu[/[defaultauthdb][?seçenekler]] şeklindedir.

• Ana makine adı <hostname>.<domain>.<TLD> biçiminde olmalıdır, örneğin mongo.ornek.com.
• SRV biçiminde yalnızca bir sunucu yazılır ve port verilmez. Aksi halde istemci ayrıştırma hatası verir ve DNS çözümlemesi yapmaz.
• Her SRV kaydı _mongodb._tcp.<hostname>.<domain>.<TLD> biçiminde olmalıdır.
• SRV kayıtlarının döndürdüğü sunucu adları, verilen ana makine adıyla aynı üst alan adını paylaşmalıdır; paylaşmıyorsa bağlantı kurulamaz.
• +srv öneki tls (veya eşdeğeri ssl) seçeneğini otomatik olarak true yapar. Kapatmak için adrese açıkça tls=false yazmanız gerekir.
• Ada karşılık gelen DNS kaydı bulunamazsa mongodb+srv bağlantısı başarısız olur.

Kendi DNS bölgenizde tanımlayacağınız kayıtlar kabaca şöyle görünür (değerler örnektir):

Record                          TTL   Class Priority Weight Port  Target
_mongodb._tcp.mongo.ornek.com.  86400 IN    SRV 0    5      27017 db1.ornek.com.
_mongodb._tcp.mongo.ornek.com.  86400 IN    SRV 0    5      27017 db2.ornek.com.

Record                          TTL   Class Text
mongo.ornek.com.                86400 IN    TXT "replicaSet=rs0&authSource=admin"

SRV adresiyle birlikte bir TXT kaydı da tanımlayabilirsiniz; bu kayıtta yalnızca replicaSet ve authSource seçenekleri bulunabilir. Her mongod için yalnızca bir TXT kaydı olabilir; birden fazla TXT kaydı varsa veya kayıtta bu ikisi dışında bir seçenek geçiyorsa istemci hata döndürür. Adresin sorgu kısmına yazdığınız bir seçenek, TXT kaydındaki aynı seçeneği geçersiz kılar. Yukarıdaki kayıtlarla mongodb+srv://uygulama:Gizli%40Parola1@mongo.ornek.com/ adresi, standart biçimde şuna karşılık gelir:

mongodb://uygulama:Gizli%40Parola1@db1.ornek.com:27017,db2.ornek.com:27017/?replicaSet=rs0&authSource=admin

Belgeler, mümkün olduğunda SRV biçimini önerir; çünkü sunucu listesi değiştiğinde istemcileri yeniden yapılandırmanız gerekmez. Kendi sunucunuzda bu biçimi kullanmak için DNS kayıtlarını yönetebilmeniz ve TLS'i yapılandırmış olmanız gerekir; TLS kurulmamış bir sunucuya SRV ile bağlanmak için tls=false yazmak zorunda kalırsınız.

Seçenekler nasıl yazılır?

Seçenekler ad=değer çiftleridir ve & ile ayrılır. Sürücülerde ve mongosh'ta seçenek adı büyük-küçük harfe duyarsızdır, değer ise her zaman duyarlıdır. Geriye dönük uyumluluk için sürücüler noktalı virgülü de ayırıcı olarak kabul eder. mongosh 2.0.0'dan itibaren boolean değerler yalnızca true veya false olabilir; 1, yes, 0 veya no kabul edilmez. Bir seçeneği hem adreste hem bir yöntemin parametresinde verirseniz (örneğin write concern), yöntem parametresi geçerli olur.

En çok kullanılan seçenekler

Bu tablodaki değerler belgelerdeki genel varsayılanlardır; bazı seçenekleri her sürücü desteklemez veya farklı varsayılan kullanabilir. Örneğin wtimeoutMS deprecated durumdadır ve yerine timeoutMS önerilir; timeoutMS adreste verildiğinde sürücü diğer zaman aşımı seçeneklerini yok sayar. maxStalenessSeconds için en küçük değer 90 saniyedir; 0 ile 90 arasındaki değerler hata üretir.

Zaman aşımı, havuz ve sunucu seçimi ayarlarını anlamak

Zaman aşımı seçenekleri farklı aşamaları ölçer ve karıştırıldığında yanlış ayar yapılır. connectTimeoutMS yalnızca bağlantı kurma denemesini, socketTimeoutMS kurulmuş bir soket üzerindeki tek bir gönderme veya alma işlemini, serverSelectionTimeoutMS ise istemcinin işlemi gönderebileceği uygun bir sunucu bulmak için ne kadar bekleyeceğini belirler. timeoutMS bunlardan farklı olarak işlemin tüm adımlarını, yani sunucu seçimini, havuzdan bağlantı almayı ve sunucu tarafındaki çalışmayı birlikte kapsar. Bu değer daha özel bir düzeyde geçersiz kılınabilir ama bir kez verildikten sonra kaldırılamaz; ayrıca henüz tüm resmî sürücüler tarafından desteklenmez.

Havuz tarafında maxPoolSize (varsayılan 100) aynı anda açık tutulabilecek en fazla bağlantıyı, maxConnecting (varsayılan 2) havuzun eş zamanlı kurabileceği bağlantı sayısını, maxIdleTimeMS boşta bekleyen bir bağlantının kapatılmadan önce ne kadar tutulacağını, waitQueueTimeoutMS ise boş bağlantı bekleyen bir iş parçacığının en fazla ne kadar bekleyeceğini belirler. Sunucu seçiminde localThresholdMS (varsayılan 15 ms) birden fazla uygun sunucu arasında seçim yapılan gecikme penceresidir; heartbeatFrequencyMS ise sürücünün kurulumun durumunu ne sıklıkla kontrol ettiğidir (tek iş parçacıklı sürücülerde 60, çok iş parçacıklılarda 10 saniye).

Ağ sıkıştırması için compressors seçeneğine virgülle ayrılmış bir liste verilir (snappy, zlib, zstd). Sıkıştırma ancak iki taraf da sıkıştırmayı açmış ve ortak bir sıkıştırıcı paylaşıyorsa uygulanır; listedeki sıra ve iletişimi kimin başlattığı önemlidir. Belgelerdeki örneğe göre istemci zlib,snappy, mongod ise snappy,zlib belirtmişse iletişimde zlib kullanılır.

mongosh ile ilgili sınırlar

• readConcernLevel seçeneği mongosh'ta kullanılamaz; read concern'ü işlem düzeyinde verin.
• mongosh retryable reads (retryReads) desteklemez.
• mongosh ağ sıkıştırmasında yalnızca zlib sıkıştırıcısını destekler; zstd ve snappy desteklenmez.
• mongosh'ta ek TLS seçenekleri komut satırından veriliyorsa adresteki tls yerine --tls seçeneğini kullanın.

Uygulamalar için örnek bağlantı adresleri

Aşağıdaki adres, bir replica set'e çoğunluk onaylı yazma (w=majority) isteyen, bağlantı zaman aşımını 5 saniyeye düşüren ve uygulama adını günlüklerde görünür kılan bir yapılandırma örneğidir:

mongodb://siparis_api:Gizli%40Parola1@db1.ornek.com:27017,db2.ornek.com:27017,db3.ornek.com:27017/siparis?replicaSet=rs0&authSource=admin&w=majority&connectTimeoutMS=5000&appName=siparis-api

appName değeri mongod ve mongos günlüklerinde, currentOp çıktısının appName alanında ve profiler çıktısında görünür; birden fazla uygulamanın aynı sunucuya bağlandığı durumlarda yavaş sorgunun kaynağını bulmayı kolaylaştırır (yavaş sorgu ve profiler). Write concern ve read preference değerlerinin anlamı write concern ve read concern yazısında anlatılıyor.

Bağlı olduğunuz mongosh oturumunun adresini öğrenmek için db.getMongo() kullanabilirsiniz; yöntem geçerli bağlantının connection string'ini döndürür.

db.getMongo()

Sık yapılan hatalar

• Parolayı kodlamadan yazmak: @ veya : içeren parola adresi bozar; yüzde kodlama kullanın.
• authSource'u unutmak: Kullanıcı admin'de tanımlıysa ama adreste başka bir veritabanı varsa kimlik doğrulama başarısız olur.
• Seçeneklerden önce bölü işaretini atlamak: Veritabanı yoksa host:port/?seçenek biçimini kullanın.
• SRV adresine port yazmak: SRV biçiminde tek sunucu ve portsuz yazım zorunludur.
• Replica set'e tek adresle ve replicaSet olmadan bağlanmak: mongosh directConnection=true ekler ve yalnızca o sunucuyla konuşur.
• Değerin büyük-küçük harfini değiştirmek: Seçenek adları duyarsızdır ama değerler duyarlıdır.

Sık Sorulan Sorular

mongodb:// ile mongodb+srv:// arasında hangisini seçmeliyim?

Belgeler mümkün olduğunda SRV biçimini önerir. Ancak SRV, DNS kayıtları ve varsayılan olarak TLS gerektirir. Tek bir VPS'te çalışan bir sunucu için standart biçim genellikle daha basittir.

Docker'daki replica set'e neden bağlanamıyorum?

Docker içindeki replica set dışarıya yalnızca tek bir uç nokta açıyorsa küme keşfedilemez ve directConnection=false bağlantıyı engelleyebilir. Test ortamında directConnection=true ile bağlanabilirsiniz; üretimde her MongoDB sunucusunu Docker sanal ağının dışından erişilebilir yapmanız önerilir.

Sunucu seçimi zaman aşımına uğruyorsa ne yapmalıyım?

İstemci serverSelectionTimeoutMS süresi (varsayılan 30 saniye) içinde uygun bir sunucu bulamamıştır. Adres, port, bindIp, güvenlik duvarı ve replica set adını kontrol edin. Tanı adımları bağlantı hataları yazısında.

Bağlantı adresini mongosh'a nasıl veririm?

Adresi tırnak içinde ilk argüman olarak verin: mongosh "mongodb://...". Kabuğun diğer seçenekleri mongosh kullanımı yazısında.

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 · mongosh kullanımı · Authentication etkinleştirme · Replica set kurulumu · Bağlantı hataları