com.vertica.jdbc.kv

Interface VerticaRoutableConnection

All Superinterfaces:

java.sql.Connection, VerticaConnection, java.sql.Wrapper

public interface VerticaRoutableConnection
extends VerticaConnection

Provides advanced routing capabilities beyond those of a normal VerticaConnection. The VerticaRoutableConnection provides access to the VGet, which performs efficient key-based lookups. Connections returned by the driver will implement this interface when the EnableRoutableQueries connection property is set to true.

The VerticaRoutableConnection maintains an internal pool of connections and a cache of table metadata that is shared by all VGets that are produced by this connection's prepareGet(String, String) method. It is also a fully-fledged JDBC connection on its own. It supports all the functionality that a VerticaConnection supports. When this connection is closed, all pooled connections managed by this VerticaRoutableConnection and all child VGets are closed too.

By default, a VerticaRoutableConnection's internal pool will use no more than 20 concurrent connections to a cluster and no more than 5 concurrent connections to a given node (these are in addition to the single connection used for normal JDBC Connection operations). Those numbers can be overridden with the MaxPooledConnections and MaxPooledConnectionsPerNode connection properties. Using a large number of connections can improve VGet performance, but it can be taxing to keep many connections open on a busy cluster. It is important for users to configure these numbers optimally for their cluster's workload.

Because VGet operations utilize multiple JDBC connections (and multiple Vertica sessions), they can not honor the connection's JDBC transaction semantics. If consistency across multiple VGet operations is required, history must be enabled. Only VGet operations that have this limitation; other operations on this connection do follow normal transaction semantics. The supportsConsistentRead() method can be used to check if history is enabled. When supportsConsistentRead() returns true, the beginConsistentRead() and endConsistentRead() methods can be used to guarantee that all child VGet operations occur at the same epoch.

Field Summary

Fields inherited from interface java.sql.Connection

TRANSACTION_NONE, TRANSACTION_READ_COMMITTED, TRANSACTION_READ_UNCOMMITTED, TRANSACTION_REPEATABLE_READ, TRANSACTION_SERIALIZABLE

Method Summary

Methods

Modifier and Type	Method and Description
void	beginConsistentRead() All subsequent VGet accesses will read from a consistent snapshot acquired at the time this method call is made.
void	clearMetadataCache() Clears the cached projection metadata used by all VGets constructed by this connection.
VerticaRoutableExecutor	createRoutableExecutor(java.lang.String schema, java.lang.String tableOrProjection) Create a KV query executor for a table/projection.
void	endConsistentRead() Stops using snapshot acquired by the last call to beginConsistentRead().
VGet	prepareGet(java.lang.String schema, java.lang.String tableOrProj) Creates a VGet for the given table or projection.
boolean	supportsConsistentRead() Checks to see if the beginConsistentRead() and endConsistentRead() methods are supported.

Methods inherited from interface com.vertica.jdbc.VerticaConnection

getLastDatabaseError, getProperty, setProperty

Methods inherited from interface java.sql.Connection

clearWarnings, close, commit, createArrayOf, createBlob, createClob, createNClob, createSQLXML, createStatement, createStatement, createStatement, createStruct, getAutoCommit, getCatalog, getClientInfo, getClientInfo, getHoldability, getMetaData, getTransactionIsolation, getTypeMap, getWarnings, isClosed, isReadOnly, isValid, nativeSQL, prepareCall, prepareCall, prepareCall, prepareStatement, prepareStatement, prepareStatement, prepareStatement, prepareStatement, prepareStatement, releaseSavepoint, rollback, rollback, setAutoCommit, setCatalog, setClientInfo, setClientInfo, setHoldability, setReadOnly, setSavepoint, setSavepoint, setTransactionIsolation, setTypeMap

Methods inherited from interface java.sql.Wrapper

isWrapperFor, unwrap

Method Detail

prepareGet

VGet prepareGet(java.lang.String schema,
              java.lang.String tableOrProj)
                throws java.sql.SQLException

Creates a VGet for the given table or projection.

Parameters:

schema - The schema name of the table or projection to get values from.

tableOrProj - The name of a table or projection to get values from.

Returns:

A VGet instance for the provided table/projection.

Throws:

java.sql.SQLException - Thrown if the schema or table does not exist, or if a database access error occurs.

clearMetadataCache

void clearMetadataCache()
                        throws java.sql.SQLException

Clears the cached projection metadata used by all VGets constructed by this connection.

Throws:

java.sql.SQLException - Thrown if a database access error occurs.

supportsConsistentRead

boolean supportsConsistentRead()
                               throws java.sql.SQLException

Checks to see if the beginConsistentRead() and endConsistentRead() methods are supported. To support consistent reads, historical queries must be enabled in the database.

Returns:

true if history retention is enabled on this database cluster.

Throws:

java.sql.SQLException - Thrown if a database access error occurs.

See Also:

beginConsistentRead(), endConsistentRead()

beginConsistentRead

void beginConsistentRead()
                         throws java.sql.SQLException

All subsequent VGet accesses will read from a consistent snapshot acquired at the time this method call is made. Care must be taken to configure Vertica to maintain historical snapshots (see AHM management in the Vertica documentation). If Vertica invalidates the snapshot, subsequent accesses will fail with error "Can't run historical queries at epochs prior to the Ancient History Mark"

Throws:

java.sql.SQLException - Thrown if snapshot cannot be acquired or if a database access error occurs.

See Also:

endConsistentRead()

endConsistentRead

void endConsistentRead()
                       throws java.sql.SQLException

Stops using snapshot acquired by the last call to beginConsistentRead().

Throws:

java.sql.SQLException - Thrown if a database access error occurs.

See Also:

beginConsistentRead()

createRoutableExecutor

VerticaRoutableExecutor createRoutableExecutor(java.lang.String schema,
                                             java.lang.String tableOrProjection)
                                               throws java.sql.SQLException

Create a KV query executor for a table/projection.

Throws:

java.sql.SQLException - Thrown if a database access error occurs.