Usando el controlador mssql-odbc (Vista previa)

mssql-python carga uno de dos proveedores ODBC nativos:

Provider ¿Qué es? Status
msodbcsql18 Microsoft ODBC Driver 18 para SQL Server, el controlador C++ establecido Por defecto, sin cambios
mssql-odbc Un nuevo controlador ODBC escrito en Rust Versión preliminar, participación voluntaria

Este artículo cubre mssql-odbcla 0.3.0, la versión actualmente utilizada por mssql-python, y en qué se diferencia de msodbcsql18.

Note

mssql-odbc está en desarrollo y validación activa. Aún no es un reemplazo completo del controlador ODBC 18 de Microsoft. Mantén msodbcsql18 como predeterminado de producción por ahora. El equipo de desarrollo planea cerrar las carencias de la versión preliminar en próximas versiones, salvo por exclusiones intencionadas explícitamente identificadas en este artículo.

Availability

El driver se distribuye dentro del paquete mssql-python-rs como wheels preconstruidas para CPython 3.10 y posteriores:

Platform Architectures
Windows x64; ARM64 en CPython 3.11+
macOS universal2 (x86_64 + arm64), macOS 15 o posterior
Linux (glibc) x86_64, aarch64 — manylinux_2_28 y manylinux_2_34
Linux (musl) x86_64, aarch64 — musllinux_1_2

Habilitación del controlador

El mssql-python paquete depende de mssql-python-rs, así que una instalación normal trae consigo el controlador de Rust:

pip install mssql-python

Si instalas con --no-deps o desde un índice privado, instala mssql-python-rs también explícitamente.

Selecciona el proveedor antes de la primera conexión, ya sea con una variable de entorno:

PowerShell:

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

Bash o Zsh:

export MSSQL_PYTHON_NATIVE_PROVIDER=mssql-odbc

o de Python:

import mssql_python

mssql_python.native_provider = "mssql-odbc"

Conéctate usando la cadena de conexión existente de tu aplicación. Mantén activada la validación de certificados (Encrypt=yes;TrustServerCertificate=no). Para autenticación y configuración de certificados, consulte Cadenas de conexión y Cifrado y certificados.

connection = mssql_python.connect(connection_string)

El controlador aplica estas reglas al seleccionar el proveedor:

  • La MSSQL_PYTHON_NATIVE_PROVIDER variable de entorno tiene precedencia sobre native_provider. Una asignación de atributos en conflicto emite RuntimeWarning.
  • La selección se fija tras la validación de la cadena de conexión e inmediatamente antes de que se establezca la conexión nativa. Un fallo de conexión posterior no elimina la selección. Un error anterior de análisis de cadena de conexión o un paquete de proveedor faltante no soluciona la selección. Una vez fijada la selección, cambiar native_provider a otro proveedor emite RuntimeWarning y no tiene efecto. Reinicia el proceso para cambiar entre proveedores.
  • Un nombre de proveedor no reconocido genera ValueError; el controlador no recurre al proveedor predeterminado. Un nombre desconocido asignado a native_provider provoca un error de inmediato. Un nombre desconocido en la variable de entorno genera un error al intentar conectarse.
  • Establece native_provider en None para borrar la selección de atributos antes de que se fije. La variable de entorno sigue teniendo prioridad.

Llama mssql_python.get_native_provider_info() para inspeccionar el proveedor seleccionado, la fuente de selección y si la selección está fija. Antes de conectarse, esto informa de la selección, no de que el controlador nativo se haya cargado correctamente.

Para volver, pon la variable en msodbcsql18, o desconfigúrala y elimina cualquier asignación de native_provider de tu código (o ponla en "msodbcsql18"). Luego reinicia el proceso.

Lo que funciona hoy en día

El controlador mssql-odbc implementa todas las funciones ODBC a las que llama mssql-python, por lo que la mayoría de las aplicaciones pueden cambiar de proveedor sin cambios en el código. Consulta los problemas conocidos para ver las diferencias restantes.

Area Notes
Ciclo de vida de la conexión Conectar, close()bloqueswith, tiempo de espera de inicio de sesión, diagnósticos y cambiar la base de datos actual. Los ajustes de la cadena de conexión incluyen ApplicationIntent, MultiSubnetFailover, IpAddressPreference, PacketSize, KeepAlive, y ConnectRetryCount / ConnectRetryInterval (resiliencia de conexión inactiva).
Authentication Autenticación SQL (UID / PWD); autenticación de Windows (Trusted_Connection=Yes, mediante SSPI en Windows o Kerberos en Linux y macOS); y Microsoft Entra interactiva, código de dispositivo, entidad de servicio, identidad administrada, credencial predeterminada y token de acceso. No se admiten la autenticación integrada de Entra y la autenticación con contraseña; ver Problemas conocidos.
TLS Encrypt, TrustServerCertificate, HostnameInCertificate y ServerCertificate.
Ejecución de la consulta Ejecución directa y preparada, reutilización de planes preparados, parámetros qmark y la conversión mssql-python que realiza pyformat.
Sintaxis de escape ODBC Formas de función, fecha/hora, unión externa, GUID, LIKE ... {escape ...}, intervalo y {encrypt ...} de escape.
Procedimientos almacenados Llámalas con T-SQL o con la sintaxis posicional {call ...} hasta execute(), lee los conjuntos de resultados y avanza con nextset().
Parámetros de entrada Parámetros escalares, SQL NULL, setinputsizes(), y parámetros mixtos regulares/streaming.
Parámetros grandes Los grandes parámetros de texto y binarios fluyen al servidor por la ruta de enlace ordinaria; A continuación se enumeran las limitaciones de parámetros XML y UDT.
executemany() Agrupado con arrays de parámetros ODBC. Las filas que contienen valores transmitidos recurren a la ejecución fila por fila.
Recuperación de filas fetchone(), fetchmany(), fetchall(), iteración, fetchval(), conversión tipada y transmisión de texto/binario de gran tamaño.
Recuperación con flecha arrow_batch(), arrow()y arrow_reader(). Se requiere pyarrow.
Varios conjuntos de resultados nextset(), incluyendo resultados producidos por matrices de parámetros.
Transactions Autocommit, commit, rollback, la confirmación automática (o reversión, si se ha producido un error) que tiene lugar cuando finaliza un bloque with connect(...), y los niveles de aislamiento read-uncommitted, read-committed, repeatable-read, serializable y snapshot.
Tiempo de espera de consulta Establece Connection.timeout (en segundos) como límite para las instrucciones ejecutadas por los cursores de esa conexión; al caducar, se genera un OperationalError. 0 significa que no hay tiempo de espera. Esta configuración es independiente del tiempo de espera de inicio de sesión especificado como connect(timeout=...).
Agrupación de conexiones El pool integradomssql-python, incluyendo el restablecimiento de la conexión al obtener una conexión del pool y pools separados según la identidad de Microsoft Entra.
API de metadatos tables(), columns(), primaryKeys(), foreignKeys(), statistics(), rowIdColumns(), rowVerColumns(), procedures()y getTypeInfo().
Codificación y convertidores Codificación y convertidores de salida por defecto de caracteres anchos. La decodificación personalizada de caracteres estrechos y la conversión de parámetros no Unicode tienen limitaciones listadas en Problemas conocidos.

Tipos de datos

Puedes leer todos los tipos de datos de SQL Server, y el controlador admite todos los tipos de parámetros que mssql-python vincula. El controlador devuelve xml, json, y vector valores como str (vector como un array JSON), y tipos de CLR como geometry, geography, y hierarchyid como bytes. Para otros mapeos en Python, véase Mapeos de tipos de datos. Para conocer las limitaciones específicas de cada tipo, consulte Problemas conocidos.

Problemas conocidos

Comprueba estas diferencias antes de migrar una carga de trabajo desde msodbcsql18.

Problema Details Workaround
Autenticación integrada de Microsoft Entra Authentication=ActiveDirectoryIntegrated no es compatible. La autenticación de Windows (Trusted_Connection=Yes) no se ve afectada. Usa otro método de Microsoft Entra, o mantén msodbcsql18.
Autenticación de contraseña de Microsoft Entra Authentication=ActiveDirectoryPassword no es compatible y no está previsto ofrecer compatibilidad porque este método no puede satisfacer MFA. La autenticación SQL (UID / PWD) no se ve afectada. Utiliza otro método de Microsoft Entra, como un principal de servicio, identidad gestionada o token de acceso.
attrs_before ajustes La autenticación, la intención de la aplicación y la conmutación por error multi-subred no pueden configurarse como atributos numéricos. Los atributos de la sentencia que no sean el tiempo de espera de la consulta son rechazados. Utiliza las palabras clave equivalentes a la cadena de conexión.
Tiempo de espera de la operación de conexión set_attr(SQL_ATTR_CONNECTION_TIMEOUT, ...) acepta y almacena el valor, pero no impone un tiempo de espera en la versión 0.3.0. Utiliza connect(timeout=...) para el inicio de sesión y Connection.timeout para las instrucciones; ninguno de ellos es un plazo general para las operaciones de conexión.
Hosts con varias direcciones msodbcsql18 activa por defecto la Resolución IP de Red Transparente (TNIR); mssql-odbc no la soporta. mssql-python rechaza la palabra clave TransparentNetworkIPResolution de la cadena de conexión con cualquiera de los dos proveedores. Sin MultiSubnetFailover=Yes, las direcciones se prueban una a una, por lo que una dirección inalcanzable puede retrasar la conexión. No se negocian el almacenamiento en caché de DNS asistido por el servidor ni el enrutamiento mejorado. Establece MultiSubnetFailover=Yes para los oyentes de grupos de disponibilidad y otros hosts con varias direcciones.
Fallos de DNS transitorios Si falla una búsqueda de DNS, el controlador no recurre a la última dirección que funcionó correctamente. (#457) Vuelva a intentar la conexión.
Clasificación de datos No hay metadatos de clasificación de sensibilidad disponibles, y SQL_COPT_SS_DATACLASSIFICATION_VERSION (1400) no se soporta. Consulta sys.sensitivity_classifications.
Multithreading El uso multihilo no ha sido validado. Mantén msodbcsql18 para cargas de trabajo multihilo.
fork() Después de conectarse En Linux, un proceso bifurcado después de que el padre se haya conectado puede quedarse colgado cuando usa el controlador, incluso con una nueva conexión. Con la agrupación activada, el proceso padre también puede colgarse. (#566) Utiliza el método de inicio spawn y conéctate dentro de cada worker.
Cancelación de una instrucción en ejecución Una consulta o búsqueda en ejecución no puede ser interrumpida. Por ejemplo, cerrar an arrow_reader() no detiene una lectura en curso en otro hilo. Utilice Connection.timeout para limitar las instrucciones de larga duración.
Resultados no leídos Cerrar un cursor o ejecutar otra instrucción lee y descarta los resultados restantes en lugar de cancelarlos, lo cual puede ser lento. Cerrar un cursor que usó una instrucción preparada ignora Connection.timeout y puede colgarse si el servidor deja de responder. (#546) Busca solo las filas que necesitas, por ejemplo con TOP.
Parámetros grandes xml y UDT Los valores vinculados como SQL_SS_XML o SQL_SS_UDT a través de setinputsizes() se almacenan en memoria en lugar de procesarse por streaming. Asigne valores a xml como cadenas normales.
Valores vacíos image Se devuelve un valor de SQL Server image vacío y no NULL como None en lugar de b"". Lee CAST(image_column AS varbinary(max)), o utiliza msodbcsql18 cuando la distinción entre vacío y NULO importa.
Parámetros de cadena que no son Unicode Las cadenas asignadas como char / varchar hasta setinputsizes() pueden codificarse incorrectamente para las colaciones de página de códigos 437, 850 y UTF-8. Utilice la asignación de cadenas predeterminada.
Decodificación de páginas de código heredadas en Windows Con setdecoding(SQL_CHAR, encoding="cp1252") o otra página de códigos heredada, el texto puede decodificarse incorrectamente o devolverse como bytes, porque el controlador devuelve los datos char / varchar como UTF-8. Usa el valor por defecto: conn.setdecoding(mssql_python.SQL_CHAR).
Connection.getinfo() SQL_USER_NAME devuelve la cadena UIDde conexión, no el usuario de la base de datos. Está vacío cuando ningún UID llega al controlador. Algunos valores de capacidad y límites basados en el tamaño del paquete difieren de msodbcsql18. Utilice SELECT USER_NAME() para el usuario de la base de datos.
Fallos por falta de memoria Algunos errores de asignación del controlador finalizan el proceso de Python en lugar de generar un MemoryError. (#484) Limita el tamaño de los valores que envías y recuperas.
Rendimiento de lectura de valores grandes En un benchmark, las lecturas fragmentadas de datos varchar(max) / nvarchar(max) fueron ligeramente más lentas que con msodbcsql18. (#473) Realice pruebas de rendimiento de su carga de trabajo.

Esta lista no es exhaustiva.

Informar de problemas

Si te encuentras con un error, selecciona msodbcsql18, reinicia el proceso y comprueba si el comportamiento sigue ocurriendo. También elimina cualquier asignación conflictiva de proveedor del lado de Python. La comparación ayuda a aislar el problema; no demuestra por sí sola su causa. Incluye la salida de mssql_python.get_native_provider_info(), tu plataforma y el SQL fallido o el mensaje de error:

Para el diagnóstico de Rust-driver, establece estas variables antes de iniciar Python y reproduce el problema con mssql-odbc seleccionado. Por ejemplo, en PowerShell:

$env:MSSQL_TDS_TRACE = "true"
$env:MSSQL_TDS_TRACE_LEVEL = "warn,mssqlodbc=debug"
$env:MSSQL_TDS_TRACE_DIR = "./traces"

MSSQL_TDS_TRACE Activa el trazado, MSSQL_TDS_TRACE_LEVEL selecciona el filtro de registro y MSSQL_TDS_TRACE_DIR escribe archivos por proceso en lugar de stderr. Reinicia Python después de cambiar estos ajustes. Las trazas pueden contener texto SQL y valores de parámetros. Revisa y oculta los datos sensibles antes de compartir extractos relevantes, y desactiva el rastreo tras el diagnóstico.

Contenido relacionado

  • Se actualizó por última vez el