ALTER DATABASE statement

ALTER DATABASE UPGRADE 
[ PROCEDURE ON ]
[ JCONNECT { ON | OFF } ]
[ RESTART { ON | OFF } ] 
[ SYSTEM PROCEDURE AS DEFINER { ON | OFF } ]

ALTER DATABASE {
 CALIBRATE [ SERVER ]
 | CALIBRATE DBSPACE dbspace-name
 | CALIBRATE DBSPACE TEMPORARY
 | CALIBRATE GROUP READ
 | CALIBRATE PARALLEL READ
 | RESTORE DEFAULT CALIBRATION
}

ALTER DATABASE dbfile
ALTER [ TRANSACTION ] LOG
{ ON [ log-name ] [ MIRROR mirror-name ] | OFF }
[ KEY key ]

ALTER DATABASE 
{ dbname FORCE START
| SET PARTNER FAILOVER }

ALTER DATABASE dbfile
CHECKSUM OFF

PROCEDURE clause Drop and recreate all dbo- and SYS-owned procedures in the database.
JCONNECT clause To allow the jConnect JDBC driver access to system catalog information, specify JCONNECT ON. This clause installs the system objects that provide jConnect support. Specify JCONNECT OFF to exclude the jConnect system objects. You can still use JDBC, as long as you do not access system information. JCONNECT is ON by default.
RESTART clause RESTART is ON by default. When RESTART ON is specified and the AutoStop connection parameter is set to No, the database restarts after it is upgraded. Otherwise, the database is stopped after an upgrade.
SYSTEM PROCEDURE AS DEFINER { ON | OFF } clause The SYSTEM PROCEDURE AS DEFINER clause specifies whether to execute pre-16.0 system procedures that perform privileged tasks with the privileges of the invoker or the definer (owner). ON means these system procedures are executed with the privileges of the definer (owner). OFF means these system procedures are executed with the privileges of the invoker.
If this clause is not specified, the default is to maintain the current behavior of the database being upgraded. When upgrading a pre-16.0 database, this means running the procedures as definer.

This setting does not impact user-defined procedures, or any procedures introduced in version 16.0 or later. For information about what system procedures this affects, and impacts of the setting, see Running pre-16.0 system procedures as invoker or definer.
CALIBRATE [ SERVER ] clause Calibrate all dbspaces except for the temporary dbspace. This clause also performs the work done by CALIBRATE PARALLEL READ.
CALIBRATE DBSPACE clause Calibrate the specified dbspace.
CALIBRATE DBSPACE TEMPORARY clause Calibrate the temporary dbspace.
CALIBRATE GROUP READ clause Perform group read calibration on the temporary dbspace. Writes large work tables to the temporary dbspace and uses different group read sizes to time the reading of the files. If adding space to the temporary table exceeds the limit for the connection, or if the cache is not large enough to allow calibration with the largest memory size, calibration fails and an error message is returned.
CALIBRATE PARALLEL READ clause Calibrate the parallel I/O capabilities of devices for all dbspace files. The CALIBRATE [ SERVER ] clause also performs this calibration.
RESTORE DEFAULT CALIBRATION clause Restore the Disk Transfer Time (DTT) model to the built-in default values that are based on typical hardware and configuration settings.
ALTER [ TRANSACTION ] LOG clause Change the file name of the transaction log or transaction log mirror file. If MIRROR mirror-name is not specified, the clause sets a file name for a new transaction log. If the database is not currently using a transaction log, it starts using one. If the database is already using a transaction log, it starts using the new file as its transaction log.
If MIRROR mirror-name is specified, the clause sets a file name for a new transaction log mirror. If the database is not currently using a transaction log mirror, it starts using one. If the database is already using a transaction log mirror, it starts using the new file as its transaction log mirror.

You can also use this clause to turn off the transaction log or transaction log mirror. For example, ALTER DATABASE ALTER LOG OFF.
KEY clause Specify the encryption key to use for the transaction log or transaction log mirror. The encryption key can be either a string or a variable name. When using the ALTER [ TRANSACTION ] LOG clause on a strongly encrypted database, you must specify the encryption key.
dbname FORCE START clause Force a database server that is currently acting as the mirror server to take ownership of the database.

Caution

Using the FORCE START clause can result in the loss of transactions if the primary server contains transactions that the mirror server does not have.

It is recommended that you restart the primary and execute ALTER DATABASE with the SET PARTNER FAILOVER clause to force a failure without lost transactions. The FORCE START clause should only be used when the primary cannot be restarted as a last resort. See Troubleshooting: The primary server cannot be restarted.

This clause can be executed from within a procedure or event, and must be executed while connected to the utility database on the mirror server.
SET PARTNER FAILOVER clause Initiate a database mirroring failover from the primary server to the mirror server without stopping the server. This statement must be executed while you are connected to the database on the primary server, and can be executed from within a procedure or event. When this statement is executed:
1. The database server closes all connections to the database, including the connection that executed the statement
2. The database stops, and then restarts in the mirror role.
3. If the statement is contained in a procedure or event, then the other statements that follow it may not be executed
CHECKSUM clause Disable global checksums for the database. By default, new databases have global checksums enabled, while version 11 and earlier databases do not have global checksums enabled.
Regardless of the setting of this clause, the database server always enables write checksums for databases running on storage devices such as removable drives, and databases running on Windows Mobile to help provide early detection if the database file becomes corrupt. The database server also calculates checksums for critical pages during validation activities.

For databases that do not have global checksums enabled, you can enable write checksums by using the -wc options.

Syntax 1 Use the ALTER DATABASE UPGRADE statement as an alternative to the Upgrade utility (dbupgrad) to upgrade or update a database. By default, the database is stopped and restarted after the upgrade. The transaction log is archived during the upgrade and a new transaction log is created before the database is stopped or restarted.
In general, changes in databases between minor versions are limited to additional database options and minor system table and system procedure changes. The ALTER DATABASE UPGRADE statement upgrades the system tables to the current version and adds any new database options. If necessary, it also drops and recreates all system procedures. You can force a rebuild of the system procedures by specifying the PROCEDURE ON clause.

An error message is returned if you execute an ALTER DATABASE UPGRADE statement on a database that is currently being mirrored.

You can also use the ALTER DATABASE UPGRADE statement to restore settings and system objects to their original installed state.

Features that require a physical reorganization of the database file are not made available by executing an ALTER DATABASE UPGRADE statement. Such features include index enhancements and changes in data storage. To obtain the benefits of these enhancements, you must unload and reload your database.

Caution

Back up your database files before attempting to upgrade your database.

To use the jConnect JDBC driver to access system catalog information, specify JCONNECT ON (the default). To exclude the jConnect system objects, specify JCONNECT OFF. Setting JCONNECT OFF does not remove jConnect support from a database. You can still use JDBC, as long as you do not access system catalog information. If you subsequently download a more recent version of jConnect, you can upgrade the version in the database by (re-)executing the ALTER DATABASE UPGRADE JCONNECT ON statement.
Syntax 2 Use Syntax 2 to perform recalibration of the I/O cost model used by the optimizer. This operation updates the Disk Transfer Time (DTT) model, which is a mathematical model of the disk I/O used by the cost model. When you recalibrate the I/O cost model, the database server is unavailable for other use. In addition, it is essential that all other activities on the computer are idle. Recalibrating the database server is an expensive operation and may take some time to complete. It is recommended that you leave the default in place.
When using the CALIBRATE PARALLEL READ clause, parallel calibration is not performed on dbspace files with fewer than 10000 pages. Even though the database server automatically suspends all of its activity during calibration operations, parallel calibration should be done when there are no processes consuming significant resources on the same computer. After calibration, you can retrieve the maximum estimated number of parallel I/O operations allowed on a dbspace file by using the IOParallelism extended database property.

To eliminate repetitive, time-consuming recalibration activities when there is a large number of similar hardware installations, you can re-use a calibration by unloading it and then applying it (loading it) into another database by using the sa_unload_cost_model and sa_load_cost_model system procedures, respectively.

Syntax 3 Use the ALTER DATABASE statement to change the transaction log and transaction log mirror names associated with a database file. The database must not be running to make these changes. These changes are the same as those made by the Transaction Log (dblog) utility. You can execute this statement while connected to the utility database or another database, depending on the setting of the -gu option.

If you are changing the transaction log or transaction log mirror of an encrypted database, you must specify a key. You cannot stop using the transaction log if the database is using auditing. Once you turn off auditing, you can stop using the transaction log. This syntax is not supported in procedures, triggers, events, or batches.

Use the BACKUP DATABASE statement to rename the transaction log for a running database. For example:

BACKUP DATABASE DIRECTORY 'directory-name'
TRANSACTION LOG ONLY
TRANSACTION LOG RENAME;

Syntax 4 ALTER DATABASE...FORCE START must be executed from the mirror server, not the primary server.
Syntax 5 This clause can only be used to disable checksums for a database.

ALTER DATABASE UPGRADE is not supported on Windows Mobile.

Syntax 1 and 2: you must have the ALTER DATABASE system privilege, and must be the only connection to the database.
Syntax 3: you must have the SERVER OPERATOR system privilege, you must have file permissions on the directories where the transaction log is located, and the database must not be running.

Your ability to execute the ALTER DATABASE dbfile ALTER TRANSACTION LOG statement depends on the setting for the -gu database option, and whether you have the SERVER OPERATOR system privilege.
Syntax 4: you must have the SERVER OPERATOR system privilege.

The privileges required to execute an ALTER DATABASE dbname FORCE START statement can be changed by the -gd database server option.
Syntax 5: you must have the ALTER DATABASE system privilege.

Automatic commit

Syntax 1: The transaction log is archived during the upgrade. A new transaction log is created when the database restarts after the upgrade.

Syntax 1: The database is stopped at the end of the upgrade and by default is restarted.

SQL/2008 Vendor extension.
Transact-SQL The ALTER DATABASE statement is supported by Adaptive Server Enterprise. However, the statement's clauses supported by Adaptive Server Enterprise are disjoint from those clauses supported by SQL Anywhere.

The following example disables jConnect support:

ALTER DATABASE UPGRADE JCONNECT OFF;

The following example sets the transaction log file name associated with demo.db to mynewdemo.log:

ALTER DATABASE 'C:\\Users\\Public\\Documents\\SQL Anywhere 16\\Samples\\demo.db'
   ALTER LOG ON 'mynewdemo.log';

ALTER DATABASE statement

Syntax 1 - Upgrading components or restoring objects

Syntax 2 - Performing calibration

Syntax 3 - Changing transaction log and transaction log mirror names

Syntax 4 - Changing ownership of a database

Syntax 5 - Changing checksum settings

Parameters

Caution

Remarks

Caution

Privileges

Side effects

Standards and compatibility

Example

See also