Services API enhancements in Firebird v2. ----------------------------------------- 1) Services API extension for new shutdown modes. (Alex Peshkov, peshkoff@mail.ru, 2008) New DB shutdown modes can now be set using services. A number of new isc_spb_prp_* constants should be used for it. isc_spb_prp_shutdown_mode and isc_spb_prp_online_mode are used to perform database shutdown/online operation. They have a single byte parameter, setting new shutdown mode: isc_spb_prp_sm_normal, isc_spb_prp_sm_multi, isc_spb_prp_sm_single and isc_spb_prp_sm_full. They exactly match gfix's shutdown modes. When performing shutdown operation, you must specify also type of shutdown: one of isc_spb_prp_force_shutdown, isc_spb_prp_attachments_shutdown or isc_spb_prp_transactions_shutdown. They have single int (4-byte) parameter, specifying timeout for desired operation. Please note that old-styled parameters are also supported and should be used to enter default shutdown (currently 'multi') and online ('normal') modes. Samples of use of new parameters in fbsvcmgr utility (supposing login and password are set using some other method): Shutdown database to single-user maintenance mode: fbsvcmgr service_mgr action_properties dbname employee prp_shutdown_mode prp_sm_single prp_force_shutdown 0 After it enable multi-user maintenance: fbsvcmgr service_mgr action_properties dbname employee prp_online_mode prp_sm_multi After it go to full shutdown mode, disabling new attachments during 60 seconds: fbsvcmgr service_mgr action_properties dbname employee prp_shutdown_mode prp_sm_full prp_attachments_shutdown 60 Return to normal state: fbsvcmgr service_mgr action_properties dbname employee prp_online_mode prp_sm_normal 2) Services API extension - nbackup support. (Alex Peshkov, peshkoff@mail.ru, 2008) Nbackup performs two logical groups of operations - locking/unlocking database and backup/restore it. It doesn't make sense duplicating locking/unlocking in services, cause that functionality is present remotely in much better (from any point of view) in SQL language interface (ALTER DATABASE). But backup and restore must be run on localhost and the only way to access them is nbackup utility. Therefore expanding services API with this functionalty is very useful. The following actions were added: isc_action_svc_nbak - incremental nbackup, isc_action_svc_nrest - incremental database restore. The following parameters were added: isc_spb_nbk_level - backup level (integer), isc_spb_nbk_file - backup file name (string), isc_spb_nbk_no_triggers - do not run DB triggers (option). Samples of use of new parameters in fbsvcmgr utility (supposing login and password are set using some other method): Create backup level 0: fbsvcmgr service_mgr action_nbak dbname employee nbk_file e.nb0 nbk_level 0 Create backup level 1: fbsvcmgr service_mgr action_nbak dbname employee nbk_file e.nb1 nbk_level 1 Restore database from this files: fbsvcmgr service_mgr action_nrest dbname e.fdb nbk_file e.nb0 nbk_file e.nb1 3) Services API extension - trace support. (Khorsun Vlad, hvlad@users.sourceforge.net, 2009) There are five new services and corresponding actions to manage by user trace sessions : Start user trace session : action isc_action_svc_trace_start parameter(s) isc_spb_trc_name : trace session name, string, optional isc_spb_trc_cfg : trace session configuration, string, mandatory output text message with status of operation : - Trace session ID NNN started - Can not start trace session. There are no trace plugins loaded contents of trace session in text format Stop trace session action isc_action_svc_trace_stop parameter(s) isc_spb_trc_id : trace session ID, integer, mandatory output text message with status of operation : - Trace session ID NNN stopped - No permissions to stop other user trace session - Trace session ID NNN not found Suspend trace session action isc_action_svc_trace_suspend parameter(s) isc_spb_trc_id : trace session ID, integer, mandatory output text message with status of operation : - Trace session ID NNN paused - No permissions to change other user trace session - Trace session ID NNN not found Resume trace session action isc_action_svc_trace_resume parameter(s) isc_spb_trc_id : trace session ID, integer, mandatory output text message with status of operation : - Trace session ID NNN resumed - No permissions to change other user trace session - Trace session ID NNN not found List of existing trace sessions action isc_action_svc_trace_list parameter(s) none output text messages with list and state of trace sessions - Session ID: <number> - name: <string> - user: <string> - date: YYYY-MM-DD HH:NN:SS - flags: <string> "name" is trace session name and not printed if empty. "user" is creator user name "date" is session start date and time "flags" is comma delimited set of session's run state : "active" or "suspend" if creator user is administrator : "admin" if the session was created by the engine itself : "system" kind of session : "audit" or "trace" if user session log file is full : "log full" Output of every service is obtained as usually using isc_service_query call with isc_info_svc_line or isc_info_svc_to_eof information items. See also README.trace_services 4) Services API extension - running gbak at server side with .fbk at the client. (Alex Peshkov, peshkoff@mail.ru, 2011-2012) This way of doing backups is specially efficient when one needs to perform backup/restore operation for database, located on a server accessed using internet, due to the great performance advantage. The simplest way to use this feature is fbsvcmgr. To backup database run approximately the following: fbsvcmgr remotehost:service_mgr -user sysdba -password XXX \ action_backup -dbname some.fdb -bkp_file stdout >some.fbk and to restore it: fbsvcmgr remotehost:service_mgr -user sysdba -password XXX \ action_restore -dbname some.fdb -bkp_file stdin <some.fbk Please notice - you can't use "verbose" switch when performing backup because data channel from server to client is used to deliver blocks of fbk files. You will get appropriate error message if you try to do it. When restoring database verbose mode may be used without limitations. If you want to perform backup/restore from your own program, you should use services API for it. Backup is very simple - just pass "stdout" as backup file name to server and use isc_info_svc_to_eof in isc_service_query() call. Data, returned by repeating calls to isc_service_query() (certainly with isc_info_svc_to_eof tag) is a stream, representing image of backup file. Restore is a bit more tricky. Client sends new spb parameter isc_info_svc_stdin to server in isc_service_query(). If service needs some data in stdin, it returns isc_info_svc_stdin in query results, followed by 4-bytes value - number of bytes server is ready to accept from client. (0 value means no more data is needed right now.) The main trick is that client should NOT send more data than requested by server - this causes an error "Size of data is more than requested". The data is sent in next isc_service_query() call in the send_items block, using isc_info_svc_line tag in tradition form: isc_info_svc_line, 2 bytes length, data. When server needs next portion, it once more returns non-zero isc_info_svc_stdin value from isc_service_query(). A sample of how services API should be used for remote backup and restore can be found in source code of fbsvcmgr. 5) Services API extension - using services with non-default security database. (Alex Peshkov, peshkoff@mail.ru, 2013) If one wants to use services API to access database which is configured to use non-default security database, new SPB item isc_spb_expected_db should be used when attaching to services manager. Value of this item is a database which is expected to be accessed. Formally this does not raise backward incompatibility - as long as one does not use new FB3 feature (multiple security databases) he has no problems with old programs using services API. In a case when one has really big need to use old program for a database with non-default configuration there is a workaround: setting environment variable FB_EXPECTED_DB which will be added to SPB automatically. Example. Imagine we have the following lines in databases.conf: employee = $(dir_sampledb)/employee.fdb { SecurityDatabase = employee } i.e. employee database is configured as security database for itself. To access it using fbsvcmgr one should use the following command line: fbsvcmgr host:service_mgr user sysdba password xxx expected_db employee action_db_stats dbname employee sts_data_pages or in advance set FB_EXPECTED_DB: export FB_EXPECTED_DB=employee fbsvcmgr host:service_mgr user sysdba password xxx action_db_stats dbname employee sts_data_pages Certainly any other database action can be used here. 6) Services API extension - using services to temporary turn off linger for database. (Alex Peshkov, peshkoff@mail.ru, 2013) Linger is used to optimize performance in some cases (see also sql.extensions/README.linger). If you want to turn off linger temporary (for next database close) you may use gfix utility or services. New tag isc_spb_prp_nolinger is added for it (option). Setting isc_spb_prp_nolinger option turns off linger for the next database close operation and may be used to force closing database in linger state. Example: fbsvcmgr host:service_mgr user sysdba password xxx action_properties dbname employee prp_nolinger 7) Services API extension - passing SQL role to services manager. (Alex Peshkov, peshkoff@mail.ru, 2014) Just a few actions (user-management related) were capable to pass SQL role to server in pre-3 releases. With flexible access control in FB3 passing role to the services manager is sometimes useful and therefore possible. Services manager now accepts SPB item isc_spb_sql_role_name in start() call and passes it to invoked utilities. Example (assumimg user "leg" is granted admin rights): fbsvcmgr host:service_mgr user leg password leg action_restore dbname target.fdb bkp_file some.fbk (fails with "no permission for CREATE access to DATABASE" error) fbsvcmgr host:service_mgr user leg password leg role 'rdb$admin' action_restore dbname target.fdb bkp_file some.fbk (works as expected) 8) Services API extension - nbackup support (more). (Alex Peshkov, peshkoff@mail.ru, 2020) Added support to fixup databases after file system copy. The following action was added: isc_action_svc_nfix - fixup database. Samples of use of new parameter in fbsvcmgr utility (supposing login and password are set using some other method): fbsvcmgr - action_nfix dbname /tmp/ecopy.fdb 9) Services API extension - support of new nbackup feature to clean history table. (Khorsun Vlad, hvlad@users.sourceforge.net, 2022) Action isc_action_svc_nbak get new parameter tags isc_spb_nbk_clean_history : tell nbackup to clean RDB$HISTORY table isc_spb_nbk_keep_days <int> : specify how many recent rows should be kept in the history isc_spb_nbk_keep_rows <int> : specify how days back from today should be kept in the history Examples: - make backup of level 1, clean RDB$HISTORY table and keep 1 recent row in it: fbsvcmgr action_nbak dbfile db.fdb nbk_file db.nbk nbk_level 1 nbk_clean_history nbk_keep_rows 1 - make backup of level 2, clean RDB$HISTORY table and keep rows for the last 7 days in it: fbsvcmgr action_nbak dbfile db.fdb nbk_file db.nbk nbk_level 2 nbk_clean_history nbk_keep_days 7