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 Vista previa, suscripció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

Activació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 construya la conexión subyacente. 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 vuelve al proveedor por defecto. Un nombre desconocido asignado a native_provider provoca un error de inmediato. Un nombre desconocido en la variable de entorno genera un error cuando intentas conectarte.
  • Configura native_provider en None para limpiar la selección de atributos antes de que quede fija. 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 conectar, esto informa de la selección, no es una prueba 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, usando SSPI en Windows o Kerberos en Linux y macOS); y Microsoft Entra interactiva, código de dispositivo, principal de servicio, identidad gestionada, 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, los parámetros de qmark y la conversión que realiza pyformatmssql-python.
Sintaxis de escape ODBC Formas de función, fecha/hora, unión externa, GUID, LIKE ... {escape ...}, intervalo y formas de escape {encrypt ...}.
Procedimientos almacenados Llámalos con T-SQL o sintaxis posicional {call ...} mediante execute(), lean conjuntos de resultados y avancen 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 en streaming vuelven a la ejecución fila por fila.
Recuperación de filas fetchone(), fetchmany(), fetchall(), iteración, fetchval(), conversión tipada y flujo extenso de texto/binario.
Obtención de flechas 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, el commit automático (o rollback, si se produjo un error no detectado) que ocurre cuando termina 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) para limitar las sentencias ejecutadas por los cursores de esa conexión; el vencimiento eleva 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 soporta todos los tipos de parámetros que enlaza mssql-python. 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

Revisa estas diferencias antes de cambiar una carga de trabajo de 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. Use connect(timeout=...) para inicio de sesión y Connection.timeout para extractos; ninguno de los dos es un plazo general para 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 de cadena de conexión TransparentNetworkIPResolution con cualquiera de los 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 admiten cachés DNS asistidos por servidor ni enrutamientos mejorados. Configure MultiSubnetFailover=Yes para listeners de grupos de disponibilidad y otros hosts de múltiples direcciones.
Fallos de DNS transitorios Si una consulta DNS falla, el controlador no recurre a la última dirección válida. (#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. Consultar 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 sentencia en curso 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. Usa Connection.timeout para limitar 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. Vincular xml valores como cadenas ordinarias.
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 enlazadas como char / varchar hasta setinputsizes() pueden codificarse incorrectamente para las páginas de códigos 437, 850 y las colaciones UTF-8. Usa la vinculación por defecto.
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ía cuando ningún UID llega al controlador. Algunos valores de capacidad y límites basados en el tamaño del paquete difieren de msodbcsql18. Use SELECT USER_NAME() para el usuario de la base de datos.
Fallos por falta de memoria Algunos fallos de asignación de drivers terminan el proceso de Python en lugar de lanzar 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) Evalúa tu 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