w:@
:url: http://pypi.python.org/pypi/pyodbc/
Connecting to PyODBC
--------------------
The URL here is to be translated to PyODBC connection strings, as
detailed in `ConnectionStrings `_.
DSN Connections
^^^^^^^^^^^^^^^
A DSN connection in ODBC means that a pre-existing ODBC datasource is
configured on the client machine. The application then specifies the name
of this datasource, which encompasses details such as the specific ODBC driver
in use as well as the network address of the database. Assuming a datasource
is configured on the client, a basic DSN-based connection looks like::
engine = create_engine("mssql+pyodbc://scott:tiger@some_dsn")
Which above, will pass the following connection string to PyODBC::
dsn=mydsn;UID=user;PWD=pass
If the username and password are omitted, the DSN form will also add
the ``Trusted_Connection=yes`` directive to the ODBC string.
Hostname Connections
^^^^^^^^^^^^^^^^^^^^
Hostname-based connections are also supported by pyodbc. These are often
easier to use than a DSN and have the additional advantage that the specific
database name to connect towards may be specified locally in the URL, rather
than it being fixed as part of a datasource configuration.
When using a hostname connection, the driver name must also be specified in the
query parameters of the URL. As these names usually have spaces in them, the
name must be URL encoded which means using plus signs for spaces::
engine = create_engine("mssql+pyodbc://scott:tiger@myhost:port/databasename?driver=SQL+Server+Native+Client+10.0")
Other keywords interpreted by the Pyodbc dialect to be passed to
``pyodbc.connect()`` in both the DSN and hostname cases include:
``odbc_autotranslate``, ``ansi``, ``unicode_results``, ``autocommit``,
``authentication`` (e.g., ``authentication=ActiveDirectoryIntegrated``).
Note that in order for the dialect to recognize these keywords
(including the ``driver`` keyword above) they must be all lowercase.
Pass through exact Pyodbc string
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A PyODBC connection string can also be sent in pyodbc's format directly, as
specified in `ConnectionStrings
`_ into the driver
using the parameter ``odbc_connect``. The delimeters must be URL encoded, as
illustrated below using ``urllib.parse.quote_plus``::
import urllib
params = urllib.parse.quote_plus("DRIVER={SQL Server Native Client 10.0};SERVER=dagger;DATABASE=test;UID=user;PWD=password")
engine = create_engine("mssql+pyodbc:///?odbc_connect=%s" % params)
Pyodbc Pooling / connection close behavior
------------------------------------------
PyODBC uses internal `pooling
`_ by
default, which means connections will be longer lived than they are within
SQLAlchemy itself. As SQLAlchemy has its own pooling behavior, it is often
preferable to disable this behavior. This behavior can only be disabled
globally at the PyODBC module level, **before** any connections are made::
import pyodbc
pyodbc.pooling = False
# don't use the engine before pooling is set to False
engine = create_engine("mssql+pyodbc://user:pass@dsn")
If this variable is left at its default value of ``True``, **the application
will continue to maintain active database connections**, even when the
SQLAlchemy engine itself fully discards a connection or if the engine is
disposed.
.. seealso::
`pooling `_ -
in the PyODBC documentation.
Driver / Unicode Support
-------------------------
PyODBC works best with Microsoft ODBC drivers, particularly in the area
of Unicode support on both Python 2 and Python 3.
Using the FreeTDS ODBC drivers on Linux or OSX with PyODBC is **not**
recommended; there have been historically many Unicode-related issues
in this area, including before Microsoft offered ODBC drivers for Linux
and OSX. Now that Microsoft offers drivers for all platforms, for
PyODBC support these are recommended. FreeTDS remains relevant for
non-ODBC drivers such as pymssql where it works very well.
Rowcount Support
----------------
Pyodbc only has partial support for rowcount. See the notes at
:ref:`mssql_rowcount_versioning` for important notes when using ORM
versioning.
.. _mssql_pyodbc_fastexecutemany:
Fast Executemany Mode
---------------------
The Pyodbc driver has added support for a "fast executemany" mode of execution
which greatly reduces round trips for a DBAPI ``executemany()`` call when using
Microsoft ODBC drivers, for **limited size batches that fit in memory**. The
feature is enabled by setting the flag ``.fast_executemany`` on the DBAPI
cursor when an executemany call is to be used. The SQLAlchemy pyodbc SQL
Server dialect supports setting this flag automatically when the
``.fast_executemany`` flag is passed to
:func:`_sa.create_engine` ; note that the ODBC driver must be the Microsoft
driver in order to use this flag::
engine = create_engine(
"mssql+pyodbc://scott:tiger@mssql2017:1433/test?driver=ODBC+Driver+13+for+SQL+Server",
fast_executemany=True)
.. warning:: The pyodbc fast_executemany mode **buffers all rows in memory** and is
not compatible with very large batches of data. A future version of SQLAlchemy
may support this flag as a per-execution option instead.
.. versionadded:: 1.3
.. seealso::
`fast executemany `_
- on github
N )BINARY)DATETIMEOFFSET) MSDialect)MSExecutionContext) VARBINARY )exc)types)util)PyODBCConnectorc . e Zd ZdZ fdZd Zd Z xZS )_ms_numeric_pyodbczTurns Decimals with adjusted() < 0 or > 7 into strings.
The routines here are needed for older pyodbc versions
as well as current mxODBC versions.
c z t t | |j sS fd}|S )Nc j rdt | t j rJ| }|dk r | S |dk r | S r | S | S )Nr ) asdecimal
isinstancedecimalDecimaladjusted_small_dec_to_string_large_dec_to_string)valuer self
super_processs t/builddir/build/BUILD/cloudlinux-venv-1.0.12/venv/lib64/python3.11/site-packages/sqlalchemy/dialects/mssql/pyodbc.pyprocessz2_ms_numeric_pyodbc.bind_processor..process s ~
<*UGO"D"D
< >>++a<< 44U;;; \\ 44U;;;
$}U+++ )superr bind_processor_need_decimal_fix)r dialectr r __class__s ` @r r! z!_ms_numeric_pyodbc.bind_processor sY 0$77FFwOO
( ! r c |dk rdpdddt | dz
z d d | d D S )Nr - z0.0r c , g | ]}t | S str).0nints r
z;_ms_numeric_pyodbc._small_dec_to_string.. s ???4SYY???r )absr joinas_tuple)r r s r r z'_ms_numeric_pyodbc._small_dec_to_string su
QY
3
$"
$
$ 3u~~''((1, - - GG??5>>+;+;A+>??? @ @ @
r c | d }dt | v rV|dk rdpdd d |D d| t | dz
z
z }nt | dz
| k r|dk rdpdd d |D d| dz d d d
|D | dz d }nH|dk rdpdd d |D d| dz }|S ) Nr Er r& r' c , g | ]}t | S r* r+ r- ss r r/ z;_ms_numeric_pyodbc._large_dec_to_string.. s ...AQ...r r( c , g | ]}t | S r* r+ r6 s r r/ z;_ms_numeric_pyodbc._large_dec_to_string.. 2 2 2SVV 2 2 2r .c , g | ]}t | S r* r+ r6 s r r/ z;_ms_numeric_pyodbc._large_dec_to_string.. r9 r c , g | ]}t | S r* r+ r6 s r r/ z;_ms_numeric_pyodbc._large_dec_to_string.. r9 r )r2 r, r1 r len)r r _intresults r r z'_ms_numeric_pyodbc._large_dec_to_string s ~~ " #e** "s(b(.....///u~~''3t99q=9::FF D A
!1!111QY&3,",GG 2 2T 2 2 21u~~7G7G!7K3K LMMMMGG 2 2T 2 2 25>>3C3Ca3G3I3I JKKK QY&3,",GG 2 2T 2 2 21u~~7G7G!7K3K LMMM
r )__name__
__module__ __qualname____doc__r! r r
__classcell__r$ s @r r r s` 2
r r c e Zd ZdS )_MSNumeric_pyodbcNr@ rA rB r* r r rG rG Dr rG c e Zd ZdS )_MSFloat_pyodbcNrH r* r r rK rK rI r rK c e Zd ZdZd ZdS )_ms_binary_pyodbczWraps binary values in dialect-specific Binary wrapper.
If the value is null, return a pyodbc-specific BinaryNull
object to prevent pyODBC [and FreeTDS] from defaulting binary
NULL types to SQLWCHAR and causing implicit conversion errors.
c @ j d S j j fd}|S )Nc 6 | | S j j S N)dbapi
BinaryNull)r DBAPIBinaryr# s r r z1_ms_binary_pyodbc.bind_processor..process s& "{5))) }//r )rQ Binary)r r# r rS s ` @r r! z _ms_binary_pyodbc.bind_processor s@ = 4 m* 0 0 0 0 0 0 r N)r@ rA rB rC r! r* r r rM rM s-
r rM c e Zd Zd ZdS )_ODBCDateTimeOffsetc d }|S )Nc | d S t | t j r| S | d }t j dd| }|S )Nz%Y-%m-%d %H:%M:%S.%f %zz([\+\-]\d{2})([\d\.]+)$z\1:\2)r r string_typesstrftimeresub)r
dto_strings r r z3_ODBCDateTimeOffset.bind_processor..process s\ }tE4#455
" #^^,E F F
V.*
"!r r* )r r# r s r r! z"_ODBCDateTimeOffset.bind_processor s " " "" r N)r@ rA rB r! r* r r rV rV
s# r rV c e Zd ZdS )_VARBINARY_pyodbcNrH r* r r r_ r_ rI r r_ c e Zd ZdS )_BINARY_pyodbcNrH r* r r ra ra $ rI r ra c , e Zd ZdZ fdZ fdZ xZS )MSExecutionContext_pyodbcFc t t | | j r?| j j r5t
| j d r d| _ | xj dz
c_ dS dS dS dS )a where appropriate, issue "select scope_identity()" in the same
statement.
Background on why "scope_identity()" is preferable to "@@identity":
http://msdn.microsoft.com/en-us/library/ms190315.aspx
Background on why we attempt to embed "scope_identity()" into the same
statement as the INSERT:
http://code.google.com/p/pyodbc/wiki/FAQs#How_do_I_retrieve_autogenerated/identity_values?
r Tz; select scope_identity()N)
r rc pre_exec_select_lastrowidr# use_scope_identityr=
parameters_embedded_scope_identity statement)r r$ s r re z"MSExecutionContext_pyodbc.pre_exec+ s '..77999
" : / : DOA&'' :
-1D ) NN 9 9NNNN : : : : : :r c H | j rr | j d }n4# | j j j $ r | j Y nw xY wUt |d | _ d S t t | d S )NTr ) ri cursorfetchallr# rQ Errornextsetint
_lastrowidr rc post_exec)r rowr$ s r rr z#MSExecutionContext_pyodbc.post_execE s ( ?
** +..003C|)/ * * * K'')))))*
* "#a&kkDOOO +T 2 2 < < > > > > >s + -AA)r@ rA rB ri re rr rD rE s @r rc rc ( sW $ : : : : :4? ? ? ? ? ? ? ? ?r rc c e Zd ZdZeZ ej ej e
j e e
j
eeeeeeee
j ee
j ei Z d fd Z fdZ fdZd Zd
fd Z fdZ xZ S ) MSDialect_pyodbcFNc 4 d|v r| d | _ t t | j di | | j o | j ot | j j d | _ | j o| dk | _
|| _ d S )Ndescription_encodingro ) r r* ) poprw r ru __init__rg rQ hasattrCursor_dbapi_versionr" fast_executemany)r rw r paramsr$ s r r{ zMSDialect_pyodbc.__init__q s "V + +(.
3I(J(JD %. %%.88888 #
6
6
)955
"& "
0C0C0E0E I
1
!1 r c | d }g }t j d }| | D ]5} | t | &# t $ r Y 2w xY wt | S # t j $ r- t t | |d cY S w xY w)Nz8SELECT CAST(SERVERPROPERTY('ProductVersion') AS VARCHAR)z[.\-]F) allow_chars)
scalarr[ compilesplitappendrp
ValueErrortupler
DBAPIErrorr ru _get_server_version_info)r
connectionrawversionrnr$ s r r z)MSDialect_pyodbc._get_server_version_info s " ##J C G
8$$AWWS\\
NN3q66****! D>> ! ~ )400II J
s# B "A))
A65A69CCc f t t fd}|S )Nc L | | d S rP )_setup_timestampoffset_type)connr super_s r
on_connectz/MSDialect_pyodbc.on_connect..on_connect s0 !t , ,T 2 2 2 2 2r )r ru r )r r r r$ s ` @r r zMSDialect_pyodbc.on_connect sG '..99;; 3 3 3 3 3 3 r c < d }d}| || d S )Nc t j d| }t j |d |d |d |d |d |d |d d z t j t j |d
|d S )
Nz<6hI2hr r rx r i r ry )hoursminutes)structunpackdatetimer timezone timedelta) dto_valuetups r _handle_datetimeoffsetzLMSDialect_pyodbc._setup_timestampoffset_type.._handle_datetimeoffset s -)44C$AAAAAAA$
&SVSVDDD
r ie)add_output_converter)r r r odbc_SQL_SS_TIMESTAMPOFFSETs r r z,MSDialect_pyodbc._setup_timestampoffset_type sA
'+#'' ')?
r c | | j rd|_ t t | |||| d S )NT)context)r r ru do_executemany)r rl rj rh r r$ s r r z MSDialect_pyodbc.do_executemany sQ +&*F #
%%44 Iz7 5
r c t || j j r|j d }|dv rdS t t
| ||| S )Nr >
010000100208001080030800708S0108S0210054HY010HYT00T)r rQ rn argsr ru
is_disconnect)r er rl coder$ s r r z MSDialect_pyodbc.is_disconnect sh a) * * 6!9D t%t,,::
z6
r )NFrP ) r@ rA rB supports_sane_rowcount_returningrc execution_ctx_clsr update_copyr colspecssqltypesNumericrG FloatrK r ra r rV r r_ LargeBinaryr{ r r r r r rD rE s @r ru ru Z s (-$1 t / NO N /
( 1 "3
H" ;@1 1 1 1 1 1$" " " " "0
,
r ru ) rC r r r[ r baser r r r r r' r
r r r connectors.pyodbcr
objectr r rG r rK rM rV r_ ra rc ru r# r* r r r s~ Q Qf
$ $ $ $ $ $ ! ! ! ! ! ! 0 0 0 0 0 0= = = = = = = =@ *H,< ((. . . , )9 & /? /? /? /? /? 2 /? /? /?d{
{
{
{
{
{
{
{
| r