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

str	get_ssh_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.

str	ssh_uri
	Retrieves the SSH 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:

Schema management operations.
Access to relational tables.
Access to Document Store collections.
Enabling/disabling warning generation.

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

name	A string value indicating the schema name.

Returns: The created schema object.

Exceptions

A	MySQL 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

name	The name of the Schema object to be retrieved.

Returns: The Schema object with the given name.

Exceptions

RuntimeError If 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

name	the 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.

◆ get_ssh_uri()

str get_ssh_uri ( )

Retrieves the URI for the current session.

Retrieves the SSH URI for the current session.

Returns: A string representing the connection data.

Returns: A string representing the SSH 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

enable Boolean 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

name	The 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

sql	A 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

id	The 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

name	Optional 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

name	string 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

name	string 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

query	the SQL query to execute against the database.
args	Optional list of literals to use when replacing ? placeholders in the query string.

Returns: An SqlResult object.

Exceptions

LogicError	if there's no open session.
ArgumentError	if the parameters are invalid.

Methods

Properties

Detailed Description

JavaScript Examples

Python Examples

Member Function Documentation

◆ create_schema()

◆ get_schema()

◆ get_default_schema()

◆ get_current_schema()

◆ set_current_schema()

◆ get_schemas()

◆ get_uri()

◆ get_ssh_uri()

◆ close()

◆ set_fetch_warnings()

◆ start_transaction()

◆ commit()

◆ rollback()

◆ drop_schema()

◆ is_open()

◆ sql()

◆ quote_name()

◆ set_savepoint()

◆ release_savepoint()

◆ rollback_to()

◆ run_sql()