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 URL.
**kwargs takes a wide variety of options which are routed towards their appropriate components. Arguments may be specific to the Engine, the underlying Dialect, as well as the Pool. Specific dialects also accept keyword arguments that are unique to that dialect. Here, we describe the parameters that are common to most create_engine() usage.
| Parameters: |
|
|---|
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 and include dialect-specific arguments.
Represent the components of a URL used to connect to a database.
This object is suitable to be passed directly to a create_engine() call. The fields of the URL are parsed from a string by the module-level make_url() function. the string format of the URL is an RFC-1738-style string.
All initialization parameters are available as public attributes.
| Parameters: |
|
|---|
Translate url attributes into a dictionary of connection arguments.
Returns attributes of this url (host, database, username, password, port) as a plain dictionary. The attribute names are used as the keys by default. Unset or false attributes are omitted from the final dictionary.
| Parameters: |
|
|---|
Connects a Pool and Dialect together to provide a source of database connectivity and behavior.
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.
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.
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.
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 thread-safe.
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 the underlying DBAPI connection associated with this Connection.
The underlying DB-API connection is literally closed (if possible), and is discarded. Its source connection pool will typically lazily create a new connection to replace it.
Upon the next usage, this Connection will attempt to reconnect to the pool with a new connection.
Transactions in progress remain in an “opened” state (even though the actual transaction is gone); these must be explicitly rolled back before a reconnect on this Connection can proceed. This is to prevent applications from accidentally continuing their transactional operations in a non-transactional state.
Executes and returns the first column of the first row.
The underlying result/cursor is closed after execution.
Interface for an object which supports execution of SQL constructs.
The two implementations of Connectable are Connection and Engine.
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.
Close this ResultProxy.
Closes 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 called automatically when:
- all result rows are exhausted using the fetchXXX() methods.
- cursor.description is None.
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 postfetch_cols() 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).
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 enclosing transaction.
Decorator, memoize a function in a connection.info stash.
Only applicable to functions which take no arguments other than a connection. The memo will be stored in connection.info[key].
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:
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.
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.
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.
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.
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.
Bases: sqlalchemy.engine.base.Dialect
Default implementation of Dialect
Create a random two-phase transaction ID.
This id will be passed to do_begin_twophase(), do_rollback_twophase(), do_commit_twophase(). Its format is unspecified.
Provide 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.
Bases: sqlalchemy.engine.base.ExecutionContext
Bases: sqlalchemy.schema.SchemaVisitor
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.
A messenger object for a Dialect that corresponds to a single execution.
ExecutionContext should have these datamembers:
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.
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.
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.
Bases: sqlalchemy.schema.SchemaVisitor
A visitor that can gather text into a buffer and execute the contents of the buffer.