com.mysql.cj.xdevapi

## Interface Session

    public interface Session

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
`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.

#### 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`

Copyright © 2016, 2024, Oracle and/or its affiliates.