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, getSocketFactory, getSoTimeout, getType, getUser, getWireCrypt, isWireCompression, setAuthPlugins, setCharSet, setConnectTimeout, setDbCryptConfig, setEnableProtocol, setEncoding, setParallelWorkers, setPassword, setPortNumber, setProcessId, setProcessName, setRoleName, setServerName, setSocketBufferSize, setSocketFactory, 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