Debian Codegraph @

doc/README.services_extension

raw
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