Metadata-Version: 2.1
Name: sqlalchemy_pyodbc_mssql
Version: 0.1.1
Summary: SA dialect for MSSQL using PyODBC which handles MSSQL-specific limitations
Home-page: https://github.com/level12/sqlalchemy_pyodbc_mssql
Author: Matt Lewellyn
Author-email: matt.lewellyn@level12.io
License: UNKNOWN
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Provides-Extra: test

sqlalchemy_pyodbc_mssql Readme
==========================================

.. image:: https://circleci.com/gh/level12/sqlalchemy_pyodbc_mssql.svg?&style=shield
    :target: https://circleci.com/gh/level12/sqlalchemy_pyodbc_mssql

.. image:: https://codecov.io/gh/level12/sqlalchemy_pyodbc_mssql/branch/master/graph/badge.svg
    :target: https://codecov.io/github/level12/sqlalchemy_pyodbc_mssql?branch=master

Overview
--------

PyODBC is Microsoft's recommended DBAPI layer for connecting a python application to MSSQL. However,
the layer is not MSSQL-specific, and so it has some limitations:

- parameterized queries with GROUP BY will not always work ([source](https://github.com/mkleehammer/pyodbc/issues/479))
- stored procedures (such as those called by the prepared statements in pyodbc) are limited to
  2100 parameters ([source](https://docs.microsoft.com/en-us/sql/sql-server/maximum-capacity-specifications-for-sql-server?view=sql-server-2017))

SQLAlchemy has a PyODBC dialect for MSSQL usage, but it also shares these limitations.

- for GROUP BY details, see https://github.com/sqlalchemy/sqlalchemy/issues/4540

[PyMSSQL](http://www.pymssql.org) exists as an alternative DBAPI layer and dialect for SQLAlchemy. Since it prepares queries
by rolling parameters into the query string itself (properly quoted, of course) rather than issuing
ODBC prepared statements, it does not share the above problems.

sqlalchemy_pyodbc_mssql extends the built-in SQLAlchemy PyODBC dialect in order to work around
these limits in a manner consistent with PyMSSQL's implementation. Most queries are passed as-is to
PyODBC to be prepared and executed normally. Those that would not work, due to the above issues,
are given special treatment to avoid the limitations and keep the app developer from needing to
keep track of when to apply workarounds.

Usage
-----

-  Installation
    - for usage in app: `pip install sqlalchemy_pyodbc_mssql`
    - to run tests: `pip install sqlalchemy_pyodbc_mssql[tests]`
-  Usage
    - see [SQLAlchemy instructions for PyODBC usage](https://docs.sqlalchemy.org/en/13/dialects/mssql.html#module-sqlalchemy.dialects.mssql.pyodbc)
    - dialect name to use is `mssql+pyodbc_mssql`
        - examples:
            - `mssql+pyodbc_mssql://<username>:<password>@<dsnname>`
            - `mssql+pyodbc_mssql://<username>:<password>@<dbname>?driver=SQL+Server+Native+Client+11.0`


Changelog
=========

0.1.1 released 2022-10-24
-------------------------

- resolve cache warning from SQLAlchemy 1.4 (480007f_)

.. _480007f: https://github.com/level12/sqlalchemy_pyodbc_mssql/commit/480007f


0.1.0 released 2019-06-17
-------------------------

- initial release



