Connecting to Databases

You connect to a database using a form of the Derby connection URL as an argument to the DriverManager.getConnection call (see Derby JDBC Database Connection URL). You specify a path to the database within this connection URL.

The standard way to access databases is in the file system by specifying the path to the database, either absolute or relative to the system directory. In a client/server environment, this path is always on the server machine.

By default, you can connect to databases within the current system directory (see Defining the System Directory). To connect to databases within the current system, just specify the database name on the connection URL. For example, if your system directory contains a database called myDB, you can connect to that database with the following connection URL:

jdbc:derby:myDB

The full call within a Java program would be:

Connection conn =DriverManager.getConnection("jdbc:derby:myDB");

You can also connect to databases in other directories (including subdirectories of the system directory) by specifying a relative or absolute path name to identify the database. The way you specify an absolute path is defined by the host operating system (see java.io.File.isAbsolute). You must specify a path for a database in a directory other than the system directory even if you have defined the derby.service property to have Derby boot the database automatically (see "derby.service" in Tuning Derby).

Using the connection URL as described here, you can connect to databases in more than one directory at a time.

Two examples:

jdbc:derby:../otherDirectory/myDB
 
jdbc:derby:c:/otherDirectory/myDB

Note:

Once connected to, such a database becomes a part of the Derby system, even though it is not in the system directory. This means that it takes on the system-wide properties of the system and that no other instance of Derby should access that database, among other things. It is recommended that you connect to databases only in the system directory. See Recommended Practices for suggestions about working with a Derby system.

When accessing databases from the file system (instead of from class path or a jar file), any path that is not absolute is interpreted as relative to the system directory.

The path must do one of the following:

• refer to a previously created Derby database
• specify the create=true attribute

The path separator in the connection URL is / (forward slash), as in the standard file:// URL protocol.

You can specify only databases that are local to the machine on which the JVM is running. NFS file systems on UNIX and remote shared files on Windows (//machine/directory) are not guaranteed to work. Using derby.system.home and forward slashes is recommended practice for platform independent applications.

If two different database name values, relative or absolute, refer to the same actual directory, they are considered equivalent. This means that connections to a database through its absolute path and its relative path are connections to the same database. Within Derby, the name of the database is defined by the canonical path of its directory from java.io.File.getCanonicalPath.

Derby automatically creates any intermediate directory that does not already exist when creating a new database. If it cannot create the intermediate directory, the database creation fails.

If the path to the database is ambiguous, i.e., potentially the same as that to a database that is available on the class path (see "Special Database Access"), use the directory: subsubprotocol to specify the one in the file system. For example:

jdbc:derby:directory:myDB

You can also access databases from the class path or from a jar file (in the class path or not) as read-only databases.

In most cases, you access databases from the file system as described above. However, it is also possible to access databases from the class path. The databases can be archived into a jar or zip file or left as is.

All such databases are read-only.

To access an unarchived database from the class path, specify the name of the database relative to the directory in the class path. You can use the class path subprotocol if such a database is ambiguous within the directory system. See Embedded Derby JDBC Database Connection URL for more information.

For example, for a database called sample in C:\derby\demo\databases, you can put the C:\derby\demo\databases directory in the class path and access sample like this:

jdbc:derby:/sample
 

The forward slash is required before sample to indicate that it is relative to C:\derby\demo\databases directory.

If only C:\derby were in the class path, you could access sample (read-only) like this:

jdbc:derby:/demo/databases/sample
 

It is possible to access databases from a jar file. The jar file can be, but does not have to be, on the class path.

Note:

All such databases are read-only.

For example, suppose you have archived the database jarDB1 into a file called jar1.jar. This archive is in the class path before you start up Derby. You can access jarDB1 with the following connection URL

jdbc:derby:/jarDB1

To access a database in a jar file that is not on the class path, use the jar subprotocol.

For example, suppose you have archived the database jarDB2 into a file called jar2.jar. This archive is not in the class path. You can access jarDB2 by specifying the path to the jar file along with the jar subsubprotocol, like this:

jdbc:derby:jar:(c:/derby/lib/jar2.jar)jarDB2
 

For complete instructions and examples of accessing databases in jar files, see Accessing a Read-Only Database in a Zip/Jar.

The examples in this section use the syntax of the connection URL for use in an embedded environment. This information also applies to the client connection URL in a client/server environment. For reference information about client connection URLs, see "java.sql.Connection" in the Derby Reference Manual.

• jdbc:derby:db1

  Open a connection to the database db1. db1 is a directory located in the system directory.

• jdbc:derby:london/sales

  Open a connection to the database london/sales. london is a subdirectory of the system directory, and sales is a subdirectory of the directory london.

• jdbc:derby:/reference/phrases/french

  Open a connection to the database /reference/phrases/french.

  On a UNIX system, this would be the path of the directory. On a Windows system, the path would be C:\reference\phrases\french if the current drive were C. If a jar file storing databases were in the user's class path, this could also be a path within the jar file.

• jdbc:derby:a:/demo/sample

  Open a connection to the database stored in the directory \demo\sample on drive A (usually the floppy drive) on a Windows system.

• jdbc:derby:c:/databases/salesdb jdbc:derby:salesdb

  These two connection URLs connect to the same database, salesdb, on a Windows platform if the system directory of the Derby system is C:\databases.

• jdbc:derby:support/bugsdb;create=true

  Create the database support/bugsdb in the system directory, automatically creating the intermediate directory support if it does not exist.

• jdbc:derby:sample;shutdown=true

  Shut down the sample database.

• jdbc:derby:/myDB

  Access myDB (which is directly in a directory in the class path) as a read-only database.

• jdbc:derby:classpath:/myDB

  Access myDB (which is directly in a directory in the class path) as a read-only database. The reason for using the subsubprotocol is that it might have the same path as a database in the directory structure.

• jdbc:derby:jar:(C:/dbs.jar)products/boiledfood

  Access the read-only database boiledfood in the products directory from the jar file C:/dbs.jar.

• jdbc:derby:directory:myDB

  Access myDB, which is in the system directory. The reason for using the directory: subsubprotocol is that it might happen to have the same path as a database in the class path.