The central "database" object used by an application. Subclasses of this object is used by the schema and SQL construction packages to provide database-specific behaviors,
as well as an execution and thread-local transaction context.
SQLEngines are constructed via the create_engine() function inside this package.
def __init__(self, pool=None, echo=False, logger=None, default_ordering=False, echo_pool=False, echo_uow=False, **params)
constructs a new SQLEngine. SQLEngines should be constructed via the create_engine()
function which will construct the appropriate subclass of SQLEngine.
|
def begin(self)
"begins" a transaction on a pooled connection, and stores the connection in a thread-local context. repeated calls to begin() within the same thread will increment a counter that must be decreased by corresponding commit() statements before an actual commit occurs. this is to provide "nested" behavior of transactions so that different functions can all call begin()/commit() and still call each other.
|
def columnimpl(self, column)
returns a new sql.ColumnImpl object to correspond to the given Column object.
A ColumnImpl provides SQL statement builder operations on a Column metadata object, and a subclass of this object may be provided by a SQLEngine subclass to provide database-specific behavior.
|
def commit(self)
commits the current thread-local transaction started by begin(). If begin() was called multiple times, a counter will be decreased for each call to commit(), with the actual commit operation occuring when the counter reaches zero. this is to provide "nested" behavior of transactions so that different functions can all call begin()/commit() and still call each other.
|
def compile(self, statement, parameters, **kwargs)
given a sql.ClauseElement statement plus optional bind parameters, creates a new instance of this engine's SQLCompiler, compiles the ClauseElement, and returns the newly compiled object.
|
def compiler(self, statement, parameters)
returns a sql.ClauseVisitor which will produce a string representation of the given ClauseElement and parameter dictionary. This object is usually a subclass of ansisql.ANSICompiler. compiler is called within the context of the compile() method.
|
def connect_args(self)
subclasses override this method to provide a two-item tuple containing the *args and **kwargs used to establish a connection.
|
def connection(self)
returns a managed DBAPI connection from this SQLEngine's connection pool.
|
def create(self, table, **params)
creates a table within this engine's database connection given a schema.Table object.
|
def dbapi(self)
subclasses override this method to provide the DBAPI module used to establish connections.
|
def defaultrunner(self, proxy)
Returns a schema.SchemaVisitor instance that can execute the default values on a column.
The base class for this visitor is the DefaultRunner class inside this module.
This visitor will typically only receive schema.DefaultGenerator schema objects. The given proxy is a callable that takes a string statement and a dictionary of bind parameters to be executed. For engines that require positional arguments, the dictionary should be an instance of OrderedDict which returns its bind parameters in the proper order.
defaultrunner is called within the context of the execute_compiled() method.
|
def dispose(self)
disposes of the underlying pool manager for this SQLEngine.
|
def do_begin(self, connection)
implementations might want to put logic here for turning autocommit on/off,
etc.
|
def do_commit(self, connection)
implementations might want to put logic here for turning autocommit on/off, etc.
|
def do_rollback(self, connection)
implementations might want to put logic here for turning autocommit on/off,
etc.
|
def drop(self, table, **params)
drops a table within this engine's database connection given a schema.Table object.
|
def execute(self, statement, parameters, connection=None, cursor=None, echo=None, typemap=None, commit=False, **kwargs)
executes the given string-based SQL statement with the given parameters.
The parameters can be a dictionary or a list, or a list of dictionaries or lists, depending on the paramstyle of the DBAPI.
If the current thread has specified a transaction begin() for this engine, the statement will be executed in the context of the current transactional connection.
Otherwise, a commit() will be performed immediately after execution, since the local pooled connection is returned to the pool after execution without a transaction set up.
In all error cases, a rollback() is immediately performed on the connection before propigating the exception outwards.
Other options include:
connection - a DBAPI connection to use for the execute. If None, a connection is pulled from this engine's connection pool.
echo - enables echo for this execution, which causes all SQL and parameters to be dumped to the engine's logging output before execution.
typemap - a map of column names mapped to sqlalchemy.types.TypeEngine objects.
These will be passed to the created ResultProxy to perform post-processing on result-set values.
commit - if True, will automatically commit the statement after completion.
|
def execute_compiled(self, compiled, parameters, connection=None, cursor=None, echo=None, **kwargs)
executes the given compiled statement object with the given parameters.
The parameters can be a dictionary of key/value pairs, or a list of dictionaries for an executemany() style of execution. Engines that use positional parameters will convert the parameters to a list before execution.
If the current thread has specified a transaction begin() for this engine, the statement will be executed in the context of the current transactional connection.
Otherwise, a commit() will be performed immediately after execution, since the local pooled connection is returned to the pool after execution without a transaction set up.
In all error cases, a rollback() is immediately performed on the connection before propigating the exception outwards.
Other options include:
connection - a DBAPI connection to use for the execute. If None, a connection is pulled from this engine's connection pool.
echo - enables echo for this execution, which causes all SQL and parameters to be dumped to the engine's logging output before execution.
typemap - a map of column names mapped to sqlalchemy.types.TypeEngine objects.
These will be passed to the created ResultProxy to perform post-processing on result-set values.
commit - if True, will automatically commit the statement after completion.
|
def get_default_schema_name(self)
returns the currently selected schema in the current connection.
|
|
|
returns an ISchema object for this engine, which allows access to information_schema tables (if supported)
def last_inserted_ids(self)
returns a thread-local list of the primary key values for the last insert statement executed.
This does not apply to straight textual clauses; only to sql.Insert objects compiled against a schema.Table object, which are executed via statement.execute(). The order of items in the list is the same as that of the Table's 'primary_key' attribute.
In some cases, this method may invoke a query back to the database to retrieve the data, based on the "lastrowid" value in the cursor.
|
def lastrow_has_defaults(self)
|
def log(self, msg)
logs a message using this SQLEngine's logger stream.
|
def multi_transaction(self, tables, func)
provides a transaction boundary across tables which may be in multiple databases.
If you have three tables, and a function that operates upon them, providing the tables as a list and the function will result in a begin()/commit() pair invoked for each distinct engine represented within those tables, and the function executed within the context of that transaction.
any exceptions will result in a rollback().
clearly, this approach only goes so far, such as if database A commits, then database B commits and fails, A is already committed. Any failure conditions have to be raised before anyone commits for this to be useful.
|
def oid_column_name(self)
returns the oid column name for this engine, or None if the engine cant/wont support OID/ROWID.
|
|
def post_exec(self, proxy, compiled, parameters, **kwargs)
called by execute_compiled after the compiled statement is executed.
|
def pre_exec(self, proxy, compiled, parameters, **kwargs)
called by execute_compiled before the compiled statement is executed.
|
def reflecttable(self, table)
given a Table object, reflects its columns and properties from the database.
|
def rollback(self)
rolls back the current thread-local transaction started by begin(). the "begin" counter is cleared and the transaction ended.
|
def schemadropper(self, **params)
returns a schema.SchemaVisitor instance that can drop schemas, when it is invoked to traverse a set of schema objects. schemagenerator is called via the drop() method.
|
def schemagenerator(self, **params)
returns a schema.SchemaVisitor instance that can generate schemas, when it is invoked to traverse a set of schema objects. schemagenerator is called via the create() method.
|
def supports_sane_rowcount(self)
Provided to indicate when MySQL is being used, which does not have standard behavior for the "rowcount" function on a statement handle.
|
def tableimpl(self, table, **kwargs)
returns a new sql.TableImpl object to correspond to the given Table object.
A TableImpl provides SQL statement builder operations on a Table metadata object, and a subclass of this object may be provided by a SQLEngine subclass to provide database-specific behavior.
|
def text(self, text, *args, **kwargs)
returns a sql.text() object for performing literal queries.
|
def transaction(self, func)
executes the given function within a transaction boundary. this is a shortcut for explicitly calling begin() and commit() and optionally rollback() when execptions are raised.
|
def type_descriptor(self, typeobj)
provides a database-specific TypeEngine object, given the generic object which comes from the types module. Subclasses will usually use the adapt_type()
method in the types module to make this job easy.
|