|
1 | | -# mssql-python |
| 1 | +# Microsoft Python Driver for SQL Server |
| 2 | + |
| 3 | +**mssql-python** is a Python driver for Microsoft SQL Server and the Azure SQL family of databases. It leverages Direct Database Connectivity (DDBC) that enables direct connections to SQL Server without requiring an external driver manager. Designed to comply with the [DB API 2.0](https://peps.python.org/pep-0249/) specification, this driver also introduces Pythonic enhancements for improved usability and functionality. It supports a full range of database operations, including connection management, query execution, and transaction handling. |
| 4 | + |
| 5 | +The driver is compatible with all the Python versions >= 3.10 |
| 6 | + |
| 7 | +[Documentation](https://github.com/microsoft/mssql-python/wiki) | [Release Notes](https://github.com/microsoft/mssql-python/releases) | [Roadmap](https://github.com/microsoft/mssql-python/blob/main/ROADMAP.md) |
| 8 | + |
| 9 | +> **Note:** |
| 10 | +> This project is currently in Public Preview, meaning it is still under active development. We are working on core functionalities and gathering more feedback before GA. Please use with caution and avoid production environments. |
| 11 | +> |
| 12 | +## Installation |
| 13 | + |
| 14 | +**Windows:** mssql-python can be installed with [pip](http://pypi.python.org/pypi/pip) |
| 15 | +```bash |
| 16 | +pip install mssql-python |
| 17 | +``` |
| 18 | +**MacOS:** mssql-python can be installed with [pip](http://pypi.python.org/pypi/pip) |
| 19 | +```bash |
| 20 | +brew install openssl |
| 21 | +pip install mssql-python |
| 22 | +``` |
| 23 | +**Linux:** mssql-python can be installed with [pip](http://pypi.python.org/pypi/pip) |
| 24 | +```bash |
| 25 | +pip install mssql-python |
| 26 | +``` |
2 | 27 |
|
3 | | -This is a new Python driver for Microsoft SQL Server currently in Alpha phase. |
| 28 | +## Key Features |
| 29 | +### Supported Platforms |
| 30 | + |
| 31 | +Windows, MacOS and Linux (manylinux2014 - Debian, Ubuntu & RHEL) |
4 | 32 |
|
5 | | -## Alpha Version Release |
| 33 | +> **Note:** |
| 34 | +> Support for additional Linux OSs (Alpine, SUSE Linux) will come soon |
| 35 | +> |
| 36 | + |
| 37 | +### DBAPI v2.0 Compliance |
| 38 | + |
| 39 | +The Microsoft **mssql-python** module is designed to be fully compliant with the DB API 2.0 specification. This ensures that the driver adheres to a standardized interface for database access in Python, providing consistency and reliability across different database systems. Key aspects of DBAPI v2.0 compliance include: |
| 40 | + |
| 41 | +- **Connection Objects**: Establishing and managing connections to the database. |
| 42 | +- **Cursor Objects**: Executing SQL commands and retrieving results. |
| 43 | +- **Transaction Management**: Supporting commit and rollback operations to ensure data integrity. |
| 44 | +- **Error Handling**: Providing a consistent set of exceptions for handling database errors. |
| 45 | +- **Parameter Substitution**: Allowing the use of placeholders in SQL queries to prevent SQL injection attacks. |
| 46 | + |
| 47 | +By adhering to the DB API 2.0 specification, the mssql-python module ensures compatibility with a wide range of Python applications and frameworks, making it a versatile choice for developers working with Microsoft SQL Server, Azure SQL Database, and Azure SQL Managed Instance. |
| 48 | + |
| 49 | +### Support for Microsoft Entra ID Authentication |
| 50 | + |
| 51 | +The Microsoft mssql-python driver enables Python applications to connect to Microsoft SQL Server, Azure SQL Database, or Azure SQL Managed Instance using Microsoft Entra ID identities. It supports a variety of authentication methods, including username and password, Microsoft Entra managed identity (system-assigned and user-assigned), Integrated Windows Authentication in a federated, domain-joined environment, interactive authentication via browser, device code flow for environments without browser access, and the default authentication method based on environment and configuration. This flexibility allows developers to choose the most suitable authentication approach for their deployment scenario. |
6 | 52 |
|
7 | | -We are excited to announce the release of the alpha version of our driver. This marks a significant milestone in our development journey. While this version is still in the early stages, it includes the foundational code and initial logic that will drive future enhancements. |
| 53 | +EntraID authentication is now fully supported on MacOS and Linux but with certain limitations as mentioned in the table: |
8 | 54 |
|
9 | | -### What's Included: |
| 55 | +| Authentication Method | Windows Support | macOS/Linux Support | Notes | |
| 56 | +|----------------------|----------------|---------------------|-------| |
| 57 | +| ActiveDirectoryPassword | ✅ Yes | ✅ Yes | Username/password-based authentication | |
| 58 | +| ActiveDirectoryInteractive | ✅ Yes | ✅ Yes | Interactive login via browser; requires user interaction | |
| 59 | +| ActiveDirectoryMSI (Managed Identity) | ✅ Yes | ✅ Yes | For Azure VMs/containers with managed identity | |
| 60 | +| ActiveDirectoryServicePrincipal | ✅ Yes | ✅ Yes | Use client ID and secret or certificate | |
| 61 | +| ActiveDirectoryIntegrated | ✅ Yes | ❌ No | Only works on Windows (requires Kerberos/SSPI) | |
| 62 | +| ActiveDirectoryDeviceCode | ✅ Yes | ✅ Yes | Device code flow for authentication; suitable for environments without browser access | |
| 63 | +| ActiveDirectoryDefault | ✅ Yes | ✅ Yes | Uses default authentication method based on environment and configuration | |
10 | 64 |
|
11 | | -Basic functionality to get you started |
12 | | -Initial implementation of core features |
13 | | -Placeholder for future improvements and updates |
| 65 | +**NOTE**: |
| 66 | + - **Access Token**: the connection string **must not** contain `UID`, `PWD`, `Authentication`, or `Trusted_Connection` keywords. |
| 67 | + - **Device Code**: make sure to specify a `Connect Timeout` that provides enough time to go through the device code flow authentication process. |
| 68 | + - **Default**: Ensure you're authenticated via az login, or running within a managed identity-enabled environment. |
14 | 69 |
|
15 | | -### What's Next: |
16 | | - |
17 | | -As we continue to develop and refine the driver, you can expect regular updates that will introduce new features, optimizations, and bug fixes. We encourage you to provide feedback and report any issues you encounter, as this will help us improve the driver for the final release. |
18 | | - |
19 | | -### Stay Tuned: |
20 | | - |
21 | | -We appreciate your interest and support in this project. Stay tuned for more updates and enhancements as we work towards delivering a robust and fully-featured driver in coming months. |
22 | | -Thank you for being a part of our journey! |
| 70 | +### Enhanced Pythonic Features |
| 71 | + |
| 72 | +The driver offers a suite of Pythonic enhancements that streamline database interactions, making it easier for developers to execute queries, manage connections, and handle data more efficiently. |
| 73 | + |
| 74 | +### Connection Pooling |
| 75 | + |
| 76 | +The Microsoft mssql_python driver provides built-in support for connection pooling, which helps improve performance and scalability by reusing active database connections instead of creating a new connection for every request. This feature is enabled by default. For more information, refer [Connection Pooling Wiki](https://github.com/microsoft/mssql-python/wiki/Connection#connection-pooling). |
| 77 | + |
| 78 | +## Getting Started Examples |
| 79 | +Connect to SQL Server and execute a simple query: |
| 80 | + |
| 81 | +```python |
| 82 | +import mssql_python |
| 83 | + |
| 84 | +# Establish a connection |
| 85 | +# Specify connection string |
| 86 | +connection_string = "SERVER=<your_server_name>;DATABASE=<your_database_name>;UID=<your_user_name>;PWD=<your_password>;Encrypt=yes;" |
| 87 | +connection = mssql_python.connect(connection_string) |
| 88 | + |
| 89 | +# Execute a query |
| 90 | +cursor = connection.cursor() |
| 91 | +cursor.execute("SELECT * from customer") |
| 92 | +rows = cursor.fetchall() |
| 93 | + |
| 94 | +for row in rows: |
| 95 | + print(row) |
| 96 | + |
| 97 | +# Close the connection |
| 98 | +connection.close() |
| 99 | + |
| 100 | +``` |
| 101 | + |
| 102 | +## Still have questions? |
| 103 | + |
| 104 | +Check out our [FAQ](https://github.com/microsoft/mssql-python/wiki/Frequently-Asked-Questions). Still not answered? Create an [issue](https://github.com/microsoft/mssql-python/issues/new/choose) to ask a question. |
| 105 | + |
| 106 | +## Contributing |
| 107 | + |
| 108 | +This project welcomes contributions and suggestions. Most contributions require you to agree to a |
| 109 | +Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us |
| 110 | +the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com. |
| 111 | + |
| 112 | +When you submit a pull request, a CLA bot will automatically determine whether you need to provide |
| 113 | +a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions |
| 114 | +provided by the bot. You will only need to do this once across all repos using our CLA. |
| 115 | + |
| 116 | +This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). |
| 117 | +For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or |
| 118 | +contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. |
| 119 | + |
| 120 | +## License |
| 121 | +The mssql-python driver for SQL Server is licensed under the MIT license, except the dynamic-link libraries (DLLs) in the [libs](https://github.com/microsoft/mssql-python/tree/alphaChanges/mssql_python/libs) folder |
| 122 | +that are licensed under MICROSOFT SOFTWARE LICENSE TERMS. |
| 123 | + |
| 124 | +Please review the [LICENSE](LICENSE) file for more details. |
| 125 | + |
| 126 | +## Trademarks |
| 127 | + |
| 128 | +This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft |
| 129 | +trademarks or logos is subject to and must follow |
| 130 | +[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general). |
| 131 | +Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. |
| 132 | +Any use of third-party trademarks or logos are subject to those third-party's policies. |
0 commit comments