SQL connections, SQL execution and high-level DB-API interface.
The engine package defines the basic components used to interface DB-API modules with higher-level statement construction, connection-management, execution and result contexts. The primary "entry point" class into this package is the Engine and it's public constructor create_engine().
This package includes:
Create a new Engine instance.
The standard method of specifying the engine is via URL as the first positional argument, to indicate the appropriate database dialect and connection arguments, with additional keyword arguments sent as options to the dialect and resulting Engine.
The URL is a string in the form dialect://user:password@host/dbname[?key=value..], where dialect is a name such as mysql, oracle, postgres, etc. Alternatively, the URL can be an instance of sqlalchemy.engine.url.URL.
**kwargs represents options to be sent to the Engine itself as well as the components of the Engine, including the Dialect, the ConnectionProvider, and the Pool. A list of common options is as follows:
allows alternate Engine implementations to take effect. Current implementations include plain and threadlocal. The default used by this function is plain.
plain provides support for a Connection object which can be used to execute SQL queries with a specific underlying DB-API connection.
threadlocal is similar to plain except that it adds support for a thread-local connection and transaction context, which allows a group of engine operations to participate using the same underlying connection and transaction without the need for explicitly passing a single Connection.
Provide a listing of all the database implementations supported.
This data is provided as a list of dictionaries, where each dictionary contains the following key/value pairs:
This function is meant for usage in automated configuration tools that wish to query the user for database and connection information.
Create a new Engine instance using a configuration dictionary.
The dictionary is typically produced from a config file where keys are prefixed, such as sqlalchemy.url, sqlalchemy.echo, etc. The 'prefix' argument indicates the prefix to be searched for.
A select set of keyword arguments will be "coerced" to their expected type based on string values. in a future release, this functionality will be expanded to include dialect-specific arguments.
A ResultProxy with column buffering behavior.
ResultProxy that loads all columns into memory each time fetchone() is called. If fetchmany() or fetchall() are called, the full grid of results is fetched. This is to operate with databases where result rows contain "live" results that fall out of scope unless explicitly fetched. Currently this includes just cx_Oracle LOB objects, but this behavior is known to exist in other DB-APIs as well (Pygresql, currently unsupported).
A ResultProxy with row buffering behavior.
ResultProxy that buffers the contents of a selection of rows before fetchone() is called. This is to allow the results of cursor.description to be available immediately, when interfacing with a DB-API that requires rows to be consumed before this information is available (currently psycopg2, when used with server-side cursors).
The pre-fetching behavior fetches only one row initially, and then grows its buffer size by a fixed amount with each successive need for additional rows up to a size of 100.
Represent a compiled SQL expression.
The __str__ method of the Compiled object should produce the actual text of the statement. Compiled objects are specific to their underlying database dialect, and also may or may not be specific to the columns referenced within a particular set of bind parameters. In no case should the Compiled object be dependent on the actual values of those bind parameters, even though it may reference those values as defaults.
Construct a new Compiled object.
Return the bind params for this compiled object.
params is a dict of string/object pairs whos values will override bind values compiled in to the statement.
Execute this compiled object and return the result's scalar value.
Interface for an object that can provide an Engine and a Connection object which correponds to that Engine.
Provides high-level functionality for a wrapped DB-API connection.
Provides execution support for string-based SQL statements as well as ClauseElement, Compiled and DefaultGenerator objects. Provides a begin method to return Transaction objects.
The Connection object is not threadsafe.
Construct a new Connection.
Connection objects are typically constructed by an Engine, see the connect() and contextual_connect() methods of Engine.
Begin a transaction and return a Transaction handle.
Repeated calls to begin on the same Connection will create a lightweight, emulated nested transaction. Only the outermost transaction may commit. Calls to commit on inner transactions are ignored. Any transaction in the hierarchy may rollback, however.
Begin a nested transaction and return a Transaction handle.
Nested transactions require SAVEPOINT support in the underlying database. Any transaction in the hierarchy may commit and rollback, however the outermost transaction still controls the overall commit or rollback of the transaction of a whole.
Begin a two-phase or XA transaction and return a Transaction handle.
Returns self.
This Connectable interface method returns self, allowing Connections to be used interchangably with Engines in most situations that require a bind.
Returns self.
This Connectable interface method returns self, allowing Connections to be used interchangably with Engines in most situations that require a bind.
Detach the underlying DB-API connection from its connection pool.
This Connection instance will remain useable. When closed, the DB-API connection will be literally closed and not returned to its pool. The pool will typically lazily create a new connection to replace the detached connection.
This method can be used to insulate the rest of an application from a modified state on a connection (such as a transaction isolation level or similar). Also see PoolListener for a mechanism to modify connection state when connections leave and return to their connection pool.
Invalidate and close the Connection.
The underlying DB-API connection is literally closed (if possible), and is discarded. Its source connection pool will typically lazilly create a new connection to replace it.
Reflect the columns in the given string table name from the database.
Executes and returns the first column of the first row.
Indicates if this Connection should be closed when a corresponding ResultProxy is closed; this is essentially an auto-release mode.
A visitor which accepts ColumnDefault objects, produces the dialect-specific SQL corresponding to their execution, and executes the SQL, returning the result value.
DefaultRunners are used internally by Engines and Dialects. Specific database modules should provide their own subclasses of DefaultRunner to allow database-specific behavior.
Do nothing.
Passive defaults by definition return None on the app side, and are post-fetched to get the DB-side value.
Define the behavior of a specific database and DB-API combination.
Any aspect of metadata definition, SQL query generation, execution, result-set handling, or anything else which varies between databases is defined under the general category of the Dialect. The Dialect acts as a factory for other database-specific object implementations including ExecutionContext, Compiled, DefaultGenerator, and TypeEngine.
All Dialects implement the following attributes:
Build DB-API compatible connection arguments.
Given a URL object, returns a tuple consisting of a *args/**kwargs suitable to send directly to the dbapi's connect function.
Return a new ExecutionContext object.
Create a two-phase transaction ID.
This id will be passed to do_begin_twophase(), do_rollback_twophase(), do_commit_twophase(). Its format is unspecified.
Returns a DB-API to sqlalchemy.types mapping.
A mapping of DB-API type objects present in this Dialect's DB-API implmentation mapped to TypeEngine implementations used by the dialect.
This is used to apply types to result sets based on the DB-API types present in cursor.description; it only takes effect for result sets against textual statements where no explicit typemap was present. Constructed SQL statements always have type information explicitly embedded.
Provide an implementation of connection.begin(), given a DB-API connection.
Provide an implementation of connection.commit(), given a DB-API connection.
Commit a two phase transaction on the given connection.
Provide an implementation of cursor.execute(statement, parameters).
Provide an implementation of cursor.executemany(statement, parameters).
Prepare a two phase transaction on the given connection.
Recover list of uncommited prepared two phase transaction identifiers on the given connection.
Release the named savepoint on a SQL Alchemy connection.
Provide an implementation of connection.rollback(), given a DB-API connection.
Rollback a SQL Alchemy connection to the named savepoint.
Rollback a two phase transaction on the given connection.
Create a savepoint with the given name on a SQLAlchemy connection.
Return the string name of the currently selected schema given a Connection.
Check the existence of a particular sequence in the database.
Given a Connection object and a string sequence_name, return True if the given sequence exists in the database, False otherwise.
Check the existence of a particular table in the database.
Given a Connection object and a string table_name, return True if the given table (possibly within the specified schema) exists in the database, False otherwise.
Return the oid column name for this Dialect
May return None if the dialect can't o won't support OID/ROWID features.
The Column instance which represents OID for the query being compiled is passed, so that the dialect can inspect the column and its parent selectable to determine if OID/ROWID is not selected for a particular selectable (i.e. Oracle doesnt support ROWID for UNION, GROUP BY, DISTINCT, etc.)
Load table description from the database.
Given a Connection and a Table object, reflect its columns and properties from the database. If include_columns (a list or set) is specified, limit the autoload to the given column names.
Transform a generic type to a database-specific type.
Transforms the given TypeEngine instance from generic to database-specific.
Subclasses will usually use the adapt_type() method in the types module to make this job easy.
Connects a Pool, a Dialect and a CompilerFactory together to provide a default implementation of SchemaEngine.
Return a Connection object which may be newly allocated, or may be part of some ongoing context.
This Connection is meant to be used by the various "auto-connecting" operations.
Create a table or index within this engine's database connection given a schema.Table object.
Drop a table or index within this engine's database connection given a schema.Table object.
when True, enable log output for this element.
This has the effect of setting the Python logging level for the namespace of this element's class and object reference. A value of boolean True indicates that the loglevel logging.INFO will be set for the logger, whereas the string value debug will set the loglevel to logging.DEBUG.
String name of the Dialect in use by this Engine.
Given a Table object, reflects its columns and properties from the database.
Return a list of all table names available in the database.
Execute the given function within a transaction boundary.
This is a shortcut for explicitly calling begin() and commit() and optionally rollback() when exceptions are raised. The given *args and **kwargs will be passed to the function, as well as the Connection used in the transaction.
A messenger object for a Dialect that corresponds to a single execution.
ExecutionContext should have these datamembers:
- connection
- Connection object which can be freely used by default value generators to execute SQL. This Connection should reference the same underlying connection/transactional resources of root_connection.
- root_connection
- Connection object which is the source of this ExecutionContext. This Connection may have close_with_result=True set, in which case it can only be used once.
dialect which created this ExecutionContext.
The Dialect should provide an ExecutionContext via the create_execution_context() method. The pre_exec and post_exec methods will be called for compiled statements.
Return a new cursor generated from this ExecutionContext's connection.
Some dialects may wish to change the behavior of connection.cursor(), such as postgres which may return a PG "server side" cursor.
Return the 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. The order of items in the list is the same as that of the Table's 'primary_key' attribute.
Return a dictionary of the full parameter dictionary for the last compiled INSERT statement.
Includes any ColumnDefaults or Sequences that were pre-executed.
Return a dictionary of the full parameter dictionary for the last compiled UPDATE statement.
Includes any ColumnDefaults that were pre-executed.
Return True if the last row INSERTED via a compiled insert statement contained PassiveDefaults.
The presence of PassiveDefaults indicates that the database inserted data beyond that which we passed to the query programmatically.
Called after the execution of a compiled statement.
If a compiled statement was passed to this ExecutionContext, the last_insert_ids, last_inserted_params, etc. datamembers should be available after this method completes.
return a list of Column objects for which a 'passive' server-side default value was fired off. applies to inserts and updates.
Called before an execution of a compiled statement.
If a compiled statement was passed to this ExecutionContext, the statement and parameters datamembers must be initialized after this statement is complete.
Return a result object corresponding to this ExecutionContext.
Returns a ResultProxy.
Return True if this context's statement should be 'committed' automatically in a non-transactional context
Wraps a DB-API cursor object to provide easier access to row columns.
Individual columns may be accessed by their integer position, case-insensitive column name, or by schema.Column object. e.g.:
row = fetchone() col1 = row[0] # access via integer position col2 = row['col2'] # access via name col3 = row[mytable.c.mycol] # access via Column object.
ResultProxy also contains a map of TypeEngine objects and will invoke the appropriate result_processor() method before returning columns, as well as the ExecutionContext corresponding to the statement execution. It provides several methods for which to obtain information from the underlying ExecutionContext.
ResultProxy objects are constructed via the execute() method on SQLEngine.
Close this ResultProxy, and the underlying DB-API cursor corresponding to the execution.
If this ResultProxy was generated from an implicit execution, the underlying Connection will also be closed (returns the underlying DB-API connection to the connection pool.)
This method is also called automatically when all result rows are exhausted.
Fetch many rows, just like DB-API cursor.fetchmany(size=cursor.arraysize).
Return last_inserted_ids() from the underlying ExecutionContext.
See ExecutionContext for details.
Return last_inserted_params() from the underlying ExecutionContext.
See ExecutionContext for details.
Return last_updated_params() from the underlying ExecutionContext.
See ExecutionContext for details.
Return lastrow_has_defaults() from the underlying ExecutionContext.
See ExecutionContext for details.
Return supports_sane_rowcount() from the underlying ExecutionContext.
See ExecutionContext for details.
Proxy a single cursor row for a parent ResultProxy.
Mostly follows "ordered dictionary" behavior, mapping result values to the string-based column name, the integer position of the result in the row, as well as Column instances which can be mapped to the original Columns that produced this result set (for results that correspond to constructed SQL expressions).
A visitor that can gather text into a buffer and execute the contents of the buffer.
Represent a Transaction in progress.
The Transaction object is not threadsafe.
close this transaction.
If this transaction is the base transaction in a begin/commit nesting, the transaction will rollback(). Otherwise, the method returns.
This is used to cancel a Transaction without affecting the scope of an enclosign transaction.