Shutting down Derby or an individual database

Applications in an embedded environment shut down the Derby system by specifying the shutdown=true attribute in the connection URL. To shut down the system, you do not specify a database name, and you do not ordinarily specify any other attribute.

jdbc:derby:;shutdown=true

A successful shutdown always results in an SQLException to indicate that Derby has shut down and that there is no other exception.

If you are running with a security manager on JDK 8 or higher, you must grant Derby permission to deregister the embedded driver in order to fully shut down the system. See Granting permissions to Derby for details.

If you have enabled user authentication at the system level, you will need to specify credentials (that is, username and password) in order to shut down a Derby system, and the supplied username and password must also be defined at the system level.

Important: Derby's BUILTIN authentication mechanism is suitable only for development and testing purposes, and it will no longer be documented in future releases. It is strongly recommended that production systems rely on NATIVE authentication, an external directory service such as LDAP, or a user-defined class for authentication. It is also strongly recommended that production systems protect network connections with SSL/TLS.

You can also shut down an individual database if you specify the databaseName. You can shut down the database of the current connection if you specify the default connection instead of a database name (within an SQL statement).

// shutting down a database from your application
DriverManager.getConnection(
    "jdbc:derby:sample;shutdown=true");

If user authentication and SQL authorization are both enabled, only the database owner can shut down the database.

// shutting down an authenticated database as database owner
DriverManager.getConnection(
    "jdbc:derby:securesample;user=joeowner;password=secret;shutdown=true");

If you previously called the java.sql.DriverManager.setLoginTimeout method to enable a login timeout, a shutdown of Derby or of an individual database can fail under circumstances like the following:

Network problems which slow down LDAP authentication
Heavily loaded databases which take a long time time to quiesce

Attention: It is good practice to close existing connections before shutting down the system or database. Connections created before the shutdown will not be usable after shutdown is performed. Attempting to access connections after shutdown may cause errors including instances of NullPointerException or protocol violations.