Note:
The default host name (or IP) and service name (or port)
may be configured with the EQ_DBSERVER environment variable.
The default user name and password can be configured with
the EQ_DBUSER and EQ_DBPASSWORD environment variables.
- help [command]
- Ask the server to provide a list of supported commands.
If the optional command argument is specified, syntax of
the specified command is displayed.
For example:
$ dbctl help shutdown
usage: shutdown [number_of_seconds|CANCEL]
- shutdown [#seconds|cancel]
- Shutdown the eloqdb server. dba or operator authorization is required.
In addition, a shutdown delay (in seconds) can be specified
to schedule the shutdown of the eloqdb server process at a later time.
The shutdown cancel operation can be used to cancel a previously
scheduled shutdown.
For example:
$ dbctl -u dba shutdown
Shutting down now.
Note that "dbctl shutdown" does NOT wait until the requested eloqdb
server shutdown has completed and is thus NOT always suitable for scripting, for
example. In cases where you need to be sure the server has been stopped, before
continuing, you must use the "eloq8 stop" command instead.
- backup {start|stop|status}
- Enter or leave on-line backup mode. dba or operator authorization is required.
When eloqdb enters on-line backup mode all changes to the data
volume(s) are redirected to the log volume(s) and the data
volume(s) are guaranteed to be consistent and not to change.
The data volume(s) can then be backed up by a backup tool (e.g.
fbackup or tar).
When the on-line backup mode is stopped, all pending data
is written to the data volume(s).
NOTE: The eloqdb performance is reduced in on-line
backup mode and the log volume must provide space for all
committed transactions during the on-line backup period.
In case the eloqdb server is shut down during on-line backup
mode (or a failure occurs) the data volume(s) will be updated
automatically when the server is restarted.
For example:
$ dbctl -u dba backup start
On-line backup mode has been started.
Please refer to the database backup
document for more information.
- list {session|dbopen|db|lock|thread} [/notitle|/count] [argument] [filter ...]
- The list command returns status information from the eloqdb
server process (similar to using the HTTP status interface).
However the dbctl is easier to use from a script file.
The list command is allowed with any valid server login.
If the /notitle option is specified, any header lines are
omitted.
One or more filter
criteria may be specified to select a subset of the dbctl list results.
If multiple filter criteria are specified, they are combined with
an implicit AND operator.
Filter criteria are specified using a field name, an operator and
a value. Valid operators for numeric fields are "=", "<>", as
well as ">", ">=", "<" and "<=". Valid operators for text
fields are "=" and "<>". For text fields, the value may include
* and ? as "wildcard" characters.
For example:
$ dbctl list session "user=root"
$ dbctl list dbopen toydb "pname=*query3k*"
$ dbctl list lock "db=toydb" "status=blocked"
$ dbctl list thread "st=W" "time>=30"
If the /count option is specified, only the number of matching entries is shown.
- list session
- Provide a list of all active database sessions. The following
information is displayed:
| TID |
eloqdb thread id associated with this session |
| IP ADDR |
IP address and port number of the client |
| User / Login |
User login on the client system and database login of the session |
| Process information |
Information about the invoking process is output on a separate line |
For example:
$ dbctl list session
TID IP ADDR User / Login
---- -------------------- -----------------------
9 127.0.0.1:54345 mike / public
uid{102}pid{17995}pname{query3k}
10 127.0.0.1:54382 root / public
uid{0}pid{18010}pname{query3k}
11 127.0.0.1:54480 lars / public
uid{233}pid{19641}pname{dbctl list session}
Valid field names for filter criteria are:
tid, ip (or ipaddr), user, login, uid, pid, pname, info.
- list dbopen database
- Provide a list of all users that opened a specific database.
The following information is displayed:
| TID |
eloqdb thread id associated with this session |
| IP ADDR |
IP address and port number of the client |
| M |
DBOPEN mode |
| User / Login |
User login on the client system and database login of the session |
| Process information |
Information about the invoking process is output on a separate line |
For example:
$ dbctl list dbopen sample
TID IP ADDR M User / Login
---- -------------------- --- -----------------------------
9 127.0.0.1:54345 1 mike / public
uid{102}pid{17995}pname{query3k}
10 127.0.0.1:54382 9 root / public
uid{0}pid{18010}pname{query3k}
NOTE: If the same database has been opened multiple times
in the same session using different modes, only the first DBOPEN mode is
displayed.
Valid field names for filter criteria are:
tid, ip (or ipaddr), mode, user, login, uid, pid, pname, info.
- list db
- Provide a list of all opened data bases. The following information
is displayed:
| Database |
data base name |
| Ref |
how often the database is accessed |
| WrShrd |
how often the database is opened in mode 1 |
| WrExcl |
how often the database is opened in mode 3 |
| RdShrd |
how often the database is opened in mode 9 |
| RdExcl |
how often the database is opened in mode 8 |
| WrSngl |
how often the database is opened in mode 4 |
For example:
$ dbctl list db
Database Ref WrShrd WrExcl RdShrd RdExcl WrSngl
---------------- ---- ------ ------ ------ ------ ------
sample 2 2 0 0 0 0
Valid field names for filter criteria are:
db (or database), ref, wrshrd, wrexcl, rdshrd, rdexcl, wrsngl.
- list lock
- Provide a list of all data base locks. The following information
is displayed:
| TID |
eloqdb thread id associated with this session |
| Database |
database name |
| DBID |
internal database instance id |
| Status |
lock status (GRANTED/BLOCKED) |
| Mode |
lock mode (rounded to next even mode) |
| Qualifier |
lock qualifier (base/set/expression) |
For example:
$ dbctl list lock
TID Database DBID Status Mode Qualifier
--- ---------------- ---- ------- ---- ---------------
9 sample 1 GRANTED 6 expression
set=1 item=@ (effective set lock)
Valid field names for filter criteria are:
tid, db (or database), dbid, stat (or status), mode, qual (or qualifier).
- list thread
- Provide a list of all database threads. The following
information is displayed:
| TID |
eloqdb thread id associated with this session |
| ST |
Current thread status.
- R - Runnable
- S - Suspended or Idle
- W - Blocked (interruptable)
|
| WCHAN |
Specifies the object the thread is waiting for.
Empty if the thread is active or idle. |
| Time |
Number of seconds the thread was blocked or idle |
| Sched |
Number of times the thread was active |
| Blocked |
Number of times the thread was waiting |
| Name |
Thread name. This is the IP address and port number in case the
thread is associated with a user session. |
For example:
$ dbctl list thread
TID ST WCHAN Time Sched Blocked Name
---- -- ------------------ -------- -------- -------- --------------------
1 R 0 790714 0 vtimer
2 R 0 0 0 event
3 S 0 262115 0 timer
4 S 262115 0 0 shutdown
5 S 262115 0 0 ps
6 S 0 524199 10 syncer
7 R 0 73 0 http
8 S 35 4406 10 checkpoint
9 S 329 28 0 127.0.0.1:50002
10 S 26 58 0 127.0.0.1:46116
11 R 0 7 0 127.0.0.1:46120
Valid field names for filter criteria are:
tid, st, wchan, time, sched, blocked, name, blocked_on.
- cancelthread threadid
- The cancelthread option can be used by the administrator or operator to
unblock a user session that is waiting for a lock.
The session is specified with its 'tid' (thread identifier)
which can be obtained with either 'dbctl list thread' or the
http status display: A thread with a 'W' state (in the 'ST' column)
can be signaled or killed.
cancelthread causes the blocking statement to return with status
-35 (secondary status -1) in case of a blocking DBLOCK.
For example:
$ dbctl -u dba cancelthread 25
Thread 25 has been cancelled.
- killthread threadid
- The killthread option can be used by the administrator or operator to
terminate a user session.
The session is specified with its 'tid' (thread identifier)
which can be obtained with either 'dbctl list thread' or the
http status display: A thread with a 'W' state (in the 'ST' column)
can be signaled or killed.
killthread terminates the entire session by closing the
server connection to the client process. The application will
fail with a -700 status for the current database request
or the next database operation in case it is idle.
For example:
$ dbctl -u dba killthread 25
Thread 25 has been notified.
- syncmode {on [msec]|off|status}
- Enable or disable the sync mode of the running eloqdb process.
dba or operator authorization is required. If enabled, the syncer journal flush
interval in milliseconds may optionally be specified.
If omitted, the interval defaults the previously active value.
For example:
$ dbctl -u dba syncmode off
Sync mode set to OFF.
- dbstore [/z] database target
- The dbctl dbstore command transfers a single database
to the target "device" which must be defined in the server configuration
file. In order to store a database, database admin (dadmin) or
server admin (dba) or operator capabilities are required.
The target specification is either the name of a
configured server device or the name of a server device
and a filename separated by a slash.
If the dbstore target is a disk file, it will be created
with permissions that restrict access to the UID used for
running the database server.
For example:
$ dbctl -u dba dbstore payrol backup/payrol.bkup
Database "payrol" has been stored to "/data/backup/payrol.bkup".
$ dbctl -u dba dbstore payrol tape
Database "payrol" has been stored to "/dev/rmt/c1t0d0BEST".
Please refer to the database backup
document for more information.
Also see the B.08.40 release notes for recent changes like /z compression.
- dbrestore [/info] [/all] [/nouser] [/force] [/nice] source [new_database_name]
- The dbctl dbrestore command restores a single database
from a source device which must be defined in the server configuration
file. The database may not already exist.
Server admin (dba) or operator capabilities are required in order to
restore a database. The /nouser option is restricted to dba users.
The source specification is either the name of a
configured server device or the name of a server device
and a filename separated by a slash.
If the optional /info argument is present, information on the
archive is returned and the archive is not restored.
The header of the specified archive is displayed.
If the optional /all argument is present, the association between
database permission groups and server users ("sysmember") is retained.
Usage of the /all argument is safe if the database environment where
the database is restored is the same or has identical server users
as the environment where the database was stored.
Specifying the /nouser option has the same effect as omitting the /all option.
If the optional /force argument is present, the database may even be
restored while the server is in online backup mode. By default, dbrestore
requests are rejected during online backup mode because of the possible negative impact
on performance and log volume size.
If the optional /nice argument is specified, the server attempts
to mitigate the performance impact on concurrent client sessions and
the operating system buffer cache at the cost of slowing down the
dbrestore progress.
If a new_database_name is specified, its length must not exceed
64 characters, it must not begin with '/' and must not contain
any space characters.
For example:
$ dbctl -u dba dbrestore /all backup/payrol.bkup
Database "PAYROL" has been restored from "/data/backup/payrol.bkup".
$ dbctl -u dba dbrestore /info tape
Created: Wed Nov 17 16:09:28 2004
Archive version: 1
Volume revision: HP-UX A.06.00
Platform : HPUX
Character set : hp-roman8
Database name : PAYROL
$ dbctl -u dba dbrestore tape
Database "PAYROL" has been restored from "/dev/rmt/c1t0d0BEST".
Please refer to the database backup
document for more information.
Also see the B.08.40 release notes for recent changes like compression or absolute pathnames.
- forwardlog {enable|disable|restart|changelog|status}
- The dbctl forwardlog command is used to control forward-logging.
dba or operator authorization is required.
If forward-logging is disabled the server stops writing to the forward-log,
for example to avoid that the forward-log quickly fills up the available
disk space during a dbimport or dbrestore.
The enable command is used to reenable a previously disabled
forward-logging. The creation of the new forward-log is delayed until
the next on-line backup because a forward-log requires a backup as a
starting point.
The restart command may be used to manually begin a new
forward-log. The changelog command is
a synonym for the restart command.
(Note that restart or changelog commands cannot
be used against a secondary server).
For example:
$ dbctl -u dba forwardlog status
Forward-logging is enabled.
Forward-log is '/data/db/db-forward-22-1.log'.
Please refer to the forward-logging
document for more information.
- bimport [/v] [/a] [/n] [/f] database set bexp_file
- The dbctl bimport command allows to efficiently import
binary data set export files.
A binary import retains any chain information and detail set record numbers.
The affected data set is erased before the import file is processed.
If the optional /v argument is specified, additional information is
displayed. Specifying /v twice (/v /v) displays progress information.
If the optional /f argument (force) is present, the database may even be
imported while the server is in online backup mode. By default, bimport
requests are rejected during online backup mode because of the possible negative impact
on performance and log volume size.
For example:
$ dbctl bimport /v /v sample 1 $PWD/SAMPLE.001.exb
P0: server: /data/tmp/SAMPLE.001.exb: 1355 records expected
P0: server: /data/tmp/SAMPLE.001.exb: completed, 1355 records processed
Please refer to the
database
migration document for more info.
Also see the B.08.40 release notes for recent changes like compression.
- logfile log_file_name
- The dbctl logfile command changes the logfile
of the running eloqdb process. dba or operator authorization is required.
Currently only files are supported
as a log target. The file name should be provided with an
absolute path since the current directory of the server process
is usually unknown.
You may not specify a file that already exists.
For example:
$ YMD=$(date +%Y%m%d)
$ mv /var/tmp/eloqdb.log /var/tmp/eloqdb.log_$YMD
$ dbctl -u dba logfile /var/tmp/eloqdb.log
Log file has been set to "/var/tmp/eloqdb.log".
- logflags log_flags
- The dbctl logflags command changes the logging
options of the running eloqdb process. dba authorization is required.
For example:
$ dbctl -u dba logflags "*1E2"
Log flags have been set to "*1E2".
- statfile [FileName|DISABLED]
- The dbctl statfile command is used to display the
current value of [server] StatFile or specify a new value.
If used without additional file name argument this returns the
current value for [server] StatFile.
When a file name is present, it specifies a new value for
[server] StatFile. If DISABLED is specified, the [server] StatFile
is unconfigured and no longer used. Otherwise an absolute file name
must be specified. The file may not exist. When a file name is
specified, dba or operator capabilities are required.
For example:
$ dbctl statfile
statfile "DISABLED"
$ dbctl -u dba statfile /tmp/server.stats
statfile set to "/tmp/server.stats".
Please refer to the server statistics
document for more information.
- statfileflags [flags]
- The dbctl statfileflags command is used to display the
current value of [server] StatFileFlags or specify a new value.
If used without additional flags argument this returns the
current value for [server] StatFileFlags.
When a flags argument is present, it specifies a new value for
[server] StatFileFlags. An empty argument may be used to reset the
flags. When a flags argument is specified, dba or operator capabilities are
required.
The following flags are supported:
- s - (single line)
- causes the values to be formatted into a single
line. Values are separated by a space and no descriptive text is
present.
- a - (append)
- causes additional values to be appended to the file
instead of replacing the previous content.
- t - (local timezone)
- causes the timestamp to include the offset
of the local timezone from UTC. If not present, the timestamp
value denotes UTC. This flag allows to use the timestamp value
with DSI (MeasureWare) on HP-UX without requiring a conversion.
For example:
$ dbctl statfileflags
statfileflags ""
$ dbctl -u dba statfileflags sat
statfileflags set to "sat"
$ dbctl -u dba statfileflags ""
statfileflags set to ""
Please refer to the server statistics
document for more information.
- sessionstatfile [FileName|DISABLED]
- The dbctl sessionstatfile command is used to display the
current value of [server] SessionStatFile or specify a new value.
If used without additional file name argument this returns the
current value for [server] SessionStatFile.
When a file name is present, it specifies a new value for
[server] SessionStatFile. If DISABLED is specified, the
[server] SessionStatFile is unconfigured and no longer used.
Otherwise an absolute file name must be specified. The file
may not exist. When a file name is specified, dba or operator capabilities
are required.
For example:
$ dbctl sessionstatfile
sessionstatfile "DISABLED"
$ dbctl -u dba sessionstatfile /tmp/session.stats
sessionstatfile set to "/tmp/session.stats"
Please refer to the server statistics
document for more information.
- sessionstatmode [ 0 | 1 | seconds ]
- The dbctl sessionstatmode command is used to display the
current value of [server] SessionStatMode or specify a new value.
If used without additional mode argument this returns the
current value for [server] SessionStatMode.
When a mode argument is present, it specifies a new value for
[server] SessionStatMode. When a mode argument is specified
dba or operator capabilities are required.
The following values are supported:
- 0 - (zero)
- The SessionStatFile is disabled
- 1 - (one)
- A log entry is written to the SessionStatFile when
a session ends.
Any other value is understood to specify an interval (in seconds)
after which an entry is logged to the SessionStatFile in addition
to the entry that is logged after the session ends. The specified
value must be at least 60 seconds.
For example:
$ dbctl sessionstatmode
sessionstatmode 0
$ dbctl -u dba sessionstatmode 1
sessionstatmode set to 1
Please refer to the server statistics
document for more information.
- replication {STOP|STATUS|MONITOR}
- The dbctl replication status command may be used to obtain
replication status information from a primary or secondary server.
Output includes
server role, forward-log status and most recently processed checkpoint.
For a secondary server it also shows whether replication is active or
inactive,
as well as additional information on the last replication activity and the
estimated replication lag.
The dbctl replication monitor command may be used on a secondary server
to retrieve replication status in a form that is easier to parse in scripts.
It returns a single line with several secondatry status fields separated by spaces.
The dbctl replication stop command may be used on a secondary server
to disconnect an active replication session. dba or operator authorization is required.
This is equivalent to performing a "dbctl killthread" on the TID of the
respective replication session.
For example:
$ dbctl replication status
Server is configured as PRIMARY
Last checkpoint is 7-1.4318 (2008-10-16 13:20:32)
Forward-logging is enabled
Forward-log is '/fwlog/fw-7-1.log'
$ dbctl -h repl_host -s repl_port replication status
Server is configured as SECONDARY
Replication is active (activity 158 sec ago, lag 0 sec)
Last checkpoint is 7-1.4318 (2008-10-16 13:20:32)
Forward-logging is enabled
Forward-log is '/repl/fwlog/fw-7-1.log'
$ dbctl -h repl_host -s replication monitor
1 158 0 7-1.4318 1224163232
$ dbctl -h repl_host -s repl_port -u dba replication stop
Replication thread 9 has been notified.
Please note:
- The "Replication is active" status on the secondary server
replication status indicates that a dbrepl process is connected.
It does not indicate if the dbrepl processes is making any progress
or is blocked. A "Replication is inactive" status would indicate that
no dbrepl process is connected to the secondary server.
-
The secondary server status displays checkpoint timestamps as
received from the primary server, i.e. when the respective checkpoint
occured on the primary, not when it was finally applied on the secondary.
This info may be helpful in cases where replication has been stopped
or is processing backlog during "catch up" phases.
-
If the primary server is idle (no database opened) the secondary server
checkpoint timestamp is not updated. The primary server does not
record its checkpoints in the fwlog file if there is no user activity.
Consequently, the last replicated checkpoint timestamp on the
secondary server is not updated.
-
As of B.08.40 the designation of replicated servers and roles was
updated. A master server is now described as primary server and a
former slave server is now described as a secondary server or a
replicated server.
This affects any messages and configuration options. Any previous
config files are fully compatible.
Please refer to the server replication
document for more information.
Also see B.08.20 release notes for details on dbctl replication status information regarding "last activity" and "estimated replication lag" as well as details on dbctl replication monitor output fields.
- encryption {STATUS|REVOKE KEY id}
- The dbctl encryption status command may be used to obtain
encryption status information from a database server. Similar to the
dbkeyutil status command,
output includes a list of (active or partial) master keys that have been
uploaded to the running server.
The dbctl encryption revoke key command may be used to remove a
previously submitted master key from the running database server, similar
to the dbkeyutil revoke command.
dba or operator authorization is required.
Note that the dbkeyutil revoke and dbctl encryption revoke key commands use
slightly different arguments to specify the master key: dbkeyutil expects the
master key "name" and looks up the respective section of the key file; dbctl
expects the master key checksum.
For example:
$ dbctl encryption status
idx master key checksum stat type ts
---- -------------------------------- ---- -------- -------------------
1 5cd056b5f56ac7557542e474ea628f6a ACTV AES 128 2010-08-20 10:55:17
2 cde36de95fd3bee5662a1108a2bc9135 ACTV AES 128 2010-08-23 16:19:09
$ dbctl -u dba encryption revoke key cde36de95fd3bee5662a1108a2bc9135
Master key revoked successfully
Note that dbctl encryption status (and dbkeyutil status) return an error message
and non-zero return-code for database servers that do not support encryption.
Please refer to the dbkeyutil document for more information.
- dbkeyupdate [/V] [/SPEED pct | /DELAY count ms] database {date|keyid}
- The dbctl dbkeyupdate command provides a means to retire
old data encryption keys from a database. It triggers a scan for the
specified database covering all datasets and indexes using encrypted
items. It searches for data encrypted with an encryption key older
than a given key ID or key creation date. If necessary it re-encrypts
any entries found (using the currently active key). It finally
discards the old and now unused data encryption keys from the catalog.
Please refer to the dbkeyupdate
document for more information.
- volume { list | limit [MB] | id [ {max|ext} [MB] | add path }
- The dbctl volume command allows
to change database volume file properties without a server restart.
Please note that any changes performed with dbctl volume commands are
not replicated to the volume files on a secondary server, and that any
change to the global volume size limit does not persist a database
server restart (the VolumeFileSizeLimit in the
eloqdb server config file has to be adjusted manually).
For example:
$ dbctl volume list
Number of volumes 5
Volume 1, type 0, curr 1024.0, max 1024.0, ext 1.0, /data/db/db01.vol
Volume 2, type 1, curr 63.5, max 0.0, ext 1.0, /data/db/log1.vol
Volume 3, type 0, curr 1024.0, max 1024.0, ext 1.0, /data/db/db03.vol
Volume 4, type 0, curr 1024.0, max 1024.0, ext 1.0, /data/db/db04.vol
Volume 5, type 0, curr 12.5, max 1024.0, ext 1.0, /data/db/db05.vol
$ dbctl volume limit
2048.0
Please refer to the B.08.40 release notes for more information.
- access { show | add | reset } { db | http } ...
- The dbctl access command may be used to manage the
[db-access] or [http-access] filter defined in
the database server configuration file.
The following syntax is supported:
dbctl access show {db|http}
dbctl access add {db|http} {allow|deny} address
dbctl access reset {db|http} [ {allow|deny} address ]
The first argument specifies the operation, the second the access-filter
to operate on (either db or http).
dbctl access requires dba or operator capabilities.
Please refer to the B.08.40 release notes for more information.
- asyncio { status | enable | disable }
- The dbctl asyncio command may be used to query the status
of async disk i/o or temporarily disable or enable async disk i/o.
dba or operator privileges are required to change the status of
async disk i/o.
$ dbctl asyncio status
asyncio is enabled
The asyncio command was added with PE83-2104230.
