connect(String url, Properties info)

Syntax:

Connection connect(String url,
                   Properties info)
                   throws SQLException

Description:

Connections can be established with information in the url and optionally in the info as well. A URL has four parts - the driver specific prefix, the location of the database, the database name, and property information. The format is as follows:

jdbc:raima:rdm://<location_info>[/<database_name>][?<property_info>]

URLs designed for the JDBC Driver for Raima Database Manager always start with the "jdbc:raima:rdm://" prefix.

For the location, you can specify either 'local' or a hostname (or IP address) and an optional port. If the database is on the current machine and you wish to access it directly through JNI, the keyword 'local' indicates this. If the database is remote or you choose to access it via a TCP/IP connection to a running rdm-tfs, specify a hostname (which can be 'localhost') and an optional port. For example - "jdbc:raima:rdm://myhost:2000" will tell the JDBC driver to try to connect to an rdm-tfs process running on the machine named 'myhost' at port 2000. It is possible to specify multiple hostnames (separated by commas) and if this is used, the system will try to connect to each in order stopping when it is able to connect.

The optional database name is prefixed by a single slash ('/'). If no database name is specified the slash is not included. A database name can include TFS access information. See elsewhere in the documentation on TFS name formatting. Multiple database names can be included and are separated by commas.

The final item is a list of key/value pairs indicating parameters to the connection. If any properties are included, they are prefixed by a question mark ('?') and separated by ampersands ('&').

Thus a full URL can look like this.

jdbc:raima:rdm://{local|<hostname_or_ip>[:<port>][,<hostname_or_ip>[:<port>]]...}[/<database>[@<tfs_info>][,<database>[@tfs_info]]...][?<property>=<value>[&<property>=<value]...]

If properties are also specified in the info field, the properties in the url override the properties in info.

Here are the properties supported by the JDBC Driver for RaimaDB. Each of these can be specified in the URL or in the info Properties.

  • auto commit - Controls whether the connection starts in auto commit mode. Auto commit mode means the system will create a transaction automatically for each statement. Options are "on" and "off" and the default is "on".
  • transaction isolation - Controls the transaction isolation mode of the connection. Options are "read_uncommitted", "read_committed", "repeatable_read", and "serializable". The default is "serializable". The underlying database engine in RaimaDB only supports the "serializable" mode, however the JDBC Driver will allow any mode to be set but effectively act in "serializable" mode.
  • open mode - Controls the open mode for accessing the database. Options are "shared" (shared mode - multiple threads/applications can access the database simultaneously), "exclusive" (exclusive mode - only one thread/application can access the database at a time), "exclusivetransoff" (exclusive mode with no transactions - transactions are ignored) and "readonly" (read-only mode - no locking needed). The default is "shared" mode.
  • storage - Specifies how the contents of the database are stored. Options are “ondisk” (the database contents are stored as physical files on disk), “inmemory_volatile” (the in-memory mode where the database contents are available in-memory as long as there is an active connection to that database), “inmemory_keep” (the in-memory mode where the database contents are available in-memory as long as the database exists and the TFS process is running), “inmemory_load” (the in-memory mode where the database contents are loaded from disk; otherwise it behaves like “inmemory_volatile”) and “inmemory_persist” (the in-memory mode where the database contents are loaded from disk, and they are written to the files on disk when the last user connected to the database has closed it). There is no default.
  • snapshot - Indicates to the SQL engine whether to use snapshots for queries. This can increase performance but can also cause increase memory usage. See the documentation on snapshots for more information. Options are "on" and "off" and the default is "off".
  • document root - Sets the document root to the path specified. This is only useful when the location has been set to 'local' as otherwise the document root is specified in the rdm-tfs that is being connected to. This is the path at which the system will look for database files. The value specified must be a valid sub-directory and there is no default.
  • date separator - Sets the character used to specify the day, month, and year portions of a date when the SQL engine converts a date to a character string. Note that this does not affect dates that are returned as java.sql.Date objects nor does it affect dates converted to strings in this JDBC driver. Valid options are '-' and '/' and the default is '-'.
  • date format - Sets the date format used when the SQL engine converts a date to a character string. Note that this does not affect dates that are returned as java.sql.Date objects nor does it affect dates converted to strings in this JDBC driver. Valid options are: “yyyy/dd/mm”, “yyyy-dd-mm”, “mm/dd/yyyy”, “mm-dd-yyyy”, “dd/mm/yyyy” and “dd-mm-yyyy”. The default is “yyyy-mm-dd”.
  • lock timeout - Sets the number of seconds for the engine to wait when a lock is not available. If the lock is not available after this many seconds the operation is aborted. The default is 10 seconds. A value of 0 indicates that the system should not wait at all. A value of -1 indicates the system should wait indefinitely.
  • tfs type -Specifies the TFS type to use when using local connections. See tfs_spec.
  • cache size - Specifies the maximum number of objects retrieved from the database the SQL engine stores in its internal cache. Using a larger value may improve performance but also increase memory usage. The default is 20,000 objects.
  • optimize parameters - Specifies whether the SQL engine re-prepare a parametrized query at execution time, taking into consideration the actual values of the bound parameters. Valid options are “on” and “off”. The default is “on”.
  • defaultFetchSize - Specifies the number of rows the RaimaDB JDBC Driver pre-fetches when executing a query. This may be useful when an application works with a remote rdm-tfs, where a large value reduces the number of RPC calls it needs to make in order to fetch the resultset. Note that a larger value may increase the driver’s memory usage. The default is 1 row.
  • allow no database - Specifies whether the connection string can include the name of a database that does not exist on TFS. If this option is enabled and the database specified in the connection string doesn’t exist, the SQL engine will create a new database with that name. Valid options are “true” and “false”. The default is “true”.

Android Specific Properties

  • appname – specifies the <package name> directing the driver to utilize the private internal storage location of the application for database storage. Using appname, all database files are stored on the device in /data/data/<package name>/files. To specify alternate database storage location use the document root property. I.e …&document root=/sdcard/<app storage>/databases

Throws:

SQLException - if a database access error occurs

Reference:

For more information, reference JDBC documentation for: Driver.connect(String, Properties)