MySQL Shell  8.0.16
Unified development interface for MySQL Products
Methods | Properties | List of all members
Session Class Reference

Enables interaction with a MySQL Server using the X Protocol. More...

Methods

Schema createSchema (String name)
 Creates a schema on the database and returns the corresponding object. More...
 
Schema getSchema (String name)
 Retrieves a Schema object from the current session through it's name. More...
 
Schema getDefaultSchema ()
 Retrieves the Schema configured as default for the session. More...
 
Schema getCurrentSchema ()
 Retrieves the active schema on the session. More...
 
Schema setCurrentSchema (String name)
 Sets the current schema for this session, and returns the schema object for it. More...
 
List getSchemas ()
 Retrieves the Schemas available on the session. More...
 
String getUri ()
 
Undefined close ()
 Closes the session. More...
 
Undefined setFetchWarnings (Boolean enable)
 Enables or disables warning generation. More...
 
Result startTransaction ()
 Starts a transaction context on the server. More...
 
Result commit ()
 Commits all the operations executed after a call to startTransaction(). More...
 
Result rollback ()
 Discards all the operations executed after a call to startTransaction(). More...
 
Undefined dropSchema (String name)
 Drops the schema with the specified name. More...
 
Bool isOpen ()
 Returns true if session is known to be open. More...
 
SqlExecute sql (String sql)
 Creates a SqlExecute object to allow running the received SQL statement on the target MySQL Server. More...
 
String quoteName (String id)
 Escapes the passed identifier. More...
 
String setSavepoint (String name="")
 Creates or replaces a transaction savepoint with the given name. More...
 
Undefined releaseSavepoint (String name)
 Removes a savepoint defined on a transaction. More...
 
Undefined rollbackTo (String name)
 Rolls back the transaction to the named savepoint without terminating the transaction. More...
 

Properties

String uri
 Same as getUri()
 
Schema defaultSchema
 Same as getDefaultSchema()
 
Schema currentSchema
 Same as getCurrentSchema()
 

Detailed Description

Enables interaction with a MySQL Server using the X Protocol.

Document Store functionality can be used through this object, in addition to SQL.

This class allows performing database operations such as:

JavaScript Examples

// Connecting to MySQL and working with a Session
var mysqlx = require('mysqlx');
// Connect to a dedicated MySQL server using a connection URL
var mySession = mysqlx.getSession('mike:paSSw0rd@localhost');
// Get a list of all available schemas
var schemaList = mySession.getSchemas();
print('Available schemas in this session:\n');
// Loop over all available schemas and print their name
for (index in schemaList) {
print(schemaList[index].name + '\n');
}
mySession.close();

Python Examples

# Connecting to MySQL and working with a Session
from mysqlsh import mysqlx
# Connect to a dedicated MySQL server using a connection URL
mySession = mysqlx.get_session('mike:paSSw0rd@localhost')
# Get a list of all available schemas
schemaList = mySession.get_schemas()
print 'Available schemas in this session:\n'
# Loop over all available schemas and print their name
for schema in schemaList:
print '%s\n' % schema.name
mySession.close()
See also
mysqlx.getSession(String connectionData, String password)
mysqlx.getSession(Map connectionData, String password)

Member Function Documentation

◆ createSchema()

Schema createSchema ( String  name)

Creates a schema on the database and returns the corresponding object.

Parameters
nameA string value indicating the schema name.
Returns
The created schema object.
Exceptions
Anexception is thrown if an error occurs creating the schema.

◆ getSchema()

Schema getSchema ( String  name)

Retrieves a Schema object from the current session through it's name.

Parameters
nameThe name of the Schema object to be retrieved.
Returns
The Schema object with the given name.
Exceptions
Anexception is thrown if the given name is not a valid schema.
See also
Schema

◆ getDefaultSchema()

Schema getDefaultSchema ( )

Retrieves the Schema configured as default for the session.

Returns
A Schema object or Null

◆ getCurrentSchema()

Schema getCurrentSchema ( )

Retrieves the active schema on the session.

Returns
A Schema object if a schema is active on the session.

◆ setCurrentSchema()

Schema setCurrentSchema ( String  name)

Sets the current schema for this session, and returns the schema object for it.

Parameters
namethe name of the new schema to switch to.
Returns
the Schema object for the new schema.

At the database level, this is equivalent at issuing the following SQL query: use <new-default-schema>;

◆ getSchemas()

List getSchemas ( )

Retrieves the Schemas available on the session.

Returns
A List containing the Schema objects available on the session.

◆ getUri()

String getUri ( )

Returns
A string representing the connection data.

◆ close()

void close ( )

Closes the session.

After closing the session it is still possible to make read only operations to gather metadata info, like getTable(name) or getSchemas().

◆ setFetchWarnings()

Result setFetchWarnings ( Boolean  enable)

Enables or disables warning generation.

Parameters
enableBoolean value to enable or disable the warnings.

Warnings are generated sometimes when database operations are executed, such as SQL statements.

On a Node session the warning generation is disabled by default. This function can be used to enable or disable the warning generation based on the received parameter.

When warning generation is enabled, the warnings will be available through the result object returned on the executed operation.

◆ startTransaction()

Result startTransaction ( )

Starts a transaction context on the server.

Returns
A SqlResult object.

Calling this function will turn off the autocommit mode on the server.

All the operations executed after calling this function will take place only when commit() is called. All the operations executed after calling this function, will be discarded is rollback() is called. When commit() or rollback() are called, the server autocommit mode will return back to it's state before calling startTransaction().

◆ commit()

void commit ( )

Commits all the operations executed after a call to startTransaction().

Returns
A SqlResult object.

All the operations executed after calling startTransaction() will take place when this function is called.

The server autocommit mode will return back to it's state before calling startTransaction().

◆ rollback()

void rollback ( )

Discards all the operations executed after a call to startTransaction().

Returns
A SqlResult object.

All the operations executed after calling startTransaction() will be discarded when this function is called.

The server autocommit mode will return back to it's state before calling startTransaction().

◆ dropSchema()

Undefined dropSchema ( String  name)

Drops the schema with the specified name.

Returns
Nothing.

◆ isOpen()

Bool isOpen ( )

Returns true if session is known to be open.

Returns
A boolean value indicating if the session is still open.

Returns true if the session is still open and false otherwise. Note: may return true if connection is lost.

◆ sql()

SqlExecute sql ( String  sql)

Creates a SqlExecute object to allow running the received SQL statement on the target MySQL Server.

Parameters
sqlA string containing the SQL statement to be executed.
Returns
A SqlExecute object.

This method creates an SqlExecute object which is a SQL execution handler.

The SqlExecute class has functions that allow defining the way the statement will be executed and allows doing parameter binding.

The received SQL is set on the execution handler.

JavaScript Example

var sql = session.sql("select * from mydb.students where age > ?");
var result = sql.bind(18).execute();
See also
SqlExecute

◆ quoteName()

String quoteName ( String  id)

Escapes the passed identifier.

Returns
A String containing the escaped identifier.

◆ setSavepoint()

String setSavepoint ( String  name = "")

Creates or replaces a transaction savepoint with the given name.

Parameters
nameOptional string with the name to be assigned to the transaction save point.
Returns
The name of the transaction savepoint.

When working with transactions, using savepoints allows rolling back operations executed after the savepoint without terminating the transaction.

Use this function to set a savepoint within a transaction.

If this function is called with the same name of another savepoint set previously, the original savepoint will be deleted and a new one will be created.

If the name is not provided an auto-generated name as 'TXSP#' will be assigned, where # is a consecutive number that guarantees uniqueness of the savepoint at Session level.

◆ releaseSavepoint()

Undefined releaseSavepoint ( String  name)

Removes a savepoint defined on a transaction.

Parameters
namestring with the name of the savepoint to be removed.

Removes a named savepoint from the set of savepoints defined on the current transaction. This does not affect the operations executed on the transaction since no commit or rollback occurs.

It is an error trying to remove a savepoint that does not exist.

◆ rollbackTo()

Undefined rollbackTo ( String  name)

Rolls back the transaction to the named savepoint without terminating the transaction.

Parameters
namestring with the name of the savepoint for the rollback operation.

Modifications that the current transaction made to rows after the savepoint was defined will be rolled back.

The given savepoint will not be removed, but any savepoint defined after the given savepoint was defined will be removed.

It is an error calling this operation with an unexisting savepoint.