Specify How CRUD Operations Run on Replica Sets

Client Configuration

This example shows how to set the read preference, read concern, and write concern of a MongoDB\Client instance by passing an array to the constructor. The code configures the following settings:

• secondary read preference: Read operations retrieve data from secondary replica set members

• local read concern: Read operations return the instance's most recent data without guaranteeing that the data has been written to a majority of the replica set members

• 2 write concern: The primary and one secondary replica set member must acknowledge the write operation

$clientOptions = [
    'readPreference' => 'secondary',
    'readConcernLevel' => 'local',
    'w' => '2',
];
$client = new Client('mongodb://localhost:27017', $clientOptions);

Alternatively, you can specify the read and write settings in the connection URI, which is passed as a parameter to the MongoDB\Client constructor:

$uri = 'mongodb://localhost:27017/?readPreference=secondary&readConcernLevel=local&w=2';
$client = new Client($uri);

Session Configuration

This example shows how to set the read preference, read concern, and write concern of a session by passing an array to the startSession() method. The code configures the following settings:

• PRIMARY_PREFERRED read preference: Read operations retrieve data from the primary replica set member, or secondary members if the primary is unavailable

• LOCAL read concern: Read operations return the instance's most recent data without guaranteeing that the data has been written to a majority of the replica set members

• MAJORITY write concern: The majority of all replica set members must acknowledge the write operation

$sessionOptions = [
    'readPreference' => new ReadPreference(ReadPreference::PRIMARY_PREFERRED),
    'readConcern' => new ReadConcern(ReadConcern::LOCAL),
    'writeConcern' => new WriteConcern(WriteConcern::MAJORITY),
];
$session = $client->startSession($sessionOptions);

Transaction Configuration

This example shows how to set the read preference, read concern, and write concern of a transaction by passing an array to the startTransaction() method. The code configures the following settings:

• PRIMARY read preference: Read operations retrieve data from the primary replica set member

• MAJORITY read concern: Read operations return the instance's most recent data that has been written to a majority of replica set members

• 1 write concern: The primary replica set member must acknowledge the write operation

$transactionOptions = [
    'readPreference' => new ReadPreference(ReadPreference::PRIMARY),
    'readConcern' => new ReadConcern(ReadConcern::MAJORITY),
    'writeConcern' => new WriteConcern(1),
];
$session->startTransaction($transactionOptions);

Database Configuration

This example shows how to set the read preference, read concern, and write concern of a database called test_database by passing an options array to the selectDatabase() method. The code configures the following settings:

• PRIMARY_PREFERRED read preference: Read operations retrieve data from the primary replica set member, or secondary members if the primary is unavailable

• AVAILABLE read concern: Read operations return the instance's most recent data without guaranteeing that the data has been written to a majority of the replica set members

• MAJORITY write concern: The majority of all replica set members must acknowledge the write operation

$db = $client->selectDatabase('test_database', [
    'readPreference' => new ReadPreference(ReadPreference::PRIMARY_PREFERRED),
    'readConcern' => new ReadConcern(ReadConcern::AVAILABLE),
    'writeConcern' => new WriteConcern(WriteConcern::MAJORITY),
]);

Collection Configuration

This example shows how to set the read preference, read concern, and write concern of a collection called test_collection by passing an options array to the selectCollection() method. The code configures the following settings:

• SECONDARY_PREFERRED read preference: Read operations retrieve data from secondary replica set members, or the primary members if no secondaries are available

• AVAILABLE read concern: Read operations return the instance's most recent data without guaranteeing that the data has been written to a majority of the replica set members

• 0 write concern: Requests no acknowledgment of the write operation

$collection = $client->selectCollection('test_database', 'test_collection', [
    'readPreference' => new ReadPreference(ReadPreference::SECONDARY_PREFERRED),
    'readConcern' => new ReadConcern(ReadConcern::AVAILABLE),
    'writeConcern' => new WriteConcern(0),
]);

Tag Sets

The MongoDB Server allows you to apply key-value tags to replica-set members according to any criteria you choose. You can then use those tags to target one or more members for a read operation.

By default, the MongoDB PHP Library ignores tags when choosing a member to read from. To instruct the MongoDB PHP Library to prefer certain tags, pass them as a parameter to your MongoDB\Driver\ReadPreference class constructor. Then, set the MongoDB\Driver\ReadPreference object as the value of the readPreference database option.

Suppose you are connected to a replica set that contains members hosted at multiple data centers across the United States. This code example sets the readPreference option to a tag set that instructs test_database to prefer reads from secondary replica set members in the following order:

1. Members from the New York data center (['dc' => 'ny'])

2. Members from the San Francisco data center (['dc' => 'sf'])

3. Any secondary members ([])

$readPreference = new ReadPreference(
    ReadPreference::RP_SECONDARY,
    [
        ['dc' => 'ny'],
        ['dc' => 'sf'],
        [],
    ],
);
$db = $client->selectDatabase(
    'test_database',
    ['readPreference' => $readPreference],
);

Local Threshold

If multiple replica-set members match the read preference and tag sets you specify, the MongoDB PHP Library reads from the nearest replica-set members, chosen according to their ping time.

By default, the library uses only members whose ping times are within 15 milliseconds of the nearest member for queries. To distribute reads between members with higher latencies, pass an options array to the MongoDB\Client constructor that sets the localThresholdMS option.

The following example specifies a local threshold of 35 milliseconds:

$options = [
    'replicaSet' => 'repl0',
    'readPreference' => new ReadPreference(ReadPreference::RP_SECONDARY_PREFERRED),
    'localThresholdMS' => 35,
];
$client = new Client('mongodb://localhost:27017', [], $options);

In the preceding example, the MongoDB PHP Library distributes reads among matching members within 35 milliseconds of the closest member's ping time.