defines the basic components used to interface DBAPI modules with higher-level statement-construction, connection-management, execution and result contexts. The primary "entry point" class into this package is the Engine.
The package is represented among several individual modules, including:
- base.py
- Defines interface classes and some implementation classes which comprise the basic components used to interface between a DBAPI, constructed and plain-text statements, connections, transactions, and results.
- default.py
- Contains default implementations of some of the components defined in base.py. All current database dialects use the classes in default.py as base classes for their own database-specific implementations.
- strategies.py
- the mechanics of constructing Engine objects are represented here. Defines the EngineStrategy class which represents how to go from arguments specified to the create_engine() function, to a fully constructed Engine, including initialization of connection pooling, dialects, and specific subclasses of Engine.
- threadlocal.py
- the TLEngine class is defined here, which is a subclass of the generic Engine and tracks Connection and Transaction objects against the identity of the current thread. This allows certain programming patterns based around the concept of a "thread-local connection" to be possible. The TLEngine is created by using the "threadlocal" engine strategy in conjunction with the create_engine() function.
- url.py
- Defines the URL class which represents the individual components of a string URL passed to create_engine(). Also defines a basic module-loading strategy for the dialect specifier within a URL.
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 DBAPI 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.
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 DBAPIs as well (Pygresql, currently unsupported).
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 DBAPI 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.
Interface for an object that can provide an Engine and a Connection object which correponds to that Engine.
Represent a single DBAPI connection returned from the underlying connection pool.
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.
connect() is implemented to return self so that an incoming Engine or Connection object can be treated similarly.
contextual_connect() is implemented to return self so that an incoming Engine or Connection object can be treated similarly.
detach the underlying DBAPI connection from its connection pool.
This Connection instance will remain useable. When closed, the DBAPI connection will be literally closed and not returned to its pool. The pool will typically create a new connection to replace it, once requested.
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).
invalidate the underying DBAPI connection and immediately close this Connection.
The underlying DBAPI connection is literally closed (if possible), and is discarded. Its source connection pool will typically create a new connection to replace it, once requested.
Reflect the columns in the given string table name from the database.
Indicates if this Connection should be closed when a corresponding ResultProxy is closed; this is essentially an auto-release mode.
Define an interface that returns raw Connection objects (or compatible).
Release all resources corresponding to this ConnectionProvider.
This includes any underlying connection pools.
Return a Connection or compatible object from a DBAPI which also contains a close() method.
It is not defined what context this connection belongs to. It may be newly connected, returned from a pool, part of some other kind of context such as thread-local, or can be a fixed member of this object.
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/DBAPI.
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:
- positional
- True if the paramstyle for this Dialect is positional
- paramstyle
- The paramstyle to be used (some DBAPIs support multiple paramstyles)
- convert_unicode
- True if unicode conversion should be applied to all str types
- encoding
- type of encoding to use for unicode, usually defaults to 'utf-8'
Compile the given ClauseElement using this Dialect.
Returns Compiled. A convenience method which flips around the compile() call on ClauseElement.
Return a Compiled object for the given statement/parameters.
The returned object is usually a subclass of ANSICompiler.
Build DBAPI execute arguments from a ClauseParameters instance.
Returns an array or dictionary suitable to pass directly to this Dialect instance's DBAPI's execute method.
Build DBAPI 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.
Return a SchemaVisitor instance that can execute defaults.
Provide an implementation of connection.begin(), given a DBAPI connection.
Provide an implementation of connection.commit(), given a DBAPI connection.
Provide an implementation of cursor.execute(statement, parameters).
Provide an implementation of cursor.executemany(statement, parameters).
Provide an implementation of connection.rollback(), given a DBAPI 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 maximum length of identifier names.
Return None if no limit.
Return the oid column name for this dialect, or None if the dialect can't/won't support OID/ROWID.
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.
Return a SchemaVisitor instance that can drop schemas.
- connection
- a Connection to use for statement execution
schemadropper() is called via the drop() method on Table, Index, and others.
Return a SchemaVisitor instance that can generate schemas.
- connection
- a Connection to use for statement execution
schemagenerator() is called via the create() method on Table, Index, and others.
Indicate whether the dialect properly implements rowcount for UPDATE and DELETE statements.
This was needed for MySQL which had non-standard behavior of rowcount, but this issue has since been resolved.
indicate whether the DBAPI can receive SQL statements as Python unicode strings
Transform 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 ConnectionProvider, 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.
the Dialect in use by this engine.
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.
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.
The URL object representing this Engine object's datasource.
A messenger object for a Dialect that corresponds to a single execution.
ExecutionContext should have these datamembers:
- connection
- Connection object which initiated the call to the dialect to create this ExecutionContext.
- dialect
- dialect which created this ExecutionContext.
- cursor
- DBAPI cursor procured from the connection
- compiled
- if passed to constructor, sql.Compiled object being executed
- compiled_parameters
- if passed to constructor, sql.ClauseParameters object
- statement
- string version of the statement to be executed. Is either passed to the constructor, or must be created from the sql.Compiled object by the time pre_exec() has completed.
- parameters
- "raw" parameters suitable for direct execution by the dialect. Either passed to the constructor, or must be created from the sql.ClauseParameters object by the time pre_exec() has completed.
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 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, which are executed via 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.
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 compiled was passed to this ExecutionContext, the last_insert_ids, last_inserted_params, etc. datamembers should be available after this method completes.
Called before an execution of a compiled statement.
If compiled and compiled_parameters were passed to this ExecutionContext, the statement and parameters datamembers must be initialized after this statement is complete.
Wraps a DBAPI 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 convert_result_value() 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 DBAPI cursor corresponding to the execution.
If this ResultProxy was generated from an implicit execution, the underlying Connection will also be closed (returns the underlying DBAPI connection to the connection pool.)
This method is also called automatically when all result rows are exhausted.
Fetch many rows, just like DBAPI 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.