Working with the Database Connection URL Attributes

You specify attributes on the Derby connection URL (see Derby JDBC Database Connection URL). The examples in this section use the syntax of the connection URL for use in an embedded environment. You can also specify these same attributes and values on the client connection URL if you are using Derby as a database server. For more information, see the Derby Server and Administration Guide.

You can also set these attributes by passing a Properties object along with a connection URL to DriverManager.getConnection when obtaining a connection; see "Specifying Attributes in a Properties Object".

All attributes are optional. For detailed information about the connection URL syntax and attributes, see "Derby Database Connection URL Syntax"in the Derby Reference Manual.

You can specify the following attributes:

• bootPassword=key
• create=true
• databaseName=nameofDatabase
• dataEncryption=true
• encryptionProvider=providerName
• encryptionAlgorithm=algorithm
• territory=ll_CC
• logDevice=logDirectoryPath
• createFrom=BackupPath
• restoreFrom=BackupPath
• rollForwardrecoveryFrom=BackupPath
• password=userPassword
• shutdown=true
• user=userName

jdbc:derby:;databaseName=databaseName
 

You can access read-only databases in jar or zip files by specifying jar as the subsubprotocol, like this:

jdbc:derby:jar:(pathToArchive)databasePathWithinArchive
 

Or, if the jar or zip file has been included in the class path, like this:

jdbc:derby:/databasePathWithinArchive
 

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 must not 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.

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");
 

You create a database by supplying a new database name in the connection URL and specifying create=true. Derby creates a new database inside a new subdirectory in the system directory. This system directory has the same name as the new database. If you specify a partial path, it is relative to the system directory. You can also specify an absolute path.

jdbc:derby:databaseName;create=true
 

For more details about create=true, see "create=true" in the Derby Reference Manual.

When user authentication is enabled, an application must provide a user name and password. One way to do this is to use connection URL attributes (see user=userName and password=userPassword).

jdbc:derby:sample;user=jill;password=toFetchAPail

For more information, see Working with User Authentication.

If your environment is configured properly, you can create your database as an encrypted database (one in which the database is encrypted on disk). To do this, you use the dataEncryption=true attribute to turn on encryption and the bootPassword=key attribute to specify a key for the encryption. You can also specify an encryption provider and encryption algorithm other than the defaults with the encryptionProvider=providerName and encryptionAlgorithm=algorithm attributes For more information about data encryption, see Encrypting Databases on Disk.

jdbc:derby:encryptedDB;create=true;dataEncryption=true;
bootPassword=DBpassword
 

You must specify the encryption key with the bootPassword=key attribute for an encrypted database when you boot it (which is the first time you connect to it within a JVM session or after shutting it down within the same JVM session). For more information about data encryption, see Encrypting Databases on Disk.

jdbc:derby:encryptedDB;bootPassword=DBpassword
 

Instead of specifying attributes on the connection URL, you can specify attributes as properties in a Properties object that you pass as a second argument to the DriverManager.getConnection method. For example, to set the user name and password:

Class.forName("org.apache.derby.jdbc.EmbeddedDriver");
 
Properties p = new Properties();
 
p.put("user", "sa");
 
p.put("password", "manager");
 
 
Connection conn = DriverManager.getConnection(
 
    "jdbc:derby:mynewDB", p);