2
# Copyright (C) 2005-2013 the SQLAlchemy authors and contributors <see AUTHORS file>
4
# This module is part of SQLAlchemy and is released under
5
# the MIT License: http://www.opensource.org/licenses/mit-license.php
7
"""Define core interfaces used by the engine system."""
9
from .. import util, event, events
12
class Dialect(object):
13
"""Define the behavior of a specific database and DB-API combination.
15
Any aspect of metadata definition, SQL query generation,
16
execution, result-set handling, or anything else which varies
17
between databases is defined under the general category of the
18
Dialect. The Dialect acts as a factory for other
19
database-specific object implementations including
20
ExecutionContext, Compiled, DefaultGenerator, and TypeEngine.
22
All Dialects implement the following attributes:
25
identifying name for the dialect from a DBAPI-neutral point of view
29
identifying name for the dialect's DBAPI
32
True if the paramstyle for this Dialect is positional.
35
the paramstyle to be used (some DB-APIs support multiple
39
True if Unicode conversion should be applied to all ``str``
43
type of encoding to use for unicode, usually defaults to
47
a :class:`.Compiled` class used to compile SQL statements
50
a :class:`.Compiled` class used to compile DDL statements
53
a tuple containing a version number for the DB backend in use.
54
This value is only available for supporting dialects, and is
55
typically populated during the initial connection to the database.
58
the name of the default schema. This value is only available for
59
supporting dialects, and is typically populated during the
60
initial connection to the database.
63
a :class:`.ExecutionContext` class used to handle statement execution
65
execute_sequence_format
66
either the 'tuple' or 'list' type, depending on what cursor.execute()
67
accepts for the second argument (they vary).
70
a :class:`~sqlalchemy.sql.compiler.IdentifierPreparer` class used to
74
``True`` if the database supports ``ALTER TABLE``.
77
The maximum length of identifier names.
79
supports_unicode_statements
80
Indicate whether the DB-API can receive SQL statements as Python
83
supports_unicode_binds
84
Indicate whether the DB-API can receive string bind parameters
85
as Python unicode strings
87
supports_sane_rowcount
88
Indicate whether the dialect properly implements rowcount for
89
``UPDATE`` and ``DELETE`` statements.
91
supports_sane_multi_rowcount
92
Indicate whether the dialect properly implements rowcount for
93
``UPDATE`` and ``DELETE`` statements when executed via
96
preexecute_autoincrement_sequences
97
True if 'implicit' primary key functions must be executed separately
98
in order to get their value. This is currently oriented towards
102
use RETURNING or equivalent during INSERT execution in order to load
103
newly generated primary keys and other column defaults in one execution,
104
which are then available via inserted_primary_key.
105
If an insert statement has returning() specified explicitly,
106
the "implicit" functionality is not used and inserted_primary_key
107
will not be available.
110
A mapping of DB-API type objects present in this Dialect's
111
DB-API implementation mapped to TypeEngine implementations used
114
This is used to apply types to result sets based on the DB-API
115
types present in cursor.description; it only takes effect for
116
result sets against textual statements where no explicit
120
A dictionary of TypeEngine classes from sqlalchemy.types mapped
121
to subclasses that are specific to the dialect class. This
122
dictionary is class-level only and is not accessed from the
123
dialect instance itself.
125
supports_default_values
126
Indicates if the construct ``INSERT INTO tablename DEFAULT
127
VALUES`` is supported
130
Indicates if the dialect supports CREATE SEQUENCE or similar.
133
If True, indicates if the "optional" flag on the Sequence() construct
134
should signal to not generate a CREATE SEQUENCE. Applies only to
135
dialects that support sequences. Currently used only to allow Postgresql
136
SERIAL to be used on a column that specifies Sequence() for usage on
140
Indicates if the dialect supports a native ENUM construct.
141
This will prevent types.Enum from generating a CHECK
142
constraint when that type is used.
144
supports_native_boolean
145
Indicates if the dialect supports a native boolean construct.
146
This will prevent types.Boolean from generating a CHECK
147
constraint when that type is used.
151
def create_connect_args(self, url):
152
"""Build DB-API compatible connection arguments.
154
Given a :class:`~sqlalchemy.engine.url.URL` object, returns a tuple
155
consisting of a `*args`/`**kwargs` suitable to send directly
156
to the dbapi's connect function.
160
raise NotImplementedError()
163
def type_descriptor(cls, typeobj):
164
"""Transform a generic type to a dialect-specific type.
166
Dialect classes will usually use the
167
:func:`.types.adapt_type` function in the types module to
170
The returned result is cached *per dialect class* so can
171
contain no dialect-instance state.
175
raise NotImplementedError()
177
def initialize(self, connection):
178
"""Called during strategized creation of the dialect with a
181
Allows dialects to configure options based on server version info or
184
The connection passed here is a SQLAlchemy Connection object,
185
with full capabilities.
187
The initalize() method of the base dialect should be called via
194
def reflecttable(self, connection, table, include_columns=None):
195
"""Load table description from the database.
197
Given a :class:`.Connection` and a
198
:class:`~sqlalchemy.schema.Table` object, reflect its columns and
199
properties from the database. If include_columns (a list or
200
set) is specified, limit the autoload to the given column
203
The default implementation uses the
204
:class:`~sqlalchemy.engine.reflection.Inspector` interface to
205
provide the output, building upon the granular table/column/
206
constraint etc. methods of :class:`.Dialect`.
210
raise NotImplementedError()
212
def get_columns(self, connection, table_name, schema=None, **kw):
213
"""Return information about columns in `table_name`.
215
Given a :class:`.Connection`, a string
216
`table_name`, and an optional string `schema`, return column
217
information as a list of dictionaries with these keys:
223
[sqlalchemy.types#TypeEngine]
229
the column's default value
235
a dictionary of the form
236
{'name' : str, 'start' :int, 'increment': int}
238
Additional column attributes may be present.
241
raise NotImplementedError()
243
def get_primary_keys(self, connection, table_name, schema=None, **kw):
244
"""Return information about primary keys in `table_name`.
247
Deprecated. This method is only called by the default
248
implementation of :meth:`.Dialect.get_pk_constraint`. Dialects should
249
instead implement this method directly.
253
raise NotImplementedError()
255
def get_pk_constraint(self, connection, table_name, schema=None, **kw):
256
"""Return information about the primary key constraint on
259
Given a :class:`.Connection`, a string
260
`table_name`, and an optional string `schema`, return primary
261
key information as a dictionary with these keys:
264
a list of column names that make up the primary key
267
optional name of the primary key constraint.
270
raise NotImplementedError()
272
def get_foreign_keys(self, connection, table_name, schema=None, **kw):
273
"""Return information about foreign_keys in `table_name`.
275
Given a :class:`.Connection`, a string
276
`table_name`, and an optional string `schema`, return foreign
277
key information as a list of dicts with these keys:
280
the constraint's name
283
a list of column names that make up the foreign key
286
the name of the referred schema
289
the name of the referred table
292
a list of column names in the referred table that correspond to
296
raise NotImplementedError()
298
def get_table_names(self, connection, schema=None, **kw):
299
"""Return a list of table names for `schema`."""
301
raise NotImplementedError
303
def get_view_names(self, connection, schema=None, **kw):
304
"""Return a list of all view names available in the database.
307
Optional, retrieve names from a non-default schema.
310
raise NotImplementedError()
312
def get_view_definition(self, connection, view_name, schema=None, **kw):
313
"""Return view definition.
315
Given a :class:`.Connection`, a string
316
`view_name`, and an optional string `schema`, return the view
320
raise NotImplementedError()
322
def get_indexes(self, connection, table_name, schema=None, **kw):
323
"""Return information about indexes in `table_name`.
325
Given a :class:`.Connection`, a string
326
`table_name` and an optional string `schema`, return index
327
information as a list of dictionaries with these keys:
333
list of column names in order
339
raise NotImplementedError()
341
def normalize_name(self, name):
342
"""convert the given name to lowercase if it is detected as
345
this method is only used if the dialect defines
346
requires_name_normalize=True.
349
raise NotImplementedError()
351
def denormalize_name(self, name):
352
"""convert the given name to a case insensitive identifier
353
for the backend if it is an all-lowercase name.
355
this method is only used if the dialect defines
356
requires_name_normalize=True.
359
raise NotImplementedError()
361
def has_table(self, connection, table_name, schema=None):
362
"""Check the existence of a particular table in the database.
364
Given a :class:`.Connection` object and a string
365
`table_name`, return True if the given table (possibly within
366
the specified `schema`) exists in the database, False
370
raise NotImplementedError()
372
def has_sequence(self, connection, sequence_name, schema=None):
373
"""Check the existence of a particular sequence in the database.
375
Given a :class:`.Connection` object and a string
376
`sequence_name`, return True if the given sequence exists in
377
the database, False otherwise.
380
raise NotImplementedError()
382
def _get_server_version_info(self, connection):
383
"""Retrieve the server version info from the given connection.
385
This is used by the default implementation to populate the
386
"server_version_info" attribute and is called exactly
387
once upon first connect.
391
raise NotImplementedError()
393
def _get_default_schema_name(self, connection):
394
"""Return the string name of the currently selected schema from
395
the given connection.
397
This is used by the default implementation to populate the
398
"default_schema_name" attribute and is called exactly
399
once upon first connect.
403
raise NotImplementedError()
405
def do_begin(self, dbapi_connection):
406
"""Provide an implementation of ``connection.begin()``, given a
409
The DBAPI has no dedicated "begin" method and it is expected
410
that transactions are implicit. This hook is provided for those
411
DBAPIs that might need additional help in this area.
413
Note that :meth:`.Dialect.do_begin` is not called unless a
414
:class:`.Transaction` object is in use. The
415
:meth:`.Dialect.do_autocommit`
416
hook is provided for DBAPIs that need some extra commands emitted
417
after a commit in order to enter the next transaction, when the
418
SQLAlchemy :class:`.Connection` is used in it's default "autocommit"
421
:param dbapi_connection: a DBAPI connection, typically
422
proxied within a :class:`.ConnectionFairy`.
426
raise NotImplementedError()
428
def do_rollback(self, dbapi_connection):
429
"""Provide an implementation of ``connection.rollback()``, given
432
:param dbapi_connection: a DBAPI connection, typically
433
proxied within a :class:`.ConnectionFairy`.
437
raise NotImplementedError()
440
def do_commit(self, dbapi_connection):
441
"""Provide an implementation of ``connection.commit()``, given a
444
:param dbapi_connection: a DBAPI connection, typically
445
proxied within a :class:`.ConnectionFairy`.
449
raise NotImplementedError()
451
def do_close(self, dbapi_connection):
452
"""Provide an implementation of ``connection.close()``, given a DBAPI
455
This hook is called by the :class:`.Pool` when a connection has been
456
detached from the pool, or is being returned beyond the normal
457
capacity of the pool.
459
.. versionadded:: 0.8
463
raise NotImplementedError()
465
def create_xid(self):
466
"""Create a two-phase transaction ID.
468
This id will be passed to do_begin_twophase(),
469
do_rollback_twophase(), do_commit_twophase(). Its format is
473
raise NotImplementedError()
475
def do_savepoint(self, connection, name):
476
"""Create a savepoint with the given name.
478
:param connection: a :class:`.Connection`.
479
:param name: savepoint name.
483
raise NotImplementedError()
485
def do_rollback_to_savepoint(self, connection, name):
486
"""Rollback a connection to the named savepoint.
488
:param connection: a :class:`.Connection`.
489
:param name: savepoint name.
493
raise NotImplementedError()
495
def do_release_savepoint(self, connection, name):
496
"""Release the named savepoint on a connection.
498
:param connection: a :class:`.Connection`.
499
:param name: savepoint name.
502
raise NotImplementedError()
504
def do_begin_twophase(self, connection, xid):
505
"""Begin a two phase transaction on the given connection.
507
:param connection: a :class:`.Connection`.
512
raise NotImplementedError()
514
def do_prepare_twophase(self, connection, xid):
515
"""Prepare a two phase transaction on the given connection.
517
:param connection: a :class:`.Connection`.
522
raise NotImplementedError()
524
def do_rollback_twophase(self, connection, xid, is_prepared=True,
526
"""Rollback a two phase transaction on the given connection.
528
:param connection: a :class:`.Connection`.
530
:param is_prepared: whether or not
531
:meth:`.TwoPhaseTransaction.prepare` was called.
532
:param recover: if the recover flag was passed.
536
raise NotImplementedError()
538
def do_commit_twophase(self, connection, xid, is_prepared=True,
540
"""Commit a two phase transaction on the given connection.
543
:param connection: a :class:`.Connection`.
545
:param is_prepared: whether or not
546
:meth:`.TwoPhaseTransaction.prepare` was called.
547
:param recover: if the recover flag was passed.
551
raise NotImplementedError()
553
def do_recover_twophase(self, connection):
554
"""Recover list of uncommited prepared two phase transaction
555
identifiers on the given connection.
557
:param connection: a :class:`.Connection`.
561
raise NotImplementedError()
563
def do_executemany(self, cursor, statement, parameters, context=None):
564
"""Provide an implementation of ``cursor.executemany(statement,
567
raise NotImplementedError()
569
def do_execute(self, cursor, statement, parameters, context=None):
570
"""Provide an implementation of ``cursor.execute(statement,
573
raise NotImplementedError()
575
def do_execute_no_params(self, cursor, statement, parameters,
577
"""Provide an implementation of ``cursor.execute(statement)``.
579
The parameter collection should not be sent.
583
raise NotImplementedError()
585
def is_disconnect(self, e, connection, cursor):
586
"""Return True if the given DB-API error indicates an invalid
589
raise NotImplementedError()
592
"""return a callable which sets up a newly created DBAPI connection.
594
The callable accepts a single argument "conn" which is the
595
DBAPI connection itself. It has no return value.
597
This is used to set dialect-wide per-connection options such as
598
isolation modes, unicode modes, etc.
600
If a callable is returned, it will be assembled into a pool listener
601
that receives the direct DBAPI connection, with all wrappers removed.
603
If None is returned, no listener will be generated.
608
def reset_isolation_level(self, dbapi_conn):
609
"""Given a DBAPI connection, revert its isolation to the default."""
611
raise NotImplementedError()
613
def set_isolation_level(self, dbapi_conn, level):
614
"""Given a DBAPI connection, set its isolation level."""
616
raise NotImplementedError()
618
def get_isolation_level(self, dbapi_conn):
619
"""Given a DBAPI connection, return its isolation level."""
621
raise NotImplementedError()
624
class ExecutionContext(object):
625
"""A messenger object for a Dialect that corresponds to a single
628
ExecutionContext should have these data members:
631
Connection object which can be freely used by default value
632
generators to execute SQL. This Connection should reference the
633
same underlying connection/transactional resources of
637
Connection object which is the source of this ExecutionContext. This
638
Connection may have close_with_result=True set, in which case it can
642
dialect which created this ExecutionContext.
645
DB-API cursor procured from the connection,
648
if passed to constructor, sqlalchemy.engine.base.Compiled object
652
string version of the statement to be executed. Is either
653
passed to the constructor, or must be created from the
654
sql.Compiled object by the time pre_exec() has completed.
657
bind parameters passed to the execute() method. For compiled
658
statements, this is a dictionary or list of dictionaries. For
659
textual statements, it should be in a format suitable for the
660
dialect's paramstyle (i.e. dict or list of dicts for non
661
positional, list or list of lists/tuples for positional).
664
True if the statement is an INSERT.
667
True if the statement is an UPDATE.
670
True if the statement is a "committable" statement.
673
a list of Column objects for which a client-side default
674
was fired off. Applies to inserts and updates.
677
a list of Column objects for which a server-side default or
678
inline SQL expression value was fired off. Applies to inserts
682
def create_cursor(self):
683
"""Return a new cursor generated from this ExecutionContext's
686
Some dialects may wish to change the behavior of
687
connection.cursor(), such as postgresql which may return a PG
688
"server side" cursor.
691
raise NotImplementedError()
694
"""Called before an execution of a compiled statement.
696
If a compiled statement was passed to this ExecutionContext,
697
the `statement` and `parameters` datamembers must be
698
initialized after this statement is complete.
701
raise NotImplementedError()
704
"""Called after the execution of a compiled statement.
706
If a compiled statement was passed to this ExecutionContext,
707
the `last_insert_ids`, `last_inserted_params`, etc.
708
datamembers should be available after this method completes.
711
raise NotImplementedError()
714
"""Return a result object corresponding to this ExecutionContext.
716
Returns a ResultProxy.
719
raise NotImplementedError()
721
def handle_dbapi_exception(self, e):
722
"""Receive a DBAPI exception which occurred upon execute, result
725
raise NotImplementedError()
727
def should_autocommit_text(self, statement):
728
"""Parse the given textual statement and return True if it refers to
729
a "committable" statement"""
731
raise NotImplementedError()
733
def lastrow_has_defaults(self):
734
"""Return True if the last INSERT or UPDATE row contained
735
inlined or database-side defaults.
738
raise NotImplementedError()
740
def get_rowcount(self):
741
"""Return the DBAPI ``cursor.rowcount`` value, or in some
742
cases an interpreted value.
744
See :attr:`.ResultProxy.rowcount` for details on this.
748
raise NotImplementedError()
751
class Compiled(object):
752
"""Represent a compiled SQL or DDL expression.
754
The ``__str__`` method of the ``Compiled`` object should produce
755
the actual text of the statement. ``Compiled`` objects are
756
specific to their underlying database dialect, and also may
757
or may not be specific to the columns referenced within a
758
particular set of bind parameters. In no case should the
759
``Compiled`` object be dependent on the actual values of those
760
bind parameters, even though it may reference those values as
764
def __init__(self, dialect, statement, bind=None,
765
compile_kwargs=util.immutabledict()):
766
"""Construct a new ``Compiled`` object.
768
:param dialect: ``Dialect`` to compile against.
770
:param statement: ``ClauseElement`` to be compiled.
772
:param bind: Optional Engine or Connection to compile this
775
:param compile_kwargs: additional kwargs that will be
776
passed to the initial call to :meth:`.Compiled.process`.
778
.. versionadded:: 0.8
782
self.dialect = dialect
784
if statement is not None:
785
self.statement = statement
786
self.can_execute = statement.supports_execution
787
self.string = self.process(self.statement, **compile_kwargs)
789
@util.deprecated("0.7", ":class:`.Compiled` objects now compile "
790
"within the constructor.")
792
"""Produce the internal string representation of this element."""
796
def sql_compiler(self):
797
"""Return a Compiled that is capable of processing SQL expressions.
799
If this compiler is one, it would likely just return 'self'.
803
raise NotImplementedError()
805
def process(self, obj, **kwargs):
806
return obj._compiler_dispatch(self, **kwargs)
809
"""Return the string text of the generated SQL or DDL."""
811
return self.string or ''
813
def construct_params(self, params=None):
814
"""Return the bind params for this compiled object.
816
:param params: a dict of string/object pairs whose values will
817
override bind values compiled in to the
821
raise NotImplementedError()
825
"""Return the bind params for this compiled object."""
826
return self.construct_params()
828
def execute(self, *multiparams, **params):
829
"""Execute this compiled object."""
833
raise exc.UnboundExecutionError(
834
"This Compiled object is not bound to any Engine "
836
return e._execute_compiled(self, multiparams, params)
838
def scalar(self, *multiparams, **params):
839
"""Execute this compiled object and return the result's
842
return self.execute(*multiparams, **params).scalar()
845
class TypeCompiler(object):
846
"""Produces DDL specification for TypeEngine objects."""
848
def __init__(self, dialect):
849
self.dialect = dialect
851
def process(self, type_):
852
return type_._compiler_dispatch(self)
855
class Connectable(object):
856
"""Interface for an object which supports execution of SQL constructs.
858
The two implementations of :class:`.Connectable` are
859
:class:`.Connection` and :class:`.Engine`.
861
Connectable must also implement the 'dialect' member which references a
862
:class:`.Dialect` instance.
866
dispatch = event.dispatcher(events.ConnectionEvents)
868
def connect(self, **kwargs):
869
"""Return a :class:`.Connection` object.
871
Depending on context, this may be ``self`` if this object
872
is already an instance of :class:`.Connection`, or a newly
873
procured :class:`.Connection` if this object is an instance
878
def contextual_connect(self):
879
"""Return a :class:`.Connection` object which may be part of an ongoing
882
Depending on context, this may be ``self`` if this object
883
is already an instance of :class:`.Connection`, or a newly
884
procured :class:`.Connection` if this object is an instance
889
raise NotImplementedError()
891
@util.deprecated("0.7",
892
"Use the create() method on the given schema "
893
"object directly, i.e. :meth:`.Table.create`, "
894
":meth:`.Index.create`, :meth:`.MetaData.create_all`")
895
def create(self, entity, **kwargs):
896
"""Emit CREATE statements for the given schema entity."""
898
raise NotImplementedError()
900
@util.deprecated("0.7",
901
"Use the drop() method on the given schema "
902
"object directly, i.e. :meth:`.Table.drop`, "
903
":meth:`.Index.drop`, :meth:`.MetaData.drop_all`")
904
def drop(self, entity, **kwargs):
905
"""Emit DROP statements for the given schema entity."""
907
raise NotImplementedError()
909
def execute(self, object, *multiparams, **params):
910
"""Executes the given construct and returns a :class:`.ResultProxy`."""
911
raise NotImplementedError()
913
def scalar(self, object, *multiparams, **params):
914
"""Executes and returns the first column of the first row.
916
The underlying cursor is closed after execution.
918
raise NotImplementedError()
920
def _run_visitor(self, visitorcallable, element,
922
raise NotImplementedError()
924
def _execute_clauseelement(self, elem, multiparams=None, params=None):
925
raise NotImplementedError()
added
removed
lib/sqlalchemy/engine/interfaces.py
