https://github.com/zillow/ctds

Python DB-API 2.0 library for MS SQL Server
https://github.com/zillow/ctds

Last synced: about 1 year ago
JSON representation

Python DB-API 2.0 library for MS SQL Server

• Host: GitHub
• URL: https://github.com/zillow/ctds
• Owner: zillow
• License: mit
• Created: 2016-03-09T21:24:04.000Z (over 10 years ago)
• Default Branch: master
• Last Pushed: 2023-06-30T17:17:19.000Z (about 3 years ago)
• Last Synced: 2025-04-13T19:27:52.969Z (about 1 year ago)
• Language: Python
• Size: 9.05 MB
• Stars: 84
• Watchers: 10
• Forks: 12
• Open Issues: 22
• Metadata Files:
  • Readme: README.rst
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

README

          
cTDS

====

.. include-documentation-begin-marker

.. image:: https://github.com/zillow/ctds/workflows/CI/CD/badge.svg?branch=master

        :target: https://github.com/zillow/ctds/actions

.. image:: https://ci.appveyor.com/api/projects/status/voa33r7qdnxh6wwp/branch/master?svg=true

        :target: https://ci.appveyor.com/project/joshuahlang/ctds/branch/master

.. image:: http://img.shields.io/pypi/v/ctds.svg

        :target: https://pypi.python.org/pypi/ctds/

.. image:: https://codecov.io/gh/zillow/ctds/branch/master/graph/badge.svg

        :target: https://codecov.io/gh/zillow/ctds

`cTDS` is a full Python `DB API-2.0`_-compliant

SQL Server database library for `Linux`, `Windows`, and `Mac OS X` supporting

both Python 2 and Python 3.

The full documentation for `cTDS` can be found

`here `_.

Features

--------

* Supports `Microsoft SQL Server `_ 2008 and up.

* Complete `DB API-2.0`_ support.

* Python 2.6, Python 2.7, Python 3.3, Python 3.4, Python 3.5, Python 3.6, Python 3.7, Python 3.8, and Python 3.9 support.

* Bulk insert (bcp) support.

* Written entirely in C.

Dependencies

------------

* `FreeTDS`_

* `Python`_

.. _`FreeTDS`: https://www.freetds.org/

.. _`Python`: https://www.python.org/

.. _`DB API-2.0`: https://www.python.org/dev/peps/pep-0249

.. include-documentation-end-marker

See `installation instructions `_

for more information on installing `FreeTDS`_.

Releasing

---------

Publishing new versions of the egg and documentation is automated using a

`Github Actions `_ workflow.

Official releases are marked using git

`tags `_. Pushing the

tag to the git remote will trigger the automated deployment. E.g.

.. code-block:: console

    git tag -a v1.2.3 -m 'v1.2.3'

    git push --tags

Documentation

-------------

Generate documentation using the following:

.. code-block:: console

    tox -e docs

    # Generated to build/docs/

Documentation is hosted on `GitHub Pages `_.

As such, the source code for the documentation pages must be committed

to the `gh-pages `_ branch in

order to update the live documentation.

Development

-----------

Local development and testing is supported on Linux-based systems running

`tox`_ and `Docker`_. Docker containers are used for running a local instance

of `SQL Server on Linux`_. Only `Docker`_ and `tox`_ are required for running

tests locally on Linux or OS X systems. `pyenv`_ is recommended for managing

multiple local versions of Python. By default all tests are run against

the system version of `FreeTDS`_. `GNU Make`_ targets are provided to make

compiling specific `FreeTDS`_ versions locally for testing purposes. For

example:

.. code-block:: console

    # Run tests against FreeTDS version 1.1.24

    make test-1.1.24

Development and testing will require an instance of `SQL Server on Linux`_

running for validation. A script, **./scripts/ensure-sqlserver.sh**, is provided

to start a `Docker`_ container running the database and create the login used

by the tests.

.. code-block:: console

    # Start a docker-based SQL Server instance.

    # The default tox targets will do this automatically for you.

    make start-sqlserver

    # Run tests as needed ...

    # Stop the docker-base SQL Server instance.

    make stop-sqlserver

Testing

-------

Testing is designed to be relatively seamless using `Docker`_ containers

and `SQL Server on Linux`_. The `pytest`_ framework is used for running

the automated tests.

To run the tests against the system version of `FreeTDS`_ and `Python`_,

use:

.. code-block:: console

    tox

`GNU make`_ targets are provided for convenience and to provide a standard

method for building and installing the various versions of `FreeTDS`_ used

in testing. Most targets are wrappers around `tox`_ or replicate some

behavior in the CI/CD automation.

To run the tests against an arbitrary version of `FreeTDS`_:

.. code-block:: console

    # Python X.Y & FreeTDS Z.ZZ.ZZ

    make test_X.Y_Z.ZZ.ZZ

To run tests against all supported versions of `FreeTDS`_ and `Python`_

and additional linting and metadata checks:

.. code-block:: console

    make check

Valgrind

--------

`valgrind`_ is utilized to ensure memory is managed properly and to detect

defects such as memory leaks, buffer overruns, etc. Because `valgrind`_

requires Python is compiled with specific flags, a `Docker`_ file is provided

to `compile Python`_ as necessary to run the test suite under `valgrind`_.

To run test test suite under `valgrind`_:

.. code-block:: console

    make valgrind

.. _`Docker`: https://www.docker.com/

.. _`compile Python`: https://pythonextensionpatterns.readthedocs.io/en/latest/debugging/valgrind.html

.. _`SQL Server on Linux`: https://hub.docker.com/r/microsoft/mssql-server-linux/

.. _`GNU make`: https://www.gnu.org/software/make/

.. _`pyenv`: https://github.com/pyenv/pyenv

.. _`pytest`: https://docs.pytest.org/en/stable/

.. _`tox`: https://tox.readthedocs.io/en/latest/

.. _`valgrind`: https://valgrind.org/