ldbc.sql.Connection.scala Maven / Gradle / Ivy
Show all versions of ldbc-sql_3 Show documentation
/**
* Copyright (c) 2023-2024 by Takahiko Tominaga
* This software is licensed under the MIT License (MIT).
* For more information see LICENSE or https://opensource.org/licenses/MIT
*/
package ldbc.sql
/**
* A connection (session) with a specific database. SQL statements are executed and results are returned within the
* context of a connection.
*
* A Connection object's database is able to provide information describing its tables, its supported SQL grammar, its
* stored procedures, the capabilities of this connection, and so on. This information is obtained with the getMetaData
* method.
*
* Note: When configuring a Connection, JDBC applications should use the appropriate Connection method such as
* setAutoCommit or setTransactionIsolation. Applications should not invoke SQL commands directly to change the
* connection's configuration when there is a JDBC method available. By default a Connection object is in auto-commit
* mode, which means that it automatically commits changes after executing each statement. If auto-commit mode has been
* disabled, the method commit must be called explicitly in order to commit changes; otherwise, database changes will
* not be saved.
*
* A new Connection object created using the JDBC 2.1 core API has an initially empty type map associated with it. A
* user may enter a custom mapping for a UDT in this type map. When a UDT is retrieved from a data source with the
* method ResultSet.getObject, the getObject method will check the connection's type map to see if there is an entry for
* that UDT. If so, the getObject method will map the UDT to the class indicated. If there is no entry, the UDT will be
* mapped using the standard mapping.
*
* A user may create a new type map, which is a java.util.Map object, make an entry in it, and pass it to the java.sql
* methods that can perform custom mapping. In this case, the method will use the given type map instead of the one
* associated with the connection.
* @tparam F
* The effect type
*/
trait Connection[F[_]]:
/**
* Creates a Statement object for sending
* SQL statements to the database.
* SQL statements without parameters are normally
* executed using Statement objects. If the same SQL statement
* is executed many times, it may be more efficient to use a
* PreparedStatement object.
*
* Result sets created using the returned Statement
* object will by default be type TYPE_FORWARD_ONLY
* and have a concurrency level of CONCUR_READ_ONLY.
* The holdability of the created result sets can be determined by
* calling [[getHoldability]].
*
* @return a new default Statement object
*/
def createStatement(): F[Statement[F]]
/**
* Creates a PreparedStatement object for sending
* parameterized SQL statements to the database.
*
* A SQL statement with or without IN parameters can be
* pre-compiled and stored in a PreparedStatement object. This
* object can then be used to efficiently execute this statement
* multiple times.
*
*
Note: This method is optimized for handling
* parametric SQL statements that benefit from precompilation. If
* the driver supports precompilation,
* the method prepareStatement will send
* the statement to the database for precompilation. Some drivers
* may not support precompilation. In this case, the statement may
* not be sent to the database until the PreparedStatement
* object is executed. This has no direct effect on users; however, it does
* affect which methods throw certain SQLException objects.
*
* Result sets created using the returned PreparedStatement
* object will by default be type TYPE_FORWARD_ONLY
* and have a concurrency level of CONCUR_READ_ONLY.
* The holdability of the created result sets can be determined by
* calling [[getHoldability]].
*
* @param sql an SQL statement that may contain one or more '?' IN
* parameter placeholders
* @return a new default PreparedStatement object containing the
* pre-compiled SQL statement
*/
def prepareStatement(sql: String): F[PreparedStatement[F]]
/**
* Creates a CallableStatement object for calling
* database stored procedures.
* The CallableStatement object provides
* methods for setting up its IN and OUT parameters, and
* methods for executing the call to a stored procedure.
*
*
Note: This method is optimized for handling stored
* procedure call statements. Some drivers may send the call
* statement to the database when the method prepareCall
* is done; others
* may wait until the CallableStatement object
* is executed. This has no
* direct effect on users; however, it does affect which method
* throws certain SQLExceptions.
*
* Result sets created using the returned CallableStatement
* object will by default be type TYPE_FORWARD_ONLY
* and have a concurrency level of CONCUR_READ_ONLY.
* The holdability of the created result sets can be determined by
* calling {@link # getHoldability}.
*
* @param sql an SQL statement that may contain one or more '?'
* parameter placeholders. Typically this statement is specified using JDBC
* call escape syntax.
* @return a new default CallableStatement object containing the
* pre-compiled SQL statement
*/
def prepareCall(sql: String): F[CallableStatement[F]]
/**
* Converts the given SQL statement into the system's native SQL grammar.
* A driver may convert the JDBC SQL grammar into its system's
* native SQL grammar prior to sending it. This method returns the
* native form of the statement that the driver would have sent.
*
* @param sql an SQL statement that may contain one or more '?'
* parameter placeholders
* @return the native form of this statement
*/
def nativeSQL(sql: String): F[String]
/**
* Sets this connection's auto-commit mode to the given state.
* If a connection is in auto-commit mode, then all its SQL
* statements will be executed and committed as individual
* transactions. Otherwise, its SQL statements are grouped into
* transactions that are terminated by a call to either
* the method commit or the method rollback.
* By default, new connections are in auto-commit
* mode.
*
* The commit occurs when the statement completes. The time when the statement
* completes depends on the type of SQL Statement:
*
* - For DML statements, such as Insert, Update or Delete, and DDL statements,
* the statement is complete as soon as it has finished executing.
*
- For Select statements, the statement is complete when the associated result
* set is closed.
*
- For
CallableStatement objects or for statements that return
* multiple results, the statement is complete
* when all of the associated result sets have been closed, and all update
* counts and output parameters have been retrieved.
*
*
* NOTE: If this method is called during a transaction and the
* auto-commit mode is changed, the transaction is committed. If
* setAutoCommit is called and the auto-commit mode is
* not changed, the call is a no-op.
*
* @param autoCommit true to enable auto-commit mode;
* false to disable it
*/
def setAutoCommit(autoCommit: Boolean): F[Unit]
/**
* Retrieves the current auto-commit mode for this Connection
* object.
*
* @return the current state of this Connection object's
* auto-commit mode
*/
def getAutoCommit(): F[Boolean]
/**
* Makes all changes made since the previous
* commit/rollback permanent and releases any database locks
* currently held by this Connection object.
* This method should be
* used only when auto-commit mode has been disabled.
*/
def commit(): F[Unit]
/**
* Undoes all changes made in the current transaction
* and releases any database locks currently held
* by this Connection object. This method should be
* used only when auto-commit mode has been disabled.
*/
def rollback(): F[Unit]
/**
* Releases this Connection object's database and JDBC resources
* immediately instead of waiting for them to be automatically released.
*
* Calling the method close on a Connection
* object that is already closed is a no-op.
*
* It is strongly recommended that an application explicitly
* commits or rolls back an active transaction prior to calling the
* close method. If the close method is called
* and there is an active transaction, the results are implementation-defined.
*/
def close(): F[Unit]
/**
* Retrieves whether this Connection object has been
* closed. A connection is closed if the method close
* has been called on it or if certain fatal errors have occurred.
* This method is guaranteed to return true only when
* it is called after the method Connection.close has
* been called.
*
* This method generally cannot be called to determine whether a
* connection to a database is valid or invalid. A typical client
* can determine that a connection is invalid by catching any
* exceptions that might be thrown when an operation is attempted.
*
* @return true if this Connection object
* is closed; false if it is still open
*/
def isClosed(): F[Boolean]
/**
* Retrieves a DatabaseMetaData object that contains
* metadata about the database to which this
* Connection object represents a connection.
* The metadata includes information about the database's
* tables, its supported SQL grammar, its stored
* procedures, the capabilities of this connection, and so on.
*
* @return a DatabaseMetaData object for this
* Connection object
*/
def getMetaData(): F[DatabaseMetaData[F]]
/**
* Puts this connection in read-only mode as a hint to the driver to enable
* database optimizations.
*
* @param isReadOnly
* true enables read-only mode; false disables it
*/
def setReadOnly(isReadOnly: Boolean): F[Unit]
/**
* Retrieves whether this Connection object is in read-only mode.
*
* @return
* true if this Connection object is read-only; false otherwise
*/
def isReadOnly: F[Boolean]
/**
* Sets the given catalog name in order to select
* a subspace of this Connection object's database
* in which to work.
*
* If the driver does not support catalogs, it will
* silently ignore this request.
*
* Calling {@code setCatalog} has no effect on previously created or prepared
* {@code Statement} objects. It is implementation defined whether a DBMS
* prepare operation takes place immediately when the {@code Connection}
* method {@code prepareStatement} or {@code prepareCall} is invoked.
* For maximum portability, {@code setCatalog} should be called before a
* {@code Statement} is created or prepared.
*
* @param catalog the name of a catalog (subspace in this
* Connection object's database) in which to work
*/
def setCatalog(catalog: String): F[Unit]
/**
* Retrieves this Connection object's current catalog name.
*
* @return the current catalog name or None if there is none
*/
def getCatalog(): F[String]
/**
* Attempts to change the transaction isolation level for this Connection object to the one given. The constants
* defined in the interface Connection are the possible transaction isolation levels.
*
* Note: If this method is called during a transaction, the result is implementation-defined.
*
* @param level
* one of the following Connection constants: Connection.TRANSACTION_READ_UNCOMMITTED,
* Connection.TRANSACTION_READ_COMMITTED, Connection.TRANSACTION_REPEATABLE_READ, or
* Connection.TRANSACTION_SERIALIZABLE. (Note that Connection.TRANSACTION_NONE cannot be used because it specifies
* that transactions are not supported.)
*/
def setTransactionIsolation(level: Int): F[Unit]
/**
* Retrieves this Connection object's current transaction isolation level.
*
* @return
* the current transaction isolation level, which will be one of the following constants:
* Connection.TRANSACTION_READ_UNCOMMITTED, Connection.TRANSACTION_READ_COMMITTED,
* Connection.TRANSACTION_REPEATABLE_READ, Connection.TRANSACTION_SERIALIZABLE, or Connection.TRANSACTION_NONE.
*/
def getTransactionIsolation(): F[Int]
/**
* Creates a Statement object that will generate
* ResultSet objects with the given type and concurrency.
* This method is the same as the createStatement method
* above, but it allows the default result set
* type and concurrency to be overridden.
* The holdability of the created result sets can be determined by
* calling {@link #getHoldability}.
*
* @param resultSetType a result set type; one of
* ResultSet.TYPE_FORWARD_ONLY,
* ResultSet.TYPE_SCROLL_INSENSITIVE, or
* ResultSet.TYPE_SCROLL_SENSITIVE
* @param resultSetConcurrency a concurrency type; one of
* ResultSet.CONCUR_READ_ONLY or
* ResultSet.CONCUR_UPDATABLE
* @return a new Statement object that will generate
* ResultSet objects with the given type and
* concurrency
*/
def createStatement(resultSetType: Int, resultSetConcurrency: Int): F[Statement[F]]
/**
* Creates a PreparedStatement object that will generate
* ResultSet objects with the given type and concurrency.
* This method is the same as the prepareStatement method
* above, but it allows the default result set
* type and concurrency to be overridden.
* The holdability of the created result sets can be determined by
* calling {@link #getHoldability}.
*
* @param sql a String object that is the SQL statement to
* be sent to the database; may contain one or more '?' IN
* parameters
* @param resultSetType a result set type; one of
* ResultSet.TYPE_FORWARD_ONLY,
* ResultSet.TYPE_SCROLL_INSENSITIVE, or
* ResultSet.TYPE_SCROLL_SENSITIVE
* @param resultSetConcurrency a concurrency type; one of
* ResultSet.CONCUR_READ_ONLY or
* ResultSet.CONCUR_UPDATABLE
* @return a new PreparedStatement object containing the
* pre-compiled SQL statement that will produce ResultSet
* objects with the given type and concurrency
*/
def prepareStatement(sql: String, resultSetType: Int, resultSetConcurrency: Int): F[PreparedStatement[F]]
/**
* Creates a CallableStatement object that will generate
* ResultSet objects with the given type and concurrency.
* This method is the same as the prepareCall method
* above, but it allows the default result set
* type and concurrency to be overridden.
* The holdability of the created result sets can be determined by
* calling {@link # getHoldability}.
*
* @param sql a String object that is the SQL statement to
* be sent to the database; may contain on or more '?' parameters
* @param resultSetType a result set type; one of
* ResultSet.TYPE_FORWARD_ONLY,
* ResultSet.TYPE_SCROLL_INSENSITIVE, or
* ResultSet.TYPE_SCROLL_SENSITIVE
* @param resultSetConcurrency a concurrency type; one of
* ResultSet.CONCUR_READ_ONLY or
* ResultSet.CONCUR_UPDATABLE
* @return a new CallableStatement object containing the
* pre-compiled SQL statement that will produce ResultSet
* objects with the given type and concurrency
*/
def prepareCall(sql: String, resultSetType: Int, resultSetConcurrency: Int): F[CallableStatement[F]]
/**
* Creates a default PreparedStatement object that has
* the capability to retrieve auto-generated keys. The given constant
* tells the driver whether it should make auto-generated keys
* available for retrieval. This parameter is ignored if the SQL statement
* is not an INSERT statement, or an SQL statement able to return
* auto-generated keys (the list of such statements is vendor-specific).
*
* Note: This method is optimized for handling
* parametric SQL statements that benefit from precompilation. If
* the driver supports precompilation,
* the method prepareStatement will send
* the statement to the database for precompilation. Some drivers
* may not support precompilation. In this case, the statement may
* not be sent to the database until the PreparedStatement
* object is executed. This has no direct effect on users; however, it does
* affect which methods throw certain SQLExceptions.
*
* Result sets created using the returned PreparedStatement
* object will by default be type TYPE_FORWARD_ONLY
* and have a concurrency level of CONCUR_READ_ONLY.
* The holdability of the created result sets can be determined by
* calling {@link #getHoldability}.
*
* @param sql an SQL statement that may contain one or more '?' IN
* parameter placeholders
* @param autoGeneratedKeys a flag indicating whether auto-generated keys
* should be returned; one of
* Statement.RETURN_GENERATED_KEYS or
* Statement.NO_GENERATED_KEYS
* @return a new PreparedStatement object, containing the
* pre-compiled SQL statement, that will have the capability of
* returning auto-generated keys
*/
def prepareStatement(
sql: String,
autoGeneratedKeys: Int
): F[PreparedStatement[F]]
/**
* Sets the schema name that will be used for subsequent queries.
*
* Calling setSchema has no effect on previously created or prepared Statement objects.
* It is implementation defined whether a DBMS prepare operation takes place immediately when the Connection method [[statement]] or [[clientPreparedStatement]], [[serverPreparedStatement]] is invoked.
* For maximum portability, setSchema should be called before a Statement is created or prepared.
*
* @param schema
* the name of a schema in which to work
*/
def setSchema(schema: String): F[Unit]
/**
* Retrieves this Connection object's current schema name.
*
* @return
* the current schema name or null if there is none
*/
def getSchema(): F[String]
/**
* Returns true if the connection has not been closed and is still valid. The driver shall submit a query on the
* connection or use some other mechanism that positively verifies the connection is still valid when this method is
* called.
*
* The query submitted by the driver to validate the connection shall be executed in the context of the current
* transaction.
*
* @param timeout
* The time in seconds to wait for the database operation used to validate the connection to complete. If the
* timeout period expires before the operation completes, this method returns false. A value of 0 indicates a
* timeout is not applied to the database operation.
* @return
* true if the connection is valid, false otherwise
*/
def isValid(timeout: Int): F[Boolean]
/**
* Creates an unnamed savepoint in the current transaction and returns the new Savepoint object that represents it.
* if setSavepoint is invoked outside of an active transaction, a transaction will be started at this newly created savepoint.
*
* @return
* the new Savepoint object
*/
def setSavepoint(): F[Savepoint]
/**
* Creates a savepoint with the given name in the current transaction and returns the new Savepoint object that represents it.
* if setSavepoint is invoked outside of an active transaction, a transaction will be started at this newly created savepoint.
*
* @param name
* a String containing the name of the savepoint
* @return
* the new Savepoint object
*/
def setSavepoint(name: String): F[Savepoint]
/**
* Undoes all changes made after the given Savepoint object was set.
* This method should be used only when auto-commit has been disabled.
*
* @param savepoint
* the Savepoint object to roll back to
*/
def rollback(savepoint: Savepoint): F[Unit]
/**
* Removes the specified Savepoint and subsequent Savepoint objects from the current transaction.
* Any reference to the savepoint after it have been removed will cause an SQLException to be thrown.
*
* @param savepoint
* the Savepoint object to release
*/
def releaseSavepoint(savepoint: Savepoint): F[Unit]
object Connection:
/**
* A constant indicating that transactions are not supported.
*/
val TRANSACTION_NONE: Int = 0
/**
* A constant indicating that
* dirty reads, non-repeatable reads and phantom reads can occur.
* This level allows a row changed by one transaction to be read
* by another transaction before any changes in that row have been
* committed (a "dirty read"). If any of the changes are rolled back,
* the second transaction will have retrieved an invalid row.
*/
val TRANSACTION_READ_UNCOMMITTED: Int = 1
/**
* A constant indicating that
* dirty reads are prevented; non-repeatable reads and phantom
* reads can occur. This level only prohibits a transaction
* from reading a row with uncommitted changes in it.
*/
val TRANSACTION_READ_COMMITTED: Int = 2
/**
* A constant indicating that
* dirty reads and non-repeatable reads are prevented; phantom
* reads can occur. This level prohibits a transaction from
* reading a row with uncommitted changes in it, and it also
* prohibits the situation where one transaction reads a row,
* a second transaction alters the row, and the first transaction
* rereads the row, getting different values the second time
* (a "non-repeatable read").
*/
val TRANSACTION_REPEATABLE_READ: Int = 4
/**
* A constant indicating that
* dirty reads, non-repeatable reads and phantom reads are prevented.
* This level includes the prohibitions in
* TRANSACTION_REPEATABLE_READ and further prohibits the
* situation where one transaction reads all rows that satisfy
* a WHERE condition, a second transaction inserts a row that
* satisfies that WHERE condition, and the first transaction
* rereads for the same condition, retrieving the additional
* "phantom" row in the second read.
*/
val TRANSACTION_SERIALIZABLE: Int = 8