When connecting to the Network Server, your application needs to load a driver and connection URL that are specific to the Network Server. In addition, you must specify a user name and password if you are using authentication.
See "Configuring user authentication" in the Derby Security Guide for information about configuring Network Server authentication.
org.apache.derby.jdbc.ClientDriver
jdbc:derby://server[:port]/ databaseName[;URL-attribute=value [;...]]where the URL-attribute is either a Derby embedded or network client attribute. Neither the database name nor the name of a directory in the database path can contain a colon (:), although the colon after the drive name in a Windows path is allowed. The path separator in the connection URL is a forward slash (/).
For complete information about the connection URL, see the Derby Reference Manual and the Derby Developer's Guide.
When you access the Network Server using a connection URL, the network client driver is loaded automatically.
To access an in-memory database using the Network Server, the syntax is:
jdbc:derby://server[:port]/memory: databaseName[;URL-attribute=value [;...]]
For more information, see "Using in-memory databases" in the Derby Developer's Guide.
For both driver and DataSource access, the database name (including path), user, password, and other attribute values must consist of characters that can be converted to UTF-8. The total byte length of the database name plus attributes when converted to UTF-8 must not exceed 1024 bytes; keep in mind that in UTF-8, a character may occupy from 1 to 4 bytes. You may be able to work around this restriction for long paths or paths that include multibyte characters by setting the derby.system.home system property when starting the Network Server and accessing the database with a relative path that is shorter and does not include multibyte characters.
The following table shows standard JDBC DataSource properties.
Property | Type | Description | URL Attribute | Notes |
---|---|---|---|---|
databaseName | String | The name of the database. This property is required. | None | This property is also available using EmbeddedDataSource. |
dataSourceName | String | The data source name. | None | This property is also available using EmbeddedDataSource. |
description | String | A description of the data source. | None | This property is also available using EmbeddedDataSource. |
user | String | The user's account name. | user | Default is APP. This property is also available using EmbeddedDataSource. |
password | String | The user's database password. | password | This property is also available using EmbeddedDataSource. |
serverName | String | The host name or TCP/IP address where the server is listening for requests. | None | Default is localhost. |
portNumber | Integer | The port number where the server is listening for requests. | None | Default is 1527. |
The following table shows client-specific JDBC DataSource properties.
Property | Type | Description | URL Attribute | Notes |
---|---|---|---|---|
traceFile | String | The filename for tracing output. Setting this property turns on tracing. See Network client tracing. | traceFile | None |
traceDirectory | String | The directory for the tracing output. Each connection will send output to a separate file. Setting this property turns on tracing. See Network client tracing. | traceDirectory | None |
traceLevel | Integer | The level of client tracing if traceFile or traceDirectory is set. | traceLevel | The default is TRACE_ALL. |
traceFileAppend | Boolean | Value is true if tracing output should append to the existing trace file. | traceFileAppend | The default is false. |
securityMechanism | Integer | The security mechanism. See "Configuring Network Client authentication without SSL/TLS" in the Derby Security Guide. | securityMechanism | The default is USER_ONLY_SECURITY. |
retrieveMessageText | Boolean | Retrieve message text from the server. A stored procedure is called to retrieve the message text with each SQLException and might start a new unit of work. Set this property to false if you do not want the performance impact or when starting new units of work. | retrieveMessageText | The default is true. |
ssl | String | The SSL mode for the client connection. See "Configuring SSL/TLS" in the Derby Security Guide. | ssl | The default is off. |
The following table shows server-specific JDBC DataSource properties.
Property | Type | Description | URL Attribute | Notes |
---|---|---|---|---|
connectionAttributes | String | Set to the list of Derby embedded connection attributes separated by semicolons. | Various | This property is also available using EmbeddedDataSource. See the Derby Reference Manual for more information about the various connection attributes. |
createDatabase | String | If set to create, create the database specified with the databaseName property. | create | This property is also available using EmbeddedDataSource. See the Derby Reference Manual for more information. Similar to setting connectionAttribute to create=true. Only create is allowed; other values equate to null. The result of conflicting settings of createDatabase, shutdownDatabase, and connectionAttributes is undefined. |
shutdownDatabase | String | If set to shutdown, shut down the database specified with the databaseName property. | shutdown | This property is also available using EmbeddedDataSource. See the Derby Reference Manual for more information. Similar to setting connectionAttribute to shutdown=true. Only shutdown is allowed; other values equate to null. The result of conflicting settings of createDatabase, shutdownDatabase, and connectionAttributes is undefined. If authentication and SQL authorization are both enabled, database shutdown is restricted to the database owner. |