{
    "content": [
        {
            "type": "text",
            "text": "# MongoDB::MongoClient (perldoc)\n\n## NAME\n\nMongoDB::MongoClient - A connection to a MongoDB server or multi-server deployment\n\n## SYNOPSIS\n\nuse MongoDB; # also loads MongoDB::MongoClient\n# connect to localhost:27017\nmy $client = MongoDB::MongoClient->new;\n# connect to specific host and port\nmy $client = MongoDB::MongoClient->new(\nhost => \"mongodb://mongo.example.com:27017\"\n);\n# connect to a replica set (set name *required*)\nmy $client = MongoDB::MongoClient->new(\nhost => \"mongodb://mongo1.example.com,mongo2.example.com\",\nreplicasetname => 'myset',\n);\n# connect to a replica set with URI (set name *required*)\nmy $client = MongoDB::MongoClient->new(\nhost => \"mongodb://mongo1.example.com,mongo2.example.com/?replicaSet=myset\",\n);\nmy $db = $client->getdatabase(\"test\");\nmy $coll = $db->getcollection(\"people\");\n$coll->insert({ name => \"John Doe\", age => 42 });\nmy @people = $coll->find()->all();\n\n## DESCRIPTION\n\nThe \"MongoDB::MongoClient\" class represents a client connection to one or more MongoDB servers.\n\n## Sections\n\n- **NAME**\n- **VERSION**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **ATTRIBUTES**\n- **METHODS**\n- **DEPLOYMENT TOPOLOGY**\n- **CONNECTION STRING URI**\n- **SERVER SELECTION**\n- **SERVER MONITORING AND FAILOVER**\n- **TRANSPORT LAYER SECURITY**\n- **AUTHENTICATION**\n- **THREAD-SAFETY AND FORK-SAFETY**\n- **AUTHORS**\n- **COPYRIGHT AND LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "MongoDB::MongoClient",
        "section": "",
        "mode": "perldoc",
        "summary": "MongoDB::MongoClient - A connection to a MongoDB server or multi-server deployment",
        "synopsis": "use MongoDB; # also loads MongoDB::MongoClient\n# connect to localhost:27017\nmy $client = MongoDB::MongoClient->new;\n# connect to specific host and port\nmy $client = MongoDB::MongoClient->new(\nhost => \"mongodb://mongo.example.com:27017\"\n);\n# connect to a replica set (set name *required*)\nmy $client = MongoDB::MongoClient->new(\nhost => \"mongodb://mongo1.example.com,mongo2.example.com\",\nreplicasetname => 'myset',\n);\n# connect to a replica set with URI (set name *required*)\nmy $client = MongoDB::MongoClient->new(\nhost => \"mongodb://mongo1.example.com,mongo2.example.com/?replicaSet=myset\",\n);\nmy $db = $client->getdatabase(\"test\");\nmy $coll = $db->getcollection(\"people\");\n$coll->insert({ name => \"John Doe\", age => 42 });\nmy @people = $coll->find()->all();",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "VERSION",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 27,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 25,
                "subsections": []
            },
            {
                "name": "ATTRIBUTES",
                "lines": 410,
                "subsections": []
            },
            {
                "name": "METHODS",
                "lines": 193,
                "subsections": []
            },
            {
                "name": "DEPLOYMENT TOPOLOGY",
                "lines": 23,
                "subsections": []
            },
            {
                "name": "CONNECTION STRING URI",
                "lines": 114,
                "subsections": []
            },
            {
                "name": "SERVER SELECTION",
                "lines": 34,
                "subsections": []
            },
            {
                "name": "SERVER MONITORING AND FAILOVER",
                "lines": 22,
                "subsections": []
            },
            {
                "name": "TRANSPORT LAYER SECURITY",
                "lines": 14,
                "subsections": []
            },
            {
                "name": "AUTHENTICATION",
                "lines": 134,
                "subsections": []
            },
            {
                "name": "THREAD-SAFETY AND FORK-SAFETY",
                "lines": 6,
                "subsections": []
            },
            {
                "name": "AUTHORS",
                "lines": 10,
                "subsections": []
            },
            {
                "name": "COPYRIGHT AND LICENSE",
                "lines": 6,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "MongoDB::MongoClient - A connection to a MongoDB server or multi-server deployment\n",
                "subsections": []
            },
            "VERSION": {
                "content": "version v2.2.2\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "use MongoDB; # also loads MongoDB::MongoClient\n\n# connect to localhost:27017\nmy $client = MongoDB::MongoClient->new;\n\n# connect to specific host and port\nmy $client = MongoDB::MongoClient->new(\nhost => \"mongodb://mongo.example.com:27017\"\n);\n\n# connect to a replica set (set name *required*)\nmy $client = MongoDB::MongoClient->new(\nhost => \"mongodb://mongo1.example.com,mongo2.example.com\",\nreplicasetname => 'myset',\n);\n\n# connect to a replica set with URI (set name *required*)\nmy $client = MongoDB::MongoClient->new(\nhost => \"mongodb://mongo1.example.com,mongo2.example.com/?replicaSet=myset\",\n);\n\nmy $db = $client->getdatabase(\"test\");\nmy $coll = $db->getcollection(\"people\");\n\n$coll->insert({ name => \"John Doe\", age => 42 });\nmy @people = $coll->find()->all();\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "The \"MongoDB::MongoClient\" class represents a client connection to one or more MongoDB servers.\n\nBy default, it connects to a single server running on the local machine listening on the default\nport 27017:\n\n# connects to localhost:27017\nmy $client = MongoDB::MongoClient->new;\n\nIt can connect to a database server running anywhere, though:\n\nmy $client = MongoDB::MongoClient->new(host => 'example.com:12345');\n\nSee the \"host\" attribute for more options for connecting to MongoDB.\n\nMongoDB can be started in authentication mode\n<http://docs.mongodb.org/manual/core/authentication/>, which requires clients to log in before\nmanipulating data. By default, MongoDB does not start in this mode, so no username or password\nis required to make a fully functional connection. To configure the client for authentication,\nsee the \"AUTHENTICATION\" section.\n\nThe actual socket connections are lazy and created on demand. When the client object goes out of\nscope, all socket will be closed. Note that MongoDB::Database, MongoDB::Collection and related\nclasses could hold a reference to the client as well. Only when all references are out of scope\nwill the sockets be closed.\n",
                "subsections": []
            },
            "ATTRIBUTES": {
                "content": "host\nThe \"host\" attribute specifies either a single server to connect to (as \"hostname\" or\n\"hostname:port\"), or else a connection string URI with a seed list of one or more servers plus\nconnection options.\n\nNOTE: Options specified in the connection string take precedence over options provided as\nconstructor arguments.\n\nDefaults to the connection string URI \"mongodb://localhost:27017\".\n\nFor IPv6 support, you must have a recent version of IO::Socket::IP installed. This module ships\nwith the Perl core since v5.20.0 and is available on CPAN for older Perls.\n\nappname\nThis attribute specifies an application name that should be associated with this client. The\napplication name will be communicated to the server as part of the initial connection handshake,\nand will appear in connection-level and operation-level diagnostics on the server generated on\nbehalf of this client. This may be set in a connection string with the \"appName\" option.\n\nThe default is the empty string, which indicates a lack of an application name.\n\nThe application name must not exceed 128 bytes.\n\nauthmechanism\nThis attribute determines how the client authenticates with the server. Valid values are:\n\n*   NONE\n\n*   DEFAULT\n\n*   MONGODB-CR\n\n*   MONGODB-X509\n\n*   GSSAPI\n\n*   PLAIN\n\n*   SCRAM-SHA-1\n\nIf not specified, then if no username or \"authSource\" URI option is provided, it defaults to\nNONE. Otherwise, it is set to DEFAULT, which chooses SCRAM-SHA-1 if available or MONGODB-CR\notherwise.\n\nThis may be set in a connection string with the \"authMechanism\" option.\n\nauthmechanismproperties\nThis is an optional hash reference of authentication mechanism specific properties. See\n\"AUTHENTICATION\" for details.\n\nThis may be set in a connection string with the \"authMechanismProperties\" option. If given, the\nvalue must be key/value pairs joined with a \":\". Multiple pairs must be separated by a comma. If\n\": or \",\" appear in a key or value, they must be URL encoded.\n\nbsoncodec\nAn object that provides the \"encodeone\" and \"decodeone\" methods, such as from BSON. It may be\ninitialized with a hash reference that will be coerced into a new BSON object.\n\nIf not provided, a BSON object with default values will be generated.\n\ncompressors\nAn array reference of compression type names. Currently, \"zlib\", \"zstd\" and \"snappy\" are\nsupported.\n\nzlibcompressionlevel\nAn integer from -1 to 9 specifying the compression level to use when \"compression\" is set to\n\"zlib\".\n\nNote: When the special value -1 is given, the default compression level will be used.\n\nconnecttimeoutms\nThis attribute specifies the amount of time in milliseconds to wait for a new connection to a\nserver.\n\nThe default is 10,000 ms.\n\nIf set to a negative value, connection operations will block indefinitely until the server\nreplies or until the operating system TCP/IP stack gives up (e.g. if the name can't resolve or\nthere is no process listening on the target host/port).\n\nA zero value polls the socket during connection and is thus likely to fail except when talking\nto a local process (and perhaps even then).\n\nThis may be set in a connection string with the \"connectTimeoutMS\" option.\n\ndbname\nOptional. If an \"authmechanism\" requires a database for authentication, this attribute will be\nused. Otherwise, it will be ignored. Defaults to \"admin\".\n\nThis may be provided in the connection string URI as a path between the authority and option\nparameter sections. For example, to authenticate against the \"admin\" database (showing a\nconfiguration option only for illustration):\n\nmongodb://localhost/admin?readPreference=primary\n\nheartbeatfrequencyms\nThe time in milliseconds (non-negative) between scans of all servers to check if they are up and\nupdate their latency. Defaults to 60,000 ms.\n\nThis may be set in a connection string with the \"heartbeatFrequencyMS\" option.\n\nj\nIf true, the client will block until write operations have been committed to the server's\njournal. Prior to MongoDB 2.6, this option was ignored if the server was running without\njournaling. Starting with MongoDB 2.6, write operations will fail if this option is used when\nthe server is running without journaling.\n\nThis may be set in a connection string with the \"journal\" option as the strings 'true' or\n'false'.\n\nlocalthresholdms\nThe width of the 'latency window': when choosing between multiple suitable servers for an\noperation, the acceptable delta in milliseconds (non-negative) between shortest and longest\naverage round-trip times. Servers within the latency window are selected randomly.\n\nSet this to \"0\" to always select the server with the shortest average round trip time. Set this\nto a very high value to always randomly choose any known server.\n\nDefaults to 15 ms.\n\nSee \"SERVER SELECTION\" for more details.\n\nThis may be set in a connection string with the \"localThresholdMS\" option.\n\nmaxstalenessseconds\nThe \"maxstalenessseconds\" parameter represents the maximum replication lag in seconds (wall\nclock time) that a secondary can suffer and still be eligible for reads. The default is -1,\nwhich disables staleness checks. Otherwise, it must be a positive integer.\n\nNote: this will only be used for server versions 3.4 or greater, as that was when support for\nstaleness tracking was added.\n\nIf the read preference mode is 'primary', then \"maxstalenessseconds\" must not be supplied.\n\nThe \"maxstalenessseconds\" must be at least the \"heartbeatfrequencyms\" plus 10 seconds (which\nis how often the server makes idle writes to the oplog).\n\nThis may be set in a connection string with the \"maxStalenessSeconds\" option.\n\nmaxtimems\nSpecifies the maximum amount of time in (non-negative) milliseconds that the server should use\nfor working on a database command. Defaults to 0, which disables this feature. Make sure this\nvalue is shorter than \"sockettimeoutms\".\n\nNote: this will only be used for server versions 2.6 or greater, as that was when the $maxTimeMS\nmeta-operator was introduced.\n\nYou are strongly encouraged to set this variable if you know your environment has MongoDB 2.6 or\nlater, as getting a definitive error response from the server is vastly preferred over a getting\na network socket timeout.\n\nThis may be set in a connection string with the \"maxTimeMS\" option.\n\nmonitoringcallback\nSpecifies a code reference used to receive monitoring events. See MongoDB::Monitoring for more\ndetails.\n\npassword\nIf an \"authmechanism\" requires a password, this attribute will be used. Otherwise, it will be\nignored.\n\nThis may be provided in the connection string URI as a \"username:password\" pair in the leading\nportion of the authority section before a \"@\" character. For example, to authenticate as user\n\"mulder\" with password \"trustno1\":\n\nmongodb://mulder:trustno1@localhost\n\nIf the username or password have a \":\" or \"@\" in it, they must be URL encoded. An empty password\nstill requires a \":\" character.\n\nport\nIf a network port is not specified as part of the \"host\" attribute, this attribute provides the\nport to use. It defaults to 27107.\n\nreadconcernlevel\nThe read concern level determines the consistency level required of data being read.\n\nThe default level is \"undef\", which means the server will use its configured default.\n\nIf the level is set to \"local\", reads will return the latest data a server has locally.\n\nAdditional levels are storage engine specific. See Read Concern\n<http://docs.mongodb.org/manual/search/?query=readConcern> in the MongoDB documentation for more\ndetails.\n\nThis may be set in a connection string with the the \"readConcernLevel\" option.\n\nreadprefmode\nThe read preference mode determines which server types are candidates for a read operation.\nValid values are:\n\n*   primary\n\n*   primaryPreferred\n\n*   secondary\n\n*   secondaryPreferred\n\n*   nearest\n\nFor core documentation on read preference see\n<http://docs.mongodb.org/manual/core/read-preference/>.\n\nThis may be set in a connection string with the \"readPreference\" option.\n\nreadpreftagsets\nThe \"readpreftagsets\" parameter is an ordered list of tag sets used to restrict the\neligibility of servers, such as for data center awareness. It must be an array reference of hash\nreferences.\n\nThe application of \"readpreftagsets\" varies depending on the \"readprefmode\" parameter. If\nthe \"readprefmode\" is 'primary', then \"readpreftagsets\" must not be supplied.\n\nFor core documentation on read preference see\n<http://docs.mongodb.org/manual/core/read-preference/>.\n\nThis may be set in a connection string with the \"readPreferenceTags\" option. If given, the value\nmust be key/value pairs joined with a \":\". Multiple pairs must be separated by a comma. If \": or\n\",\" appear in a key or value, they must be URL encoded. The \"readPreferenceTags\" option may\nappear more than once, in which case each document will be added to the tag set list.\n\nreplicasetname\nSpecifies the replica set name to connect to. If this string is non-empty, then the topology is\ntreated as a replica set and all server replica set names must match this or they will be\nremoved from the topology.\n\nThis may be set in a connection string with the \"replicaSet\" option.\n\nretryreads\nretrywrites\nWhether the client should use retryable writes for supported commands. The default value is\ntrue, which means that commands which support retryable writes will be retried on certain\nerrors, such as \"not master\" and \"node is recovering\" errors.\n\nThis may be set in a connection string with the \"retryWrites\" option.\n\nNote that this is only supported on MongoDB > 3.6 in Replica Set or Shard Clusters, and will be\nignored on other deployments.\n\nUnacknowledged write operations also do not support retryable writes, even when retrywrites has\nbeen enabled.\n\nThe supported single statement write operations are currently as follows:\n\n*   \"insertone\"\n\n*   \"updateone\"\n\n*   \"replaceone\"\n\n*   \"deleteone\"\n\n*   \"findoneanddelete\"\n\n*   \"findoneandreplace\"\n\n*   \"findoneandupdate\"\n\nThe supported multi statement write operations are as follows:\n\n*   \"insertmany\"\n\n*   \"bulkwrite\"\n\nThe multi statement operations may be ether ordered or unordered. Note that for \"bulkwrite\"\noperations, the request may not include updatemany or deletemany operations.\n\nserverselectiontimeoutms\nThis attribute specifies the amount of time in milliseconds to wait for a suitable server to be\navailable for a read or write operation. If no server is available within this time period, an\nexception will be thrown.\n\nThe default is 30,000 ms.\n\nSee \"SERVER SELECTION\" for more details.\n\nThis may be set in a connection string with the \"serverSelectionTimeoutMS\" option.\n\nserverselectiontryonce\nThis attribute controls whether the client will make only a single attempt to find a suitable\nserver for a read or write operation. The default is true.\n\nWhen true, the client will not use the \"serverselectiontimeoutms\". Instead, if the topology\ninformation is stale and needs to be checked or if no suitable server is available, the client\nwill make a single scan of all known servers to try to find a suitable one.\n\nWhen false, the client will continually scan known servers until a suitable server is found or\nthe \"serverSelectionTimeoutMS\" is reached.\n\nSee \"SERVER SELECTION\" for more details.\n\nThis may be set in a connection string with the \"serverSelectionTryOnce\" option.\n\nserverselector\nOptional. This takes a function that augments the server selection rules. The function takes as\na parameter a list of server descriptions representing the suitable servers for the read or\nwrite operation, and returns a list of server descriptions that should still be considered\nsuitable. Most users should rely on the default server selection algorithm and should not need\nto set this attribute.\n\nsocketcheckintervalms\nIf a socket to a server has not been used in this many milliseconds, an \"ismaster\" command will\nbe issued to check the status of the server before issuing any reads or writes. Must be\nnon-negative.\n\nThe default is 5,000 ms.\n\nThis may be set in a connection string with the \"socketCheckIntervalMS\" option.\n\nsockettimeoutms\nThis attribute specifies the amount of time in milliseconds to wait for a reply from the server\nbefore issuing a network exception.\n\nThe default is 30,000 ms.\n\nIf set to a negative value, socket operations will block indefinitely until the server replies\nor until the operating system TCP/IP stack gives up.\n\nThe driver automatically sets the TCP keepalive option when initializing the socket. For\nkeepalive related issues, check the MongoDB documentation for Does TCP keepalive time affect\nMongoDB Deployments?\n<https://docs.mongodb.com/v3.2/faq/diagnostics/#does-tcp-keepalive-time-affect-mongodb-deploymen\nts>.\n\nA zero value polls the socket for available data and is thus likely to fail except when talking\nto a local process (and perhaps even then).\n\nThis may be set in a connection string with the \"socketTimeoutMS\" option.\n\nssl\nssl => 1\nssl => \\%ssloptions\n\nThis tells the driver that you are connecting to an SSL mongodb instance.\n\nYou must have IO::Socket::SSL 1.42+ and Net::SSLeay 1.49+ installed for SSL support.\n\nThe \"ssl\" attribute takes either a boolean value or a hash reference of options to pass to\nIO::Socket::SSL. For example, to set a CA file to validate the server certificate and set a\nclient certificate for the server to validate, you could set the attribute like this:\n\nssl => {\nSSLcafile   => \"/path/to/ca.pem\",\nSSLcertfile => \"/path/to/client.pem\",\n}\n\nIf \"SSLcafile\" is not provided, server certificates are verified against a default list of\nCAs, either Mozilla::CA or an operating-system-specific default CA file. To disable\nverification, you can use \"SSLverifymode => 0x00\".\n\nYou are strongly encouraged to use your own CA file for increased security.\n\nServer hostnames are also validated against the CN name in the server certificate using\n\"SSLverifycnscheme => 'http'\". You can use the scheme 'none' to disable this check.\n\nDisabling certificate or hostname verification is a security risk and is not recommended.\n\nThis may be set to the string 'true' or 'false' in a connection string with the \"ssl\" option,\nwhich will enable ssl with default configuration. (See connection string URI for additional TLS\nconfiguration options.)\n\nusername\nOptional username for this client connection. If this field is set, the client will attempt to\nauthenticate when connecting to servers. Depending on the \"authmechanism\", the \"password\" field\nor other attributes will need to be set for authentication to succeed.\n\nThis may be provided in the connection string URI as a \"username:password\" pair in the leading\nportion of the authority section before a \"@\" character. For example, to authenticate as user\n\"mulder\" with password \"trustno1\":\n\nmongodb://mulder:trustno1@localhost\n\nIf the username or password have a \":\" or \"@\" in it, they must be URL encoded. An empty password\nstill requires a \":\" character.\n\nw\nThe client *write concern*.\n\n*   0 Unacknowledged. MongoClient will NOT wait for an acknowledgment that the server has\nreceived and processed the request. Older documentation may refer to this as\n\"fire-and-forget\" mode. This option is not recommended.\n\n*   1 Acknowledged. MongoClient will wait until the primary MongoDB acknowledges the write.\n\n*   2 Replica acknowledged. MongoClient will wait until at least two replicas (primary and one\nsecondary) acknowledge the write. You can set a higher number for more replicas.\n\n*   \"all\" All replicas acknowledged.\n\n*   \"majority\" A majority of replicas acknowledged.\n\nIf not set, the server default is used, which is typically \"1\".\n\nIn MongoDB v2.0+, you can \"tag\" replica members. With \"tagging\" you can specify a custom write\nconcern For more information see Data Center Awareness\n<http://docs.mongodb.org/manual/data-center-awareness/>\n\nThis may be set in a connection string with the \"w\" option.\n\nwtimeout\nThe number of milliseconds an operation should wait for \"w\" secondaries to replicate it.\n\nDefaults to 1000 (1 second). If you set this to undef, it could block indefinitely (or until\nsocket timeout is reached).\n\nSee \"w\" above for more information.\n\nThis may be set in a connection string with the \"wTimeoutMS\" option.\n",
                "subsections": []
            },
            "METHODS": {
                "content": "readpreference\nReturns a MongoDB::ReadPreference object constructed from \"readprefmode\" and\n\"readpreftagsets\"\n\nThe use of \"readpreference\" as a mutator has been removed. Read preference is read-only. If you\nneed a different read preference for a database or collection, you can specify that in\n\"getdatabase\" or \"getcollection\".\n\nwriteconcern\nReturns a MongoDB::WriteConcern object constructed from \"w\", \"writeconcern\" and \"j\".\n\nreadconcern\nReturns a MongoDB::ReadConcern object constructed from \"readconcernlevel\".\n\ntopologytype\nReturns an enumerated topology type. If the \"replicasetname\" is set, the value will be either\n'ReplicaSetWithPrimary' or 'ReplicaSetNoPrimary' (if the primary is down or not yet discovered).\nWithout \"replicasetname\", if there is more than one server in the list of hosts, the type will\nbe 'Sharded'.\n\nWith only a single host and no replica set name, the topology type will start as 'Direct' until\nthe server is contacted the first time, after which the type will be 'Sharded' for a mongos or\n'Single' for standalone server or direct connection to a replica set member.\n\nconnect\n$client->connect;\n\nCalling this method is unnecessary, as connections are established automatically as needed. It\nis kept for backwards compatibility. Calling it will check all servers in the deployment which\nensures a connection to any that are available.\n\nSee \"reconnect\" for a method that is useful when using forks or threads.\n\ndisconnect\n$client->disconnect;\n\nDrops all connections to servers.\n\nreconnect\n$client->reconnect;\n\nThis method closes all connections to the server, as if \"disconnect\" were called, and then\nimmediately reconnects. It also clears the session cache. Use this after forking or spawning off\na new thread.\n\ntopologystatus\n$client->topologystatus;\n$client->topologystatus( refresh => 1 );\n\nReturns a hash reference with server topology information like this:\n\n{\n'topologytype' => 'ReplicaSetWithPrimary'\n'replicasetname' => 'foo',\n'lastscantime'   => '1433766895.183241',\n'servers'          => [\n{\n'address'     => 'localhost:50003',\n'ewmarttms' => '0.223462326',\n'type'        => 'RSSecondary'\n},\n{\n'address'     => 'localhost:50437',\n'ewmarttms' => '0.268435456',\n'type'        => 'RSArbiter'\n},\n{\n'address'     => 'localhost:50829',\n'ewmarttms' => '0.737782272',\n'type'        => 'RSPrimary'\n}\n},\n}\n\nIf the 'refresh' argument is true, then the topology will be scanned to update server data\nbefore returning the hash reference.\n\nstartsession\n$client->startsession;\n$client->startsession( $options );\n\nReturns a new MongoDB::ClientSession with the supplied options.\n\nwill throw a \"MongoDB::ConfigurationError\" if sessions are not supported by the connected\nMongoDB deployment.\n\nthe options hash is an optional hash which can have the following keys:\n\n*   \"causalConsistency\" - Enable Causally Consistent reads for this session. Defaults to true.\n\nfor more information see \"options\" in MongoDB::ClientSession.\n\nlistdatabases\n# get all information on all databases\nmy @dbs = $client->listdatabases;\n\n# get only the foo databases\nmy @foodbs = $client->listdatabases({ filter => { name => qr/^foo/ } });\n\nLists all databases with information on each database. Supports filtering by any of the output\nfields under the \"filter\" argument, such as:\n\n*   \"name\"\n\n*   \"sizeOnDisk\"\n\n*   \"empty\"\n\n*   \"shards\"\n\ndatabasenames\nmy @dbs = $client->databasenames;\n\n# get only the foo database names\nmy @foodbs = $client->databasenames({ filter => { name => qr/^foo/ } });\n\nList of all database names on the MongoDB server. Supports filters in the same way as\n\"listdatabases\".\n\ngetdatabase, db\nmy $database = $client->getdatabase('foo');\nmy $database = $client->getdatabase('foo', $options);\nmy $database = $client->db('foo', $options);\n\nReturns a MongoDB::Database instance for the database with the given $name.\n\nIt takes an optional hash reference of options that are passed to the MongoDB::Database\nconstructor.\n\nThe \"db\" method is an alias for \"getdatabase\".\n\ngetnamespace, ns\nmy $collection = $client->getnamespace('test.foo');\nmy $collection = $client->getnamespace('test.foo', $options);\nmy $collection = $client->ns('test.foo', $options);\n\nReturns a MongoDB::Collection instance for the given namespace. The namespace has both the\ndatabase name and the collection name separated with a dot character.\n\nThis is a quick way to get a collection object if you don't need the database object separately.\n\nIt takes an optional hash reference of options that are passed to the MongoDB::Collection\nconstructor. The intermediate MongoDB::Database object will be created with default options.\n\nThe \"ns\" method is an alias for \"getnamespace\".\n\nfsync(\\%args)\n$client->fsync();\n\nA function that will forces the server to flush all pending writes to the storage layer.\n\nThe fsync operation is synchronous by default, to run fsync asynchronously, use the following\nform:\n\n$client->fsync({async => 1});\n\nThe primary use of fsync is to lock the database during backup operations. This will flush all\ndata to the data storage layer and block all write operations until you unlock the database.\nNote: you can still read while the database is locked.\n\n$conn->fsync({lock => 1});\n\nfsyncunlock\n$conn->fsyncunlock();\n\nUnlocks a database server to allow writes and reverses the operation of a $conn->fsync({lock =>\n1}); operation.\n\nwatch\nWatches for changes on the cluster.\n\nPerform an aggregation with an implicit initial $changeStream stage and returns a\nMongoDB::ChangeStream result which can be used to iterate over the changes in the cluster. This\nfunctionality is available since MongoDB 4.0.\n\nmy $stream = $client->watch();\nmy $stream = $client->watch( \\@pipeline );\nmy $stream = $client->watch( \\@pipeline, \\%options );\n\nwhile (1) {\n\n# This inner loop will only run until no more changes are\n# available.\nwhile (my $change = $stream->next) {\n# process $change\n}\n}\n\nThe returned stream will not block forever waiting for changes. If you want to respond to\nchanges over a longer time use \"maxAwaitTimeMS\" and regularly call \"next\" in a loop.\n\nSee \"watch\" in MongoDB::Collection for details on usage and available options.\n",
                "subsections": []
            },
            "DEPLOYMENT TOPOLOGY": {
                "content": "MongoDB can operate as a single server or as a distributed system. One or more servers that\ncollectively provide access to a single logical set of MongoDB databases are referred to as a\n\"deployment\".\n\nThere are three types of deployments:\n\n*   Single server – a stand-alone mongod database\n\n*   Replica set – a set of mongod databases with data replication and fail-over capability\n\n*   Sharded cluster – a distributed deployment that spreads data across one or more shards, each\nof which can be a replica set. Clients communicate with a mongos process that routes\noperations to the correct share.\n\nThe state of a deployment, including its type, which servers are members, the server types of\nmembers and the round-trip network latency to members is referred to as the \"topology\" of the\ndeployment.\n\nTo the greatest extent possible, the MongoDB driver abstracts away the details of communicating\nwith different deployment types. It determines the deployment topology through a combination of\nthe connection string, configuration options and direct discovery communicating with servers in\nthe deployment.\n",
                "subsections": []
            },
            "CONNECTION STRING URI": {
                "content": "MongoDB uses a pseudo-URI connection string to specify one or more servers to connect to, along\nwith configuration options.\n\nNOTE: any non-printable ASCII characters should be UTF-8 encoded and converted URL-escaped\ncharacters.\n\nTo connect to more than one database server, provide host or host:port pairs as a comma\nseparated list:\n\nmongodb://host1[:port1][,host2[:port2],...[,hostN[:portN]]]\n\nThis list is referred to as the \"seed list\". An arbitrary number of hosts can be specified. If a\nport is not specified for a given host, it will default to 27017.\n\nIf multiple hosts are given in the seed list or discovered by talking to servers in the seed\nlist, they must all be replica set members or must all be mongos servers for a sharded cluster.\n\nA replica set MUST have the \"replicaSet\" option set to the replica set name.\n\nIf there is only single host in the seed list and \"replicaSet\" is not provided, the deployment\nis treated as a single server deployment and all reads and writes will be sent to that host.\n\nProviding a replica set member as a single host without the set name is the way to get a \"direct\nconnection\" for carrying out administrative activities on that server.\n\nThe connection string may also have a username and password:\n\nmongodb://username:password@host1:port1,host2:port2\n\nThe username and password must be URL-escaped.\n\nA optional database name for authentication may be given:\n\nmongodb://username:password@host1:port1,host2:port2/mydatabase\n\nFinally, connection string options may be given as URI attribute pairs in a query string:\n\nmongodb://host1:port1,host2:port2/?ssl=1&wtimeoutMS=1000\nmongodb://username:password@host1:port1,host2:port2/mydatabase?ssl=1&wtimeoutMS=1000\n\nThe currently supported connection string options are:\n\n*   \"appName\"\n\n*   \"authMechanism\"\n\n*   \"authMechanismProperties\"\n\n*   \"authSource\"\n\n*   \"compressors\"\n\n*   \"connect\"\n\n*   \"connectTimeoutMS\"\n\n*   \"heartbeatFrequencyMS\"\n\n*   \"journal\"\n\n*   \"localThresholdMS\"\n\n*   \"maxStalenessSeconds\"\n\n*   \"maxTimeMS\"\n\n*   \"readConcernLevel\"\n\n*   \"readPreference\"\n\n*   \"readPreferenceTags\"\n\n*   \"replicaSet\"\n\n*   \"retryReads\"\n\n*   \"retryWrites\"\n\n*   \"serverSelectionTimeoutMS\"\n\n*   \"serverSelectionTryOnce\"\n\n*   \"socketCheckIntervalMS\"\n\n*   \"socketTimeoutMS\"\n\n*   \"ssl\"\n\n*   \"tls\" (an alias for \"ssl\")\n\n*   \"tlsAllowInvalidCertificates\"\n\n*   \"tlsAllowInvalidHostnames\"\n\n*   \"tlsCAFile\"\n\n*   \"tlsCertificateKeyFile\"\n\n*   \"tlsCertificateKeyFilePassword\"\n\n*   \"tlsInsecure\"\n\n*   \"w\"\n\n*   \"wTimeoutMS\"\n\n*   \"zlibCompressionLevel\"\n\nNOTE: Options specified in the connection string take precedence over options provided as\nconstructor arguments.\n\nSee the official MongoDB documentation on connection strings for more on the URI format and\nconnection string options: <http://docs.mongodb.org/manual/reference/connection-string/>.\n",
                "subsections": []
            },
            "SERVER SELECTION": {
                "content": "For a single server deployment or a direct connection to a mongod or mongos, all reads and\nwrites are sent to that server. Any read-preference is ignored.\n\nWhen connected to a deployment with multiple servers, such as a replica set or sharded cluster,\nthe driver chooses a server for operations based on the type of operation (read or write),\napplication-provided server selector, the types of servers available and a read preference.\n\nFor a replica set deployment, writes are sent to the primary (if available) and reads are sent\nto a server based on the \"readpreference\" attribute, which defaults to sending reads to the\nprimary. See MongoDB::ReadPreference for more.\n\nFor a sharded cluster reads and writes are distributed across mongos servers in the seed list.\nAny read preference is passed through to the mongos and used by it when executing reads against\nshards.\n\nIf multiple servers can service an operation (e.g. multiple mongos servers, or multiple replica\nset members), one is chosen by filtering with server selector and then at random from within the\n\"latency window\". The server with the shortest average round-trip time (RTT) is always in the\nwindow. Any servers with an average round-trip time less than or equal to the shortest RTT plus\nthe \"localthresholdms\" are also in the latency window.\n\nIf a suitable server is not immediately available, what happens next depends on the\n\"serverselectiontryonce\" option.\n\nIf that option is true, a single topology scan will be performed. Afterwards if a suitable\nserver is available, it will be returned; otherwise, an exception is thrown.\n\nIf that option is false, the driver will do topology scans repeatedly looking for a suitable\nserver. When more than \"serverselectiontimeoutms\" milliseconds have elapsed since the start\nof server selection without a suitable server being found, an exception is thrown.\n\nNote: the actual maximum wait time for server selection could be as long\n\"serverselectiontimeoutms\" plus the amount of time required to do a topology scan.\n",
                "subsections": []
            },
            "SERVER MONITORING AND FAILOVER": {
                "content": "When the client first needs to find a server for a database operation, all servers from the\n\"host\" attribute are scanned to determine which servers to monitor. If the deployment is a\nreplica set, additional hosts may be discovered in this process. Invalid hosts are dropped.\n\nAfter the initial scan, whenever the servers have not been checked in \"heartbeatfrequencyms\"\nmilliseconds, the scan will be repeated. This amortizes monitoring time over many of operations.\nAdditionally, if a socket has been idle for a while, it will be checked before being used for an\noperation.\n\nIf a server operation fails because of a \"not master\" or \"node is recovering\" error, or if there\nis a network error or timeout, then the server is flagged as unavailable and exception will be\nthrown. See MongoDB::Errors for exception types.\n\nIf the error is caught and handled, the next operation will rescan all servers immediately to\nupdate its view of the topology. The driver can continue to function as long as servers are\nsuitable per \"SERVER SELECTION\".\n\nWhen catching an exception, users must determine whether or not their application should retry\nan operation based on the specific operation attempted and other use-case-specific\nconsiderations. For automating retries despite exceptions, consider using the Try::Tiny::Retry\nmodule.\n",
                "subsections": []
            },
            "TRANSPORT LAYER SECURITY": {
                "content": "Warning: industry best practices, and some regulations, require the use of TLS 1.1 or newer.\n\nSome operating systems or versions may not provide an OpenSSL version new enough to support the\nlatest TLS protocols. If your OpenSSL library version number is less than 1.0.1, then support\nfor TLS 1.1 or newer is not available. Contact your operating system vendor for a solution or\nupgrade to a newer operating system distribution.\n\nSee also the documentation for Net::SSLeay for details on installing and compiling against\nOpenSSL.\n\nTLS connections in the driver rely on the default settings provided by IO::Socket::SSL, but\nallow you to pass custom configuration to it. Please read its documentation carefully to see how\nto control your TLS configuration.\n",
                "subsections": []
            },
            "AUTHENTICATION": {
                "content": "The MongoDB server provides several authentication mechanisms, though some are only available in\nthe Enterprise edition.\n\nMongoDB client authentication is controlled via the \"authmechanism\" attribute, which takes one\nof the following values:\n\nNOTE: MONGODB-CR was deprecated with the release of MongoDB 3.6 and is no longer supported by\nMongoDB 4.0.\n\n*   MONGODB-CR -- legacy username-password challenge-response (< 4.0)\n\n*   SCRAM-SHA-1 -- secure username-password challenge-response (3.0+)\n\n*   MONGODB-X509 -- SSL client certificate authentication (2.6+)\n\n*   PLAIN -- LDAP authentication via SASL PLAIN (Enterprise only)\n\n*   GSSAPI -- Kerberos authentication (Enterprise only)\n\nThe mechanism to use depends on the authentication configuration of the server. See the core\ndocumentation on authentication: <http://docs.mongodb.org/manual/core/access-control/>.\n\nUsage information for each mechanism is given below.\n\nMONGODB-CR and SCRAM-SHA-1 (for username/password)\nThese mechanisms require a username and password, given either as constructor attributes or in\nthe \"host\" connection string.\n\nIf a username is provided and an authentication mechanism is not specified, the client will use\nSCRAM-SHA-1 for version 3.0 or later servers and will fall back to MONGODB-CR for older servers.\n\nmy $mc = MongoDB::MongoClient->new(\nhost => \"mongodb://mongo.example.com/\",\nusername => \"johndoe\",\npassword => \"trustno1\",\n);\n\nmy $mc = MongoDB::MongoClient->new(\nhost => \"mongodb://johndoe:trustno1@mongo.example.com/\",\n);\n\nUsernames and passwords will be UTF-8 encoded before use. The password is never sent over the\nwire -- only a secure digest is used. The SCRAM-SHA-1 mechanism is the Salted Challenge Response\nAuthentication Mechanism defined in RFC 5802 <http://tools.ietf.org/html/rfc5802>.\n\nThe default database for authentication is 'admin'. If another database name should be used,\nspecify it with the \"dbname\" attribute or via the connection string.\n\ndbname => authdb\n\nmongodb://johndoe:trustno1@mongo.example.com/authdb\n\nMONGODB-X509 (for SSL client certificate)\nX509 authentication requires SSL support (IO::Socket::SSL), requires that a client certificate\nbe configured in the ssl parameters, and requires specifying the \"MONGODB-X509\" authentication\nmechanism.\n\nmy $mc = MongoDB::MongoClient->new(\nhost => \"mongodb://sslmongo.example.com/\",\nssl => {\nSSLcafile   => \"certs/ca.pem\",\nSSLcertfile => \"certs/client.pem\",\n},\nauthmechanism => \"MONGODB-X509\",\n);\n\nNote: Since MongoDB Perl driver v1.8.0, you no longer need to specify a \"username\" parameter for\nX509 authentication; the username will be extracted automatically from the certificate.\n\nPLAIN (for LDAP)\nThis mechanism requires a username and password, which will be UTF-8 encoded before use. The\n\"authmechanism\" parameter must be given as a constructor attribute or in the \"host\" connection\nstring:\n\nmy $mc = MongoDB::MongoClient->new(\nhost => \"mongodb://mongo.example.com/\",\nusername => \"johndoe\",\npassword => \"trustno1\",\nauthmechanism => \"PLAIN\",\n);\n\nmy $mc = MongoDB::MongoClient->new(\nhost => \"mongodb://johndoe:trustno1@mongo.example.com/authMechanism=PLAIN\",\n);\n\nGSSAPI (for Kerberos)\nKerberos authentication requires the CPAN module Authen::SASL and a GSSAPI-capable backend.\n\nOn Debian systems, Authen::SASL may be available as \"libauthen-sasl-perl\"; on RHEL systems, it\nmay be available as \"perl-Authen-SASL\".\n\nThe Authen::SASL::Perl backend comes with Authen::SASL and requires the GSSAPI CPAN module for\nGSSAPI support. On Debian systems, this may be available as \"libgssapi-perl\"; on RHEL systems,\nit may be available as \"perl-GSSAPI\".\n\nInstalling the GSSAPI module from CPAN rather than an OS package requires \"libkrb5\" and the\n\"krb5-config\" utility (available for Debian/RHEL systems in the \"libkrb5-dev\" package).\n\nAlternatively, the Authen::SASL::XS or Authen::SASL::Cyrus modules may be used. Both rely on\nCyrus \"libsasl\". Authen::SASL::XS is preferred, but not yet available as an OS package.\nAuthen::SASL::Cyrus is available on Debian as \"libauthen-sasl-cyrus-perl\" and on RHEL as\n\"perl-Authen-SASL-Cyrus\".\n\nInstalling Authen::SASL::XS or Authen::SASL::Cyrus from CPAN requires \"libsasl\". On Debian\nsystems, it is available from \"libsasl2-dev\"; on RHEL, it is available in \"cyrus-sasl-devel\".\n\nTo use the GSSAPI mechanism, first run \"kinit\" to authenticate with the ticket granting service:\n\n$ kinit johndoe@EXAMPLE.COM\n\nConfigure MongoDB::MongoClient with the principal name as the \"username\" parameter and specify\n'GSSAPI' as the \"authmechanism\":\n\nmy $mc = MongoDB::MongoClient->new(\nhost => 'mongodb://mongo.example.com',\nusername => 'johndoe@EXAMPLE.COM',\nauthmechanism => 'GSSAPI',\n);\n\nBoth can be specified in the \"host\" connection string, keeping in mind that the '@' in the\nprincipal name must be encoded as \"%40\":\n\nmy $mc = MongoDB::MongoClient->new(\nhost =>\n'mongodb://johndoe%40EXAMPLE.COM@mongo.example.com/?authMechanism=GSSAPI',\n);\n\nThe default service name is 'mongodb'. It can be changed with the \"authmechanismproperties\"\nattribute or in the connection string.\n\nauthmechanismproperties => { SERVICENAME => 'otherservice' }\n\nmongodb://.../?authMechanism=GSSAPI&authMechanismProperties=SERVICENAME:otherservice\n",
                "subsections": []
            },
            "THREAD-SAFETY AND FORK-SAFETY": {
                "content": "You MUST call the \"reconnect\" method on any MongoDB::MongoClient objects after forking or\nspawning a thread.\n\nNOTE: Per threads documentation, use of Perl threads is discouraged by the maintainers of Perl\nand the MongoDB Perl driver does not test or provide support for use with threads.\n",
                "subsections": []
            },
            "AUTHORS": {
                "content": "*   David Golden <david@mongodb.com>\n\n*   Rassi <rassi@mongodb.com>\n\n*   Mike Friedman <friedo@friedo.com>\n\n*   Kristina Chodorow <k.chodorow@gmail.com>\n\n*   Florian Ragwitz <rafl@debian.org>\n",
                "subsections": []
            },
            "COPYRIGHT AND LICENSE": {
                "content": "This software is Copyright (c) 2020 by MongoDB, Inc.\n\nThis is free software, licensed under:\n\nThe Apache License, Version 2.0, January 2004\n",
                "subsections": []
            }
        }
    }
}