MySQL Shell API  8.0.26
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 create_schema (str name)
 Creates a schema on the database and returns the corresponding object. More...
 
Schema get_schema (str name)
 Retrieves a Schema object from the current session through it's name. More...
 
Schema get_default_schema ()
 Retrieves the Schema configured as default for the session. More...
 
Schema get_current_schema ()
 Retrieves the active schema on the session. More...
 
Schema set_current_schema (str name)
 Sets the current schema for this session, and returns the schema object for it. More...
 
list get_schemas ()
 Retrieves the Schemas available on the session. More...
 
str get_uri ()
 Retrieves the URI for the current session. More...
 
None close ()
 Closes the session. More...
 
None set_fetch_warnings (bool enable)
 Enables or disables warning generation. More...
 
Result start_transaction ()
 Starts a transaction context on the server. More...
 
Result commit ()
 Commits all the operations executed after a call to start_transaction(). More...
 
Result rollback ()
 Discards all the operations executed after a call to start_transaction(). More...
 
None drop_schema (str name)
 Drops the schema with the specified name. More...
 
Bool is_open ()
 Returns true if session is known to be open. More...
 
SqlExecute sql (str sql)
 Creates a SqlExecute object to allow running the received SQL statement on the target MySQL Server. More...
 
str quote_name (str id)
 Escapes the passed identifier. More...
 
str set_savepoint (str name="")
 Creates or replaces a transaction savepoint with the given name. More...
 
None release_savepoint (str name)
 Removes a savepoint defined on a transaction. More...
 
None rollback_to (str name)
 Rolls back the transaction to the named savepoint without terminating the transaction. More...
 
SqlResult run_sql (str query, list args)
 Executes a query and returns the corresponding SqlResult object. More...
 

Properties

str uri
 Retrieves the URI for the current session.
 
Schema default_schema
 Retrieves the Schema configured as default for the session.
 
Schema current_schema
 Retrieves the active schema on the session.
 

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

◆ create_schema()

Schema create_schema ( str  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
AMySQL error is thrown if fails creating the schema.

◆ get_schema()

Schema get_schema ( str  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
RuntimeErrorIf the given name is not a valid schema.
See also
Schema

◆ get_default_schema()

Schema get_default_schema ( )

Retrieves the Schema configured as default for the session.

Returns
A Schema object or Null

◆ get_current_schema()

std::string get_current_schema ( )

Retrieves the active schema on the session.

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

◆ set_current_schema()

Schema set_current_schema ( str  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>;

◆ get_schemas()

shcore::Array_t get_schemas ( )

Retrieves the Schemas available on the session.

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

◆ get_uri()

str get_uri ( )

Retrieves the URI for the current session.

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 get_table(name) or get_schemas().

◆ set_fetch_warnings()

std::shared_ptr< Result > set_fetch_warnings ( bool  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.

◆ start_transaction()

void start_transaction ( )

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 if rollback() is called.

When commit() or rollback() are called, the server autocommit mode will return back to it's state before calling start_transaction().

◆ commit()

void commit ( )

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

Returns
A SqlResult object.

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

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

◆ rollback()

void rollback ( )

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

Returns
A SqlResult object.

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

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

◆ drop_schema()

None drop_schema ( str  name)

Drops the schema with the specified name.

Parameters
nameThe name of the schema to be dropped.
Returns
Nothing.

◆ is_open()

bool is_open ( )

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
This function may return true if connection is lost.

◆ sql()

SqlExecute sql ( str  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

◆ quote_name()

str quote_name ( str  id)

Escapes the passed identifier.

Parameters
idThe identifier to be quoted.
Returns
A String containing the escaped identifier.

◆ set_savepoint()

str set_savepoint ( str  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.

◆ release_savepoint()

None release_savepoint ( str  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.

◆ rollback_to()

None rollback_to ( str  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.

◆ run_sql()

SqlResult run_sql ( str  query,
list  args 
)

Executes a query and returns the corresponding SqlResult object.

Parameters
querythe SQL query to execute against the database.
argsOptional list of literals to use when replacing ? placeholders in the query string.
Returns
An SqlResult object.
Exceptions
LogicErrorif there's no open session.
ArgumentErrorif the parameters are invalid.