Set or Modify the Distribution Scheme of a Database (dbDistribute)
The dbDistribute
command can add, remove, evict, and replace elements of a database in the distribution map of the database, then distribute or redistribute data among elements. You must always use -apply
to apply changes and redistribute data. You can do this either in the same command or in a separate command.
ttGridAdmin dbDistribute name [-list] [-add all | hostname[.instancename]] [-remove hostname[.instancename] [-replaceWith hostname[.instancename]]] [-evict hostname[.instancename] [-replaceWith hostname[.instancename]]] [-apply|-reset|-resync]
Wait until the elements are loaded on all instances on which you will perform operations before using dbDistribute
. You can use the dbStatus
command to confirm this.
See Define the Distribution Map of the Database in Oracle TimesTen In-Memory Database Scaleout User's Guide for additional information.
Options
The dbDistribute
command has the options:
Option | Description |
---|---|
|
Name of the database for data distribution changes. |
- |
Adds elements to the distribution map, either all currently existing elements in the grid or elements on the specified instances. (If an element was not created because an instance is down, there would be no attempt to add it with Specify one instance per usage, but you can use When the additions are applied, data will be distributed evenly across the grid. Notes:
Also see Notes below for this and other options taking |
|
Use this option in any circumstance where you want to remove, and optionally replace, an element, such as to replace an older host system with a newer one. Also see Notes below. Specify one instance per usage, but you can use It is typical to use If you have a grid with Note: Until you issue Also see Redistributing Data in a Database in Oracle TimesTen In-Memory Database Scaleout User's Guide. |
|
Use this option if all elements of a replica set (one element if Important: Using the Specify one instance per usage, but you can use If you use You can use Notes:
Also see Notes below for additional considerations. For additional information, see Redistributing Data in a Database in Oracle TimesTen In-Memory Database Scaleout User's Guide. |
|
Optionally use this with The |
|
Displays the current and pending distribution map of the database ("Holds Data" and "Will Hold Data", respectively). |
|
Applies the new distribution to the database. You can use this option by itself to apply settings from previous commands, or in the same command line with the settings. |
|
Discards all distribution settings that have not yet been applied. This option cannot be combined with any other option. Note: You cannot use |
|
Attempts to resynchronize metadata in the user database with metadata in the active management instance in case the state of a This option cannot be used with any other See Recovering from a Data Distribution Error in Oracle TimesTen In-Memory Database Scaleout User's Guide for related information. Note: The |
Examples
This example adds all elements in the grid to the distribution map then distributes data among the elements:
% ttGridAdmin dbDistribute database1 -add all -apply Distribution map updated
You can then use the -list
option to show the distribution map of elements in the grid (elements able to hold data):
% ttGridAdmin dbDistribute database11 -list Distribution Map version: 1 RS Host Instance Holds Data Will Hold Data Removed Evicted -- ----------- --------- ---------- -------------- ------- ------- 1 mysys3host griddata1 Y Y N N 1 mysys4host griddata2 Y Y N N 2 mysys5host griddata3 Y Y N N 2 mysys6host griddata4 Y Y N N
Now remove both elements in replica set 1, then look at the -list
output again, which indicates the two elements removed from the grid and therefore unable to hold data:
% ttGridAdmin dbDistribute database1 -remove mysys3host.griddata1 Element mysys3host.griddata1 is removed Distribution map change enqueued % ttGridAdmin dbDistribute database1 -remove mysys4host.griddata2 Element mysys4host.griddata2 is removed Distribution map change enqueued % ttGridAdmin dbDistribute database1 -apply Distribution map updated % ttGridAdmin dbDistribute database1 -list Distribution Map version: 3 RS Host Instance Holds Data Will Hold Data Removed Evicted ---- ----------- --------- ---------- -------------- ------- ------- NULL mysys3host griddata1 N N Y N NULL mysys4host griddata2 N N Y N 1 mysys5host griddata3 Y Y N N 1 mysys6host griddata4 Y Y N N
The following is a new example that evicts two elements (from the same replica set) then looks at the -list
output, which shows the two elements evicted from the grid and therefore unable to hold data.
% ttGridAdmin dbDistribute database1 -evict mysys3host.griddata1 -evict mysys4host.griddata2 -apply Distribution map updated % ttGridAdmin dbDistribute database1 -list Distribution Map version: 2 RS Host Instance Holds Data Will Hold Data Removed Evicted ---- ---------- --------- ---------- -------------- ------- ------- NULL mysys3host griddata1 N N N Y NULL mysys4host griddata2 N N N Y 1 mysys5host griddata3 Y Y N N 1 mysys6host griddata4 Y Y N N
This example shows where the -resync
option successfully completed a data distribution operation:
% ttGridAdmin dbDistribute database1 -apply ...
(Process fails or is interrupted.)
% ttGridAdmin dbDistribute database1 -resync Distributiom map updated
And this example shows where the -resync
option rolled back a data distribution operation:
% ttGridAdmin dbDistribute database1 -apply ...
(Process fails or is interrupted.)
% ttGridAdmin dbDistribute database1 -resync Distributiom map Rolled Back
Notes
-
You can use
-list
and-resync
while distribution is in progress. Other operations will fail if distribution is in progress. -
To specify an element, express its instance as
hostname
[.
instancename
]
. The host name is required. The instance name is required only if there are multiple instances on the host. (See Grid Objects and Object Naming.) -
If you need to confirm which elements are in each replica set, use the
dbStatus
command with the-replicaSet
option. -
Once an element has been removed or evicted from the distribution, the only possibility is to eliminate it with
dbDestroy -instance
. It is advisable to do that as soon as possible to reclaim the disk space that it used. If you want to be able to use the instance again later, you must recreate the element withdbCreate -instance
, then add it to the distribution. -
If
k=2
and one element of a replica set has an irrecoverable failure, use-remove
and -replaceWith
to make the replica set fully operational again. Do not use-evict
when an active replica is available. -
If all elements of any replica set are down, you cannot perform global operations. If you cannot recover any element of the replica set, evicting the elements of the replica set will allow you to perform global operations again, but there will be permanent loss of data.
-
It is valid to use
-add
instead of-replaceWith
to replace the elements of an evicted replica set, but in either case data on the evicted replica set is lost. Also note that -add
results in redistribution of data while-replaceWith
(used with either-evict
or-remove
) does not. See Recovering When the Replica Set Has a Permanently Failed Element in Oracle TimesTen In-Memory Database Scaleout User's Guide for additional information. -
See Recovering from Failure in Oracle TimesTen In-Memory Database Scaleout User's Guide for additional information and considerations regarding failure modes.