Package com.mysql.cj.xdevapi

Interface Session

All Known Implementing Classes:
SessionImpl
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

    Modifier and Type Method Description
    void close()
    Close this session.
    void commit()
    Commit the transaction.
    Schema createSchema​(java.lang.String schemaName)
    Create and return a new schema with the name given by name.
    Schema createSchema​(java.lang.String schemaName, boolean reuseExistingObject)
    Create and return a new schema with the name given by name.
    void dropSchema​(java.lang.String schemaName)
    Drop the existing schema with the name given by name.
    Schema getDefaultSchema()
    Retrieve the default schema which may be configured at connect time.
    java.lang.String getDefaultSchemaName()
    Retrieve the default schema name which may be configured at connect time.
    Schema getSchema​(java.lang.String schemaName)
    Retrieve the Schema corresponding to name.
    java.util.List<Schema> getSchemas()
    Retrieve the list of Schema objects for which the current user has access.
    java.lang.String getUri()
    Get the URL used to create this session.
    boolean isOpen()
    Is this session open?
    void releaseSavepoint​(java.lang.String name)
    Releases the named savepoint.
    void rollback()
    Rollback the transaction.
    void rollbackTo​(java.lang.String name)
    Rolls back the transaction to the named savepoint.
    java.lang.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).
    java.lang.String setSavepoint​(java.lang.String name)
    Creates or replaces a transaction savepoint with the given name.
    SqlStatement sql​(java.lang.String sql)
    Create a native SQL command.
    void startTransaction()
    Start a new transaction.

  • Method Details

    • getSchemas

      java.util.List<Schema> getSchemas()
      Retrieve the list of Schema objects for which the current user has access.
      Returns:
      list of Schema objects

    • getSchema

      Schema getSchema​(java.lang.String schemaName)
      Retrieve the Schema corresponding to name.
      Parameters:
      schemaName - name of schema to retrieve
      Returns:
      Schema

    • getDefaultSchemaName

      java.lang.String getDefaultSchemaName()
      Retrieve the default schema name which may be configured at connect time.
      Returns:
      default schema name

    • getDefaultSchema

      Schema getDefaultSchema()
      Retrieve the default schema which may be configured at connect time.
      Returns:
      default Schema

    • createSchema

      Schema createSchema​(java.lang.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​(java.lang.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​(java.lang.String schemaName)
      Drop the existing schema with the name given by name.
      Parameters:
      schemaName - name of schema to drop

    • getUri

      java.lang.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

      java.lang.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

      java.lang.String setSavepoint​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.String sql)
      Create a native SQL command. Placeholders are supported using the native "?" syntax.
      Parameters:
      sql - native SQL statement
      Returns:
      SqlStatement