JDBC Driver - Driver | Polypheny Documentation

On this page

Creating a Connection
Closing a Connection
More methods

The Polypheny JDBC Driver is a bridge between applications and Polypheny databases, enabling seamless data access and manipulation. Built upon the Java Database Connectivity (JDBC) API, this driver facilitates integration with Polypheny’s distinctive capabilities while adhering to standard JDBC workflows, ensuring both reliability and performance for transactional and analytical tasks alike.

Creating a Connection

A connection to a Polypheny instance can be established using the getConnection method.

`getConnection`

public Connection getConnection(String url)
            throws SQLException

public Connection getConnection(String url, Properties info)
            throws SQLException

public Connection getConnection(String url, String user, String password)
            throws SQLException

Parameters:

Parameter	Description	Overload Availability
`url`	The connection URL for the Polypheny database.	All
`info`	A list of arbitrary string tag/value pairs in a `Properties` object.	Second (`getConnection(String, Properties)`)
`user`	The username for authentication.	Third (`getConnection(String, String, String)`)
`password`	The password associated with the given username.	Third (`getConnection(String, String, String)`)

Usage:

Using the Simple URL String

try ( Connection conn = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" ) ) {
    // Your database operations...
} catch ( SQLException e ) {
    e.printStackTrace();
}

Using a Properties Object for Additional Settings

Properties props = new Properties();
props.put( "user", "pa" );
props.put( "password", "pa" );
// ... add other properties as needed

try ( Connection conn = DriverManager.getConnection( "jdbc:polypheny://localhost:20590", props ) ) {
    // Your database operations...
} catch ( SQLException e ) {
    e.printStackTrace();
}

Using Separate String Parameters for Username and Password

try ( Connection conn = DriverManager.getConnection( "jdbc:polypheny://localhost:20590", "pa", "pa" ) ) {
    // Your database operations...
} catch ( SQLException e ) {
    e.printStackTrace();
}

URL Structure

The JDBC URL for connecting to Polypheny has a specific structure that allows for various configurations. The generic structure is as follows:

jdbc:polypheny://[username:password]@host[:port][/namespace][?property1=value1&...&propertyN=valueN]

Each section in the URL represents:

username:password: Optional authentication credentials.
host: The address of the Polypheny server.
port: The port number on which the Polypheny server is running.
namespace: Optional database namespace.
property=value: Optional properties that configure the connection.

Default values:

If no host is specified, localhost is used as the default.
If no port is specified, 20591 is used as the default.

Examples:

Basic Connection: A connection to the default Polypheny instance (using default port).
```
jdbc:polypheny://localhost
```
With Authentication: A connection with specified username and password (“pa” for both).
```
jdbc:polypheny://pa:pa@localhost
```
With Port: Specifying the port in the connection. In this example, we use the default port 20591.
```
jdbc:polypheny://localhost:20591
```
With Namespace: A connection specifying a particular namespace to use as default for all executed statements. Here we specify the default namespace called “pulic”. Please refer to the corresponding documentation for further information on namespaces.
```
jdbc:polypheny://localhost/public
```
With Properties: A connection with additional properties like autocommit and nwtimeout.
```
jdbc:polypheny://localhost?autocommit=false&nwtimeout=2500
```
Combination: A combined example with username, password, port, namespace, and properties.
```
jdbc:polypheny://pa:pa@localhost:20591/myNamespace?autocommit=true&nwtimeout=3000
```

Connection Properties Details

The table below provides a comprehensive overview of the connection properties available for a Polypheny JDBC connection:

Property	Type	Values/Description	Example	Notes
`user`	String	Specifies the username for authentication.	`user=pa`
`password`	String	Specifies the password associated with the given username.	`password=pa`
`autocommit`	Boolean	Determines if each SQL statement is treated as a transaction.	`autocommit=true`	Values: `true` or `false`
`readonly`	Boolean	Indicates if the connection is in read-only mode.	`readonly=true`	Values: true or false. Currently ignored, reserved for future use.
`holdability`	String	Specifies the holdability of `ResultSet` objects.	`holdability=HOLD`	Values: `HOLD` or `CLOSE` (Currently ignored)
`isolation`	String	Indicates the transaction isolation level.	`isolation=SERIALIZABLE`	Values: `COMMITTED`, `DIRTY`, `SERIALIZABLE`, `REPEATABLE_READ` (Currently ignored)
`nwtimeout`	Integer	Specifies the network timeout in seconds. Corresponds to the JDBC network timeout.	`nwtimeout=30`	Values: `true` or `false`
`strict`	Boolean	Specifies if the driver should strictly adhere to the jdbc standard (see callout below).	`strict=true`

Be aware that older versions of the Polypheny JDBC Driver (prior to the 2.0 release) exhibited behavior that was not fully compliant with the JDBC standard. In developing the new driver, the focus has been on strict adherence to the standard. However, to maintain compatibility with applications crafted for older versions of the driver, the strict property can be set to false.

Please note that schemas are called namespaces in Polypheny. Please refer to the corresponding documentation for further information.

Closing a Connection

It’s essential to close connections when they are no longer needed to prevent resource leaks and to ensure optimal application and database performance. This can be achieved automatically using one of the methods below.

Using Try-With-Resources: Leveraging the try-with-resources statement, connections close automatically after the block executes.

try ( Connection conn = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" ) ) {
  // Use the connection
} catch ( SQLException e ) {
  e.printStackTrace();
}

Explicit Close: For those not using the try-with-resources feature, manually close the connection within a finally block.

Connection conn = null;
try {
  conn = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" );
  // Use the connection
} catch ( SQLException e ) {
  e.printStackTrace();
} finally {
  if ( conn != null ) {
      try {
          conn.close();
      } catch ( SQLException e ) {
          e.printStackTrace();
      }
  }
}

More methods

`acceptsURL`

public boolean acceptsURL(String url)
            throws SQLException

The PolyphenyDriver is Polypheny’s implementation of the JDBC Driver interface, designed to facilitate Java applications in connecting and interacting with the Polypheny database system. This implementation ensures seamless integration with Java’s standard JDBC API while harnessing the specific features and capabilities of the Polypheny system. This document will guide you through the intricacies of using the PolyphenyDriver to establish and manage your database connections.

The method acceptsURL( String url ) of the PolyphenyDriver can be used to check if the Polypheny JDBC Driver understands and can potentially connect to the given URL. This method can be particularly useful if your application has to manage connections to multiple types of databases or needs to verify the validity of a connection string before attempting a connection.

The acceptsURL method returns a boolean. It will return true if the driver understands the provided URL, otherwise false.

The method does not establish an actual connection to the database. It simply checks if the URL structure is something the driver can understand.

If the driver recognizes the URL but realizes it is malformed, it still returns true.

Usage:

Driver polyphenyDriver = new org.polypheny.jdbc.PolyphenyDriver();
boolean isSupported = polyphenyDriver.acceptsURL( "jdbc:polypheny://localhost:20591" );

if ( isSupported ) {
    // Proceed with the connection or other logic
} else {
    System.out.println( "Provided URL is supported by the Polypheny JDBC driver." );
}

`getMajorVersion`

public int getMajorVersion()

The method getMajorVersion() of the PolyphenyDriveris designed to help applications retrieve the major version number of the Polypheny JDBC driver, enabling them to manage compatibility and features accordingly.

Usage:

To obtain the major version of the Polypheny JDBC Driver, simply invoke the getMajorVersion() method on an instance of the driver:

Driver polyphenyDriver = new org.polypheny.jdbc.PolyphenyDriver();
int majorVersion = polyphenyDriver.getMajorVersion();

System.out.println( "Polypheny JDBC Driver Major Version: " + majorVersion );

`getMinorVersion`

public int getMinorVersion()

The getMinorVersion() method of the PolyphenyDriver provides applications with the ability to retrieve the minor version number of the Polypheny JDBC driver.

Usage:

To acquire the minor version of the Polypheny JDBC Driver, invoke the getMinorVersion() method on a driver instance:

Driver polyphenyDriver = new org.polypheny.jdbc.PolyphenyDriver();
int minorVersion = polyphenyDriver.getMinorVersion();

System.out.println( "Polypheny JDBC Driver Minor Version: " + minorVersion );

`getParentLogger`

public Logger getParentLogger()
            throws SQLFeatureNotSupportedException

The getParentLogger() method of the PolyphenyDriver is a part of the JDBC specification, designed to retrieve the parent Logger object for a Driver. It helps in getting an understanding of the logging activities of the underlying driver.

However, for the Polypheny JDBC Driver, logging functionality has not been implemented. As a result, invoking the getParentLogger() method will always result in a SQLFeatureNotSupportedException being thrown, indicating that this feature is not currently supported by the driver.

Usage & Expectation:

While developers can technically invoke the getParentLogger() method on a driver instance, they should anticipate a SQLFeatureNotSupportedException as mentioned above:

Driver polyphenyDriver = new org.polypheny.jdbc.PolyphenyDriver();
try {
    Logger parentLogger = polyphenyDriver.getParentLogger();
    // This block will not be reached
} catch ( SQLFeatureNotSupportedException e ) {
    System.out.println( "Logging is not implemented in the Polypheny JDBC Driver." );
}

`getPropertyInfo`

public DriverPropertyInfo[] getPropertyInfo(String url, Properties info)
            throws SQLException

The method getPropertyInfo of the PolyphenyDriver retrieves an array of DriverPropertyInfo objects, providing details about the properties supported and required by the Polypheny JDBC driver. The DriverPropertyInfo objects returned as well as their values is based on the properties already specified and/or set in the url or the Property object passed to this method. This method offers applications such as GUI tools insights into the possible properties they can request form a user, especially when establishing a connection.

DriverPropertyInfo Attributes:

Attribute	Type	Description
`name`	String	Name of the property
`value`	String	Current value of the property
`required`	Boolean	Indicates if the property is mandatory
`description`	String	A brief description of the property
`choices`	String[]	Array of possible choices (only for properties with a limited set of possible values)

Supported Properties:

Property	Description	Choices	Required
`user`	Specifies the username for authentication. If not specified, the database uses the default user.	-	No
`password`	Specifies the password. If not specified, the database assumes no password.	-	No
`autocommit`	Determines if each SQL statement is treated as a transaction.	`true`, `false`	No
`readonly`	Indicates if the connection is in read-only mode. Currently ignored.	`true`, `false`	No
`holdability`	Specifies the holdability of `ResultSet` objects.	`HOLD`, `CLOSE`	No
`isolation`	Indicates the transaction isolation level.	`COMMITTED`, `DIRTY`, `SERIALIZABLE`, `REPEATABLE_READ`	No
`nwtimeout`	Specifies the network timeout in seconds. Corresponds to the JDBC network timeout.	-	No

Usage:

To retrieve properties associated with a given URL and a set of Properties, use the method as follows:

Driver polyphenyDriver = new org.polypheny.jdbc.PolyphenyDriver();
Properties props = new Properties();
// Set any desired properties
DriverPropertyInfo[] infos = polyphenyDriver.getPropertyInfo( "jdbc:polypheny://localhost:20590", props );

// Loop through infos to get details about each property
for ( DriverPropertyInfo info : infos ) {
    System.out.println( info.name + ": " + info.description );
}

`jdbcCompliant`

public boolean jdbcCompliant()

The jdbcCompliant() method of the PolyphenyDriver allows applications to determine if the Polypheny JDBC Driver adheres to the JDBC specification. For the Polypheny JDBC Driver, this method will always return true, indicating that it is fully JDBC compliant.

This compliance assures that the Polypheny JDBC Driver meets the standard requirements set out in the JDBC specification, providing reliable and consistent behavior for applications that rely on said standard.

Usage:

To check the JDBC compliance of the Polypheny JDBC Driver, invoke the jdbcCompliant() method on a driver instance:

Driver polyphenyDriver = new org.polypheny.jdbc.PolyphenyDriver();

if ( polyphenyDriver.jdbcCompliant() ) {
    System.out.println( "The Polypheny JDBC Driver is JDBC compliant." );
} else {
    // This block will never be executed for the Polypheny JDBC Driver
    System.out.println( "The Polypheny JDBC Driver is not JDBC compliant." );
}

Overview

Quick Search Results

JDBC Driver - Driver

Creating a Connection

getConnection

URL Structure

Connection Properties Details

Closing a Connection

More methods

acceptsURL

getMajorVersion

getMinorVersion

getParentLogger

getPropertyInfo

jdbcCompliant

`getConnection`

`acceptsURL`

`getMajorVersion`

`getMinorVersion`

`getParentLogger`

`getPropertyInfo`

`jdbcCompliant`