Session (MySQL Connector/J X DevAPI Reference)

All Superinterfaces:

AutoCloseable
```
public interface Session
extends AutoCloseable
```
X DevAPI introduces a new, high-level database connection concept that is called Session. When working with X DevAPI it is important to understand this new Session concept which is different from working with traditional low-level MySQL connections.
An application using the Session class can be run against a single MySQL server or large number of MySQL servers forming a sharding cluster with no code changes.
When using literal/verbatim SQL the common API patterns are mostly the same compared to using DML and CRUD operations on Tables and Collections. Two differences exist: setting the current schema and escaping names.
You cannot call getSchema(String) or getDefaultSchema() to obtain a Schema object against which you can issue verbatin SQL statements. The Schema object does not feature a sql() function.
The sql() function is a method of the Session class. Use sql(String) and the SQL command USE to change the current schema
Session session = SessionFactory.getSession("root:s3kr3t@localhost");
session.sql("USE test");
If a Session has been established using a data source file the name of the default schema can be obtained to change the current database.
Properties p = new Properties();
p.setProperty("dataSourceFile", "/home/app_instance50/mysqlxconfig.json");
Session session = SessionFactory.getSession(p);
String defaultSchema = session.getDefaultSchema().getName();
session.sql("USE ?").bind(defaultSchema).execute();

A quoting function exists to escape SQL names/identifiers. StringUtils.quoteIdentifier(String, boolean) will escape the identifier given in accordance to the settings of the current connection. The escape function must not be used to escape values. Use the value bind syntax of sql(String) instead.
// use bind syntax for values
session.sql("DROP TABLE IF EXISTS ?").bind(name).execute();

// use escape function to quote names/identifier
var create = "CREATE TABLE ";
create += StringUtils.quoteIdentifier(name, true);
create += "(id INT NOT NULL PRIMARY KEY AUTO_INCREMENT");

session.sql(create).execute();
Users of the CRUD API do not need to escape identifiers. This is true for working with collections and for working with relational tables.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`close()` Close this session.
`void`	`commit()` Commit the transaction.
`Schema`	`createSchema(String schemaName)` Create and return a new schema with the name given by name.
`Schema`	`createSchema(String schemaName, boolean reuseExistingObject)` Create and return a new schema with the name given by name.
`void`	`dropSchema(String schemaName)` Drop the existing schema with the name given by name.
`Schema`	`getDefaultSchema()` Retrieve the default schema name, which might have been configured at the time of connection.
`String`	`getDefaultSchemaName()` Retrieve the default schema name, which might have been configured at the time of connection.
`Schema`	`getSchema(String schemaName)` Retrieve the Schema corresponding to name.
`List<Schema>`	`getSchemas()` Retrieve the list of Schema objects for which the current user has access.
`String`	`getUri()` Get the URL used to create this session.
`boolean`	`isOpen()` Is this session open?
`void`	`releaseSavepoint(String name)` Releases the named savepoint.
`void`	`rollback()` Rollback the transaction.
`void`	`rollbackTo(String name)` Rolls back the transaction to the named savepoint.
`String`	`setSavepoint()` Creates a transaction savepoint with an implementation-defined generated name and returns its name, which can be used in `rollbackTo(String)` or `releaseSavepoint(String)`.
`String`	`setSavepoint(String name)` Creates or replaces a transaction savepoint with the given name.
`SqlStatement`	`sql(String sql)` Create a native SQL command.
`void`	`startTransaction()` Start a new transaction.

- Method Detail
  - getSchemas
```
List<Schema> getSchemas()
```
    Retrieve the list of Schema objects for which the current user has access.
    
    Returns:
    
    list of Schema objects
  - getSchema
```
Schema getSchema(String schemaName)
```
    Retrieve the Schema corresponding to name.
    
    Parameters:
    
    schemaName - name of schema to retrieve
    
    Returns:
    
    Schema
  - getDefaultSchemaName
```
String getDefaultSchemaName()
```
    Retrieve the default schema name, which might have been configured at the time of connection. Returns empty String if no default schema has been set.
    
    Returns:
    
    default schema name or empty String if no default schema has been set
  - getDefaultSchema
```
Schema getDefaultSchema()
```
    Retrieve the default schema name, which might have been configured at the time of connection. Returns null if no default schema has been set.
    
    Returns:
    
    default Schema or null if no default schema has been set
  - createSchema
```
Schema createSchema(String schemaName)
```
    Create and return a new schema with the name given by name.
    
    Parameters:
    
    schemaName - name of schema to create
    
    Returns:
    
    Schema created
  - createSchema
```
Schema createSchema(String schemaName,
                    boolean reuseExistingObject)
```
    Create and return a new schema with the name given by name. If the schema already exists, a reference to it is returned.
    
    Parameters:
    
    schemaName - name of schema to create
    
    reuseExistingObject - true to reuse
    
    Returns:
    
    Schema created
  - dropSchema
```
void dropSchema(String schemaName)
```
    Drop the existing schema with the name given by name.
    
    Parameters:
    
    schemaName - name of schema to drop
  - getUri
```
String getUri()
```
    Get the URL used to create this session.
    
    Returns:
    
    URI
  - isOpen
```
boolean isOpen()
```
    Is this session open?
    
    Returns:
    
    true if session is open
  - close
```
void close()
```
    Close this session.
    
    Specified by:
    
    close in interface AutoCloseable
  - startTransaction
```
void startTransaction()
```
    Start a new transaction.
  - commit
```
void commit()
```
    Commit the transaction.
  - rollback
```
void rollback()
```
    Rollback the transaction.
  - setSavepoint
```
String setSavepoint()
```
    Creates a transaction savepoint with an implementation-defined generated name and returns its name, which can be used in rollbackTo(String) or releaseSavepoint(String). Calling this method more than once should always work. The generated name shall be unique per session.
    
    Returns:
    
    savepoint name
  - setSavepoint
```
String setSavepoint(String name)
```
    Creates or replaces a transaction savepoint with the given name. Calling this method more than once should always work.
    
    Parameters:
    
    name - savepoint name
    
    Returns:
    
    savepoint name
  - rollbackTo
```
void rollbackTo(String name)
```
    Rolls back the transaction to the named savepoint. This method will succeed as long as the given save point has not been already rolled back or released. Rolling back to a savepoint prior to the one named will release or rollback any that came after.
    
    Parameters:
    
    name - savepoint name
  - releaseSavepoint
```
void releaseSavepoint(String name)
```
    Releases the named savepoint. This method will succeed as long as the given save point has not been already rolled back or released. Rolling back to a savepoint prior to the one named will release or rollback any that came after.
    
    Parameters:
    
    name - savepoint name
  - sql
```
SqlStatement sql(String sql)
```
    Create a native SQL command. Placeholders are supported using the native "?" syntax.
    
    Parameters:
    
    sql - native SQL statement
    
    Returns:
    
    SqlStatement

Interface Session

Method Summary

Method Detail

getSchemas

getSchema

getDefaultSchemaName

getDefaultSchema

createSchema

createSchema

dropSchema

getUri

isOpen

close

startTransaction

commit

rollback

setSavepoint

setSavepoint

rollbackTo

releaseSavepoint

sql