defines the base components of SQL expression trees.
joins a list of clauses together by the AND operator. the & operator can be used as well.
returns BETWEEN predicate clause (clausetest BETWEEN clauseleft AND clauseright).
this is better called off a ColumnElement directly, i.e.
column.between(value1, value2).
creates a bind parameter clause with the given key.
An optional default value can be specified by the value parameter, and the optional type parameter is a sqlalchemy.types.TypeEngine object which indicates bind-parameter and result-set translation for this bind parameter.
SQL CASE statement -- whens are a sequence of pairs to be translated into "when / then" clauses; optional [value] for simple case statements, and [else_] for case defaults
returns CAST function CAST(clause AS totype) Use with a sqlalchemy.types.TypeEngine object, i.e cast(table.c.unit_price * table.c.qty, Numeric(10,4)) or cast(table.c.timestamp, DATE)
returns a textual column clause, relative to a table. this is also the primitive version of a schema.Column which is a subclass.
returns a DELETE clause element.
This can also be called from a table directly via the table's delete() method.
'table' is the table to be updated. 'whereclause' is a ClauseElement describing the WHERE condition of the UPDATE statement.
returns an INSERT clause element.
This can also be called from a table directly via the table's insert() method.
'table' is the table to be inserted into.
'values' is a dictionary which specifies the column specifications of the INSERT, and is optional. If left as None, the column specifications are determined from the bind parameters used during the compile phase of the INSERT statement. If the bind parameters also are None during the compile phase, then the column specifications will be generated from the full list of table columns.
If both 'values' and compile-time bind parameters are present, the compile-time bind parameters override the information specified within 'values' on a per-key basis.
The keys within 'values' can be either Column objects or their string identifiers. Each key may reference one of: a literal data value (i.e. string, number, etc.), a Column object, or a SELECT statement. If a SELECT statement is specified which references this INSERT statement's table, the statement will be correlated against the INSERT statement.
return a JOIN clause element (regular inner join).
left - the left side of the join right - the right side of the join onclause - optional criterion for the ON clause, is derived from foreign key relationships otherwise
To chain joins together, use the resulting Join object's "join()" or "outerjoin()" methods.
returns a literal clause, bound to a bind parameter.
literal clauses are created automatically when used as the right-hand side of a boolean or math operation against a column object. use this function when a literal is needed on the left-hand side (and optionally on the right as well).
the optional type parameter is a sqlalchemy.types.TypeEngine object which indicates bind-parameter and result-set translation for this literal.
returns a negation of the given clause, i.e. NOT(clause). the ~ operator can be used as well.
joins a list of clauses together by the OR operator. the | operator can be used as well.
return an OUTER JOIN clause element.
left - the left side of the join right - the right side of the join onclause - optional criterion for the ON clause, is derived from foreign key relationships otherwise
To chain joins together, use the resulting Join object's "join()" or "outerjoin()" methods.
returns a SELECT clause element.
this can also be called via the table's select() method.
'columns' is a list of columns and/or selectable items to select columns from 'whereclause' is a text or ClauseElement expression which will form the WHERE clause 'from_obj' is an list of additional "FROM" objects, such as Join objects, which will extend or override the default "from" objects created from the column list and the whereclause. **kwargs - additional parameters for the Select object.
returns a table clause. this is a primitive version of the schema.Table object, which is a subclass of this object.
creates literal text to be inserted into a query.
When constructing a query from a select(), update(), insert() or delete(), using plain strings for argument values will usually result in text objects being created automatically. Use this function when creating textual clauses outside of other ClauseElement objects, or optionally wherever plain text is to be used.
Arguments include:
text - the text of the SQL statement to be created. use :<param> to specify bind parameters; they will be compiled to their engine-specific format.
engine - an optional engine to be used for this text query.
bindparams - a list of bindparam() instances which can be used to define the types and/or initial values for the bind parameters within the textual statement; the keynames of the bindparams must match those within the text of the statement. The types will be used for pre-processing on bind values.
typemap - a dictionary mapping the names of columns represented in the SELECT clause of the textual statement to type objects, which will be used to perform post-processing on columns within the result set (for textual statements that produce result sets).
returns an UPDATE clause element.
This can also be called from a table directly via the table's update() method.
'table' is the table to be updated. 'whereclause' is a ClauseElement describing the WHERE condition of the UPDATE statement. 'values' is a dictionary which specifies the SET conditions of the UPDATE, and is optional. If left as None, the SET conditions are determined from the bind parameters used during the compile phase of the UPDATE statement. If the bind parameters also are None during the compile phase, then the SET conditions will be generated from the full list of table columns.
If both 'values' and compile-time bind parameters are present, the compile-time bind parameters override the information specified within 'values' on a per-key basis.
The keys within 'values' can be either Column objects or their string identifiers. Each key may reference one of: a literal data value (i.e. string, number, etc.), a Column object, or a SELECT statement. If a SELECT statement is specified which references this UPDATE statement's table, the statement will be correlated against the UPDATE statement.
represents the behavior of a particular database. Used by Compiled objects.
base class for elements of a programmatically constructed SQL expression.
compare this ClauseElement to the given ClauseElement.
Subclasses should override the default behavior, which is a straight identity comparison.
compile this SQL expression.
Uses the given Compiler, or the given AbstractDialect or Engine to create a Compiler. If no compiler arguments are given, tries to use the underlying Engine this ClauseElement is bound to to create a Compiler, if any. Finally, if there is no bound Engine, uses an ANSIDialect to create a default Compiler.
bindparams is a dictionary representing the default bind parameters to be used with the statement. if the bindparams is a list, it is assumed to be a list of dictionaries and the first dictionary in the list is used with which to compile against. The bind parameters can in some cases determine the output of the compilation, such as for UPDATE and INSERT statements the bind parameters that are present determine the SET and VALUES clause of those statements.
return a copy of this ClauseElement, iff this ClauseElement contains other ClauseElements.
If this ClauseElement is not a container, it should return self. This is used to create copies of expression trees that still reference the same "leaf nodes". The new structure can then be restructured without affecting the original.
represents a dictionary/iterator of bind parameter key names/values.
Tracks the original BindParam objects as well as the keys/position of each parameter, and can return parameters as a dictionary or a list. Will process parameter values according to the TypeEngine objects present in the BindParams.
an ordered dictionary that stores a list of ColumnElement instances.
overrides the __eq__() method to produce SQL clauses between sets of correlated columns.
represents a column element within the list of a Selectable's columns. A ColumnElement can either be directly associated with a TableClause, or a free-standing textual column with no table, or is a "proxy" column, indicating it is placed on a Selectable such as an Alias or Select statement and ultimately corresponds to a TableClause-attached column (or in the case of a CompositeSelect, a proxy ColumnElement may correspond to several TableClause-attached columns).
Columns accessor which just returns self, to provide compatibility with Selectable objects.
foreign key accessor. points to a ForeignKey object which represents a Foreign Key placed on this column's ultimate ancestor.
a Set containing TableClause-bound, non-proxied ColumnElements for which this ColumnElement is a proxy. In all cases except for a column proxied from a Union (i.e. CompoundSelect), this set will be just one element.
represents a compiled SQL expression. the __str__ method of the Compiled object should produce the actual text of the statement. Compiled objects are specific to the database library that created them, 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.
statement - ClauseElement to be compiled
parameters - optional dictionary indicating a set of bind parameters specified with this Compiled object. These parameters are the "default" values corresponding to the ClauseElement's _BindParamClauses when the Compiled is executed. In the case of an INSERT or UPDATE statement, these parameters will also result in the creation of new _BindParamClause objects for each key and will also affect the generated column list in an INSERT statement and the SET clauses of an UPDATE statement. The keys of the parameter dictionary can either be the string names of columns or _ColumnClause objects.
engine - optional Engine to compile this statement against
returns the bind params for this compiled object.
Will start with the default parameters specified when this Compiled object was first constructed, and will override those values with those sent via **params, which are key/value pairs. Each key should match one of the _BindParamClause objects compiled into this object; either the "key" or "shortname" property of the _BindParamClause.
represents a 'thing that can produce Compiled objects and execute them'.
represents an element that can be used within the FROM clause of a SELECT statement.
given a ColumnElement, return the ColumnElement object from this Selectable which corresponds to that original Column via a proxy relationship.
True if the name of this FromClause may be prepended to a column in a generated SQL statement
represents a SELECT statement, with appendable clauses, as well as the ability to execute itself and return a result set.
the schema module provides the building blocks for database metadata. This means all the entities within a SQL database that we might want to look at, modify, or create and delete are described by these objects, in a database-agnostic way.
A structure of SchemaItems also provides a "visitor" interface which is the primary method by which other methods operate upon the schema. The SQL package extends this structure with its own clause-specific objects as well as the visitor interface, so that the schema package "plugs in" to the SQL package.
builds upon MetaData to provide the capability to bind to an Engine implementation.
represents a column in a database table. this is a subclass of sql.ColumnClause and represents an actual existing table in the database, in a similar fashion as TableClause/Table.
constructs a new Column object. Arguments are:
name : the name of this column. this should be the identical name as it appears, or will appear, in the database.
type: the TypeEngine for this column. This can be any subclass of types.AbstractType, including the database-agnostic types defined in the types module, database-specific types defined within specific database modules, or user-defined types.
*args: Constraint, ForeignKey, ColumnDefault and Sequence objects should be added as list values.
**kwargs : keyword arguments include:
key=None : an optional "alias name" for this column. The column will then be identified everywhere in an application, including the column list on its Table, by this key, and not the given name. Generated SQL, however, will still reference the column by its actual name.
primary_key=False : True if this column is a primary key column. Multiple columns can have this flag set to specify composite primary keys. As an alternative, the primary key of a Table can be specified via an explicit PrimaryKeyConstraint instance appended to the Table's list of objects.
nullable=True : True if this column should allow nulls. Defaults to True unless this column is a primary key column.
default=None : a scalar, python callable, or ClauseElement representing the "default value" for this column, which will be invoked upon insert if this column is not present in the insert list or is given a value of None. The default expression will be converted into a ColumnDefault object upon initialization.
_is_oid=False : used internally to indicate that this column is used as the quasi-hidden "oid" column
index=False : Indicates that this column is indexed. The name of the index is autogenerated. to specify indexes with explicit names or indexes that contain multiple columns, use the Index construct instead.
unique=False : Indicates that this column contains a unique constraint, or if index=True as well, indicates that the Index should be created with the unique flag. To specify multiple columns in the constraint/index or to specify an explicit name, use the UniqueConstraint or Index constructs instead.
autoincrement=True : Indicates that integer-based primary key columns should have autoincrementing behavior, if supported by the underlying database. This will affect CREATE TABLE statements such that they will use the databases "auto-incrementing" keyword (such as SERIAL for postgres, AUTO_INCREMENT for mysql) and will also affect the behavior of some dialects during INSERT statement execution such that they will assume primary key values are created in this manner. If a Column has an explicit ColumnDefault object (such as via the "default" keyword, or a Sequence or PassiveDefault), then the value of autoincrement is ignored and is assumed to be False. autoincrement value is only significant for a column with a type or subtype of Integer.
quote=False : indicates that the Column identifier must be properly escaped and quoted before being sent to the database. This flag should normally not be required as dialects can auto-detect conditions where quoting is required.
case_sensitive=True : indicates that the identifier should be interpreted by the database in the natural case for identifiers. Mixed case is not sufficient to cause this identifier to be quoted; it must contain an illegal character.
A plain default value on a column. this could correspond to a constant, a callable function, or a SQL clause.
represents a table-level Constraint such as a composite primary key, foreign key, or unique constraint.
Implements a hybrid of dict/setlike behavior with regards to the list of underying columns
builds upon MetaData to provide the capability to bind to multiple Engine implementations on a dynamically alterable, thread-local basis.
defines a column-level ForeignKey constraint between two columns.
ForeignKey is specified as an argument to a Column object.
One or more ForeignKey objects are used within a ForeignKeyConstraint object which represents the table-level constraint definition.
Construct a new ForeignKey object.
"column" can be a schema.Column object representing the relationship, or just its string name given as "tablename.columnname". schema can be specified as "schema.tablename.columnname"
"constraint" is the owning ForeignKeyConstraint object, if any. if not given, then a ForeignKeyConstraint will be automatically created and added to the parent table.
table-level foreign key constraint, represents a colleciton of ForeignKey objects.
Represents an index of columns from a database table
Constructs an index object. Arguments are:
name : the name of the index
*columns : columns to include in the index. All columns must belong to the same table, and no column may appear more than once.
**kw : keyword arguments include:
unique=True : create a unique index
represents a collection of Tables and their associated schema constructs.
create all tables stored in this metadata.
This will conditionally create tables depending on if they do not yet exist in the database.
connectable - a Connectable used to access the database; or use the engine bound to this MetaData.
tables - optional list of tables, which is a subset of the total tables in the MetaData (others are ignored)
drop all tables stored in this metadata.
This will conditionally drop tables depending on if they currently exist in the database.
connectable - a Connectable used to access the database; or use the engine bound to this MetaData.
tables - optional list of tables, which is a subset of the total tables in the MetaData (others are ignored)
a default that takes effect on the database side
represents a sequence, which applies to Oracle and Postgres databases.
represents a relational database table. This subclasses sql.TableClause to provide a table that is "wired" to an engine. Whereas TableClause represents a table as its used in a SQL expression, Table represents a table as its created in the database.
Be sure to look at sqlalchemy.sql.TableImpl for additional methods defined on a Table.
Construct a Table.
Table objects can be constructed directly. The init method is actually called via the TableSingleton metaclass. Arguments are:
name : the name of this table, exactly as it appears, or will appear, in the database. This property, along with the "schema", indicates the "singleton identity" of this table. Further tables constructed with the same name/schema combination will return the same Table instance.
*args : should contain a listing of the Column objects for this table.
**kwargs : options include:
schema=None : the "schema name" for this table, which is required if the table resides in a schema other than the default selected schema for the engine's database connection.
autoload=False : the Columns for this table should be reflected from the database. Usually there will be no Column objects in the constructor if this property is set.
mustexist=False : indicates that this Table must already have been defined elsewhere in the application, else an exception is raised.
useexisting=False : indicates that if this Table was already defined elsewhere in the application, disregard the rest of the constructor arguments. If this flag and the "redefine" flag are not set, constructing the same table twice will result in an exception.
owner=None : optional owning user of this table. useful for databases such as Oracle to aid in table reflection.
quote=False : indicates that the Table identifier must be properly escaped and quoted before being sent to the database. This flag overrides all other quoting behavior.
quote_schema=False : indicates that the Namespace identifier must be properly escaped and quoted before being sent to the database. This flag overrides all other quoting behavior.
case_sensitive=True : indicates that the identifier should be interpreted by the database in the natural case for identifiers. Mixed case is not sufficient to cause this identifier to be quoted; it must contain an illegal character.
case_sensitive_schema=True : indicates that the identifier should be interpreted by the database in the natural case for identifiers. Mixed case is not sufficient to cause this identifier to be quoted; it must contain an illegal character.
issue a CREATE statement for this table.
see also metadata.create_all().
creates a new Engine instance. Using the given strategy name, locates that strategy and invokes its create() method to produce the Engine. The strategies themselves are instances of EngineStrategy, and the built in ones are present in the sqlalchemy.engine.strategies module. 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 connection and transaction without the need for explicit passing of a Connection object.
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 in the form <dialect>://opt1=val1&opt2=val2. Where <dialect> is a name such as "mysql", "oracle", "postgres", and the options indicate username, password, database, etc. Supported keynames include "username", "user", "password", "pw", "db", "database", "host", "filename".
**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:
pool=None : an instance of sqlalchemy.pool.DBProxy or sqlalchemy.pool.Pool to be used as the underlying source for connections (DBProxy/Pool is described in the previous section). If None, a default DBProxy will be created using the engine's own database module with the given arguments.
echo=False : if True, the Engine will log all statements as well as a repr() of their parameter lists to the engines logger, which defaults to sys.stdout. A Engine instances' "echo" data member can be modified at any time to turn logging on and off. If set to the string 'debug', result rows will be printed to the standard output as well.
logger=None : a file-like object where logging output can be sent, if echo is set to True. This defaults to sys.stdout.
encoding='utf-8' : the encoding to be used when encoding/decoding Unicode strings
convert_unicode=False : True if unicode conversion should be applied to all str types
module=None : used by Oracle and Postgres, this is a reference to a DBAPI2 module to be used instead of the engine's default module. For Postgres, the default is psycopg2, or psycopg1 if 2 cannot be found. For Oracle, its cx_Oracle. For mysql, MySQLdb.
use_ansi=True : used only by Oracle; when False, the Oracle driver attempts to support a particular "quirk" of some Oracle databases, that the LEFT OUTER JOIN SQL syntax is not supported, and the "Oracle join" syntax of using <column1>(+)=<column2> must be used in order to achieve a LEFT OUTER JOIN. Its advised that the Oracle database be configured to have full ANSI support instead of using this feature.
provides 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:
name : the name of the engine, suitable for use in the create_engine function
description: a plain description of the engine.
arguments : a dictionary describing the name and description of each parameter used to connect to this engine's underlying DBAPI.
This function is meant for usage in automated configuration tools that wish to query the user for database and connection information.
interface for an object that can provide an Engine and a Connection object which correponds to that Engine.
represents 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.
executes the given statement string and parameter object. the parameter object is expected to be the result of a call to compiled.get_params(). This callable is a generic version of a connection/cursor-specific callable that is produced within the execute_compiled method, and is used for objects that require this style of proxy when outside of an execute_compiled method, primarily the DefaultRunner.
defines an interface that returns raw Connection objects (or compatible).
releases all resources corresponding to this ConnectionProvider, such as any underlying connection pools.
this method should 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.
Defines the behavior of a specific database/DBAPI.
Any aspect of metadata defintion, 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)
supports_autoclose_results - usually True; if False, indicates that rows returned by fetchone() might not be just plain tuples, and may be "live" proxy objects which still require the cursor to be open in order to be read (such as pyPgSQL which has active filehandles for BLOBs). in that case, an auto-closing ResultProxy cannot automatically close itself after results are consumed.
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.
a convenience method which simply flips around the compile() call on ClauseElement.
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.
given a sql.ClauseParameters object, returns an array or dictionary suitable to pass directly to this Dialect's DBAPI's execute method.
given a dictionary of key-valued connect parameters, returns a tuple consisting of a *args/**kwargs suitable to send directly to the dbapi's connect function. The connect args will have any number of the following keynames: host, hostname, database, dbanme, user,username, password, pw, passwd, filename.
subclasses override this method to provide the DBAPI module used to establish connections.
returns a schema.SchemaVisitor instances that can execute defaults.
returns the currently selected schema given an connection
returns the oid column name for this dialect, or None if the dialect cant/wont support OID/ROWID.
given an Connection and a Table object, reflects its columns and properties from the database.
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 on Table, Index, and others.
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 on Table, Index, and others.
Connects a ConnectionProvider, a Dialect and a CompilerFactory together to provide a default implementation of SchemaEngine.
returns 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.
creates a table or index within this engine's database connection given a schema.Table object.
drops a table or index within this engine's database connection given a schema.Table object.
given a Table object, reflects its columns and properties from the database.
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. 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. 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, afterwhich it is expected that the various methods last_inserted_ids, last_inserted_params, etc. will contain appropriate values, if applicable.
returns the count of rows updated/deleted for an UPDATE/DELETE statement
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 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.
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. proxy is a callable that takes a string statement and a bind parameter list/dictionary.
wraps a DBAPI cursor object to provide access to row columns based on 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.
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.
proxies 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.
construct a new SchemaIterator.
engine - the Engine used by this SchemaIterator
proxy - a callable which takes a statement and bind parameters and executes it, returning the cursor (the actual DBAPI cursor). The callable should use the same cursor repeatedly.
represents 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.
Attributes on URL include:
drivername
username
password
host
port
database
query - a dictionary containing key/value pairs representing the URL's query string.
translate this URL's attributes into a dictionary of connection arguments.
given a list of argument names corresponding to the URL attributes ('host', 'database', 'username', 'password', 'port'), will assemble the attribute values of this URL into the dictionary using the given names.
the mapper package provides object-relational functionality, building upon the schema and sql packages and tying operations to class properties and constructors.
create a BackRef object with explicit arguments, which are the same arguments one can send to relation().
used with the "backref" keyword argument to relation() in place of a string argument.
attempt to create a series of relations() between mappers automatically, via introspecting the foreign key relationships of the underlying tables.
given a list of classes and/or mappers, identifies the foreign key relationships between the given mappers or corresponding class mappers, and creates relation() objects representing those relationships, including a backreference. Attempts to find the "secondary" table in a many-to-many relationship as well. The names of the relations will be a lowercase version of the related class. In the case of one-to-many or many-to-many, the name will be "pluralized", which currently is based on the English language (i.e. an 's' or 'es' added to it).
NOTE: this method usually works poorly, and its usage is generally not advised.
given a ClassKey, returns the primary Mapper associated with the key.
remove the given mapper from the storage of mappers.
when a new mapper is created for the previous mapper's class, it will be used as that classes' new primary mapper.
remove all mappers that have been created thus far.
when new mappers are created, they will be assigned to their classes as their primary mapper.
return a MapperOption that will indicate to the query that the given attribute will be eagerly loaded without any row decoration, or using a custom row decorator.
used when feeding SQL result sets directly into query.instances().
return a MapperOption that will convert the column property of the given name into a deferred load.
used with query.options()
return a DeferredColumnProperty, which indicates this object attributes should only be loaded from its corresponding table column when first accessed.
used with the 'properties' dictionary sent to mapper().
return a MapperOption that will convert the property of the given name into an eager load.
used with query.options().
return a MapperOption that will insert the given MapperExtension to the beginning of the list of extensions that will be called in the context of the Query.
used with query.options().
return a MapperOption that will convert the property of the given name into a lazy load.
used with query.options().
return a new Mapper object.
See the Mapper class for a description of arguments.
return a MapperOption that will convert the property of the given name into a non-load.
used with query.options().
given an object, returns the primary Mapper associated with the object instance
create a UNION statement used by a polymorphic mapper.
See the SQLAlchemy advanced mapping docs for an example of how this is used.
provide a relationship of a primary Mapper to a secondary Mapper.
This corresponds to a parent-child or associative table relationship.
base implementation for an object that provides overriding behavior to various Mapper functions. For each method in MapperExtension, a result of EXT_PASS indicates the functionality is not overridden.
receive an object instance after that instance is DELETEed.
receive an object instance after that instance is INSERTed.
receive an object instance after that instance is UPDATEed.
receive an object instance before that instance is appended to a result list.
If this method returns EXT_PASS, result appending will proceed normally. if this method returns any other value or None, result appending will not proceed for this instance, giving this extension an opportunity to do the appending itself, if desired.
mapper - the mapper doing the operation
selectcontext - SelectionContext corresponding to the instances() call
row - the result row from the database
instance - the object instance to be appended to the result
identitykey - the identity key of the instance
result - list to which results are being appended
isnew - indicates if this is the first time we have seen this object instance in the current result set. if you are selecting from a join, such as an eager load, you might see the same object instance many times in the same result set.
receive an object instance before that instance is DELETEed.
receive an object instance before that instance is INSERTed into its table.
this is a good place to set up primary key values and such that arent handled otherwise.
receive an object instance before that instance is UPDATEed.
receieve a row when a new object instance is about to be created from that row. the method can choose to create the instance itself, or it can return None to indicate normal object creation should take place.
mapper - the mapper doing the operation
selectcontext - SelectionContext corresponding to the instances() call
row - the result row from the database
class_ - the class we are mapping.
override the get method of the Query object.
the return value of this method is used as the result of query.get() if the value is anything other than EXT_PASS.
override the get_by method of the Query object.
the return value of this method is used as the result of query.get_by() if the value is anything other than EXT_PASS.
retrieve a contextual Session instance with which to register a new object.
Note: this is not called if a session is provided with the __init__ params (i.e. _sa_session)
override the load method of the Query object.
the return value of this method is used as the result of query.load() if the value is anything other than EXT_PASS.
receive a newly-created instance before that instance has its attributes populated.
The normal population of attributes is according to each attribute's corresponding MapperProperty (which includes column-based attributes as well as relationships to other classes). If this method returns EXT_PASS, instance population will proceed normally. If any other value or None is returned, instance population will not proceed, giving this extension an opportunity to populate the instance itself, if desired.
Defines the correlation of class attributes to database table columns.
Instances of this class should be constructed via the sqlalchemy.orm.mapper() function.
construct a new mapper.
All arguments may be sent to the sqlalchemy.orm.mapper() function where they are passed through to here.
class_ - the class to be mapped.
local_table - the table to which the class is mapped, or None if this mapper inherits from another mapper using concrete table inheritance.
properties - a dictionary mapping the string names of object attributes to MapperProperty instances, which define the persistence behavior of that attribute. Note that the columns in the mapped table are automatically converted into ColumnProperty instances based on the "key" property of each Column (although they can be overridden using this dictionary).
primary_key - a list of Column objects which define the "primary key" to be used against this mapper's selectable unit. This is normally simply the primary key of the "local_table", but can be overridden here.
non_primary - construct a Mapper that will define only the selection of instances, not their persistence.
inherits - another Mapper for which this Mapper will have an inheritance relationship with.
inherit_condition - for joined table inheritance, a SQL expression (constructed ClauseElement) which will define how the two tables are joined; defaults to a natural join between the two tables.
extension - a MapperExtension instance or list of MapperExtension instances which will be applied to all operations by this Mapper.
order_by - a single Column or list of Columns for which selection operations should use as the default ordering for entities. Defaults to the OID/ROWID of the table if any, or the first primary key column of the table.
allow_column_override - if True, allows association relationships to be set up which override the usage of a column that is on the table (based on key/attribute name).
entity_name - a name to be associated with the class, to allow alternate mappings for a single class.
always_refresh - if True, all query operations for this mapped class will overwrite all data within object instances that already exist within the session, erasing any in-memory changes with whatever information was loaded from the database.
version_id_col - a Column which must have an integer type that will be used to keep a running "version id" of mapped entities in the database. this is used during save operations to insure that no other thread or process has updated the instance during the lifetime of the entity, else a ConcurrentModificationError exception is thrown.
polymorphic_on - used with mappers in an inheritance relationship, a Column which will identify the class/mapper combination to be used with a particular row. requires the polymorphic_identity value to be set for all mappers in the inheritance hierarchy.
_polymorphic_map - used internally to propigate the full map of polymorphic identifiers to surrogate mappers.
polymorphic_identity - a value which will be stored in the Column denoted by polymorphic_on, corresponding to the "class identity" of this mapper.
concrete - if True, indicates this mapper should use concrete table inheritance with its parent mapper.
select_table - a Table or (more commonly) Selectable which will be used to select instances of this mapper's class. usually used to provide polymorphic loading among several classes in an inheritance hierarchy.
allow_null_pks - indicates that composite primary keys where one or more (but not all) columns contain NULL is a valid primary key. Primary keys which contain NULL values usually indicate that a result row does not contain an entity and should be skipped.
batch - indicates that save operations of multiple entities can be batched together for efficiency. setting to False indicates that an instance will be fully saved before saving the next instance, which includes inserting/updating all table rows corresponding to the entity as well as calling all MapperExtension methods corresponding to the save operation.
column_prefix - a string which will be prepended to the "key" name of all Columns when creating column-based properties from the given Table. does not affect explicitly specified column-based properties
adds the given dictionary of properties to this mapper, using add_property.
add an indiviual MapperProperty to this mapper.
If the mapper has not been compiled yet, just adds the property to the initial properties dictionary sent to the constructor. if this Mapper has already been compiled, then the given MapperProperty is compiled immediately.
execute a callable for each element in an object graph, for all relations that meet the given cascade rule.
type - the name of the cascade rule (i.e. save-update, delete, etc.)
object - the lead object instance. child items will be processed per the relations defined for this object's mapper.
callable_ - the callable function.
recursive - used by the function for internal context during recursive calls, leave as None.
iterate each element in an object graph, for all relations taht meet the given cascade rule.
type - the name of the cascade rule (i.e. save-update, delete, etc.)
object - the lead object instance. child items will be processed per the relations defined for this object's mapper.
recursive - used by the function for internal context during recursive calls, leave as None.
return true if the given mapper shares a common inherited parent as this mapper
compile this mapper into its final internal format.
this is the 'external' version of the method which is not reentrant.
issue DELETE statements for a list of objects.
this is called within the context of a UOWTransaction during a flush operation.
return an instance attribute using a Column as the key.
return the mapper used for issuing selects.
this mapper is the same mapper as 'self' unless the select_table argument was specified for this mapper.
return the contextual session provided by the mapper extension chain, if any.
raises InvalidRequestError if a session cannot be retrieved from the extension chain
return the identity key for the given instance, based on its primary key attributes.
this value is typically also found on the instance itself under the attribute name '_instance_key'.
return an identity-map key for use in storing/retrieving an item from an identity map.
primary_key - a list of values indicating the identifier.
return an identity-map key for use in storing/retrieving an item from the identity map.
row - a sqlalchemy.dbengine.RowProxy instance or other map corresponding result-set column names to their values within a row.
return a list of mapped instances corresponding to the rows in a given ResultProxy.
return True if this mapper handles the given instance.
this is dependent not only on class assignment but the optional "entity_name" parameter as well.
iterates through the collection including this mapper and all descendant mappers.
this includes not just the immediately inheriting mappers but all their inheriting mappers as well.
To iterate through an entire hierarchy, use mapper.base_mapper().polymorphic_iterator().
populate an instance from a result row.
This method iterates through the list of MapperProperty objects attached to this Mapper and calls each properties execute() method.
return the list of primary key values for the given instance.
returns the primary mapper corresponding to this mapper's class key (class + entity_name)
compiles this mapper if needed, and returns the dictionary of MapperProperty objects associated with this mapper.
register DependencyProcessor instances with a unitofwork.UOWTransaction.
this calls register_dependencies on all attached MapperProperty instances.
issue INSERT and/or UPDATE statements for a list of objects.
this is called within the context of a UOWTransaction during a flush operation.
save_obj issues SQL statements not just for instances mapped directly by this mapper, but for instances mapped by all inheriting mappers as well. This is to maintain proper insert ordering among a polymorphic chain of instances. Therefore save_obj is typically called only on a "base mapper", or a mapper which does not inherit from any other mapper.
encapsulates the object-fetching operations provided by Mappers.
given a WHERE criterion, produce a ClauseElement-based statement suitable for usage in the execute() method.
given a WHERE criterion, create a SELECT COUNT statement, execute and return the resulting count value.
returns the count of instances based on the given clauses and key/value criterion. The criterion is constructed in the same way as the select_by() method.
execute the given ClauseElement-based statement against this Query's session/mapper, return the resulting list of instances.
After execution, closes the ResultProxy and its underlying resources. This method is one step above the instances() method, which takes the executed statement's ResultProxy directly.
return an instance of the object based on the given identifier, or None if not found.
The ident argument is a scalar or tuple of primary key column values in the order of the table def's primary key columns.
return a single object instance based on the given key/value criterion.
this is either the first value in the result list, or None if the list is empty.
the keys are mapped to property or column names mapped by this mapper's Table, and the values are coerced into a WHERE clause separated by AND operators. If the local property/column names dont contain the key, a search will be performed against this mapper's immediate list of relations as well, forming the appropriate join conditions if a matching property is located.
e.g. u = usermapper.get_by(user_name = 'fred')
return a list of mapped instances corresponding to the rows in a given "cursor" (i.e. ResultProxy).
return a ClauseElement representing the WHERE clause that would normally be sent to select_whereclause() by select_by().
given the key name of a property, will recursively descend through all child properties from this Query's mapper to locate the property, and will return a ClauseElement representing a join from this Query's mapper to the endmost mapper.
given a list of keys that represents a path from this Query's mapper to a related mapper based on names of relations from one mapper to the next, returns a ClauseElement representing a join from this Query's mapper to the endmost mapper.
return an instance of the object based on the given identifier.
If not found, raises an exception. The method will *remove all pending changes* to the object already existing in the Session. The ident argument is a scalar or tuple of primary key column values in the order of the table def's primary key columns.
return a new Query object, applying the given list of MapperOptions.
selects instances of the object from the database.
arg can be any ClauseElement, which will form the criterion with which to load the objects.
For more advanced usage, arg can also be a Select statement object, which will be executed and its resulting rowset used to build new object instances. in this case, the developer must insure that an adequate set of columns exists in the rowset with which to build new object instances.
return an array of object instances based on the given clauses and key/value criterion.
*args is a list of zero or more ClauseElements which will be connected by AND operators.
**params is a set of zero or more key/value parameters which are converted into ClauseElements. the keys are mapped to property or column names mapped by this mapper's Table, and the values are coerced into a WHERE clause separated by AND operators. If the local property/column names dont contain the key, a search will be performed against this mapper's immediate list of relations as well, forming the appropriate join conditions if a matching property is located.
e.g. result = usermapper.select_by(user_name = 'fred')
given a ClauseElement-based statement, execute and return the resulting instances.
given a literal string-based statement, execute and return the resulting instances.
given a WHERE criterion, create a SELECT statement, execute and return the resulting instances.
works like select(), but only returns the first result by itself, or None if no objects returned.
works like select_by(), but only returns the first result by itself, or None if no objects returned. Synonymous with get_by()
works like selectfirst(), but throws an error if not exactly one result was returned.
created within the Query.compile() method to store and share state among all the Mappers and MapperProperty objects used in a query construction.
created within the query.instances() method to store and share state among all the Mappers and MapperProperty objects used in a load operation.
SelectionContext contains these attributes:
mapper - the Mapper which originated the instances() call.
session - the Session that is relevant to the instances call.
identity_map - a dictionary which stores newly created instances that have not yet been added as persistent to the Session.
attributes - a dictionary to store arbitrary data; eager loaders use it to store additional result lists
populate_existing - indicates if its OK to overwrite the attributes of instances that were already in the Session
version_check - indicates if mappers that have version_id columns should verify that instances existing already within the Session should have this attribute compared to the freshly loaded value
given a ClassKey, returns the primary Mapper associated with the key.
encapsulates a set of objects being operated upon within an object-relational operation.
The Session object is **not** threadsafe. For thread-management of Sessions, see the sqlalchemy.ext.sessioncontext module.
bind the given Mapper to the given Engine or Connection.
All subsequent operations involving this Mapper will use the given bindto.
bind the given Table to the given Engine or Connection.
All subsequent operations involving this Table will use the given bindto.
removes all object instances from this Session. this is equivalent to calling expunge() for all objects in this Session.
returns a unique connection corresponding to the given mapper. this connection will not be part of any pre-existing transactional context.
returns a Connection corresponding to the given mapper. used by the execute() method which performs select operations for Mapper and Query. if this Session is transactional, the connection will be in the context of this session's transaction. otherwise, the connection is returned by the contextual_connect method, which some Engines override to return a thread-local connection, and will have close_with_result set to True.
the given **kwargs will be sent to the engine's contextual_connect() method, if no transaction is in progress.
returns a new SessionTransaction corresponding to an existing or new transaction. if the transaction is new, the returned SessionTransaction will have commit control over the underlying transaction, else will have rollback control only.
mark the given instance as deleted.
the delete operation occurs upon flush().
using the given mapper to identify the appropriate Engine or Connection to be used for statement execution, executes the given ClauseElement using the provided parameter dictionary. Returns a ResultProxy corresponding to the execution's results. If this method allocates a new Connection for the operation, then the ResultProxy's close() method will release the resources of the underlying Connection, otherwise its a no-op.
mark the given object as expired.
this will add an instrumentation to all mapped attributes on the instance such that when an attribute is next accessed, the session will reload all attributes on the instance from the database.
remove the given object from this Session.
this will free all internal references to the object. cascading will be applied according to the 'expunge' cascade rule.
flush all the object modifications present in this session to the database.
'objects' is a list or tuple of objects specifically to be flushed; if None, all new and modified objects are flushed.
return an instance of the object based on the given identifier, or None if not found.
The ident argument is a scalar or tuple of primary key column values in the order of the table def's primary key columns.
the entity_name keyword argument may also be specified which further qualifies the underlying Mapper used to perform the query.
return the Engine or Connection which is used to execute statements on behalf of the given Mapper.
Calling connect() on the return result will always result in a Connection object. This method disregards any SessionTransaction that may be in progress.
The order of searching is as follows:
if an Engine or Connection was bound to this Mapper specifically within this Session, returns that Engine or Connection.
if an Engine or Connection was bound to this Mapper's underlying Table within this Session (i.e. not to the Table directly), returns that Engine or Conneciton.
if an Engine or Connection was bound to this Session, returns that Engine or Connection.
finally, returns the Engine which was bound directly to the Table's MetaData object.
If no Engine is bound to the Table, an exception is raised.
a WeakValueDictionary consisting of all objects within this Session keyed to their _instance_key value.
return True if the given object has been marked as expired.
return an instance of the object based on the given identifier.
If not found, raises an exception. The method will *remove all pending changes* to the object already existing in the Session. The ident argument is a scalar or tuple of primary key columns in the order of the table def's primary key columns.
the entity_name keyword argument may also be specified which further qualifies the underlying Mapper used to perform the query.
given an Class, return the primary Mapper responsible for persisting it
merge the object into a newly loaded or existing instance from this Session.
note: this method is currently not completely implemented.
return a new Query object corresponding to this Session and the mapper, or the classes' primary mapper.
reload the attributes for the given object from the database, clear any changes made.
Add a transient (unsaved) instance to this Session.
This operation cascades the "save_or_update" method to associated instances if the relation is mapped with cascade="save-update".
The 'entity_name' keyword argument will further qualify the specific Mapper used to handle this instance.
save or update the given object into this Session.
The presence of an '_instance_key' attribute on the instance determines whether to save() or update() the instance.
works like execute() but returns a scalar result.
Bring the given detached (saved) instance into this Session.
If there is a persistent instance with the same identifier already associated with this Session, an exception is thrown.
This operation cascades the "save_or_update" method to associated instances if the relation is mapped with cascade="save-update".
represents a Session-level Transaction. This corresponds to one or more sqlalchemy.engine.Transaction instances behind the scenes, with one Transaction per Engine in use.
the SessionTransaction object is **not** threadsafe.
provides a connection pool implementation, which optionally manages connections on a thread local basis. Also provides a DBAPI2 transparency layer so that pools can be managed automatically, based on module type and connect arguments, simply by calling regular DBAPI connect() methods.
given a DBAPI2 module and pool management parameters, returns a proxy for the module that will automatically pool connections, creating new connection pools for each distinct set of connection arguments sent to the decorated module's connect() function.
Arguments: module : a DBAPI2 database module.
poolclass=QueuePool : the class used by the pool module to provide pooling.
Options: See Pool for options.
a Pool implementation which will raise an exception if more than one connection is checked out at a time. Useful for debugging code that is using more connections than desired.
TODO: modify this to handle an arbitrary connection count.
a Pool implementation which does not pool connections; instead it literally opens and closes the underlying DBAPI connection per each connection open/close.
Base Pool class. This is an abstract class, which is implemented by various subclasses including:
QueuePool - pools multiple connections using Queue.Queue
SingletonThreadPool - stores a single connection per execution thread
NullPool - doesnt do any pooling; opens and closes connections
AssertionPool - stores only one connection, and asserts that only one connection is checked out at a time.
the main argument, "creator", is a callable function that returns a newly connected DBAPI connection object.
Options that are understood by Pool are:
echo=False : if set to True, connections being pulled and retrieved from/to the pool will be logged to the standard output, as well as pool sizing information. Echoing can also be achieved by enabling logging for the "sqlalchemy.pool" namespace.
use_threadlocal=True : if set to True, repeated calls to connect() within the same application thread will be guaranteed to return the same connection object, if one has already been retrieved from the pool and has not been returned yet. This allows code to retrieve a connection from the pool, and then while still holding on to that connection, to call other functions which also ask the pool for a connection of the same arguments; those functions will act upon the same connection that the calling method is using.
recycle=-1 : if set to non -1, a number of seconds between connection recycling, which means upon checkout, if this timeout is surpassed the connection will be closed and replaced with a newly opened connection.
auto_close_cursors = True : cursors, returned by connection.cursor(), are tracked and are automatically closed when the connection is returned to the pool. some DBAPIs like MySQLDB become unstable if cursors remain open.
disallow_open_cursors = False : if auto_close_cursors is False, and disallow_open_cursors is True, will raise an exception if an open cursor is detected upon connection checkin.
If auto_close_cursors and disallow_open_cursors are both False, then no cursor processing occurs upon checkin.
uses Queue.Queue to maintain a fixed-size list of connections.
Arguments include all those used by the base Pool class, as well as:
pool_size=5 : the size of the pool to be maintained. This is the largest number of connections that will be kept persistently in the pool. Note that the pool begins with no connections; once this number of connections is requested, that number of connections will remain.
max_overflow=10 : the maximum overflow size of the pool. When the number of checked-out connections reaches the size set in pool_size, additional connections will be returned up to this limit. When those additional connections are returned to the pool, they are disconnected and discarded. It follows then that the total number of simultaneous connections the pool will allow is pool_size + max_overflow, and the total number of "sleeping" connections the pool will allow is pool_size. max_overflow can be set to -1 to indicate no overflow limit; no limit will be placed on the total number of concurrent connections.
timeout=30 : the number of seconds to wait before giving up on returning a connection
Maintains one connection per each thread, never moving a connection to a thread other than the one which it was created in.
this is used for SQLite, which both does not handle multithreading by default, and also requires a singleton connection if a :memory: database is being used.
options are the same as those of Pool, as well as:
pool_size=5 - the number of threads in which to maintain connections at once.
A simple wrapper for ScopedRegistry that provides a "current" property which can be used to get, set, or remove the session in the current scope.
By default this object provides thread-local scoping, which is the default scope provided by sqlalchemy.util.ScopedRegistry.
Usage: engine = create_engine(...) def session_factory(): return Session(bind_to=engine) context = SessionContext(session_factory)
s = context.current # get thread-local session context.current = Session(bind_to=other_engine) # set current session del context.current # discard the thread-local session (a new one will # be created on the next call to context.current)
this plugin installs thread-local behavior at the Engine and Session level.
The default Engine strategy will be "threadlocal", producing TLocalEngine instances for create_engine by default. With this engine, connect() method will return the same connection on the same thread, if it is already checked out from the pool. this greatly helps functions that call multiple statements to be able to easily use just one connection without explicit "close" statements on result handles.
on the Session side, module-level methods will be installed within the objectstore module, such as flush(), delete(), etc. which call this method on the thread-local session.
Note: this mod creates a global, thread-local session context named sqlalchemy.objectstore. All mappers created while this mod is installed will reference this global context when creating new mapped object instances.
Builds a query one component at a time via separate method calls, each call transforming the previous SelectResults instance into a new SelectResults instance with further limiting criterion added. When interpreted in an iterator context (such as via calling list(selectresults)), executes the query.
constructs a new SelectResults using the given Query object and optional WHERE clause. ops is an optional dictionary of bind parameter values.
join the table of this SelectResults to the table located against the given property name.
subsequent calls to join_to or outerjoin_to will join against the rightmost table located from the previous join_to or outerjoin_to call, searching for the property starting with the rightmost mapper last located.
return the results represented by this SelectResults as a list.
this results in an execution of the underlying query.
outer join the table of this SelectResults to the table located against the given property name.
subsequent calls to join_to or outerjoin_to will join against the rightmost table located from the previous join_to or outerjoin_to call, searching for the property starting with the rightmost mapper last located.
raised for all those conditions where invalid arguments are sent to constructed objects. This error generally corresponds to construction time state errors.
corresponds to internal state being detected in an invalid state
raised when a concurrent modification condition is detected
sqlalchemy was asked to do something it cant do, return nonexistent data, etc. This error generally corresponds to runtime state errors.
raised by RowProxy when a nonexistent column is requested from a row
sqlalchemy was asked to load a table's definition from the database, but the table doesn't exist.
raised when the execution of a SQL statement fails. includes accessors for the underlying exception, as well as the SQL and bind parameters
raised when a connection pool times out on getting a connection
An SQLEngine proxy that automatically connects when necessary.
Basis for all proxy engines.
this method is required to be present as it overrides the compiler method present in sql.Engine