1===============================
2Building and developing pymssql
3===============================
4
5Building
6========
7
8To build pymssql you should have:
9
10* Python >= 2.7 including development files. Please research your OS usual
11  software distribution channels, e.g, ``python-dev`` or ``python-devel``
12  packages.
13* Cython >= 0.19.1
14* FreeTDS >= 0.91 including development files. Please research your OS usual
15  software distribution channels, e.g, ``freetds-dev`` or ``freetds-devel``
16  packages.
17* Microsoft SQL Server
18
19.. note::
20    If developing on Windows you will want to make sure you install debug symbols.
21    For more information see https://docs.python.org/3/using/windows.html#installation-steps
22.. note::
23    If you need to connect to Azure make sure FreeTDS is built with SSL support.
24    Instructions on how to do this are out of the scope of this document.
25
26Windows
27-------
28
29
30Required Tools
31______________
32In addition to the requirements above when developing ``pymssql`` on the Windows
33platform you will need these additional tools installed:
34
35* Visual Studio C++ Compiler Tools
36* Developer Command Prompt for Visual Studio
37* `Cmake <https://cmake.org/download/>`_
38* `7Zip <https://www.7-zip.org/download.html>`_
39
40For C++ and the Developer Command Prompt the easiest path is installing Visual Studio.
41When installing make sure you select the C++ libraries and components. Also make sure that
42Visual Studio installs nmake with the C++ library installs.
43
44* https://visualstudio.microsoft.com/vs/community/
45
46.. note::
47    One thing to be aware of is which version of Python you are using relative to which
48    C++ compilers you have installed. When building on Windows you should make sure you
49    have the required compiler, pip and setuptools versions installed. For more
50    information see https://wiki.python.org/moin/WindowsCompilers
51
52
53Required Libraries
54__________________
55
56Developing ``pymssql`` on Windows also requires the following libraries:
57
58* `FreeTDS <http://www.freetds.org/>`_
59* `iconv <https://www.gnu.org/software/libiconv/>`_
60
61For development you will want ``freetds`` to be available in your project path.
62You can find prebuilt artifacts at the `FreeTDS Appveyor project <https://ci.appveyor.com/project/FreeTDS/freetds?branch=master>`_
63
64To download select the job name that matches your environment (platform, version and tds
65version) and then click the artifacts tag. You can download the zip file with or without
66ssl depending on your needs.
67
68
69.. note::
70    Remove the existing ``freetds0.95`` directory in the ``pymssql`` project directory
71
72Extract the .zip artifact into your project path into a directory named ``freetds``
73
74    ``C:\\%USERPATH%\\pymssql\\freetds``
75
76You will also need to remove the branch tag from the artifact directory (for instance
77``master`` from ``vs2015_64-master``) or update the ``INCLUDE`` and ``LIB`` environment
78variables so that the compiler and linker are able to find the path to
79``%PROJECTROOT%\\freetds\\<artifact folder>\\include`` and
80``%PROJECTROOT%\\freetds\\<artifact folder>\\lib``
81in the build step.
82
83
84.. note::
85    If you decide to add the directories to ``INCLUDE`` and ``LIB`` the below provide example
86    commands
87
88    .. code-block::
89
90        set INCLUDE=%INCLUDE%;%USERPROJECTS%\\pymssql\\freetds\\vs2015_64-master\\include
91
92        set LIB=%LIB%;%USERPROJECTS%\\pymssql\\freetds\\vs2015_64-master\\lib
93
94In addition to ``freetds`` you will want ``iconv`` available on your project path. For iconv
95on Windows we recommend https://github.com/win-iconv/win-iconv.git. We will retrieve this in
96an upcoming build step.
97
98If you prefer to build FreeTDS on your own please refer to the FreeTDS `config <http://www.freetds.org/>`_ and
99`os issues <http://www.freetds.org/userguide/osissues.htm>`_ build pages.
100
101
102Required Environment Variables
103______________________________
104
105You will need to set the following environment variables in
106Visual Studio Developer Command Prompt before installing iconv.
107
108* set PYTHON_VERSION=<Python Version>
109* set PYTHON_ARCH=<Python Architecture>
110* set VS_VER=<MSVC Compiler Version>
111
112Example:
113
114    .. code-block::
115
116        set PYTHON_VERSION=3.6.6
117        set PYTHON_ARCH=64
118        set VS_VER=2015
119
120
121Installing iconv
122________________
123
124``pymssql`` expects ``iconv`` header and lib objects and to be available in the ``build\\include``
125and ``build\\bin`` directories
126
127From the root of your project (pymssql directory) run:
128
129.. code-block::
130
131    powershell dev\appveyor\install-win-iconv.ps1
132
133This is a powershell script that will download `win-iconv <https://github.com/win-iconv/win-iconv/>`_
134from the previously mentioned GitHub repository, build and move the artifacts to the
135directory that ``pymssql`` will use with ``Cython``.
136
137.. note::
138
139    If you receive the following TLS error that is probably due to a mismatch between powershells
140    TLS version and GitHub.
141
142    .. code-block::
143
144        Exception calling "DownloadFile" with "2" argument(s): "The request was aborted: Could not create SSL/TLS secure channel."
145
146    You can add this line to ``%PROJECTROOT%\\dev\\appveyor\\install-win-iconv.ps1``
147
148    .. code-block:: PowerShell
149
150        [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
151
152    On line 3 and the powershell script should run with TLS1.2. See issue `547 <https://github.com/pymssql/pymssql/issues/547>`_
153    for more information
154
155
156Required Python Packages
157________________________
158For Python you will need the following packages installed into your virtual environment:
159
160* Cython
161* pytest == 3.2.5
162* SQLAlchemy
163* wheel
164
165
166Running the build
167_________________
168
169With the above libraries, pacakges and potential environment variables in place we are ready to
170build.
171
172At the root of the project with your virtual environment activated run
173
174.. code-block::
175
176    python setup.py build
177
178If there are no errors you are then ready to run
179
180.. code-block::
181
182    python setup.py install
183
184or continue on to the `Testing`_ documentation which advises using
185
186.. code-block::
187
188    python setup.py develop.
189
190To report any issues with building on Windows please use the `mailing list <https://groups.google.com/forum/#!forum/pymssql>`_
191
192
193Unix
194----
195
196To build on Unix you must also have:
197
198* gcc
199
200Then you can simply run::
201
202  python setup.py build
203
204or other ``setup.py`` commands as needed.
205
206Testing
207=======
208
209.. danger::
210
211  ALL DATA IN TESTING DBS WILL BE DELETED !!!!
212
213You will need to install two additional packages for testing::
214
215  easy_install pytest SQLAlchemy
216
217You should build the package with::
218
219  python setup.py develop
220
221You need to setup a ``tests.cfg`` file in ``tests/`` with the correct DB
222connection information for your environment::
223
224  cp tests/tests.cfg.tpl tests/tests.cfg
225  vim|emacs|notepad tests/tests.cfg
226
227To run the tests::
228
229  cd tests # optional
230  py.test
231
232Which will go through and run all the tests with the settings from the ``DEFAULT``
233section of ``tests.cfg``.
234
235To run with a different ``tests.cfg`` section::
236
237  py.test --pymssql-section=<secname>
238
239example::
240
241  py.test --pymssql-section=AllTestsWillRun
242
243to avoid slow tests::
244
245  py.test -m "not slow"
246
247to select specific tests to run::
248
249  py.test tests/test_types.py
250  py.test tests/test_types.py tests/test_sprocs.py
251  py.test tests/test_types.py::TestTypes
252  py.test tests/test_types.py::TestTypes::test_image
253