Maintenance without night shifts

Sweep, database validation, index statistics recalculation, your SQL scripts and Firebird updates run at night on a schedule. Group sweep, SQL scripts and Firebird updates start only in their own window. The agent does not get in the way of backups and users. If something goes wrong, the agent restores the previous state itself.

  • 4 maintenance jobs
  • 1 heavy operation per database
  • 2 heavy tasks per server
  • 03:30–04:00 Firebird update window
  • auto-rollback if the check fails

Default schedule

Server night

Maintenance runs at night, each job at its own time. Below are the default times and windows. You change them in the agent configuration editor.

Sweep, gfix validation, index recalculation and SQL scripts are off by default: you turn them on for your databases. Times use the agent's time zone.

Sunday night runs in this order: gfix validation at 02:30, sweep at 03:00, index recalculation at 04:00. First the check, then garbage collection, then statistics on live data.

sweep · gfix · indexes · SQL

Four maintenance jobs

Each job is a normal Firebird command. The agent adds what a DBA usually does by hand: a schedule, a window, a database lock, a log and a clear error reason.

JobWhat it doesWhich databasesDefault
Sweepgfix -sweep: removes old record versions.Explicit database listSun 03:00
Group sweepThe same sweep for all databases in folders. Masks, exclusions, scan depth.Folders, mask *.fdb00:15–01:15
gfix validationgfix -v -full: checks every database page.Explicit list onlySun 02:30
Index recalculationSET STATISTICS for user indexes. Also finds inactive indexes.Database listSun 04:00
SQL scriptsYour DDL and DML from the incoming scripts folder or from the queue.One database per script03:00–04:00
  • Long transactions before sweepAs an option, the agent disconnects connections with transactions older than 5 hours (the threshold is configurable). It does not touch gbak, gfix, gstat and fbsvcmgr.
  • The group does not stopAn error on one database does not stop the scan of the other databases.
  • A clear reasonFirebird 3 and later does not allow validation of a database with connected users. The agent says exactly that instead of showing only an error code.
  • SQL: the agent adds COMMITDDL: COMMIT after each statement, DML: after every 100 statements. SET BAIL ON: the first error stops the script.
  • Dangerous SQL does not runDROP DATABASE, users and roles, GRANT and REVOKE, ALTER DATABASE: such a script goes to quarantine as a whole.
  • Run logWhich command, when and with what result. For sweep and gfix validation the agent keeps a command history: up to 50 per job, the last two are visible in the editor. The password never goes into the log.

Windows · locks · slots

If the server is busy, the job waits or skips the database

Before a start, the agent checks several conditions. If a condition is not met, the job waits or skips the database. It does not interrupt other work.

Turn on the conditions on the left and see what the agent does with the sales.fdb database during a group sweep of its folder.

    RuleWhat countsWhat the agent does
    Maintenance windowGroup sweep 00:15–01:15, SQL scripts 03:00–04:00, performance test Sat 22:00 — Sun 06:00.Outside the window the job does not start. If less than a minute is left in the window, it does not start either.
    One heavy operation per databaseBackup, sweep, validation, index recalculation, restore and SQL script take a database lock.A backup waits up to 60 minutes for the database to become free. Sweep, validation and index recalculation skip a busy database until the next scheduled run. Run now waits and tries again.
    No more than 2 heavy tasks per serverBackups, restores, sweep, validations, index recalculation, SQL scripts, full gstat, the test. Heavy work of the agent itself also takes a slot: processing of traces and logs.A third task waits for a free slot. You change the number in the settings; the new value takes effect after an agent restart.
    .delta fileThere is a .delta file next to the database: nbackup holds the database.Sweep skips such a database.
    An error in one database of a groupThe sweep of one database in the group ended with an error.The group sweep continues with the next database. If continuation is off, only this job stops. The databases with an error are named in the job outcome.

    If a gbak backup and an nbackup of the same database fall on the same minute, the gbak backup moves 15 minutes later. A manual start with Run now does not move.

    One button

    Run now: start it now

    Need a backup before a software update, or a sweep right now? The “Run now” button on the job row starts the job once. The schedule does not change.

    Run now is available for backups, restores, sweep, index recalculation and gfix validation. You can also run a disabled job once: after that it stays disabled. The agent checks the same conditions as for a scheduled run and shows what it waits for.

    • You see what it waits forThe database is busy with another operation, the job waits for its window, disk space is low.
    • CancelWhile a run is queued or waiting, you can cancel it. A job that has started is not cancelled.
    • A request lives 60 minutesIf the agent did not take it in this time, the run counts as expired, not lost.
    • You see which database will runThe run window starts with the database field. For a group job, these are check boxes for the databases and the line “N of M selected”.
    • Performance report on requestRun now builds a report for any range up to 24 hours, with filters by database, duration and program. This is the same run as the “Build report…” button on the report page.
    • Locally and from the centerThe local console goes straight to the agent. From the center, the request goes through goafts. The agent takes it at the next sync, in about a minute.
    • Database replacement is separateRestore with replace and the backup-restore-replace cycle: you must type the database file name and have a separate permission. Remote start of such jobs is off on the server by default.
    • Right after SaveRun now waits until the agent accepts the new configuration, and only then starts the job.
    The “Jobs” tab. Jobs by group: state, schedule, last run and result. Dangerous restore jobs are turned on with a separate checkbox.

    Engine update

    A new Firebird build is a normal night operation

    The agent downloads a new Firebird build itself, waits for the maintenance window, installs it and checks it. If the check fails, the agent returns the previous version and does not install this build again.

    • Window03:30–04:00 by default. Outside the window, the downloaded build waits for the window to open. If the update is postponed inside the window, the agent tries again in 10 minutes. The agent finds a new build in the center in about an hour.
    • Jobs that must not be cut offIf gbak, nbackup, a restore or an SQL script is running, the update waits until the next check. Sweep, gfix validation and gstat do not block it: they can be repeated.
    • One engine at a timeOn a server with several Firebird instances, only one is updated at a time.
    • Space and locked filesFree space and files held by another program are checked before Firebird stops. If a file cannot be replaced, Firebird does not stop.
    • Your files stayThe agent replaces only the distribution files. firebird.conf, databases.conf, replication.conf, the security database, UDFs and third-party plugins stay. Only missing required parameters are added to firebird.conf.
    • RollbackThe replaced files are kept in the update backup. A rollback puts them back. The last 2 backups are kept.
    • Version blockA build that was rolled back, automatically or by hand, is blocked. One command removes the block.
    • Unfinished updateIf the process stopped in the middle, a new update does not start until the administrator rolls back or completes the previous one.

    The agent does not update Firebird installed from OS packages (apt, dnf): the package manager owns the files. How to move such a server to HQbird is described below.

    Test · databases.conf · migration

    Administrator tools

    Server performance test

    Once a week the agent runs the IBSurgeon test: INSERT, UPDATE and DELETE on a million rows in a temporary database. The test history shows how the server worked before and after a change of hardware, disk or settings.

    The test loads the disk, so it runs only in its own window. Firebird itself deletes the temporary database. If the agent crashed during the test, the file is deleted at the next start.

    WindowSat 22:00 — Sun 06:00
    StartSun 01:00
    Rows1 000 000
    Free disk spaceabout 7.2 GiB, or the test does not start
    Historylast 30 runs
    At the same timeone test; a second run is skipped

    Firebird users: Security.fdb/Users

    A separate settings page shows the security databases of the server: the shared one, private ones and those embedded in a database. Labels show a problem: no login for reading, the list did not refresh, the entry is out of date.

    The Create user button creates a Firebird user through the agent. In the window: name, password twice, plugin from the UserManager setting, the flags “active” and “administrator”. Administrator rights are confirmed in a second step. Before it runs, you see the command text, with the password hidden.

    Creation works with the local agent and does not work for Firebird 2.5.

    databases.conf editor

    The file is shown as a list of database paths. Each path has its aliases and a parameter block. The parameter list holds only those that this Firebird version accepts for a single database. The value from firebird.conf is shown next to it.

    A repeated alias and a second block for the same path are errors: you cannot save such a file. A typo in a parameter name gets a hint. On save, the agent checks the file again and keeps a copy of the previous file next to it. If the file changed while you edited it, the agent refuses, and your text stays in the editor. Edits in the form do not touch comments in the file. Each save is written to the audit log.

    From the center, the file is delivered through goafts. The agent applies it in about a minute and reports the result: accepted or rejected.

    databases.conf editor. On the left, paths and aliases; on the right, aliases and parameters of the selected path. The firebird.conf column shows the server value.
    Config history. The agent saves a copy of databases.conf, firebird.conf and replication.conf on every change. You see what changed and when.

    Moving to HQbird and settings changes

    FBDataGuard

    Old HQbird settings move over by themselves

    At the first start, the agent finds the FBDataGuard configuration and moves the backup, sweep and index statistics jobs. The import runs once. By default the jobs arrive disabled. If the installer disables FBDataGuard, it enables the jobs that FBDataGuard ran and that were imported without warnings. So the server is not left without backups. The other jobs stay disabled: check them and enable them yourself. The agent takes old backups from the FBDataGuard journals into its own records: retention and restore see them.

    apt · dnf

    Firebird from OS packages

    The installer finds Firebird from packages and stops without changing anything. It prints commands that remove the package and keep the security database, databases.conf and the databases. Then the installer installs HQbird and takes the users and aliases of the old server. Tested for Firebird 2.5, 3.0, 4.0 and 5.0.

    without restart

    New settings, with a check

    The agent checks the new configuration, makes a copy of the old one and applies the new one without a restart. If the new one does not load, the agent returns the previous one. Most settings apply without a restart. A restart is needed for the data folder, the agent log, Local API, the connection to the center, Prometheus, the cluster, load limits and the agent time zone. The agent reports which changes wait for a restart.

    ← Back to the HQbird 2027 overview · Backups in detail → · Server health →