Module org.firebirdsql.jaybird
Package org.firebirdsql.management

# Interface MaintenanceManager

All Superinterfaces:
  `AttachmentProperties`, `BaseProperties`, `ServiceConnectionProperties`, `ServiceManager`

All Known Implementing Classes:
  `FBMaintenanceManager`

public interface MaintenanceManager extends ServiceManager
A `MaintenanceManager` is responsible for replicating the functionality provided by the `gfix` command-line tool.

Among the responsibilities of this class are:

- Database shutdown
- Extended database shutdown/online modes
- Changing database mode to read-only or read-write
- Enabling or disabling forced writes in the database
- Changing the dialect of the database
- Setting the cache size at database-level
- Mending databases and making minor repairs
- Sweeping databases
- Displaying, committing, or recovering limbo transactions
- Activating and killing shadow files
- Configuring page fill

Author:
  Gabriel Reid, Thomas Steinmaurer

## Field Summary

Fields
Modifier and Type
Field
Description
`static final int`
`ACCESS_MODE_READ_ONLY`
Database read-only mode
`static final int`
`ACCESS_MODE_READ_WRITE`
Database read-write mode
`static final byte`
`OPERATION_MODE_FULL_SHUTDOWN`
Operation mode full shutdown.
`static final byte`
`OPERATION_MODE_MULTI`
Operation mode multi shutdown/online.
`static final byte`
`OPERATION_MODE_NORMAL`
Operation mode normal online.
`static final byte`
`OPERATION_MODE_SINGLE`
Operation mode single shutdown/online.
`static final int`
`PAGE_FILL_FULL`
Fully fill pages when inserting records.
`static final int`
`PAGE_FILL_RESERVE`
While inserting records, reserve 20% of each page for later record deltas
`static final int`
`SHUTDOWN_ATTACH`
Don't allow new connections while waiting to shut down.
`static final int`
`SHUTDOWN_FORCE`
Forced database shutdown.
`static final int`
`SHUTDOWN_TRANSACTIONAL`
Don't allow new transactions while waiting to shut down.
`static final int`
`SHUTDOWNEX_ATTACHMENTS`
Shutdown attachments.
`static final int`
`SHUTDOWNEX_FORCE`
Force shutdown.
`static final int`
`SHUTDOWNEX_TRANSACTIONS`
Shutdown transactions.
`static final int`
`VALIDATE_FULL`
Do a full check on record and pages structures, releasing unassigned record fragments.
`static final int`
`VALIDATE_IGNORE_CHECKSUM`
Ignore checksums during repair operations.
`static final int`
`VALIDATE_READ_ONLY`
Only report corrupt or misallocated structures, don't fix.

## Method Summary

Modifier and Type
Method
Description
`void`
`activateShadowFile()`
Activate a database shadow file to be used as the actual database.
`void`
`bringDatabaseOnline()`
Bring a shutdown database online.
`void`
`bringDatabaseOnline(byte operationMode)`
Bring a shutdown database online with enhanced operation modes (FB 2.5 or higher).
`void`
`commitTransaction(long transactionId)`
Commit a limbo transaction based on its ID.
`void`
`fixIcu()`
Update or rebuild ICU-dependent collations and indexes when ICU version changed.
`long[]`
`getLimboTransactions()`
Retrieve the ID of each limbo transaction as an array of longs.
`void`
`killUnavailableShadows()`
Remove references to unavailable shadow files.
`List<Long>`
`limboTransactionsAsList()`
Retrieve the ID of each limbo transaction as a List of Long objects.
`void`
`markCorruptRecords()`
Mark corrupt records in the database as unavailable.
`void`
`rollbackTransaction(long transactionId)`
Rollback a limbo transaction based on its ID.
`void`
`setDatabaseAccessMode(int mode)`
Set the database to have read-write or read-only access.
`void`
`setDatabaseDialect(int dialect)`
Set the database's dialect.
`void`
`setDefaultCacheBuffer(int pageCount)`
Set the default page-buffer count to be cached in the database.
`void`
`setForcedWrites(boolean forced)`
Enable or disable forced (synchronous) writes in the database.
`void`
`setPageFill(int pageFill)`
Set the page fill strategy for when inserting records.
`void`
`setSweepThreshold(int transactions)`
Set the database automatic sweep interval to a given number of transactions.
`void`
`shutdownDatabase(byte operationMode, int shutdownModeEx, int timeout)`
Shutdown the current database with enhanced modes (FB 2.5 or higher).
`void`
`shutdownDatabase(int shutdownMode, int timeout)`
Shutdown the current database.
`void`
`sweepDatabase()`
Perform an immediate sweep of the database.
`void`
`upgradeOds()`
Perform minor ODS upgrade.
`void`
`validateDatabase()`
Locate and release database pages that are allocated but unassigned to any data structures.
`void`
`validateDatabase(int options)`
Locate and release database pages that are allocated but unassigned to any data structures.

### Methods inherited from interface org.firebirdsql.jaybird.props.AttachmentProperties

`getAuthPlugins, getCharSet, getConnectTimeout, getDbCryptConfig, getEnableProtocol, getEncoding, getParallelWorkers, getPassword, getPortNumber, getProcessId, getProcessName, getRoleName, getServerName, getSocketBufferSize, getSoTimeout, getType, getUser, getWireCrypt, isWireCompression, setAuthPlugins, setCharSet, setConnectTimeout, setDbCryptConfig, setEnableProtocol, setEncoding, setParallelWorkers, setPassword, setPortNumber, setProcessId, setProcessName, setRoleName, setServerName, setSocketBufferSize, setSoTimeout, setType, setUser, setWireCompression, setWireCrypt`

### Methods inherited from interface org.firebirdsql.jaybird.props.BaseProperties

`connectionPropertyValues, getBooleanProperty, getBooleanProperty, getIntProperty, getIntProperty, getProperty, getProperty, setBooleanProperty, setIntProperty, setProperty`

### Methods inherited from interface org.firebirdsql.jaybird.props.ServiceConnectionProperties

`getExpectedDb, getServiceName, setExpectedDb, setServiceName`

### Methods inherited from interface org.firebirdsql.management.ServiceManager

`getDatabase, getHost, getLogger, getPort, getServerVersion, getWireCryptAsEnum, setDatabase, setHost, setLogger, setPort, setWireCryptAsEnum`

## Field Details

### ACCESS_MODE_READ_WRITE

static final int ACCESS_MODE_READ_WRITE
Database read-write mode

See Also:
  - Constant Field Values

### ACCESS_MODE_READ_ONLY

static final int ACCESS_MODE_READ_ONLY
Database read-only mode

See Also:
  - Constant Field Values

### SHUTDOWN_ATTACH

static final int SHUTDOWN_ATTACH
Don't allow new connections while waiting to shut down.

See Also:
  - Constant Field Values

### SHUTDOWN_TRANSACTIONAL

static final int SHUTDOWN_TRANSACTIONAL
Don't allow new transactions while waiting to shut down.

See Also:
  - Constant Field Values

### SHUTDOWN_FORCE

static final int SHUTDOWN_FORCE
Forced database shutdown.

See Also:
  - Constant Field Values

### VALIDATE_READ_ONLY

static final int VALIDATE_READ_ONLY
Only report corrupt or misallocated structures, don't fix.

See Also:
  - Constant Field Values

### VALIDATE_IGNORE_CHECKSUM

static final int VALIDATE_IGNORE_CHECKSUM
Ignore checksums during repair operations.

See Also:
  - Constant Field Values

### VALIDATE_FULL

static final int VALIDATE_FULL
Do a full check on record and pages structures, releasing unassigned record fragments.

See Also:
  - Constant Field Values

### PAGE_FILL_FULL

static final int PAGE_FILL_FULL
Fully fill pages when inserting records.

See Also:
  - Constant Field Values

### PAGE_FILL_RESERVE

static final int PAGE_FILL_RESERVE
While inserting records, reserve 20% of each page for later record deltas

See Also:
  - Constant Field Values

### OPERATION_MODE_NORMAL

static final byte OPERATION_MODE_NORMAL
Operation mode normal online.

To be used with the `shutdownDatabase(byte, int, int)` method.

Since:
  Firebird 2.5
See Also:
  - `shutdownDatabase(byte, int, int)`
  - Constant Field Values

### OPERATION_MODE_MULTI

static final byte OPERATION_MODE_MULTI
Operation mode multi shutdown/online.

To be used with the `shutdownDatabase(byte, int, int)` method.

Since:
  Firebird 2.5
See Also:
  - `shutdownDatabase(byte, int, int)`
  - Constant Field Values

### OPERATION_MODE_SINGLE

static final byte OPERATION_MODE_SINGLE
Operation mode single shutdown/online.

To be used with the `shutdownDatabase(byte, int, int)` method.

Since:
  Firebird 2.5
See Also:
  - `shutdownDatabase(byte, int, int)`
  - Constant Field Values

### OPERATION_MODE_FULL_SHUTDOWN

static final byte OPERATION_MODE_FULL_SHUTDOWN
Operation mode full shutdown.

To be used with the `shutdownDatabase(byte, int, int)` method.

Since:
  Firebird 2.5
See Also:
  - `shutdownDatabase(byte, int, int)`
  - Constant Field Values

### SHUTDOWNEX_FORCE

static final int SHUTDOWNEX_FORCE
Force shutdown.

To be used with the `shutdownDatabase(byte, int, int)` method.

Since:
  Firebird 2.5
See Also:
  - `shutdownDatabase(byte, int, int)`
  - Constant Field Values

### SHUTDOWNEX_ATTACHMENTS

static final int SHUTDOWNEX_ATTACHMENTS
Shutdown attachments.

To be used with the `shutdownDatabase(byte, int, int)` method.

Since:
  Firebird 2.5
See Also:
  - `shutdownDatabase(byte, int, int)`
  - Constant Field Values

### SHUTDOWNEX_TRANSACTIONS

static final int SHUTDOWNEX_TRANSACTIONS
Shutdown transactions.

To be used with the `shutdownDatabase(byte, int, int)` method.

Since:
  Firebird 2.5
See Also:
  - `shutdownDatabase(byte, int, int)`
  - Constant Field Values

## Method Details

### setDatabaseAccessMode

void setDatabaseAccessMode(int mode) throws SQLException
Set the database to have read-write or read-only access.

Parameters:
  `mode` - Must be either `ACCESS_MODE_READ_WRITE` or `ACCESS_MODE_READ_ONLY`
Throws:
  `SQLException` - if a database access error occurs

### setDatabaseDialect

void setDatabaseDialect(int dialect) throws SQLException
Set the database's dialect.

Parameters:
  `dialect` - The database dialect, must be either 1 or 3
Throws:
  `SQLException` - if a database access error occurs

### setDefaultCacheBuffer

void setDefaultCacheBuffer(int pageCount) throws SQLException
Set the default page-buffer count to be cached in the database.

Parameters:
  `pageCount` - The number of pages to be cached, must be a positive
Throws:
  `SQLException` - If the given page count cannot be set, or a database access error occurs

### setForcedWrites

void setForcedWrites(boolean forced) throws SQLException
Enable or disable forced (synchronous) writes in the database.

Note, it is considered to be a very bad idea to disable forced writes on Windows platforms.

Parameters:
  `forced` - If `true`, forced writes will be used in the database, otherwise buffered writes will be used.
Throws:
  `SQLException` - if a database access error occurs

### setPageFill

void setPageFill(int pageFill) throws SQLException
Set the page fill strategy for when inserting records.

`pageFill` can be one of:

- `PAGE_FILL_FULL` Fully fill database pages
- `PAGE_FILL_RESERVE` Reserve 20% of page space for later record deltas

Parameters:
  `pageFill` - The page-filling strategy, either `PAGE_FILL_FULL` or `PAGE_FILL_RESERVE`
Throws:
  `SQLException` - if a database access error occurs

### shutdownDatabase

void shutdownDatabase(int shutdownMode, int timeout) throws SQLException
Shutdown the current database.

Shutdown can be done in three modes:

- `SHUTDOWN_ATTACH` - No new non-owner connections will be allowed to the database during the shutdown, and shutdown is cancelled if there are still processes connected at the end of the timeout.
- `SHUTDOWN_TRANSACTIONAL` - No new transactions can be started during the timeout period, and shutdown is cancelled if there are still active transactions at the end of the timeout.
- `SHUTDOWN_FORCE` - Forcefully shuts down the database at the end of the timeout.

Parameters:
  `shutdownMode` - One of `SHUTDOWN_ATTACH`, `SHUTDOWN_TRANSACTIONAL`, or `SHUTDOWN_FORCE`.
  `timeout` - The maximum amount of time allocated for the operation, in seconds
Throws:
  `SQLException` - if the requested operation cannot be completed within the given timeout, or a database access error occurs

### shutdownDatabase

void shutdownDatabase(byte operationMode, int shutdownModeEx, int timeout) throws SQLException
Shutdown the current database with enhanced modes (FB 2.5 or higher).

There are three operation modes for shutdown available:

- `OPERATION_MODE_MULTI` - Multi-user maintenance. Unlimited SYSDBA/database owner connections are allowed.
- `OPERATION_MODE_SINGLE` - Single-user maintenance. Only one SYSDBA/database owner connection is allowed.
- `OPERATION_MODE_FULL_SHUTDOWN` - Full shutdown. Full exclusive shutdown. No connections are allowed.

There are three extended shutdown modes for shutdown available:

- `SHUTDOWNEX_FORCE` - Force shutdown.
- `SHUTDOWNEX_ATTACHMENTS` - Shutdown attachments.
- `SHUTDOWNEX_TRANSACTIONS` - Shutdown transactions.

Parameters:
  `operationMode` - one of `OPERATION_MODE_*` operation modes listed above
  `shutdownModeEx` - one of `SHUTDOWNEX_*` extended shutdown modes listed above
  `timeout` - The maximum amount of time allocated for the operation, in seconds. 0 = immediately.
Throws:
  `SQLException` - if the requested operation cannot be completed within the given timeout, or a database access error occurs
Since:
  Firebird 2.5

### bringDatabaseOnline

void bringDatabaseOnline() throws SQLException
Bring a shutdown database online.

Throws:
  `SQLException` - if a database access error occurs

### bringDatabaseOnline

void bringDatabaseOnline(byte operationMode) throws SQLException
Bring a shutdown database online with enhanced operation modes (FB 2.5 or higher).

There are three operation modes for bringing a database online available:

- `OPERATION_MODE_NORMAL` - Normal operation modes.
- `OPERATION_MODE_MULTI` - Multi-user maintenance. Unlimited SYSDBA/database owner connections are allowed.
- `OPERATION_MODE_SINGLE` - Single-user maintenance. Only one SYSDBA/database owner connection is allowed.

Throws:
  `SQLException` - if a database access error occurs
Since:
  Firebird 2.5

### markCorruptRecords

void markCorruptRecords() throws SQLException
Mark corrupt records in the database as unavailable.

This operation ensures that the corrupt records are skipped (for example, during a subsequent backup).

Throws:
  `SQLException` - if a database access error occurs

### validateDatabase

void validateDatabase() throws SQLException
Locate and release database pages that are allocated but unassigned to any data structures. This method also reports corrupt structures.

Throws:
  `SQLException` - if a database access error occurs

### validateDatabase

void validateDatabase(int options) throws SQLException
Locate and release database pages that are allocated but unassigned to any data structures. This method also reports corrupt structures.

The value supplied for `options` must be one of the following:

- 0 - Simple validation
- `VALIDATE_READ_ONLY` - read-only validation, no repair
- `VALIDATE_FULL` - full validation and repair

The value for `options` can additionally be combined in a bitmask with `VALIDATE_IGNORE_CHECKSUM` to ignore checksums while performing validation.

Parameters:
  `options` - Either 0, `VALIDATE_READ_ONLY`, or `VALIDATE_FULL`
Throws:
  `SQLException` - if a database access error occurs

### setSweepThreshold

void setSweepThreshold(int transactions) throws SQLException
Set the database automatic sweep interval to a given number of transactions.

The Firebird default value is 20,000. If `transactions` is 0, automatic sweeping is disabled.

Parameters:
  `transactions` - The interval of transactions between automatic sweeps of the database. Can be set to 0, which disables automatic sweeping of the database.
Throws:
  `SQLException` - if a database access error occurs

### sweepDatabase

void sweepDatabase() throws SQLException
Perform an immediate sweep of the database.

Throws:
  `SQLException` - if a database access error occurs

### activateShadowFile

void activateShadowFile() throws SQLException
Activate a database shadow file to be used as the actual database.

This method is the equivalent of `gfix -activate`.

Throws:
  `SQLException` - if a database access error occurs

### killUnavailableShadows

void killUnavailableShadows() throws SQLException
Remove references to unavailable shadow files.

This method is the equivalent of `gfix -kill`.

Throws:
  `SQLException` - if a database access error occurs

### limboTransactionsAsList

List<Long> limboTransactionsAsList() throws SQLException
Retrieve the ID of each limbo transaction as a List of Long objects.

Throws:
  `SQLException` - if a database access error occurs

### getLimboTransactions

long[] getLimboTransactions() throws SQLException
Retrieve the ID of each limbo transaction as an array of longs.

In Firebird 3, transactions are (unsigned) 48 bit longs.

Throws:
  `SQLException` - if a database access error occurs

### commitTransaction

void commitTransaction(long transactionId) throws SQLException
Commit a limbo transaction based on its ID.

The transaction id is expected to be a positive long. If you have a negative `int`, convert the int to an unsigned long using `NumericHelper.toUnsignedLong(int)`

Parameters:
  `transactionId` - The ID of the limbo transaction to be committed (must be `> 0`)
Throws:
  `SQLException` - if a database access error occurs or the given transaction ID is not valid

### rollbackTransaction

void rollbackTransaction(long transactionId) throws SQLException
Rollback a limbo transaction based on its ID.

The transaction id is expected to be a positive long. If you have a negative `int`, convert the int to an unsigned long using `NumericHelper.toUnsignedLong(int)`

Parameters:
  `transactionId` - The ID of the limbo transaction to be rolled back (must be `> 0`)
Throws:
  `SQLException` - if a database access error occurs or the given transaction ID is not valid

### upgradeOds

void upgradeOds() throws SQLException
Perform minor ODS upgrade.

Requires Firebird 5.0 or higher.

Throws:
  `SQLException` - if a database access error occurs
Since:
  5.0.2

### fixIcu

void fixIcu() throws SQLException
Update or rebuild ICU-dependent collations and indexes when ICU version changed.

Requires Firebird 3.0 or higher.

Throws:
  `SQLException` - if a database access error occurs
Since:
  5.0.2