1. Reference
  2. TimesTen Scaleout Utilities
  3. ttGridAdmin
  4. Database Operations

Database Operations

Use ttGridAdmin commands in this section to perform operations on databases.

Some of these operations are creating, destroying, loading, unloading, opening, closing, importing, and exporting a database; setting the distribution scheme of a database; determining the status of a database; and forcing the termination of connections to the database.

Close a Database (dbClose)

The dbClose command closes the database so that applications can no longer connect to it. 

ttGridAdmin dbClose name 
                    [-nowait | -wait [timeout]]

Options

The dbClose command has the options:

Option Description

name

Name of the database to close.

-nowait | -wait [timeout]

The command initiates a state change that is recorded in the active management instance of the grid.

The -nowait option causes the command to return immediately without waiting for the state change. This is the default behavior.

The -wait option causes the command to wait for the state change to complete, when the database element has been closed on each instance in the grid. You can optionally subject the wait to a limit of timeout seconds. Otherwise, or if timeout is set to 0, there is no limit.

In a large grid, it is not typical or generally advisable to use -wait. If you do, it is advisable to set a timeout. (See Database Management Operations.)

Examples

This example closes a database without waiting for the elements to be closed on all instances, then checks status (after the database was successfully closed):

% ttGridAdmin dbClose database1
Database database1 close started
...
% ttGridAdmin dbStatus database1
Database database1 summary status as of Mon Nov 13 19:27:48 PST 2017
 
created,loaded-complete,closed
Completely created elements: 4 (of 4)
Completely loaded elements: 4 (of 4)
Completely created replica sets: 2 (of 2)
Completely loaded replica sets: 2 (of 2)
 
Open elements: 0 (of 4)

Notes

  • After the command has completed, the database is still loaded but is closed to connections. Only the instance administrator can connect to a closed database.

  • If you run dbClose asynchronously (without waiting), you can use the dbStatus command to see when the database is closed.

  • The command does not close existing database connections. Any previously open connections must be terminated independently.

  • If a database has been closed with dbClose, attempting to close it again typically results in an error. However, if any element is in "close failed" state, you can retry dbClose. Doing so will change any element in "close failed" state to "opened" state, which will result in TimesTen Scaleout trying to close it again.

Create a Database (dbCreate)

The dbCreate command creates a database in the grid according to the specified database definition. 

ttGridAdmin dbCreate name 
                     [-instance hostname[.instancename]]
                     [-nowait | -wait [timeout]]

Options

The dbCreate command has the options:

Option Description

name

Name of the database definition to use in creating the database. This becomes the name of the database.

-instance hostname[.instancename]

If specified, database element(s) will be created only on the specified instance(s), instead of on all instances of the grid. Any element previously created successfully on any of the specified instances must first be destroyed.

This is typically used to recover after a failure in the grid or after database elements were not successfully created on one or more instances in a previous run of dbCreate.

The hostname is required. The instancename is required only if there is more than one instance on the host. (See Grid Objects and Object Naming.)

You can use this option only once, specifying a single instance, in a single command.

-nowait | -wait [timeout]

The command initiates a state change that is recorded in the active management instance of the grid.

The -nowait option causes the command to return immediately without waiting for the state change. This is the default behavior.

The -wait option causes the command to wait for the state change to complete, when the database element has been created on each instance in the grid. You can optionally subject the wait to a limit of timeout seconds. Otherwise, or if timeout is set to 0, there is no limit.

In a large grid, it is not typical or generally advisable to use -wait. If you do, it is advisable to set a timeout. (See Database Management Operations.)

Examples

This example creates a database without waiting for the elements to be created on all instances, then checks the status, first while database creation is still in progress, then after it is complete. 

% ttGridAdmin dbCreate database1
Database database1 creation started
...
% ttGridAdmin dbStatus database1
Database database1 summary status as of Mon Nov 13 18:38:39 PST 2017
 
creating,loading-partial,closed
Completely created elements: 1 (of 4) (3 in progress)
Completely loaded elements: 1 (of 4) (3 in progress)
Completely created replica sets: 0 (of 0)
Completely loaded replica sets: 0 (of 0)
 
Open elements: 0 (of 4)
...
% ttGridAdmin dbStatus database1
Database database1 summary status as of Mon Nov 13 18:39:16 PST 2017
 
created,loaded,closed
Completely created elements: 4 (of 4)
Completely loaded elements: 4 (of 4)
Completely created replica sets: 0 (of 0)
Completely loaded replica sets: 0 (of 0)
 
Open elements: 0 (of 4)

In the following example, element creation on one instance fails. The example tries again to create the element on that instance after the problem is resolved.

% ttGridAdmin dbCreate database1
Database database1 creation started
...
% ttGridAdmin dbStatus database1 -all
Database database1 summary status as of Sat Nov 11 14:23:05 PST 2017
 
created-partial,loaded,closed
Completely created elements: 3 (of 4)(1 failed)
Completely loaded elements: 3 (of 4)
Completely created replica sets: 0 (of 0)
Completely loaded replica sets: 0 (of 0)

Open elements: 0 (of 4)

Database database1 element level status as of Sat Nov 11 14:23:05 PST 2017
 
Host       Instance  Elem Status Date/Time of Event  Message 
---------- --------- ---- ------ ------------------- ------- 
mysys3host griddata1    1 loaded 2017-11-11 14:22:52         
mysys4host griddata2    2 loaded 2017-11-11 14:22:51         
mysys5host griddata3    3 failed 2017-11-11 14:22:52         
mysys6host griddata4    4 loaded 2017-11-11 14:22:53         
 
Database database1 Replica Set status as of Sat Nov 11 14:23:05 PST 2017
 
RS DS Elem Host Instance Status Date/Time of Event Message 
-- -- ---- ---- -------- ------ ------------------ ------- 
 
Database database1 Data Space Group status as of Sat Nov 11 14:23:05 PST 2017
 
DS RS Elem Host Instance Status Date/Time of Event Message 
-- -- ---- ---- -------- ------ ------------------ -------

(Resolve the problem with mysys5host.griddata3.) 

% ttGridAdmin dbCreate database1 -instance mysys5host.griddata3
Database database1 creation started
...
% ttGridAdmin dbStatus database1
Database database1 summary status as of Mon Nov 13 13:44:12 PST 2017
 
created,loaded,closed
Completely created elements: 4 (of 4)
Completely loaded elements: 4 (of 4)
Completely created replica sets: 0 (of 0)
Completely loaded replica sets: 0 (of 0)
 
Open elements: 0 (of 4)

Notes

  • Each instance creates its element of the database, loads the element into memory, and records the state of the element.

  • If you run dbCreate asynchronously (without waiting), you can use the dbStatus command to see when the database is created.

  • The database is marked as "existing" as soon as the dbCreate command returns. If you run the command in the default -nowait mode, you can unload the database while its creation is still in progress.

  • The database is not available for connections from users other than the instance administrator until you define the database distribution map with dbDistribute and open the database with dbOpen.

  • A typical use case for the -instance option is when an element of the database had previously failed, been evicted or removed from the database distribution map, and been destroyed. (Then also use dbDistribute to add the element to the distribution map.)

Destroy a Database (dbDestroy)

The dbDestroy command destroys the specified database. All data and schema contained in the database are irretrievably lost. 

ttGridAdmin dbDestroy name 
                      [-instance hostname[.instancename]]
                      [-nowait | -wait [timeout]]

Options

The dbDestroy command has the options:

Option Description

name

Name of the database to destroy.

-instance hostname[.instancename]

If specified, database element(s) will be destroyed only on the specified instance(s), but elements will remain on all other instances of the grid. The elements to destroy must have been previously evicted or removed from the database distribution map or never added to the distribution map.

The hostname is required. The instancename is required only if there is more than one instance on the host.

You can use this option only once, specifying a single instance, in a single command.

-nowait | -wait [timeout]

The command initiates a state change that is recorded in the active management instance of the grid.

The -nowait option causes the command to return immediately without waiting for the state change. This is the default behavior.

The -wait option causes the command to wait for the state change to complete, when the database element has been destroyed on each instance in the grid. You can optionally subject the wait to a limit of timeout seconds. Otherwise, or if timeout is set to 0, there is no limit.

In a large grid, it is not typical or generally advisable to use -wait. If you do, it is advisable to set a timeout. (See Database Management Operations.)

Examples

This example destroys a database without waiting for the elements to be destroyed on all instances. A subsequent attempt to check status indicates that the database was successfully destroyed.

% ttGridAdmin dbDestroy database1
Database database1 destroy started
...
% ttGridAdmin dbStatus database1
Error 2: Database database1 does not exist

This example destroys two of the four elements in the database. Both elements are from the same replica set and had previously been evicted.

% ttGridAdmin dbDestroy database1 -instance mysys3host.griddata1
Database database1 instance mysys3host.griddata1 destroy started
% ttGridAdmin dbDestroy database1 -instance mysys4host.griddata2 
Database database1 instance mysys4host.griddata2 destroy started
% ttGridAdmin dbStatus database1 -all
Database database1 summary status as of Tue Jan  9 16:04:16 PST 2021
 
created,unloaded,closed
Completely created elements: 2 (of 4)
Completely loaded elements: 0 (of 4)
Completely created replica sets: 1 (of 1)
Completely loaded replica sets: 0 (of 1)
 
Open elements: 0 (of 2)
 
Database database1 element level status as of Tue Jan  9 16:04:16 PST 2021
 
Host       Instance  Elem Status    Date/Time of Event  Message 
---------- --------- ---- --------- ------------------- ------- 
mysys3host griddata1    1 destroyed 2021-01-09 16:04:02         
mysys4host griddata2    2 destroyed 2021-01-09 16:04:01         
mysys5host griddata3    3 unloaded  2021-01-09 16:01:25         
mysys6host griddata4    4 unloaded  2021-01-09 16:01:01         
 
Database database1 Replica Set status as of Tue Jan  9 16:04:16 PST 2021
 
RS DS Elem Host       Instance  Status   Date/Time of Event  Message 
-- -- ---- ---------- --------- -------- ------------------- ------- 
 1  1    3 mysys5host griddata3 unloaded 2021-01-09 16:01:25         
 1  2    4 mysys6host griddata4 unloaded 2021-01-09 16:01:01         
 
Database database1 Data Space Group status as of Tue Jan  9 16:04:16 PST 2021
 
DS RS Elem Host       Instance  Status Date/Time of Event  Message 
-- -- ---- ---------- --------- -------- ------------------- ------- 
 1  1    3 mysys5host griddata3 unloaded 2021-01-09 16:01:25         
 2  1    4 mysys6host griddata4 unloaded 2021-01-09 16:01:01

Notes

  • The database must be unloaded or unloading.

  • If you run dbDestroy asynchronously (without waiting), you can use the dbStatus command to see when the database is removed.

  • A typical use case for the -instance option is after an element of the database failed and was evicted or removed from the database distribution map. Then using dbDestroy with -instance recovers the disk space of the failed element.

Force All Connections to Disconnect (dbDisconnect)

The dbDisconnect command forces all user connections to the specified database to be disconnected. This is useful, for example, prior to maintenance operations. Closing connections is mandatory to ensure a smooth shutdown and no data loss. 

ttGridAdmin dbDisconnect name
                         -transactional|-immediate|-abort
                         [-nowait | -wait [timeout]]

No new transactions are allowed before the command runs.

A disconnection request is sent to each data instance in the grid.

See Unloading a Database From Memory in Oracle TimesTen In-Memory Database Scaleout User's Guide for related information.

Note:

The dbDisconnect command does not affect subdaemon connections.

Options

The dbDisconnect command has the options:

Option Description

name

Name of the database.

-transactional|-immediate|-abort

Specify the mode for the disconnection process. You must specify one of the following modes (there is no default):

  • Transactional: Allow any open transactions to be committed or rolled back before disconnecting.

  • Immediate: Roll back any open transactions before immediately disconnecting.

  • Abort: Abort all direct mode application processes and client/server agents in order to disconnect.

A recommended best practice is to run dbDisconnect twice, as necessary. First run it in transactional mode. Then, after allowing some time, if not all connections have been closed yet, run it in immediate mode. Use dbStatus -connections to confirm whether connections have been closed.

Use abort mode only as a last resort if transactional and immediate levels do not result in all connections being closed. Abort may result in loss of data. Abort abruptly causes every user and ttcserver process connected to the database to exit. This may result in lost transactions.

Note: Execution in immediate mode also disconnects idle connections. Execution in transactional mode does not.

-nowait | -wait [timeout]

Specifies whether the command should return immediately (the default) or wait until all disconnections finish. With -wait, you can optionally limit the wait time to timeout seconds.

Database management commands initiate a state change that is recorded in the active management instance of the grid. More specifically, the -nowait option causes the command to return without waiting for the state change. Use dbDisconnectStatus to check status of the disconnection process.

The -wait option causes the command to wait for the state change to complete, when all disconnections are complete. Without timeout or if timeout is set to 0, there is no limit.

If there is a large number of connections, it may not be advisable to use -wait. If you do, it is advisable to set a timeout. If disconnections have not completed in the specified wait time and you are using transactional mode, consider using immediate mode.

Note: Even when using -wait, it is advisable to use dbStatus -connections afterward to confirm connections are closed.

Examples

This example:

  1. Uses dbStatus to show existing connections.

  2. Closes the database and confirms.

  3. Disconnects in transactional mode (without wait).

  4. Checks status of the dbDisconnect command with dbDisconnectStatus and the status of the connections with dbStatus. (The dbDisconnect command is in progress and the connections still exist.)

  5. Disconnects in immediate mode (without wait), to be sure connections are closed.

  6. Again checks status of the dbDisconnect command with dbDisconnectStatus and the status of the connections with dbStatus. (The dbDisconnect command has completed and the connections are gone.) 

% ttGridAdmin dbStatus database1 -connections
Host       Instance  ConnId Name      Pid   Type   CHost CAddr CPid
---------- --------- ------ --------- ----- ------ ----- ----- ----
mysys5host instance3      1 database1 20233 Direct
mysys4host instance2      1 database1 26529 Direct
mysys3host instance1      1 database1  1600 Direct
mysys6host instance4      1 database1  1678 Direct

% ttGridAdmin dbClose database1
Database database1 close started
 
% ttGridAdmin dbStatus database1
Database database1 summary status as of Tue Sep 27 16:12:16 PST 2021
 
created,loaded-complete,closed
Completely created elements: 4 (of 4)
Completely loaded elements: 4 (of 4)
Completely created replica sets: 2 (of 2)
Completely loaded replica sets: 2 (of 2)
 
Open elements: 0 (of 4)

First try disconnecting in transactional mode:

% ttGridAdmin dbDisconnect database1 -transactional
Database database1 dbDisconnect started

Let some time pass, then check status—connections still exist:

% ttGridAdmin dbDisconnectStatus database1
Database  Host       Instance  Elem State         Started
--------- ---------- --------- ---- ------------- ------------------------
database1                           Disconnecting 2021-09-27T16:12:55.000Z
          mysys5host instance3    1 Disconnecting
          mysys4host instance2    2 Disconnecting
          mysys3host instance1    3 Disconnecting
          mysys6host instance4    4 Disconnecting
 
% ttGridAdmin dbStatus -connections
Database database1:
 
Host       Instance  ConnId Name      Pid   Type   CHost CAddr CPid
---------- --------- ------ --------- ----- ------ ----- ----- ----
mysys5host instance3      1 database1 20233 Direct
mysys4host instance2      1 database1 26529 Direct
mysys3host instance1      1 database1  1600 Direct
mysys4host instance4      1 database1  1678 Direct

Try again in immediate mode:

% ttGridAdmin dbDisconnect database1 -immediate
Database database1 dbDisconnect started

Check status again—now the connections are gone.:

% ttGridAdmin dbDisconnectStatus database1
Database  Host       Instance  Elem State        Started
--------- ---------- --------- ---- ------------ ------------------------
database1                           Complete     2021-09-27T16:14:03.000Z
          mysys5host instance3    1 Disconnected
          myshs4host instance2    2 Disconnected
          mysys3host instance1    3 Disconnected
          mysys6host instance4    4 Disconnected
 
% ttGridAdmin dbStatus database1 -connections
Host Instance ConnId Name Pid Type CHost CAddr CPid
---- -------- ------ ---- --- ---- ----- ----- ----
%

Notes

  • The database must be in a closed state before you run this command. (Closing a database does not affect existing connections, but does prevent new connections.)

  • In TimesTen Scaleout, the capability to force disconnections is always enabled and the forceDisconnectEnabled connection attribute is ignored.

Check Status of Forced Disconnection (dbDisconnectStatus)

The dbDisconnectStatus command reports the status of the executing or most recently run dbDisconnect command. 

ttGridAdmin dbDisconnectStatus name

Any of these states may be reported for the overall status of the dbDisconnect command:

  • Defined: Disconnect has been requested but not yet initiated.

  • Disconnecting: Disconnect is still in progress on at least one element.

  • Failed: Disconnect failed on at least one element.

  • Complete: Disconnect completed successfully on all elements.

Any of these states may be reported for the status of the disconnect on any given instance:

  • Disconnecting: Disconnect is in progress on the instance.

  • Failed: Disconnect failed on the instance.

  • Disconnected: Disconnect completed successfully on the instance.

Options

The dbDisconnectStatus command has the option:

Option Description

name

Name of the database.

Examples

A dbDisconnectStatus example is included in the dbDisconnect example in the preceding section.

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

Name of the database for data distribution changes.

-add all | hostname[.instancename]

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 -add all. It is not currently existing.)

Specify one instance per usage, but you can use -add more than once on a command line.

When the additions are applied, data will be distributed evenly across the grid.

Notes:

  • If you use -add all, you must use -apply in the same command.

  • Until you issue -apply, the element is marked to be added but is not actually added yet.

Also see Notes below for this and other options taking hostname[.instancename].

-remove hostname[.instancename]

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 -remove more than once on a command line.

It is typical to use -replaceWith to replace the element. The -remove option without -replaceWith results in redistribution of data.

If you have a grid with k=2 and you remove one element of a replica set, you must either replace it or also remove the other element of the replica set.

Note: Until you issue -apply, the element is marked for removal but is not actually removed yet.

Also see Redistributing Data in a Database in Oracle TimesTen In-Memory Database Scaleout User's Guide.

-evict hostname[.instancename]

Use this option if all elements of a replica set (one element if k=1, two elements if k=2) have unrecoverable failures and you cannot repair them.

Important: Using the -evict option inevitably results in data loss. Use this only as a last resort.

Specify one instance per usage, but you can use -evict more than once on a command line.

If you use -evict, you must evict all elements in the replica set.

You can use -replaceWith to replace the element.

Notes:

  • Do not issue or apply -evict together with -add or -remove.

  • Until you issue -apply, the element is marked for eviction but is not actually evicted yet.

  • Eviction results in the element being forcibly unloaded.

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.

-replaceWith hostname[.instancename]

Optionally use this with -evict or -remove to have the specified replacement contain the same data. The element on the replacing instance must not have previously been added to the distribution.

The -replaceWith option must immediately follow the corresponding -remove or -evict option on the command line.

-list

Displays the current and pending distribution map of the database ("Holds Data" and "Will Hold Data", respectively).

-apply

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.

-reset

Discards all distribution settings that have not yet been applied. This option cannot be combined with any other option.

Note: You cannot use -reset while distribution (-apply) is in progress. You can try -resync instead, as appropriate.

-resync

Attempts to resynchronize metadata in the user database with metadata in the active management instance in case the state of a dbDistribute -apply command is unknown. For example, the user database and management instance may not have matching states due to some failure or loss of communication. In some cases, the management instance may not know about the success or failure of a dbDistribute operation on the data instances and is left in an intermediate state.

This option cannot be used with any other dbDistribute options.

See Recovering From a Data Distribution Error in Oracle TimesTen In-Memory Database Scaleout User's Guide for related information.

Note: The -resync option results in metadata in the management instance being read to see if there is a dbDistribute operation that is in progress but was neither committed nor rolled back. Resynchronizing may involve committing or rolling back the metadata changes of the dbDistribute operation (which are intended to be recorded in the management instance).

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 with dbCreate -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.

List Databases (dbList)

The dbList command lists the databases that have been created in the grid and indicates whether they have been loaded or opened. 

ttGridAdmin dbList

Examples

% ttGridAdmin dbList
Database                       Loaded Opened
database1                        Y      Y
testdb                           Y      N

Load a Database into Memory (dbLoad)

The ttGridAdmin dbLoad command loads the specified database into memory. A database must be loaded and opened before it is used by applications. 

ttGridAdmin dbLoad name 
                   [-nowait | -wait [timeout]]

Options

The dbLoad command has the options:

Option Description

name

Name of the database to load.

-nowait | -wait [timeout]

The command initiates a state change that is recorded in the active management instance of the grid.

The -nowait option causes the command to return immediately without waiting for the state change. This is the default behavior.

The -wait option causes the command to wait for the state change to complete, when the database element has been loaded on each instance in the grid. You can optionally subject the wait to a limit of timeout seconds. Otherwise, or if timeout is set to 0, there is no limit.

In a large grid, it is not typical or generally advisable to use -wait. If you do, it is advisable to set a timeout. (See Database Management Operations.)

Examples

This example loads a database without waiting for the elements to be loaded on all instances, then checks status (after the database was successfully loaded):

% ttGridAdmin dbLoad database1
Database database1 load started
...
% ttGridAdmin dbStatus database1
Database database1 summary status as of Mon Nov 13 18:58:53 PST 2017
 
created,loaded,closed
Completely created elements: 4 (of 4)
Completely loaded elements: 4 (of 4)
Completely created replica sets: 0 (of 0)
Completely loaded replica sets: 0 (of 0)
 
Open elements: 0 (of 4)

Notes

  • Before loading a database, it is advisable to run dbStatus with the -loadReadiness option to confirm all replica sets can be loaded.

  • After the command has completed, the database is loaded but closed. (Use dbOpen to open it.)

  • It is not necessary to run dbLoad after dbCreate, because dbCreate loads the database automatically.

  • If you run dbLoad asynchronously (without waiting), you can use the dbStatus command to see when the database is loaded.

Open a Database (dbOpen)

The dbOpen command opens the database so that applications can connect to it. 

ttGridAdmin dbOpen name 
                   [-nowait | -wait [timeout]]

Options

The dbOpen command has the options:

Option Description

name

Name of the database to open.

-nowait | -wait [timeout]

The command initiates a state change that is recorded in the active management instance of the grid.

The -nowait option causes the command to return immediately without waiting for the state change. This is the default behavior.

The -wait option causes the command to wait for the state change to complete, when the database element has been opened on each instance in the grid. You can optionally subject the wait to a limit of timeout seconds. Otherwise, or if timeout is set to 0, there is no limit.

In a large grid, it is not typical or generally advisable to use -wait. If you do, it is advisable to set a timeout. (See Database Management Operations.)

Examples

This example opens a database without waiting for the elements to be opened on all instances, then checks status (after the database was opened successfully):

% ttGridAdmin dbOpen database1
Database database1 open started
...
% ttGridAdmin dbStatus database1
Database database1 summary status as of Mon Nov 13 19:24:39 PST 2017
 
created,loaded-complete,open
Completely created elements: 4 (of 4)
Completely loaded elements: 4 (of 4)
Completely created replica sets: 2 (of 2)
Completely loaded replica sets: 2 (of 2)
 
Open elements: 4 (of 4)

Notes

  • The database must be loaded or loading (performed automatically by dbCreate).

  • The database must have a distribution map (dbDistribute -apply).

  • If you run dbOpen asynchronously (without waiting), you can use the dbStatus command to see when the database is open.

  • If a database has been opened with dbOpen, attempting to open it again typically results in an error. However, if any element is in "open failed" state, you can retry dbOpen. Doing so will change any element in "open failed" state to "loaded" state, which will result in TimesTen Scaleout trying to open it again.

Monitor the Status of a Database (dbStatus)

The dbStatus command reports the status of a database or databases or the status of specified components of the database or databases, using information from the active management instance. This includes the status of any pending command to create, destroy, load, unload, open, or close the database. You can also request additional details, or request information about the state of each instance regarding whether its element can be loaded. 

ttGridAdmin dbStatus [name]
                     [-summary]
                     [-element]
                     [-replicaSet]
                     [-dataSpaceGroup]
                     [-all]
                     [-details]
                     [-loadReadiness]
                     [-epochs]
                     [-connections [-proxy] [-system]]

You can also refer to dbStatus discussion and examples in Recovering from Failure in Oracle TimesTen In-Memory Database Scaleout User's Guide.

Options

The dbStatus command has the options:

Option Description

name

Name of the database for which to display status. The default is to display status of all databases in the grid.

-summary

Shows an overall summary of database status. (This is the default mode.)

-element

Shows the status of each element of the database.

-replicaSet

Shows the status of each replica set of the database.

-dataSpaceGroup

Shows the status of each data space group of the database.

-all

Shows summary, element, replica set, and data space group status (equivalent to -summary -element -replicaSet -dataSpaceGroup).

-details

Shows daemon state information in addition to the status information from the active management instance. You can use this option in addition to any of the preceding options.

-loadReadiness

Shows information, including up/down status, indicating whether instances in each replica set are in a state where their elements can be loaded.

It is advisable to use this option before trying to load a database. You can also use it while a load is in progress.

-epochs

Shows the most recent epochs available for each element of the grid, and the most recent epoch that could be used for recovery.

An epoch is a transaction that marks a globally consistent point in time across all elements of the database. See Epoch Transactions in Oracle TimesTen In-Memory Database Scaleout User's Guide .

-connections

Displays information for existing connections to the specified database. Without the -proxy or -system suboptions, only application connections are shown.

-proxy

Used with the -connections option, this also displays information for all proxy connections associated with existing application connections.

Note: This option cannot be used without the -connections option.

-system

Used with the -connections option, this also displays TimesTen internal connections, such as those used by subdaemons and TimesTen utilities.

Note: This option cannot be used without the -connections option.

Overall Database Status

The dbStatus command indicates the status of the database as a whole with a line showing overall created/destroyed, loaded/unloaded, and opened/closed states. (For example: "created,loaded-complete,closed".)

The states of created, creating, destroyed, loading, loaded, unloaded, unloading, opening, opened, closing, and closed indicate that the corresponding database management command is in progress or has finished, as stated.

In addition:

  • created-partial or creating-partial: Some elements of the database are in the process of being created or have successfully been created, but others could not be created.

  • createFailed: Creation of the database failed. This occurs when no elements could be created, such as when every TimesTen instance is down.

  • loaded-partial or loading-partial: The dbDistribute command has not yet been run on the database (so no replica sets have been defined) and at least one element could not be created or loaded.

  • loaded-incomplete or loading-incomplete: At least one replica has no elements that finished loading successfully.

  • loaded-functional or loading-functional: At least one element from each replica set is loaded.

  • loaded-complete or loading-complete: Every element loaded successfully.

  • notLoaded: Loading of the database failed—none of the elements is loaded or loading.

These states can help you determine if the grid is usable even if it is not fully operational. For example, you can execute dbOpen before all the elements have been loaded.

Element Status Values

The dbStatus command returns these database element status values:

Note:

See Troubleshooting Distributed Transactions in Oracle TimesTen In-Memory Database Scaleout User's Guide for recommendations regarding these status values.

Status Description

close failed

The attempt to close the element failed.

closing

The element is in the process of closing.

create failed

The attempt to create the element failed.

creating

The element is being created.

destroy failed

The attempt to destroy the element failed.

destroyed

The element has been destroyed.

destroying

The element is being destroyed.

down

The data instance where this element is located is not running.

evicted

The element was evicted or removed through dbDistribute and has been unloaded from RAM.

evicted (loaded)

The element was evicted or removed through dbDistribute but unloading it from RAM has not yet begun.

evicted (unloading)

The element was evicted or removed through dbDistribute and is being unloaded from RAM.

load failed

The attempt to load the element into RAM failed.

loaded

The element is loaded into RAM.

loading

The element is being loaded into RAM.

opened

The element is open.

open failed

The attempt to open the element failed.

opening

The element is in the process of opening.

uncreated

The element should be created, but creation has not yet started.

unloaded

The element has been unloaded from RAM.

unloading

The element is being unloaded from RAM.

waiting for seed

The element will be loaded into RAM, but not until after the other element in its replica set is loaded.

Connections Status

This section describes information displayed by the -connections, -proxy, and -system options that show existing connections.

Connection status item Description

Host

For the target of the connection, name of the host object in the model for the host where the data instance resides.

Instance

For the target of the connection, name of the instance object in the model for the data instance.

ConnId

Connection ID of the connection to the data instance.

Name

Name of the connection as indicated by the TimesTen ConnectionName connection attribute. (See ConnectionName for information about that attribute.)

Pid

Operating system process ID of the process that established the connection.

For direct mode applications, this is the process ID of the application. For client/server applications, this is the process ID of the client/server ttcserver process acting on behalf of the application.

Type

The type of connection. One of the following:

  • Direct for connections from direct mode applications.

  • C/S for connections from client/server applications.

  • Proxy for connections created by TimesTen that work on behalf of application connections, such as a connection to a different grid element that is necessary to access some of the data.

  • GCW for TimesTen internal connections from grid connection workers.

  • Subdaemon for TimesTen internal connections from TimesTen subdaemons.

  • TTStats for TimesTen internal connections for collection of statistics.

CHost

For client/server connections, the host name of the client where the application is running.

Note: This item is not shown when the -proxy option is used.

CAddr

For client server connections, the IP address of the client where the application is running.

Note: This item is not shown when the -proxy option is used.

CPid

For client/server connections, the operating system process ID of the application.

Note: This item is not shown when the -proxy option is used.

PHost

For proxy connections, the name of the host where the proxy connection is established.

PInstance

For proxy connections, the name of the TimesTen instance where the proxy connection is established.

PPid

For proxy connections, the operating system process ID of the process that established the connection.

PConnId

For proxy connections, the connection ID.

Examples

Database Status Examples

Key for these examples:

  • RS: Identifying number of the replica set that each element belongs to.

  • DS: Identifying number of the data space group that each element belongs to.

  • Elem: Element number for each element.

  • Status: Status of the operation on each element. See "Status values" above for the list of element states that can be returned.

This example shows complete dbStatus output after a database has had its distribution specified, but the database is closed. 

% ttGridAdmin dbStatus database1 -all
Database database1 summary status as of Thu Nov 17 13:28:16 PST 2016
 
created,loaded-complete,closed
Completely created elements: 4 (of 4)
Completely loaded elements: 4 (of 4)
Completely created replica sets: 2 (of 2)
Completely loaded replica sets: 2 (of 2)
 
Open elements: 0 (of 4)
 
Database database1 element level status as of Thu Nov 17 13:28:16 PST 2016
 
Host        Instance     Elem Status Date/Time of Event  Message
----------- ------------ ---- ------ ------------------- -------
 mysys3host griddata1       3 loaded 2016-11-16 17:36:39
 mysys4host griddata2       1 loaded 2016-11-16 17:36:40
 mysys5host griddata3       4 loaded 2016-11-16 17:36:39
 mysys6host griddata4       2 loaded 2016-11-16 17:36:41
 
Database database1 Replica Set status as of Thu Nov 17 13:28:16 PST 2016
 
RS DS Elem Host        Instance  Status Date/Time of Event  Message
-- -- ---- ----------- --------  ------ ------------------- -------
 1  1    3 mysys3host  griddata1 loaded 2016-11-16 17:36:39      
    2    1 mysys4host  griddata2 loaded 2016-11-16 17:36:40      
 2  1    4 mysys5host  griddata3 loaded 2016-11-16 17:36:39      
    2    2 mysys6host  griddata4 loaded 2016-11-16 17:36:41      
 
Database database1 Data Space Group status as of Thu Nov 17 13:28:16 PST 2016
 
DS RS Elem Host        Instance  Status Date/Time of Event  Message
-- -- ---- ----------- --------- ------ ------------------- -------
 1  1    3 mysys3host  griddata1 loaded 2016-11-16 17:36:39      
    2    4 mysys5host  griddata3 loaded 2016-11-16 17:36:39      
 2  1    1 mysys4host  griddata2 loaded 2016-11-16 17:36:40      
    2    2 mysys6host  griddata4 loaded 2016-11-16 17:36:41

This example shows load readiness with all instances up, then with one instance in a replica set down, then with both instances in a replica set down. If all instances in a replica set are down, the database cannot be loaded. 

% ttGridAdmin dbStatus database1 -loadReadiness
Data Elements:
RS DS Instance             State
-- -- -------------------- --------
 1  1 mysys3host.griddata1 Unloaded
 1  2 mysys4host.griddata2 Unloaded
 1                         Loadable
 2  1 mysys5host.griddata3 Unloaded
 2  2 mysys6host.griddata4 Unloaded
 2                         Loadable
 
database1 load state: Loadable
Total Elements Loaded:0/4
...

% ttGridAdmin dbStatus database1 -loadReadiness
Data Elements:
RS DS Instance             State
-- -- -------------------- --------
 1  1 mysys3host.griddata1 Down
 1  2 mysys4host.griddata2 Unloaded
 1                         Loadable
 2  1 mysys5host.griddata3 Unloaded
 2  2 mysys6host.griddata4 Unloaded
 2                         Loadable
 
database1 load state: Loadable
Total Elements Loaded:0/4
...

% ttGridAdmin dbStatus database1 -loadReadiness
Data Elements:
RS DS Instance             State
-- -- -------------------- -------------
 1  1 mysys3host.griddata1 Down
 1  2 mysys4host.griddata2 Down
 1                         Not Loadable
 2  1 mysys5host.griddata3 Unloaded
 2  2 mysys6host.griddata4 Unloaded
 2                         Loadable
 
database1 load state: Not Loadable
Total Elements Loaded:0/4

This example shows the epochs of the database. The important point is that if durability=0 and no recovery epoch is shown, the database is not recoverable. 

% ttGridAdmin dbStatus database1 -epochs
Database database1 element level status as of Tue Jan  9 16:49:39 PST 2018
 
Host       Instance  Elem Status Recent Epochs
---------- --------- ---- ------ ------------------------------------------------------------
mysys4host griddata2    1 loaded 286.3 288.1 290.2 292.4 294.3 296.1 298.2 300.1 302.2 304.4
mysys6host griddata4    2 loaded 286.3 288.1 290.2 292.4 294.3 296.1 298.2 300.1 302.2 304.4
mysys3host griddata1    3 loaded 286.3 288.1 290.2 292.4 294.3 296.1 298.2 300.1 302.2 304.4
mysys5host griddata3    4 loaded 286.3 288.1 290.2 292.4 294.3 296.1 298.2 300.1 302.2 304.4
 
Most recent recovery epoch: 304.4

Connection Status Examples

Examples are shown for the -connections option by itself, -connections with -proxy, -connections with -system, and -connections with both -proxy and -system. 

% ttgridadmin dbstatus database1 -connections
Host   Instance  ConnId Name        Pid  Type   CHost  CAddr         CPid
------ --------- ------ ----------- ---- ------ ------ ------------- ----
mysys1 instance1      1 database1   8631 Direct                          
mysys1 instance1      2 con1        8631 Direct                          
mysys1 instance1      3 con2        8631 Direct                          
mysys2 instance2      1 database1cs 8653 C/S    mysys2 10.90.137.240 8637
mysys2 instance2      2 con1        8666 C/S    mysys2 10.90.137.240 8637

% ttgridadmin dbstatus database1 -connections -proxy
Host   Instance  ConnId Name        Pid  Type   PHost  PInstance PPid  PConnId
------ --------- ------ ----------- ---- ------ ------ --------- ----- -------
mysys1 instance1      1 database1   8631 Direct                               
mysys1 instance1      2 con1        8631 Direct                               
mysys1 instance1      2 con1        8631 Proxy  mysys2 instance2 31210       4
mysys1 instance1      3 con2        8631 Direct                               
mysys1 instance1      3 con2        8631 Proxy  mysys2 instance2 31210       3
mysys2 instance2      1 database1cs 8653 C/S                                  
mysys2 instance2      2 con1        8666 C/S                                  

% ttgridadmin dbstatus database1 -connections -system
Host   Instance  ConnId Name                       Pid   Type      CHost    CAddr         CPid
------ --------- ------ -------------------------- ----- --------- -------- ------------- ----
mysys1 instance1      1 database1                   8631 Direct                               
mysys1 instance1      2 con1                        8631 Direct                               
mysys1 instance1      3 con2                        8631 Direct                               
mysys1 instance1    128 Grid Epoch Generator(TM=2) 31183 GCW                                  
mysys1 instance1    129 ttStats Collector          31183 GCW                                  
mysys1 instance1    130 ttStats Collector          31871 TTStats                              
mysys1 instance1    131 Garbage Collector          30876 Subdaemon                            
mysys1 instance1    132 Grid Watch Remote TM       30876 Subdaemon                            
mysys1 instance1    133 Grid Rem Elem Mon          30876 Subdaemon                            
mysys1 instance1    134 XactId Rollback            30876 Subdaemon                            
mysys1 instance1    135 Grid Epoch Generator       30876 Subdaemon                            
mysys1 instance1    136 Grid Seq Batch             30876 Subdaemon                            
mysys1 instance1    137 GCW Watcher                30876 Subdaemon                            
mysys1 instance1    138 HistGC                     30876 Subdaemon                            
mysys1 instance1    139 Log Marker                 30876 Subdaemon                            
mysys1 instance1    140 IndexGC                    30876 Subdaemon                            
mysys1 instance1    141 Grid Task                  30876 Subdaemon                            
mysys1 instance1    142 Deadlock Detector          30876 Subdaemon                            
mysys1 instance1    143 Flusher                    30876 Subdaemon                            
mysys1 instance1    144 Monitor                    30876 Subdaemon                            
mysys1 instance1    145 Checkpoint                 30876 Subdaemon                            
mysys1 instance1    146 Rollback                   30876 Subdaemon                            
mysys1 instance1    147 Manager                    30876 Subdaemon                            
mysys2 instance2      1 database1cs                 8653 C/S       mysys2 10.90.137.240   8637
mysys2 instance2      2 con1                        8666 C/S       mysys2 10.90.137.240   8637
mysys2 instance2      3 con2                       31210 GCW                                  
mysys2 instance2      4 con1                       31210 GCW                                  
mysys2 instance2    128 Grid Epoch Generator(TM=1) 31210 GCW                                  
mysys2 instance2    129 ttStats Collector          31210 GCW                                  
mysys2 instance2    130 ttStats Collector          31878 TTStats                              
mysys2 instance2    131 Grid Watch Remote TM       30950 Subdaemon                            
mysys2 instance2    132 HistGC                     30950 Subdaemon                            
mysys2 instance2    133 GCW Watcher                30950 Subdaemon                            
mysys2 instance2    134 Grid Epoch Generator       30950 Subdaemon                            
mysys2 instance2    135 Grid Seq Batch             30950 Subdaemon                            
mysys2 instance2    136 XactId Rollback            30950 Subdaemon                            
mysys2 instance2    137 Garbage Collector          30950 Subdaemon                            
mysys2 instance2    138 Grid Task                  30950 Subdaemon                            
mysys2 instance2    139 Log Marker                 30950 Subdaemon                            
mysys2 instance2    140 Grid Rem Elem Mon          30950 Subdaemon                            
mysys2 instance2    141 Flusher                    30950 Subdaemon                            
mysys2 instance2    142 IndexGC                    30950 Subdaemon                            
mysys2 instance2    143 Checkpoint                 30950 Subdaemon                            
mysys2 instance2    144 Deadlock Detector          30950 Subdaemon                            
mysys2 instance2    145 Monitor                    30950 Subdaemon                            
mysys2 instance2    146 Rollback                   30950 Subdaemon                            
mysys2 instance2    147 Manager                    30950 Subdaemon                            

% ttgridadmin dbstatus database1 -connections -proxy -system
Host   Instance  ConnId Name                       Pid   Type      PHost  PInstance PPid  PConnId
------ --------- ------ -------------------------- ----- --------- ------ --------- ----- -------
mysys1 instance1      1 database1                   8631 Direct                                  
mysys1 instance1      2 con1                        8631 Direct                                  
mysys1 instance1      2 con1                        8631 Proxy     mysys2 instance2 31210       4
mysys1 instance1      3 con2                        8631 Direct                                  
mysys1 instance1      3 con2                        8631 Proxy     mysys2 instance2 31210       3
mysys1 instance1    128 Grid Epoch Generator(TM=2) 31183 GCW                                     
mysys1 instance1    129 ttStats Collector          31183 GCW                                     
mysys1 instance1    130 ttStats Collector          31871 TTStats                                 
mysys1 instance1    130 ttStats Collector          31871 Proxy     mysys2 instance2 31210     129
mysys1 instance1    131 Garbage Collector          30876 Subdaemon                               
mysys1 instance1    132 Grid Watch Remote TM       30876 Subdaemon                               
mysys1 instance1    133 Grid Rem Elem Mon          30876 Subdaemon                               
mysys1 instance1    134 XactId Rollback            30876 Subdaemon                               
mysys1 instance1    135 Grid Epoch Generator       30876 Subdaemon                               
mysys1 instance1    135 Grid Epoch Generator       30876 Proxy     mysys2 instance2 31210     128
mysys1 instance1    136 Grid Seq Batch             30876 Subdaemon                               
mysys1 instance1    137 GCW Watcher                30876 Subdaemon                               
mysys1 instance1    138 HistGC                     30876 Subdaemon                               
mysys1 instance1    139 Log Marker                 30876 Subdaemon                               
mysys1 instance1    140 IndexGC                    30876 Subdaemon                               
mysys1 instance1    141 Grid Task                  30876 Subdaemon                               
mysys1 instance1    142 Deadlock Detector          30876 Subdaemon                               
mysys1 instance1    143 Flusher                    30876 Subdaemon                               
mysys1 instance1    144 Monitor                    30876 Subdaemon                               
mysys1 instance1    145 Checkpoint                 30876 Subdaemon                               
mysys1 instance1    146 Rollback                   30876 Subdaemon                               
mysys1 instance1    147 Manager                    30876 Subdaemon                               
mysys2 instance2      1 database1cs                 8653 C/S                                     
mysys2 instance2      2 con1                        8666 C/S                                     
mysys2 instance2      3 con2                       31210 GCW                                     
mysys2 instance2      4 con1                       31210 GCW                                     
mysys2 instance2    128 Grid Epoch Generator(TM=1) 31210 GCW                                     
mysys2 instance2    129 ttStats Collector          31210 GCW                                     
mysys2 instance2    130 ttStats Collector          31878 TTStats                                 
mysys2 instance2    130 ttStats Collector          31878 Proxy     mysys1 instance1 31183     129
mysys2 instance2    131 Grid Watch Remote TM       30950 Subdaemon                               
mysys2 instance2    132 HistGC                     30950 Subdaemon                               
mysys2 instance2    133 GCW Watcher                30950 Subdaemon                               
mysys2 instance2    134 Grid Epoch Generator       30950 Subdaemon                               
mysys2 instance2    134 Grid Epoch Generator       30950 Proxy     mysys1 instance1 31183     128
mysys2 instance2    135 Grid Seq Batch             30950 Subdaemon                               
mysys2 instance2    136 XactId Rollback            30950 Subdaemon                               
mysys2 instance2    137 Garbage Collector          30950 Subdaemon                               
mysys2 instance2    138 Grid Task                  30950 Subdaemon                               
mysys2 instance2    139 Log Marker                 30950 Subdaemon                               
mysys2 instance2    140 Grid Rem Elem Mon          30950 Subdaemon                               
mysys2 instance2    141 Flusher                    30950 Subdaemon                               
mysys2 instance2    142 IndexGC                    30950 Subdaemon                               
mysys2 instance2    143 Checkpoint                 30950 Subdaemon                               
mysys2 instance2    144 Deadlock Detector          30950 Subdaemon                               
mysys2 instance2    145 Monitor                    30950 Subdaemon                               
mysys2 instance2    146 Rollback                   30950 Subdaemon                               
mysys2 instance2    147 Manager                    30950 Subdaemon

Unload a Database (dbUnload)

The dbUnload command unloads the specified database from memory. 

ttGridAdmin dbUnload name 
                     [-nowait | -wait [timeout]]
                     [-force]

Note:

If a dbUnload command is issued while a transaction is in progress, the command will not wait for the transaction to complete. Data may be lost as a result.

Options

The dbUnload command has the options:

Option Description

name

Name of the database to unload.

-nowait | -wait [timeout]

The command initiates a state change that is recorded in the active management instance of the grid.

The -nowait option causes the command to return immediately without waiting for the state change. This is the default behavior.

The -wait option causes the command to wait for the state change to complete, when the database element has been unloaded on each instance in the grid. You can optionally subject the wait to a limit of timeout seconds. Otherwise, or if timeout is set to 0, there is no limit.

In a large grid, it is not typical or generally advisable to use -wait. If you do, it is advisable to set a timeout. (See Database Management Operations.)

-force

If Durability=0 and at least one replica set is completely down, this option allows the unload to proceed anyway.

Important: Using this option will likely result in data loss.

(Tipically, to prevent data loss, a database with Durability=0 cannot be unloaded unless at least one element from every replica set is loaded.)

Examples

This example unloads a database without waiting for the elements to be unloaded on all instances, then checks status (after the database was successfully unloaded).

% ttGridAdmin dbUnload database1
Database database1 unload started
...
% ttGridAdmin dbStatus database1
Database database1 summary status as of Mon Nov 13 18:52:47 PST 2017
 
created,unloaded,closed
Completely created elements: 4 (of 4)
Completely loaded elements: 0 (of 4)
Completely created replica sets: 0 (of 0)
Completely loaded replica sets: 0 (of 0)
 
Open elements: 0 (of 4)

Notes

  • Do not begin any transactions after issuing a dbUnload command.

  • All connections to the database must be closed.

  • The database must be closed.

  • If you run dbUnload asynchronously (without waiting), you can use the dbStatus command to see when the database is loaded.