-
Notifications
You must be signed in to change notification settings - Fork 135
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #1943 from reebhub/PHP_opsBatch4
[PHP] Operations batch 4 [Replace C# samples]
- Loading branch information
Showing
19 changed files
with
1,483 additions
and
1 deletion.
There are no files selected for viewing
164 changes: 164 additions & 0 deletions
164
....Pages/client-api/configuration/load-balance/load-balance-behavior.php.markdown
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,164 @@ | ||
| # Load balance behavior | ||
|
|
||
| --- | ||
|
|
||
| {NOTE: } | ||
|
|
||
| * The `loadBalanceBehavior` configuration allows you to specify which sessions should | ||
| communicate with the same node. | ||
|
|
||
| * Sessions that are assigned the **same context** will have all their _Read_ & _Write_ | ||
| requests routed to the **same node**. Gain load balancing by assigning **different contexts** | ||
| to **different sessions**. | ||
|
|
||
| --- | ||
|
|
||
| * In this page: | ||
| * [LoadBalanceBehavior options](../../../client-api/configuration/load-balance/load-balance-behavior#loadbalancebehavior-options) | ||
| * [Initialize LoadBalanceBehavior on the client](../../../client-api/configuration/load-balance/load-balance-behavior#initialize-loadbalancebehavior-on-the-client) | ||
| * [Set LoadBalanceBehavior on the server:](../../../client-api/configuration/load-balance/load-balance-behavior#set-loadbalancebehavior-on-the-server) | ||
| * [By operation](../../../client-api/configuration/load-balance/load-balance-behavior#set-loadbalancebehavior-on-the-server---by-operation) | ||
| * [From Studio](../../../client-api/configuration/load-balance/load-balance-behavior#set-loadbalancebehavior-on-the-server---from-studio) | ||
| * [When to use](../../../client-api/configuration/load-balance/load-balance-behavior#when-to-use) | ||
|
|
||
| {NOTE/} | ||
|
|
||
| --- | ||
|
|
||
| {PANEL: LoadBalanceBehavior options } | ||
|
|
||
| ### `None` (default option) | ||
|
|
||
| * Requests will be handled based on the `ReadBalanceBehavior` configuration. | ||
| See the conditional flow described in [Client logic for choosing a node](../../../client-api/configuration/load-balance/overview#client-logic-for-choosing-a-node). | ||
| * **_Read_** requests: | ||
| The client will calculate the target node from the configured [ReadBalanceBehavior Option](../../../client-api/configuration/load-balance/read-balance-behavior#readbalancebehavior-options). | ||
| * **_Write_** requests: | ||
| Will be sent to the [preferred node](../../../client-api/configuration/load-balance/overview#the-preferred-node). | ||
| The data will then be replicated to all the other nodes in the database group. | ||
|
|
||
| --- | ||
|
|
||
| ### `UseSessionContext` | ||
|
|
||
| * **Load-balance** | ||
|
|
||
| * When this option is enabled, the client will calculate the target node from the session-id. | ||
| The session-id is hashed from a **context string** and an optional **seed** given by the user. | ||
| The context string together with the seed are referred to as **"The session context"**. | ||
|
|
||
| * Per session, the client will select a node from the topology list based on this session-context. | ||
| So sessions that use the **same** context will target the **same** node. | ||
|
|
||
| * All **_Read & Write_** requests made on the session (i.e a query or a load request, etc.) | ||
| will address this calculated node. | ||
| _Read & Write_ requests that are made on the store (i.e. executing an [operation](../../../client-api/operations/what-are-operations)) | ||
| will go to the preferred node. | ||
|
|
||
| * All _Write_ requests will be replicated to all the other nodes in the database group as usual. | ||
|
|
||
| * **Failover** | ||
|
|
||
| * In case of a failure, the client will try to access the next node from the topology nodes list. | ||
|
|
||
| {PANEL/} | ||
|
|
||
| {PANEL: Initialize LoadBalanceBehavior on the client } | ||
|
|
||
| * The `LoadBalanceBehavior` convention can be set **on the client** when initializing the Document Store. | ||
| This will set the load balance behavior for the default database that is set on the store. | ||
|
|
||
| * This setting can be **overriden** by setting 'LoadBalanceBehavior' on the server, see [below](../../../client-api/configuration/load-balance/load-balance-behavior#set-loadbalancebehavior-on-the-server). | ||
|
|
||
| --- | ||
|
|
||
| **Initialize conventions**: | ||
|
|
||
| {CODE:php LoadBalance_1@ClientApi\Configuration\LoadBalance\LoadBalance.php /} | ||
| {CODE:php LoadBalance_6@ClientApi\Configuration\LoadBalance\LoadBalance.php /} | ||
|
|
||
| --- | ||
|
|
||
| **Session usage**: | ||
|
|
||
| {CODE:php LoadBalance_2@ClientApi\Configuration\LoadBalance\LoadBalance.php /} | ||
| {CODE:php LoadBalance_3@ClientApi\Configuration\LoadBalance\LoadBalance.php /} | ||
|
|
||
| {PANEL/} | ||
|
|
||
| {PANEL: Set LoadBalanceBehavior on the server } | ||
|
|
||
| {NOTE: } | ||
|
|
||
| **Note**: | ||
|
|
||
| * Setting the load balance behavior on the server, either by an **Operation** or from the **Studio**, | ||
| only 'enables the feature' and sets the seed. | ||
|
|
||
| * For the feature to be in effect, you still need to define the context string itself: | ||
| * either, per session, call the advanced `setContext` method | ||
| * or, set a default document store value using `setLoadBalancerPerSessionContextSelector` | ||
|
|
||
| {NOTE/} | ||
|
|
||
| --- | ||
|
|
||
| #### Set LoadBalanceBehavior on the server - by operation: | ||
|
|
||
| * The `LoadBalanceBehavior` configuration can be set **on the server** by sending an [operation](../../../client-api/operations/what-are-operations). | ||
|
|
||
| * The operation can modify the default database only, or all databases - see examples below. | ||
|
|
||
| * Once configuration on the server has changed, the running client will get updated with the new settings. | ||
| See [keeping client up-to-date](../../../client-api/configuration/load-balance/overview#keeping-the-client-topology-up-to-date). | ||
|
|
||
| {CODE-TABS} | ||
| {CODE-TAB:php:Operation_For_Default_Database LoadBalance_4@ClientApi\Configuration\LoadBalance\LoadBalance.php /} | ||
| {CODE-TAB:php:Operation_For_All_Databases LoadBalance_5@ClientApi\Configuration\LoadBalance\LoadBalance.php /} | ||
| {CODE-TABS/} | ||
|
|
||
| --- | ||
|
|
||
| #### Set LoadBalanceBehavior on the server - from Studio: | ||
|
|
||
| * The `LoadBalanceBehavior` configuration can be set from the Studio's [Client Configuration view](../../../studio/database/settings/client-configuration-per-database). | ||
| Setting it from the Studio will set this configuration directly **on the server**. | ||
|
|
||
| * Once configuration on the server has changed, the running client will get updated with the new settings. | ||
| See [keeping client up-to-date](../../../client-api/configuration/load-balance/overview#keeping-the-client-topology-up-to-date). | ||
|
|
||
| {PANEL/} | ||
|
|
||
| {PANEL: When to use } | ||
|
|
||
| * Distributing _Read & Write_ requests among the cluster nodes can be beneficial | ||
| when a set of sessions handle a specific set of documents or similar data. | ||
| Load balancing can be achieved by routing requests from the sessions that handle similar topics to the same node, while routing other sessions to other nodes. | ||
|
|
||
| * Another usage example can be setting the session's context to be the current user. | ||
| Thus spreading the _Read & Write_ requests per user that logs into the application. | ||
|
|
||
| * Once setting the load balance to be per session-context, | ||
| in the case when detecting that many or all sessions send requests to the same node, | ||
| a further level of node randomization can be added by changing the seed. | ||
|
|
||
| {PANEL/} | ||
|
|
||
| ## Related Articles | ||
|
|
||
| ### Operations | ||
|
|
||
| - [What are operations](../../../client-api/operations/what-are-operations) | ||
|
|
||
| ### Configuration | ||
|
|
||
| - [Load balancing client requests - overview](../../../client-api/configuration/load-balance/overview) | ||
| - [Read balance behavior](../../../client-api/configuration/load-balance/read-balance-behavior) | ||
| - [Conventions](../../../client-api/configuration/conventions) | ||
| - [Querying](../../../client-api/configuration/querying) | ||
|
|
||
| ### Client Configuration in Studio | ||
|
|
||
| - [Requests Configuration in Studio](../../../studio/server/client-configuration) | ||
| - [Requests Configuration per Database](../../../studio/database/settings/client-configuration-per-database) | ||
| - [Database-group-topology](../../../studio/database/settings/manage-database-group#database-group-topology---view) |
129 changes: 129 additions & 0 deletions
129
....Pages/client-api/configuration/load-balance/read-balance-behavior.php.markdown
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,129 @@ | ||
| # Read balance behavior | ||
|
|
||
| --- | ||
|
|
||
| {NOTE: } | ||
|
|
||
| * When set, the `ReadBalanceBehavior` configuration will be in effect according to the | ||
| conditional flow described in [Client logic for choosing a node](../../../client-api/configuration/load-balance/overview#client-logic-for-choosing-a-node). | ||
|
|
||
| * Once configuration is in effect then: | ||
| * **_Read_** requests - will be sent to the node determined by the configured option - see below. | ||
| * **_Write_** requests - are always sent to the preferred node. | ||
| The data will then be replicated to all the other nodes in the database group. | ||
| * Upon a node failure, the node to failover to is also determined by the defined option. | ||
|
|
||
| * In this page: | ||
| * [ReadBalanceBehavior options](../../../client-api/configuration/load-balance/read-balance-behavior#readbalancebehavior-options) | ||
| * [Initialize ReadBalanceBehavior on the client](../../../client-api/configuration/load-balance/read-balance-behavior#initialize-readbalancebehavior-on-the-client) | ||
| * [Set ReadBalanceBehavior on the server:](../../../client-api/configuration/load-balance/read-balance-behavior#set-readbalancebehavior-on-the-server) | ||
| * [By operation](../../../client-api/configuration/load-balance/read-balance-behavior#set-readbalancebehavior-on-the-server---by-operation) | ||
| * [From Studio](../../../client-api/configuration/load-balance/read-balance-behavior#set-readbalancebehavior-on-the-server---from-studio) | ||
| * [When to use](../../../client-api/configuration/load-balance/read-balance-behavior#when-to-use) | ||
|
|
||
| {NOTE/} | ||
|
|
||
| --- | ||
|
|
||
| {PANEL: readBalanceBehavior options } | ||
|
|
||
| ### `None` (default option) | ||
|
|
||
| * **Read-balance** | ||
| No read balancing will occur. | ||
| The client will always send _Read_ requests to the [preferred node](../../../client-api/configuration/load-balance/overview#the-preferred-node). | ||
| * **Failover** | ||
| The client will failover nodes in the order they appear in the [topology nodes list](../../../studio/database/settings/manage-database-group#database-group-topology---actions). | ||
|
|
||
| --- | ||
|
|
||
| ### `RoundRobin` | ||
|
|
||
| * **Read-balance** | ||
| * Each session opened is assigned an incremental session-id number. | ||
| **Per session**, the client will select the next node from the topology list based on this internal session-id. | ||
| * All _Read_ requests made on the session (i.e a query or a load request, etc.) | ||
| will address the calculated node. | ||
| * A _Read_ request that is made on the store (i.e. executing an [operation](../../../client-api/operations/what-are-operations)) | ||
| will go to the preferred node. | ||
| * **Failover** | ||
| In case of a failure, the client will try the next node from the topology nodes list. | ||
|
|
||
| --- | ||
|
|
||
| ### `FastestNode` | ||
|
|
||
| * **Read-balance** | ||
| All _Read_ requests will go to the fastest node. | ||
| The fastest node is determined by a [Speed Test](../../../client-api/cluster/speed-test). | ||
| * **Failover** | ||
| In case of a failure, a speed test will be triggered again, | ||
| and in the meantime the client will use the preferred node. | ||
|
|
||
| {PANEL/} | ||
|
|
||
| {PANEL: Initialize ReadBalanceBehavior on the client } | ||
|
|
||
| * The `ReadBalanceBehavior` convention can be set **on the client** when initializing the Document Store. | ||
| This will set the read balance behavior for the default database that is set on the store. | ||
|
|
||
| * This setting can be **overriden** by setting 'ReadBalanceBehavior' on the server, see [below](../../../client-api/configuration/load-balance/read-balance-behavior#set-readbalancebehavior-on-the-server). | ||
|
|
||
| {CODE:php ReadBalance_1@ClientApi\Configuration\LoadBalance\ReadBalance.php /} | ||
|
|
||
| {PANEL/} | ||
|
|
||
| {PANEL: Set ReadBalanceBehavior on the server } | ||
|
|
||
| #### Set ReadBalanceBehavior on the server - by operation: | ||
|
|
||
| * The `ReadBalanceBehavior` configuration can be set **on the server** by sending an [operation](../../../client-api/operations/what-are-operations). | ||
|
|
||
| * The operation can modify the default database only, or all databases - see examples below. | ||
|
|
||
| * Once configuration on the server has changed, the running client will get updated with the new settings. | ||
| See [keeping client up-to-date](../../../client-api/configuration/load-balance/overview#keeping-the-client-topology-up-to-date). | ||
|
|
||
| {CODE-TABS} | ||
| {CODE-TAB:php:Operation_For_Default_Database ReadBalance_2@ClientApi\Configuration\LoadBalance\ReadBalance.php /} | ||
| {CODE-TAB:php:Operation_For_All_Databases ReadBalance_3@ClientApi\Configuration\LoadBalance\ReadBalance.php /} | ||
| {CODE-TABS/} | ||
|
|
||
| #### Set ReadBalanceBehavior on the server - from Studio: | ||
|
|
||
| * The `ReadBalanceBehavior` configuration can be set from the Studio's [Client Configuration view](../../../studio/database/settings/client-configuration-per-database). | ||
| Setting it from the Studio will set this configuration directly **on the server**. | ||
|
|
||
| * Once configuration on the server has changed, the running client will get updated with the new settings. | ||
| See [keeping client up-to-date](../../../client-api/configuration/load-balance/overview#keeping-the-client-topology-up-to-date). | ||
|
|
||
| {PANEL/} | ||
|
|
||
| {PANEL: When to use } | ||
|
|
||
| * Setting the read balance behavior is beneficial when you only care about distributing the _Read_ requests among the cluster nodes, | ||
| and when all _Write_ requests can go to the same node. | ||
|
|
||
| * Using the 'FastestNode' option is beneficial when some nodes in the system are known to be faster than others, | ||
| thus letting the fastest node serve each read request. | ||
|
|
||
| {PANEL/} | ||
|
|
||
| ## Related Articles | ||
|
|
||
| ### Operations | ||
|
|
||
| - [What are operations](../../../client-api/operations/what-are-operations) | ||
|
|
||
| ### Configuration | ||
|
|
||
| - [Load balancing client requests - overview](../../../client-api/configuration/load-balance/overview) | ||
| - [Load balance behavior](../../../client-api/configuration/load-balance/load-balance-behavior) | ||
| - [Conventions](../../../client-api/configuration/conventions) | ||
| - [Querying](../../../client-api/configuration/querying) | ||
|
|
||
| ### Client Configuration in Studio | ||
|
|
||
| - [Requests Configuration in Studio](../../../studio/server/client-configuration) | ||
| - [Requests Configuration per Database](../../../studio/database/settings/client-configuration-per-database) | ||
| - [Database-group-topology](../../../studio/database/settings/manage-database-group#database-group-topology---view) |
67 changes: 67 additions & 0 deletions
67
...nt-api/operations/how-to/switch-operations-to-a-different-database.php.markdown
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,67 @@ | ||
| # Switch Operations to a Different Database | ||
|
|
||
| --- | ||
|
|
||
| {NOTE: } | ||
|
|
||
| * By default, all operations work on the default database defined in the [Document Store](../../../client-api/creating-document-store). | ||
|
|
||
| * **To operate on a different database**, use the `for_database` method. | ||
| If the requested database doesn't exist on the server, an exception will be thrown. | ||
|
|
||
| * In this page: | ||
| * [Common operation: `forDatabase`](../../../client-api/operations/how-to/switch-operations-to-a-different-database#common-operation:-fordatabase) | ||
| * [Maintenance operation: `maintenance.for_database`](../../../client-api/operations/how-to/switch-operations-to-a-different-database#maintenance-operation:-maintenance.for_database) | ||
| {NOTE/} | ||
|
|
||
| --- | ||
|
|
||
| {PANEL: Common operation: `forDatabase`} | ||
|
|
||
| * For reference, all common operations are listed [here](../../../client-api/operations/what-are-operations#common-operations). | ||
|
|
||
| {CODE:php for_database_1@ClientApi\Operations\HowTo\SwitchOperationsToDifferentDatabase.php /} | ||
|
|
||
| --- | ||
|
|
||
| **Syntax**: | ||
|
|
||
| {CODE:php syntax_1@ClientApi\Operations\HowTo\SwitchOperationsToDifferentDatabase.php /} | ||
|
|
||
| | Parameters | Type | Description | | ||
| | - | - | - | | ||
| | **$databaseName** | `?string` | Name of the database to operate on | | ||
|
|
||
| | Return Value | Description | | ||
| | - | - | | ||
| | `OperationExecutor` | New instance of Operation Executor that is scoped to the requested database | | ||
|
|
||
| {PANEL/} | ||
|
|
||
| {PANEL: Maintenance operation: `maintenance.for_database`} | ||
|
|
||
| * For reference, all maintenance operations are listed [here](../../../client-api/operations/what-are-operations#maintenance-operations). | ||
|
|
||
| {CODE:php for_database_2@ClientApi\Operations\HowTo\SwitchOperationsToDifferentDatabase.php /} | ||
|
|
||
| --- | ||
|
|
||
| **Syntax**: | ||
|
|
||
| {CODE:php syntax_2@ClientApi\Operations\HowTo\SwitchOperationsToDifferentDatabase.php /} | ||
|
|
||
| | Parameters | Type | Description | | ||
| | - | - | - | | ||
| | **$databaseName** | `?string` | Name of the database to operate on | | ||
|
|
||
| | Return Value | Description | | ||
| | - | - | | ||
| | `MaintenanceOperationExecutor` | New instance of Maintenance Operation Executor that is scoped to the requested database | | ||
|
|
||
| {PANEL/} | ||
|
|
||
| ## Related Articles | ||
|
|
||
| ### Operations | ||
|
|
||
| - [What are Operations](../../../client-api/operations/what-are-operations) |
Oops, something went wrong.