-
Notifications
You must be signed in to change notification settings - Fork 3
How to Contribute
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
- Ensure that Python > 3.9.x is installed - older versions of Python may work but are not supported
- Note that when these instructions refer to 'python3' or 'pip3' you may need to use the commands 'python' or 'pip' instead if you are on Windows
- Make sure you have MSVC 140 installed, Build Tools Installation
- Run
pip3 install -r requirements.txt
from the root of the project- If you need to install pip, see pip Installation
We follow Python's PEP 8 style guide with a maximum line length of 160 characters. To ensure that your code has no style problems, run the following commands before committing (install them from pip first if needed):
- Run autopep8 to format your code according to PEP 8
-
autopep8 --in-place --aggressive --aggressive --max-line-length 160 -r .
(from the project's root directory)
-
- Run flake8 to look for problems that need to be resolved manually
- On Mac/Linux:
./scripts/flake8.sh
- On Windows:
.\scripts\flake8.ps1
- On Mac/Linux:
The following directions can be used to run all tests:
- Run
pip3 install -r requirements.txt
if you haven't already - To run unit tests, run script
./scripts/test-unit.sh
orscripts\test-unit.ps1
as needed for your platform. - To run integration tests, run script
./scripts/test-integration.sh
orscripts\test-integration.ps1
as needed for your platform. See the section below for more specific details on integration tests.
The MySQL Tools Service supports tests that connect to a real mysql database, which we call integration tests. These can be run by calling ./scripts/test-integration.sh
or scripts\test-integration.ps1
from the project's root directory.
Integration tests require a local config file that contains the options for connecting to your test database. The template config file is located in tests/integration/config.json.txt
. Copy this file to tests/integration/config.json
and modify values as appropriate. The template lists the most common options. You can put multiple server configurations in the file in order to run each integration test multiple times, once per server.
Integration tests can be inserted in line with our unit tests. The tests.integration
module exports a integration_test
decorator and a get_connection
function that can be used in integration tests.
To declare that a test is an integration test, mark it with the imported @integration_test
decorator. This will automatically patch driver.connect
in your test to return the test database connection from your config file, and will let you use the get_connection
function to retrieve that connection if you need it elsewhere. You can optionally pass min_version
and max_version
integer arguments to the @integration_test
decorator to make the test only run when connected to the specified versions of MySQL. You can also use the create_extra_test_database
function if your test needs additional databases.
Each integration test will run with its own database, which will be created before the test starts and dropped when the test ends.
You can find an integration test example in code in tests/query_execution/test_query_execution_service.py
's test_query_execution_and_retrieval
method.
You can also create end-to-end JSON RPC integration tests, which test the entire service using JSON RPC inputs and outputs. An example of these tests is located in tests/json_rpc_tests/object_explorer_json_rpc_tests.py
.
When creating one of these tests, mark the test with an integration test decorator as usual. Then, create tests.json_rpc_tests.RPCTestMessage
objects for each message to send as part of the test, including any connection messages that are needed. Finally, initialize a tests.json_rpc_tests.JSONRPCTestCase
object with the ordered list of messages to send, and call its .run()
method to run the test.
When creating each tests.json_rpc_tests.RPCTestMessage
, you should include a response verification callback that will be called with the response as a parameter, deserialized as a dictionary, when the server responds to the request. You should also include a list of notification verifiers. Each verifier is a tuple consisting of two functions. The first function is a filter function that will be called to determine which single notification the verifier applies to. If the verifier function returns true for multiple notifications, the first one will be used. The second function is a callback that will be called with the notification as a parameter, deserialized as a dictionary.
- Update your PYTHONPATH environment variable to contain the source directory. From within the project's main directory, run the following commands:
- On Mac/Linux:
export PYTHONPATH=$(pwd)
- On Windows:
set PYTHONPATH=%cd%
- On Mac/Linux:
python3 ossdbtoolsservice/ossdbtoolsservice_main.py
- Now you can pass in JSON RPC requests to stdin, following the language server protocol specifications.
It is possible to remotely attach a debugger to the MySQL Tools Service through VS Code's Python extension. Just start the service with the command line argument --enable-remote-debugging
and then, from the debug tab in VS Code, click 'Attach (Remote Debug)'.
If you want to debug startup, use the flag --enable-remote-debugging-wait
instead, and the service will wait for you to attach the debugger before starting up.
By default, the remote debugging server runs on port 3000. If you need to use a different port, just pass it as the argument to that flag, e.g. --enable-remote-debugging=3001
You can set configuration options in Azure Data Studio to let you attach the remote debugger to the MySQL Tools Service running inside Azure Data Studio. Set MySQL.useDebugSource
to true and set MySQL.debugSourcePath
to the path to the root of your MySQL Tools Service repo (i.e. the folder containing this readme file). If you want to debug startup, also set MySQL.enableStartupDebugging
to true. Here are examples from a settings.json file:
"MySQL.debugSourcePath": "/Users/mairvine/code/mysqltoolsservice",
"MySQL.useDebugSource": true,
"MySQL.enableStartupDebugging": true
To build an executable, run the following commands starting from the main source code directory on the platform you want to build for. The output will be placed in a folder called build.
- On Mac:
./scripts/build-mac.sh
- The output will be placed in the build/mysqltoolsservice directory
- On Linux:
./scripts/build-linux.sh
- On Windows:
.\scripts\build.ps1
- Or, from cmd.exe:
powershell.exe scripts\build.ps1
- Or, from cmd.exe:
Project Management
Contributing
Documentation