development_guide.md

Development Guide

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

Table of Contents

1. Environment Setup
   1. Install Python / Clone Source Code
   2. Create Virtual Environment
   3. Build mssql-cli
   4. Run mssql-cli From Source Code
   5. Run Unit Tests / Integration Tests
2. IDE Setup
   1. Install Visual Studio Code
   2. Configure Python Settings in Visual Studio Code
   3. How To Run mssql-cli With Debugger
   4. How To Run Unit Tests With / Without Debugger

Environment Setup

mssql-cli sources are located on GitHub (https://github.com/dbcli/mssql-cli). In order to contribute to the project, you are expected to:

• Have a GitHub account. For Microsoft contributors, follow the guidelines on https://opensourcehub.microsoft.com/ to create, configure and link your account
• Clone or fork the https://github.com/dbcli/mssql-cli repository into your private GitHub account
• Create pull requests against the https://github.com/dbcli/mssql-cli repository to get your code changes merged into the project repository.

1. Install Python / Clone Source Code

1. Install latest Python from http://python.org. Please note that the version of Python that comes preinstalled on macOS is 2.7. It is recommended to install both Python 2.7 and supported versions of Python 3 (3.8 at the time of this writing) to ensure backwards compatibility for testing.

   Windows

   • The latest Python installation package can be downloaded from here.
   • During installation, select the 'Add Python to PATH' option. Python must be in the PATH environment variable.

2. Clone the repo from https://github.com/dbcli/mssql-cli

2. Create Virtual Environment

When developing on a Python project, it is recommended to do so in a virtual environment. A virtual environment is a sandbox that maintains a copy of all libraries necessary to run python in a isolated environment without interfering with the system or global python. For more information on virtual environments, go to Virtual Environment Info.

If not developing in a virtual environment, please proceed to Install All Dependencies

1. Create Virtual Environment

Create a virtual environment in a subdirectory of your <workspaceRoot> (<workspaceRoot>/env, for example). Open command prompt or bash.

Windows (Python3.x)

set PYLOC=<python3_location>
set PATH=%PYLOC%\Scripts;%PYLOC%;%PATH%
set PYTHONPATH=<workspaceRoot>
python -m venv <workspaceRoot>\env

Windows (Python2.x)

set PYLOC=<python2_location>
set PATH=%PYLOC%\Scripts;%PYLOC%;%PATH%
set PYTHONPATH=<workspaceRoot>
python -m pip install --upgrade pip
python -m pip install --upgrade virtualenv
python -m virtualenv <workspaceRoot>\env

MacOS (Python3.x)

export PYTHONPATH=<workspaceRoot>
python3 -m venv <workspaceRoot>/env

MacOS (Python2.x)

export PYTHONPATH=<workspaceRoot>
python -m venv <workspaceRoot>/env

Linux (Python3.x) -- Ubuntu for example

export PYTHONPATH=<workspaceRoot>
sudo apt-get update
sudo apt-get install python3-pip
sudo apt-get install python3-venv
python3 -m venv <workspaceRoot>/env

Linux (Python2.x) -- Ubuntu for example

export PYTHONPATH=<workspaceRoot>
sudo apt-get update
sudo apt-get install python-pip
python -m pip install --upgrade pip
python -m pip install virtualenv
python -m virtualenv <workspaceRoot>/env

2. Activate Virtual Environment

Windows

<workspaceRoot>\env\scripts\activate.bat

MacOS/Linux

source <workspaceRoot>/env/bin/activate

(To deactivate the Virtual Environment)

Windows/MacOS/Linux

deactivate

3. Build mssql-cli

General development steps that apply to both a virtual environment or a global environment. If working in a virtual environment, do ensure the virtual environment is activated as the first command line of each following script.

Windows

<workspaceRoot>\env\scripts\activate.bat

set PYTHONPATH=<workspaceRoot>

cd <workspaceRoot>
python -m pip install --upgrade pip
python dev_setup.py
python build.py build

MacOS/Linux (Python3.x)

. <workspaceRoot>/env/bin/activate

export PYTHONPATH=<workspaceRoot>

cd <workspaceRoot>
python3 -m pip install --upgrade pip
python3 dev_setup.py
python3 build.py build

MacOS/Linux (Python2.x)

. <workspaceRoot>/env/bin/activate

export PYTHONPATH=<workspaceRoot>

cd <workspaceRoot>
python -m pip install --upgrade pip
python dev_setup.py
python build.py build

4. Run mssql-cli From Source Code

Windows

<workspaceRoot>\env\scripts\activate.bat

set PYTHONPATH=<workspaceRoot>

cd <workspaceRoot>
mssql-cli -S <hostname> -d <database> -U <username>

MacOS/Linux

. <workspaceRoot>/env/bin/activate

export PYTHONPATH=<workspaceRoot>

cd <workspaceRoot>
./mssql-cli -S <hostname> -d <database> -U <username>

5. Run Unit Tests / Integration Tests

Windows

<workspaceRoot>\env\scripts\activate.bat

set PYTHONPATH=<workspaceRoot>
set MSSQL_CLI_SERVER=<hostname>
set MSSQL_CLI_DATABASE=<database>
set MSSQL_CLI_USER=<username>
set MSSQL_CLI_PASSWORD=<password>
set PYTHONIOENCODING=UTF-8

cd <workspaceRoot>
python build.py unit_test
python build.py integration_test

MacOS/Linux (Python3.x)

. <workspaceRoot>/env/bin/activate

export PYTHONPATH=<workspaceRoot>
export MSSQL_CLI_SERVER=<hostname>
export MSSQL_CLI_DATABASE=<database>
export MSSQL_CLI_USER=<username>
export MSSQL_CLI_PASSWORD=<password>
export PYTHONIOENCODING=UTF-8

cd <workspaceRoot>
python3 build.py unit_test
python3 build.py integration_test

MacOS/Linux (Python2.x)

. <workspaceRoot>/env/bin/activate

export PYTHONPATH=<workspaceRoot>
export MSSQL_CLI_SERVER=<hostname>
export MSSQL_CLI_DATABASE=<database>
export MSSQL_CLI_USER=<username>
export MSSQL_CLI_PASSWORD=<password>
export PYTHONIOENCODING=UTF-8

cd <workspaceRoot>
python build.py unit_test
python build.py integration_test

IDE Setup

1. Install Visual Studio Code

1. Install Visual Studio Code
2. Install the the VS Code Python extension

2. Configure Python Settings in Visual Studio Code

1. Activate VSCode Python Extension

Open the workspace folder with VS Code. The python extension is not active yet as in the screenshot.

In order to activate the python extension, select one of the *.py file in the explorer on the left. You will see the extension becomes active and showes current version of python hooked up to the extension by default.

2. Edit .env file

Create a file named <workspaceRoot>/.env with contents:

MSSQL_CLI_SERVER=<hostname>
MSSQL_CLI_DATABASE=<database>
MSSQL_CLI_USER=<username>
MSSQL_CLI_PASSWORD=<password>
PYTHONIOENCODING=UTF-8

3. How To Run mssql_cli With Debugger

Select Python: Launch mssql-cli and click the green arrow in order to launch mssql-cli debugger. Debugger will run successfully as shown below.

4. How To Run Unit Tests With / Without Debugger

1. Discover All Unit Tests Of Project In VSCode

Click Run Tests on the bottom of VSCode, and select Discover Tests among the test menu.

You can see all the discovered unit tests after discover process finishes. A test or a group of tests can be executed by one-click in VSCode as shown below.

2. Run Unit Test In VSCode

Run unit tests as shown below.

3. Run Unit Test With Debugger

Clicking Debug Test will start debugger for a corresponding unit test as shown below.