Package com.firstworks.sqlrelay

Class SQLRConnection

java.lang.Object
com.firstworks.sqlrelay.SQLRConnection
public class SQLRConnection extends Object

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    long
    connection
    connection is used internally, it's just public to make the JNI wrapper work faster.

  • Constructor Summary

    Constructors
    Constructor
    Description
    SQLRConnection(String server, short port, String socket, String user, String password, int retrytime, int tries)
    Initiates a connection to "server" on "port" or to the unix "socket" on the local machine and auths with "user" and "password".

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    autoCommitOff()
    Instructs the database to wait for the client to tell it when to commit.
    boolean
    autoCommitOn()
    Instructs the database to perform a commit after every successful query.
    boolean
    begin()
    Begins a transaction.
    String
    bindFormat()
    Returns a string representing the bind variable format used by the database.
    String
    clientVersion()
    Returns the version of the sqlrelay client software
    boolean
    commit()
    Issues a commit.
    String
    dbHostName()
    Returns the host name of the database
    String
    dbIpAddress()
    Returns the ip address of the database
    String
    dbVersion()
    Returns the version of the database
    void
    debugOff()
    Turns debugging off.
    void
    debugOn()
    Causes verbose debugging information to be sent to standard output.
    void
    delete()
    Disconnects and ends the session if it hasn't been ended already.
    void
    disableEncryption()
    Disables encryption.
    void
    enableKerberos(String service, String mech, String flags)
    Enables Kerberos authentication and encryption.
    void
    enableTls(String version, String cert, String password, String ciphers, String validate, String ca, short depth)
    Enables TLS/SSL encryption, and optionally authentication.
    void
    endSession()
    Ends the session.
    String
    errorMessage()
    If an operation failed and generated an error, the error message is available here.
    long
    errorNumber()
    If an operation failed and generated an error, the error number is available here.
    boolean
    getBindVariableDelimiterAtSignSupported()
    Returns true if at-signs (@) are considered to be valid bind variable delimiters.
    boolean
    getBindVariableDelimiterColonSupported()
    Returns true if colons (:) are considered to be valid bind variable delimiters.
    boolean
    getBindVariableDelimiterDollarSignSupported()
    Returns true if dollar signs ($) are considered to be valid bind variable delimiters.
    boolean
    getBindVariableDelimiterQuestionMarkSupported()
    Returns true if question marks (?) are considered to be valid bind variable delimiters.
    String
    getClientInfo()
    Returns the string that was set by setClientInfo().
    short
    getConnectionPort()
    Returns the inet port that the connection is communicating over.
    String
    getConnectionSocket()
    Returns the unix socket that the connection is communicating over.
    String
    getCurrentDatabase()
    Returns the database/schema that is currently in use
    String
    getCurrentSchema()
    Returns the schema that is currently in use
    boolean
    getDebug()
    Returns 0 if debugging is off and 1 if debugging is on.
    long
    getLastInsertId()
    Returns the value of the autoincrement column for the last insert
    String
    identify()
    Returns the type of database: oracle, postgresql, mysql, etc.
    String
    nextvalFormat()
    Returns a string representing the format of the sequence nextval command used in the database.
    boolean
    ping()
    Returns 1 if the database is up and 0 if it's down.
    boolean
    resumeSession(short port, String socket)
    Resumes a session previously left open using suspendSession().
    boolean
    rollback()
    Issues a rollback.
    boolean
    selectDatabase(String database)
    Sets the current database/schema to "database"
    String
    serverVersion()
    Returns the version of the sqlrelay server software
    void
    setBindVariableDelimiters(String delimiters)
    Sets which delimiters are used to identify bind variables in countBindVariables() and validateBinds().
    boolean
    setClientInfo(String clientinfo)
    Allows you to set a string that will be passed to the server and ultimately included in server-side logging along with queries that were run by this instance of the client.
    void
    setConnectTimeout(int timeoutsec, int timeoutusec)
    Sets the server connect timeout in seconds and milliseconds.
    boolean
    setDebugFile(String debugfile)
    Allows you to specify a file to write debug to.
    void
    setResponseTimeout(int timeoutsec, int timeoutusec)
    Sets the response timeout (for queries, commits, rollbacks, pings, etc.) in seconds and milliseconds.
    boolean
    suspendSession()
    Disconnects this connection from the current session but leaves the session open so that another connection can connect to it using resumeSession().

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • connection

      public long connection
      connection is used internally, it's just public to make the JNI wrapper work faster.

  • Constructor Details

    • SQLRConnection

      public SQLRConnection(String server, short port, String socket, String user, String password, int retrytime, int tries)
      Initiates a connection to "server" on "port" or to the unix "socket" on the local machine and auths with "user" and "password". Failed connections will be retried for "tries" times, waiting "retrytime" seconds between each try. If "tries" is 0 then retries will continue forever. If "retrytime" is 0 then retries will be attempted on a default interval. If "server" is a comma-separated list of hosts, then an attempt will be made to connect to each until the attempt succeeds, or there are no more hosts left to try. If the "socket" parameter is neither NULL nor "" then an attempt will be made to connect through it before attempting to connect to "server" on "port". If it is NULL or "" then no attempt will be made to connect through the socket.

  • Method Details

    • delete

      public void delete()
      Disconnects and ends the session if it hasn't been ended already.

    • setConnectTimeout

      public void setConnectTimeout(int timeoutsec, int timeoutusec)
      Sets the server connect timeout in seconds and milliseconds. Setting either parameter to -1 disables the timeout. You can also set this timeout using the SQLR_CLIENT_CONNECT_TIMEOUT environment variable.

    • setResponseTimeout

      public void setResponseTimeout(int timeoutsec, int timeoutusec)
      Sets the response timeout (for queries, commits, rollbacks, pings, etc.) in seconds and milliseconds. Setting either parameter to -1 disables the timeout. You can also set this timeout using the SQLR_CLIENT_RESPONSE_TIMEOUT environment variable.

    • setBindVariableDelimiters

      public void setBindVariableDelimiters(String delimiters)
      Sets which delimiters are used to identify bind variables in countBindVariables() and validateBinds(). Valid delimiters include ?,:,@, and $. Defaults to "?:@$"

    • getBindVariableDelimiterQuestionMarkSupported

      public boolean getBindVariableDelimiterQuestionMarkSupported()
      Returns true if question marks (?) are considered to be valid bind variable delimiters.

    • getBindVariableDelimiterColonSupported

      public boolean getBindVariableDelimiterColonSupported()
      Returns true if colons (:) are considered to be valid bind variable delimiters.

    • getBindVariableDelimiterAtSignSupported

      public boolean getBindVariableDelimiterAtSignSupported()
      Returns true if at-signs (@) are considered to be valid bind variable delimiters.

    • getBindVariableDelimiterDollarSignSupported

      public boolean getBindVariableDelimiterDollarSignSupported()
      Returns true if dollar signs ($) are considered to be valid bind variable delimiters.

    • enableKerberos

      public void enableKerberos(String service, String mech, String flags)
      Enables Kerberos authentication and encryption. "service" indicates the Kerberos service name of the SQL Relay server. If left empty or NULL then the service name "sqlrelay" will be used. "sqlrelay" is the default service name of the SQL Relay server. Note that on Windows platforms the service name must be fully qualified, including the host and realm name. For example: "sqlrelay/sqlrserver.firstworks.com@AD.FIRSTWORKS.COM". "mech" indicates the specific Kerberos mechanism to use. On Linux/Unix platforms, this should be a string representation of the mechnaism's OID, such as: { 1 2 840 113554 1 2 2 } On Windows platforms, this should be a string like: Kerberos If left empty or NULL then the default mechanism will be used. Only set this if you know that you have a good reason to. "flags" indicates what Kerberos flags to use. Multiple flags may be specified, separated by commas. If left empty or NULL then a defalt set of flags will be used. Only set this if you know that you have a good reason to. Valid flags include: * GSS_C_MUTUAL_FLAG * GSS_C_REPLAY_FLAG * GSS_C_SEQUENCE_FLAG * GSS_C_CONF_FLAG * GSS_C_INTEG_FLAG For a full list of flags, consult the GSSAPI documentation, though note that only the flags listed above are supported on Windows.

    • enableTls

      public void enableTls(String version, String cert, String password, String ciphers, String validate, String ca, short depth)
      Enables TLS/SSL encryption, and optionally authentication. "version" specifies the TLS/SSL protocol version that the client will attempt to use. Valid values include SSL2, SSL3, TLS1, TLS1.1, TLS1.2 or any more recent version of TLS, as supported by and enabled in the underlying TLS/SSL library. If left blank or empty then the highest supported version will be negotiated. "cert" is the file name of the certificate chain file to send to the SQL Relay server. This is only necessary if the SQL Relay server is configured to authenticate and authorize clients by certificate. If "cert" contains a password-protected private key, then "password" may be supplied to access it. If the private key is not password-protected, then this argument is ignored, and may be left empty or NULL. "ciphers" is a list of ciphers to allow. Ciphers may be separated by spaces, commas, or colons. If "ciphers" is empty or NULL then a default set is used. Only set this if you know that you have a good reason to. For a list of valid ciphers on Linux/Unix platforms, see: man ciphers For a list of valid ciphers on Windows platforms, see: https://msdn.microsoft.com/en-us/library/windows/desktop/aa375549%28v=vs.85%29.aspx On Windows platforms, the ciphers (alg_id's) should omit CALG_ and may be given with underscores or dashes. For example: 3DES_112 "validate" indicates whether to validate the SQL Relay's server certificate, and may be set to one of the following: "no" - Don't validate the server's certificate. "ca" - Validate that the server's certificate was signed by a trusted certificate authority. "ca+host" - Perform "ca" validation and also validate that one of the subject altenate names (or the common name if no SANs are present) in the certificate matches the host parameter. (Falls back to "ca" validation when a unix socket is used.) "ca+domain" - Perform "ca" validation and also validate that the domain name of one of the subject alternate names (or the common name if no SANs are present) in the certificate matches the domain name of the host parameter. (Falls back to "ca" validation when a unix socket is used.) "ca" is the location of a certificate authority file to use, in addition to the system's root certificates, when validating the SQL Relay server's certificate. This is useful if the SQL Relay server's certificate is self-signed. On Windows, "ca" must be a file name. On non-Windows systems, "ca" can be either a file or directory name. If it is a directory name, then all certificate authority files found in that directory will be used. If it a file name, then only that file will be used. Note that the supported "cert" and "ca" file formats may vary between platforms. A variety of file formats are generally supported on Linux/Unix platfoms (.pem, .pfx, etc.) but only the .pfx format is currently supported on Windows.

    • disableEncryption

      public void disableEncryption()
      Disables encryption.

    • endSession

      public void endSession()
      Ends the session.

    • suspendSession

      public boolean suspendSession()
      Disconnects this connection from the current session but leaves the session open so that another connection can connect to it using resumeSession().

    • getConnectionPort

      public short getConnectionPort()
      Returns the inet port that the connection is communicating over. This parameter may be passed to another connection for use in the resumeSession() method. Note: the value returned by this method is only valid after a call to suspendSession().

    • getConnectionSocket

      public String getConnectionSocket()
      Returns the unix socket that the connection is communicating over. This parameter may be passed to another connection for use in the resumeSession() method. Note: the value returned by this method is only valid after a call to suspendSession().

    • resumeSession

      public boolean resumeSession(short port, String socket)
      Resumes a session previously left open using suspendSession(). Returns 1 on success and 0 on failure.

    • ping

      public boolean ping()
      Returns 1 if the database is up and 0 if it's down.

    • identify

      public String identify()
      Returns the type of database: oracle, postgresql, mysql, etc.

    • dbVersion

      public String dbVersion()
      Returns the version of the database

    • dbHostName

      public String dbHostName()
      Returns the host name of the database

    • dbIpAddress

      public String dbIpAddress()
      Returns the ip address of the database

    • serverVersion

      public String serverVersion()
      Returns the version of the sqlrelay server software

    • clientVersion

      public String clientVersion()
      Returns the version of the sqlrelay client software

    • bindFormat

      public String bindFormat()
      Returns a string representing the bind variable format used by the database. For example: ? - database uses a ? to represent a bind variable * - database uses a @ followed by any characters to represent a bind variable $1 - database uses a $ followed by a number to represent a bind variable :* - database uses a : followed by any characters to represent a bind variable

    • nextvalFormat

      public String nextvalFormat()
      Returns a string representing the format of the sequence nextval command used in the database. The format will contain a %s in place of the sequence name. For example: (nextval for %s) next value for %s nextval('%s') %s.nextval Returns an empty string if the database does not support sequences.

    • selectDatabase

      public boolean selectDatabase(String database)
      Sets the current database/schema to "database"

    • getCurrentDatabase

      public String getCurrentDatabase()
      Returns the database/schema that is currently in use

    • getCurrentSchema

      public String getCurrentSchema()
      Returns the schema that is currently in use

    • getLastInsertId

      public long getLastInsertId()
      Returns the value of the autoincrement column for the last insert

    • autoCommitOn

      public boolean autoCommitOn()
      Instructs the database to perform a commit after every successful query.

    • autoCommitOff

      public boolean autoCommitOff()
      Instructs the database to wait for the client to tell it when to commit.

    • begin

      public boolean begin()
      Begins a transaction. Returns true if the begin succeeded, false if it failed. If the database automatically begins a new transaction when a commit or rollback is issued then this doesn't do anything unless SQL Relay is faking transaction blocks.

    • commit

      public boolean commit()
      Issues a commit. Returns true if the commit succeeded, false if it failed.

    • rollback

      public boolean rollback()
      Issues a rollback. Returns true if the rollback succeeded, false if it failed.

    • errorMessage

      public String errorMessage()
      If an operation failed and generated an error, the error message is available here. If there is no error then this method returns NULL.

    • errorNumber

      public long errorNumber()
      If an operation failed and generated an error, the error number is available here. If there is no error then this method returns 0.

    • debugOn

      public void debugOn()
      Causes verbose debugging information to be sent to standard output. Another way to do this is to start a query with "-- debug\n". Yet another way is to set the environment variable SQLR_CLIENT_DEBUG to "ON"

    • debugOff

      public void debugOff()
      Turns debugging off.

    • getDebug

      public boolean getDebug()
      Returns 0 if debugging is off and 1 if debugging is on.

    • setDebugFile

      public boolean setDebugFile(String debugfile)
      Allows you to specify a file to write debug to. Setting "filename" to NULL or an empty string causes debug to be written to standard output (the default).

    • setClientInfo

      public boolean setClientInfo(String clientinfo)
      Allows you to set a string that will be passed to the server and ultimately included in server-side logging along with queries that were run by this instance of the client.

    • getClientInfo

      public String getClientInfo()
      Returns the string that was set by setClientInfo().