| 1 |
Services API enhancements in Firebird v2. |
| 2 |
----------------------------------------- |
| 3 |
|
| 4 |
1) Services API extension for new shutdown modes. |
| 5 |
(Alex Peshkov, [email protected], 2008) |
| 6 |
|
| 7 |
New DB shutdown modes can now be set using services. A number of new |
| 8 |
isc_spb_prp_* constants should be used for it. |
| 9 |
|
| 10 |
isc_spb_prp_shutdown_mode and isc_spb_prp_online_mode are used to perform |
| 11 |
database shutdown/online operation. They have a single byte parameter, |
| 12 |
setting new shutdown mode: isc_spb_prp_sm_normal, isc_spb_prp_sm_multi, |
| 13 |
isc_spb_prp_sm_single and isc_spb_prp_sm_full. They exactly match gfix's |
| 14 |
shutdown modes. When performing shutdown operation, you must specify |
| 15 |
also type of shutdown: one of isc_spb_prp_force_shutdown, |
| 16 |
isc_spb_prp_attachments_shutdown or isc_spb_prp_transactions_shutdown. |
| 17 |
They have single int (4-byte) parameter, specifying timeout for desired |
| 18 |
operation. |
| 19 |
Please note that old-styled parameters are also supported and should be |
| 20 |
used to enter default shutdown (currently 'multi') and online ('normal') |
| 21 |
modes. |
| 22 |
|
| 23 |
Samples of use of new parameters in fbsvcmgr utility (supposing login and |
| 24 |
password are set using some other method): |
| 25 |
Shutdown database to single-user maintenance mode: |
| 26 |
fbsvcmgr service_mgr action_properties dbname employee prp_shutdown_mode prp_sm_single prp_force_shutdown 0 |
| 27 |
After it enable multi-user maintenance: |
| 28 |
fbsvcmgr service_mgr action_properties dbname employee prp_online_mode prp_sm_multi |
| 29 |
After it go to full shutdown mode, disabling new attachments during 60 seconds: |
| 30 |
fbsvcmgr service_mgr action_properties dbname employee prp_shutdown_mode prp_sm_full prp_attachments_shutdown 60 |
| 31 |
Return to normal state: |
| 32 |
fbsvcmgr service_mgr action_properties dbname employee prp_online_mode prp_sm_normal |
| 33 |
|
| 34 |
2) Services API extension - nbackup support. |
| 35 |
(Alex Peshkov, [email protected], 2008) |
| 36 |
|
| 37 |
Nbackup performs two logical groups of operations - locking/unlocking database |
| 38 |
and backup/restore it. It doesn't make sense duplicating locking/unlocking in |
| 39 |
services, cause that functionality is present remotely in much better (from any |
| 40 |
point of view) in SQL language interface (ALTER DATABASE). But backup and restore |
| 41 |
must be run on localhost and the only way to access them is nbackup utility. |
| 42 |
Therefore expanding services API with this functionalty is very useful. |
| 43 |
|
| 44 |
The following actions were added: |
| 45 |
isc_action_svc_nbak - incremental nbackup, |
| 46 |
isc_action_svc_nrest - incremental database restore. |
| 47 |
The following parameters were added: |
| 48 |
isc_spb_nbk_level - backup level (integer), |
| 49 |
isc_spb_nbk_file - backup file name (string), |
| 50 |
isc_spb_nbk_no_triggers - do not run DB triggers (option). |
| 51 |
|
| 52 |
Samples of use of new parameters in fbsvcmgr utility (supposing login and |
| 53 |
password are set using some other method): |
| 54 |
Create backup level 0: |
| 55 |
fbsvcmgr service_mgr action_nbak dbname employee nbk_file e.nb0 nbk_level 0 |
| 56 |
Create backup level 1: |
| 57 |
fbsvcmgr service_mgr action_nbak dbname employee nbk_file e.nb1 nbk_level 1 |
| 58 |
Restore database from this files: |
| 59 |
fbsvcmgr service_mgr action_nrest dbname e.fdb nbk_file e.nb0 nbk_file e.nb1 |
| 60 |
|
| 61 |
|
| 62 |
3) Services API extension - trace support. |
| 63 |
(Khorsun Vlad, [email protected], 2009) |
| 64 |
|
| 65 |
There are five new services and corresponding actions to manage by user |
| 66 |
trace sessions : |
| 67 |
|
| 68 |
Start user trace session : |
| 69 |
action |
| 70 |
isc_action_svc_trace_start |
| 71 |
|
| 72 |
parameter(s) |
| 73 |
isc_spb_trc_name : trace session name, string, optional |
| 74 |
isc_spb_trc_cfg : trace session configuration, string, mandatory |
| 75 |
|
| 76 |
output |
| 77 |
text message with status of operation : |
| 78 |
- Trace session ID NNN started |
| 79 |
- Can not start trace session. There are no trace plugins loaded |
| 80 |
contents of trace session in text format |
| 81 |
|
| 82 |
|
| 83 |
Stop trace session |
| 84 |
action |
| 85 |
isc_action_svc_trace_stop |
| 86 |
|
| 87 |
parameter(s) |
| 88 |
isc_spb_trc_id : trace session ID, integer, mandatory |
| 89 |
|
| 90 |
output |
| 91 |
text message with status of operation : |
| 92 |
- Trace session ID NNN stopped |
| 93 |
- No permissions to stop other user trace session |
| 94 |
- Trace session ID NNN not found |
| 95 |
|
| 96 |
|
| 97 |
Suspend trace session |
| 98 |
action |
| 99 |
isc_action_svc_trace_suspend |
| 100 |
|
| 101 |
parameter(s) |
| 102 |
isc_spb_trc_id : trace session ID, integer, mandatory |
| 103 |
|
| 104 |
output |
| 105 |
text message with status of operation : |
| 106 |
- Trace session ID NNN paused |
| 107 |
- No permissions to change other user trace session |
| 108 |
- Trace session ID NNN not found |
| 109 |
|
| 110 |
Resume trace session |
| 111 |
action |
| 112 |
isc_action_svc_trace_resume |
| 113 |
|
| 114 |
parameter(s) |
| 115 |
isc_spb_trc_id : trace session ID, integer, mandatory |
| 116 |
|
| 117 |
output |
| 118 |
text message with status of operation : |
| 119 |
- Trace session ID NNN resumed |
| 120 |
- No permissions to change other user trace session |
| 121 |
- Trace session ID NNN not found |
| 122 |
|
| 123 |
List of existing trace sessions |
| 124 |
action |
| 125 |
isc_action_svc_trace_list |
| 126 |
|
| 127 |
parameter(s) |
| 128 |
none |
| 129 |
|
| 130 |
output |
| 131 |
text messages with list and state of trace sessions |
| 132 |
- Session ID: <number> |
| 133 |
- name: <string> |
| 134 |
- user: <string> |
| 135 |
- date: YYYY-MM-DD HH:NN:SS |
| 136 |
- flags: <string> |
| 137 |
|
| 138 |
"name" is trace session name and not printed if empty. |
| 139 |
"user" is creator user name |
| 140 |
"date" is session start date and time |
| 141 |
"flags" is comma delimited set of |
| 142 |
session's run state : "active" or "suspend" |
| 143 |
if creator user is administrator : "admin" |
| 144 |
if the session was created by the engine itself : "system" |
| 145 |
kind of session : "audit" or "trace" |
| 146 |
if user session log file is full : "log full" |
| 147 |
|
| 148 |
|
| 149 |
Output of every service is obtained as usually using isc_service_query call |
| 150 |
with isc_info_svc_line or isc_info_svc_to_eof information items. |
| 151 |
|
| 152 |
See also README.trace_services |
| 153 |
|
| 154 |
|
| 155 |
4) Services API extension - running gbak at server side with .fbk at the client. |
| 156 |
(Alex Peshkov, [email protected], 2011-2012) |
| 157 |
|
| 158 |
This way of doing backups is specially efficient when one needs to perform |
| 159 |
backup/restore operation for database, located on a server accessed using |
| 160 |
internet, due to the great performance advantage. |
| 161 |
|
| 162 |
The simplest way to use this feature is fbsvcmgr. To backup database run |
| 163 |
approximately the following: |
| 164 |
fbsvcmgr remotehost:service_mgr -user sysdba -password XXX \ |
| 165 |
action_backup -dbname some.fdb -bkp_file stdout >some.fbk |
| 166 |
|
| 167 |
and to restore it: |
| 168 |
fbsvcmgr remotehost:service_mgr -user sysdba -password XXX \ |
| 169 |
action_restore -dbname some.fdb -bkp_file stdin <some.fbk |
| 170 |
|
| 171 |
Please notice - you can't use "verbose" switch when performing backup because |
| 172 |
data channel from server to client is used to deliver blocks of fbk files. You |
| 173 |
will get appropriate error message if you try to do it. When restoring database |
| 174 |
verbose mode may be used without limitations. |
| 175 |
|
| 176 |
If you want to perform backup/restore from your own program, you should use |
| 177 |
services API for it. Backup is very simple - just pass "stdout" as backup file |
| 178 |
name to server and use isc_info_svc_to_eof in isc_service_query() call. Data, |
| 179 |
returned by repeating calls to isc_service_query() (certainly with |
| 180 |
isc_info_svc_to_eof tag) is a stream, representing image of backup file. Restore |
| 181 |
is a bit more tricky. Client sends new spb parameter isc_info_svc_stdin to server |
| 182 |
in isc_service_query(). If service needs some data in stdin, it returns |
| 183 |
isc_info_svc_stdin in query results, followed by 4-bytes value - number of bytes |
| 184 |
server is ready to accept from client. (0 value means no more data is needed right |
| 185 |
now.) The main trick is that client should NOT send more data than requested by |
| 186 |
server - this causes an error "Size of data is more than requested". The data is |
| 187 |
sent in next isc_service_query() call in the send_items block, using |
| 188 |
isc_info_svc_line tag in tradition form: isc_info_svc_line, 2 bytes length, data. |
| 189 |
When server needs next portion, it once more returns non-zero isc_info_svc_stdin |
| 190 |
value from isc_service_query(). |
| 191 |
|
| 192 |
A sample of how services API should be used for remote backup and restore can be |
| 193 |
found in source code of fbsvcmgr. |
| 194 |
|
| 195 |
|
| 196 |
5) Services API extension - using services with non-default security database. |
| 197 |
(Alex Peshkov, [email protected], 2013) |
| 198 |
|
| 199 |
If one wants to use services API to access database which is configured to use |
| 200 |
non-default security database, new SPB item isc_spb_expected_db should be used |
| 201 |
when attaching to services manager. Value of this item is a database which is |
| 202 |
expected to be accessed. |
| 203 |
|
| 204 |
Formally this does not raise backward incompatibility - as long as one does not |
| 205 |
use new FB3 feature (multiple security databases) he has no problems with old |
| 206 |
programs using services API. In a case when one has really big need to use old |
| 207 |
program for a database with non-default configuration there is a workaround: |
| 208 |
setting environment variable FB_EXPECTED_DB which will be added to SPB |
| 209 |
automatically. |
| 210 |
|
| 211 |
Example. Imagine we have the following lines in databases.conf: |
| 212 |
employee = $(dir_sampledb)/employee.fdb |
| 213 |
{ |
| 214 |
SecurityDatabase = employee |
| 215 |
} |
| 216 |
i.e. employee database is configured as security database for itself. |
| 217 |
|
| 218 |
To access it using fbsvcmgr one should use the following command line: |
| 219 |
fbsvcmgr host:service_mgr user sysdba password xxx expected_db employee action_db_stats dbname employee sts_data_pages |
| 220 |
|
| 221 |
or in advance set FB_EXPECTED_DB: |
| 222 |
export FB_EXPECTED_DB=employee |
| 223 |
fbsvcmgr host:service_mgr user sysdba password xxx action_db_stats dbname employee sts_data_pages |
| 224 |
|
| 225 |
Certainly any other database action can be used here. |
| 226 |
|
| 227 |
|
| 228 |
6) Services API extension - using services to temporary turn off linger for database. |
| 229 |
(Alex Peshkov, [email protected], 2013) |
| 230 |
|
| 231 |
Linger is used to optimize performance in some cases (see also sql.extensions/README.linger). |
| 232 |
If you want to turn off linger temporary (for next database close) you may use gfix utility or |
| 233 |
services. New tag isc_spb_prp_nolinger is added for it (option). Setting isc_spb_prp_nolinger |
| 234 |
option turns off linger for the next database close operation and may be used to force closing |
| 235 |
database in linger state. |
| 236 |
|
| 237 |
Example: |
| 238 |
fbsvcmgr host:service_mgr user sysdba password xxx action_properties dbname employee prp_nolinger |
| 239 |
|
| 240 |
|
| 241 |
7) Services API extension - passing SQL role to services manager. |
| 242 |
(Alex Peshkov, [email protected], 2014) |
| 243 |
|
| 244 |
Just a few actions (user-management related) were capable to pass SQL role to server in pre-3 |
| 245 |
releases. With flexible access control in FB3 passing role to the services manager is sometimes |
| 246 |
useful and therefore possible. Services manager now accepts SPB item isc_spb_sql_role_name in |
| 247 |
start() call and passes it to invoked utilities. |
| 248 |
|
| 249 |
Example (assumimg user "leg" is granted admin rights): |
| 250 |
fbsvcmgr host:service_mgr user leg password leg action_restore dbname target.fdb bkp_file some.fbk |
| 251 |
(fails with "no permission for CREATE access to DATABASE" error) |
| 252 |
fbsvcmgr host:service_mgr user leg password leg role 'rdb$admin' action_restore dbname target.fdb bkp_file some.fbk |
| 253 |
(works as expected) |
| 254 |
|