Accessing the Network Server by using the network client driver

When connecting to the Network Server, your application needs to load a driver and connection URL that is specific to the Network Server. In addition, you must specify a user name and password if you are using authentication.

The driver that you need to access the Network Server is:

org.apache.derby.jdbc.ClientDriver

The syntax of the URL that is required to access the Network Server is:

jdbc:derby://server[:port]/
databaseName[;URL-attribute=value [;...]]

where the URL-attribute is either a Derby embedded or network client attribute.

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 255 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.

Table 1. 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.

Table 2. Client-specific 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 Network client security.	`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 Network encryption and authentication with SSL/TLS.	`ssl`	The default is `off`.

The following table shows server-specific JDBC DataSource properties.

Table 3. Server-specific 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.

Note: The setAttributesAsPassword property, which is available for the embedded DataSource, is not available for the client DataSource.