MySQL Connector/J 9.2.0 · com.mysql.cj.xdevapi.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 Session#getSchema(String) or Session#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 Session#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 Session#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

Modifier and Type	Method and Description
public void	close() Redeclares java.lang.AutoCloseable.close. Close this session.
public void	commit() Commit the transaction.
public Schema	Returns: `Schema` created createSchema(String name of schema to create schemaName) Create and return a new schema with the name given by name.
public Schema	Returns: `Schema` created createSchema(String name of schema to create schemaName, boolean true to reuse reuseExistingObject) Create and return a new schema with the name given by name.
public void	dropSchema(String name of schema to drop schemaName) Drop the existing schema with the name given by name.
public Schema	Returns: default `Schema` or `null` if no default schema has been set getDefaultSchema() Retrieve the default schema name, which might have been configured at the time of connection.
public String	Returns: default schema name or empty String if no default schema has been set getDefaultSchemaName() Retrieve the default schema name, which might have been configured at the time of connection.
public Schema	Returns: `Schema` getSchema(String name of schema to retrieve schemaName) Retrieve the Schema corresponding to name.
public List<Schema>	Returns: list of Schema objects getSchemas() Retrieve the list of Schema objects for which the current user has access.
public String	Returns: URI getUri() Get the URL used to create this session.
public boolean	Returns: true if session is open isOpen() Is this session open?
public void	releaseSavepoint(String savepoint name name) Releases the named savepoint.
public void	rollback() Rollback the transaction.
public void	rollbackTo(String savepoint name name) Rolls back the transaction to the named savepoint.
public String	Returns: savepoint name 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)`.
public String	Returns: savepoint name setSavepoint(String savepoint name name) Creates or replaces a transaction savepoint with the given name.
public SqlStatement	Returns: `SqlStatement` sql(String native SQL statement sql) Create a native SQL command.
public void	startTransaction() Start a new transaction.

Method Detail

close	back to summary
public void close() Redeclares java.lang.AutoCloseable.close. Close this session. Annotations @Override

back to summary

public void close()

Redeclares java.lang.AutoCloseable.close.

Close this session.

Annotations

@Override

commit	back to summary
public void commit() Commit the transaction.

createSchema back to summary

createSchema	back to summary
public Schema createSchema(String schemaName) Create and return a new schema with the name given by name. Parameters schemaName:String name of schema to create Returns:Schema `Schema` created

public Schema createSchema(String schemaName)

Create and return a new schema with the name given by name.

Parameters

schemaName:String: name of schema to create

Returns:Schema

Schema created

createSchema back to summary

createSchema	back to summary
public 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:String name of schema to create reuseExistingObject:boolean true to reuse Returns:Schema `Schema` created

public 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:String: name of schema to create
reuseExistingObject:boolean: true to reuse

Returns:Schema

Schema created

dropSchema	back to summary
public void dropSchema(String schemaName) Drop the existing schema with the name given by name. Parameters schemaName:String name of schema to drop

dropSchema

back to summary

public void dropSchema(String schemaName)

Drop the existing schema with the name given by name.

Parameters

schemaName:String: name of schema to drop

getDefaultSchema back to summary

getDefaultSchema	back to summary
public 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:Schema default `Schema` or `null` if no default schema has been set

public 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:Schema: default Schema or null if no default schema has been set

getDefaultSchemaName	back to summary
public 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:String default schema name or empty String if no default schema has been set

getDefaultSchemaName

back to summary

public 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:String: default schema name or empty String if no default schema has been set

getSchema back to summary

getSchema	back to summary
public Schema getSchema(String schemaName) Retrieve the Schema corresponding to name. Parameters schemaName:String name of schema to retrieve Returns:Schema `Schema`

public Schema getSchema(String schemaName)

Retrieve the Schema corresponding to name.

Parameters

schemaName:String: name of schema to retrieve

Returns:Schema

Schema

getSchemas	back to summary
public List<Schema> getSchemas() Retrieve the list of Schema objects for which the current user has access. Returns:List<Schema> list of Schema objects

getSchemas

back to summary

public List<Schema> getSchemas()

Retrieve the list of Schema objects for which the current user has access.

Returns:List<Schema>: list of Schema objects

getUri	back to summary
public String getUri() Get the URL used to create this session. Returns:String URI

getUri

back to summary

public String getUri()

Get the URL used to create this session.

Returns:String: URI

isOpen	back to summary
public boolean isOpen() Is this session open? Returns:boolean true if session is open

isOpen

back to summary

public boolean isOpen()

Is this session open?

Returns:boolean: true if session is open

releaseSavepoint	back to summary
public 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:String savepoint name

releaseSavepoint

back to summary

public 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:String: savepoint name

rollback	back to summary
public void rollback() Rollback the transaction.

rollbackTo	back to summary
public 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:String savepoint name

rollbackTo

back to summary

public 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:String: savepoint name

setSavepoint back to summary

setSavepoint	back to summary
public 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:String savepoint name

public 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:String: savepoint name

setSavepoint	back to summary
public 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:String savepoint name Returns:String savepoint name

setSavepoint

back to summary

public 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:String: savepoint name

Returns:String

savepoint name

sql back to summary

sql	back to summary
public SqlStatement sql(String sql) Create a native SQL command. Placeholders are supported using the native "?" syntax. Parameters sql:String native SQL statement Returns:SqlStatement `SqlStatement`

public SqlStatement sql(String sql)

Create a native SQL command. Placeholders are supported using the native "?" syntax.

Parameters

sql:String: native SQL statement

Returns:SqlStatement

SqlStatement

startTransaction	back to summary
public void startTransaction() Start a new transaction.

public Interface Session

Method Summary

Method Detail