Usa el controlador mssql-odbc (Vista previa)

mssql-python carga uno de dos proveedores ODBC nativos:

Provider Description Status
msodbcsql18 Microsoft ODBC Driver 18 for SQL Server Default
mssql-odbc Controlador ODBC basado en Rust Vista previa, opt-in

El mssql-python-rs paquete 0.4.0 incluye el mssql-odbc proveedor.

Note

Use msodbcsql18 para cargas de producción. Antes de optar por el proveedor de vista previa mssql-odbc , revisa sus problemas conocidos.

Availability

El controlador se incluye dentro del paquete mssql-python-rs como wheels precompiladas para CPython 3.10 y versiones posteriores:

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

Activar el controlador

Instalar mssql-python también instala mssql-python-rs, que contiene el mssql-odbc controlador:

python -m 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 abrir la primera conexión. Use uno de los métodos siguientes.

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

Configura la variable de entorno MSSQL_CONNECTION_STRING con la cadena de conexión de tu aplicación. Mantén activada la validación de certificados (Encrypt=yes;TrustServerCertificate=no). Para más información, consulte Cadenas de conexión y Cifrado y certificados.

Prueba este ejemplo con el proveedor que elijas:

import os
import mssql_python

with mssql_python.connect(os.environ["MSSQL_CONNECTION_STRING"], timeout=45) as connection:
    with connection.cursor() as cursor:
        cursor.execute("SELECT 1")
        print(cursor.fetchone()[0])

El ejemplo imprime 1.

La selección de proveedores sigue las siguientes reglas:

  • MSSQL_PYTHON_NATIVE_PROVIDER tiene prioridad sobre native_provider. Establecer el atributo a un proveedor en conflicto genera RuntimeWarning.
  • Antes de que cargue el controlador, pon native_provider en None para borrar la configuración de Python. Esto no elimina la variable de entorno.
  • Un nombre de proveedor no reconocido genera ValueError. Asignar un nombre inválido a native_provider genera un error inmediatamente; una variable de entorno inválida genera un error al conectarte. El controlador no recurre al proveedor por defecto.
  • El proveedor se fija cuando el controlador inicia un intento de conexión nativa, incluso si ese intento falla. Reinicia Python para cambiar entre proveedores. Cambiar native_provider a otro proveedor emite RuntimeWarning y no tiene efecto.

Los errores de validación de cadenas de conexión y los paquetes de proveedores faltantes ocurren antes de este punto. Puedes corregir estos errores y elegir otro proveedor sin tener que reiniciar.

Llama a mssql_python.get_native_provider_info() para comprobar el nombre del proveedor, cómo se seleccionó y si la selección es fija.

Para volver a msodbcsql18, elimina MSSQL_PYTHON_NATIVE_PROVIDER y cualquier asignación de native_provider de tu aplicación, y luego reinicia Python.

Valores predeterminados de conmutación por error para varias subredes

El proveedor Rust habilita MultiSubnetFailover de forma predeterminada para las conexiones TCP aplicables. Establece MultiSubnetFailover=no explícitamente para solicitar intentos de conexión secuenciales. Para cambiar el valor predeterminado a nivel de despliegue, establezca MSSQL_RS_MULTISUBNET_FAILOVER_DEFAULT en true o false antes de que se utilice por primera vez el controlador nativo. La palabra clave connection-string anula este valor predeterminado.

El atributo numérico SQL_COPT_SS_MULTISUBNET_FAILOVER (1248) también anula la palabra clave cuando se establece antes de conectar.

El controlador no activa este valor predeterminado para transportes no TCP, espejado de bases de datos, instancias nombradas que requieren el descubrimiento de SQL Server Browser, ni conexiones locales de Windows que omiten un protocolo y dirección explícitos. Habilitar explícitamente MultiSubnetFailover para un transporte no TCP, el reflejo de base de datos o el descubrimiento de SQL Server Browser genera un error de conexión. Para más información, consulta Alta disponibilidad y conmutación por error.

Características compatibles

Se soportan las siguientes funciones, sujetas a los problemas conocidos.

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). El controlador nativo también negocia la caché asistida por servidor del Sistema de Nombres de Dominio (DNS) y el enrutamiento mejorado cuando el servidor las admite.
Authentication Autenticación SQL (UID / PWD); autenticación de Windows (Trusted_Connection=Yes, usando Security Support Provider Interface (SSPI) en Windows o Kerberos en Linux y macOS); y autenticación de Microsoft Entra ID interactiva, integrada, con código de dispositivo, con entidad de servicio, con identidad administrada, con credencial predeterminada y con token de acceso. No se soporta la autenticación por contraseña de Microsoft Entra ID. Para obtener más información, consulte problemas conocidos.
Seguridad de la capa de transporte (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 Función, fecha/hora, unión externa, identificador global único (GUID), LIKE ... {escape ...}, intervalo y formas de escape de {encrypt ...}.
Procedimientos almacenados Llámalos con Transact-SQL (T-SQL) o sintaxis posicional {call ...} a través de execute(), lee 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 Texto grande, binario, lenguaje de marcado extensible (XML) y tipos definidos por el usuario (UDT) admiten la transmisión de datos en el momento de la ejecución.
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 y los niveles de aislamiento read-uncommitted, read-committed, repeatable-read, serializable y snapshot isolation. Con el autocommit desactivado, el gestor de contexto de conexión confirma al salir exitosamente y revierte en una excepción.
Tiempo de espera de consulta Configura Connection.timeout en segundos antes de crear un cursor. Cuando una sentencia supera ese tiempo de espera, el driver lanza OperationalError. 0 significa que no hay tiempo de espera. Establece el tiempo de espera de inicio de sesión por separado con connect(timeout=...).
Agrupación de conexiones El grupo integrado mssql-python, incluido el restablecimiento de la conexión antes de reutilizarla. Para el aislamiento específico de grupos de autenticación, véase aislamiento de identidades.
API de metadatos tables(), columns(), primaryKeys(), foreignKeys(), statistics(), rowIdColumns(), rowVerColumns(), procedures()y getTypeInfo().
Codificación y convertidores Codificación predeterminada de caracteres anchos, convertidores de salida y parámetros no Unicode sensibles a la intercalación, incluidos UTF-8 e intercalaciones SQL heredadas con ID de ordenación. La decodificación personalizada de caracteres de un byte debe coincidir con la página de códigos del cliente. Para obtener más información, consulte problemas conocidos.

La autenticación integrada de Microsoft Entra ID utiliza la cuenta de Windows con la sesión iniciada en Windows. En Linux y macOS, utiliza un ticket de Kerberos para autenticarse en el endpoint Servicios de federación de Active Directory (AD FS) (AD FS) del tenant. Para los requisitos previos, consulte la autenticación integrada de Windows.

Cerrar un arrow_reader() envía SQLCancel para interrumpir una recuperación en curso. La llamada cercana espera a que termine la limpieza de cancelaciones. Para más información, véase integración con Apache Arrow.

Tipos de datos

El controlador devuelve valores xml, json y vector como objetos Pythonstr, representando vector como un array de Notación de Objetos JavaScript (JSON). Devuelve tipos de tiempo de ejecución de lenguaje común (CLR) como geometry, geography y hierarchyid como objetos Pythonbytes. Para más información, consulta Mapeos de tipos de datos y Problemas conocidos.

Problemas conocidos

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

Problema Details Workaround
Autenticación por contraseña de Microsoft Entra ID Authentication=ActiveDirectoryPassword no es compatible. Este método no puede satisfacer la autenticación multifactor (MFA). La autenticación SQL (UID / PWD) no se ve afectada. Utiliza otro método de Microsoft Entra ID, como un principal de servicio, identidad gestionada o token de acceso.
attrs_before ajustes El modo de autenticación de Microsoft Entra ID y la intención de la aplicación no pueden configurarse como atributos numéricos de conexión. Usa las palabras clave de cadena de conexión Authentication y ApplicationIntent.
Tiempo de espera de la operación de conexión SQL_ATTR_CONNECTION_TIMEOUT gestiona la limpieza de la cancelación. No aplica un tiempo de espera en el restablecimiento de conexiones del grupo. Una solicitud de conexión puede permanecer bloqueada si el servidor deja de responder durante el reinicio. No hay tiempo de espera para restablecimiento del grupo. Configura connect(timeout=...) para inicio de sesión y Connection.timeout para extractos.
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. Use MultiSubnetFailover=yes para listeners de grupos de disponibilidad y otros hosts de múltiples direcciones. Para los valores predeterminados, véase valores predeterminados de conmutación por error de varias subredes.
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.
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.
Trazado nativo en Linux Con el trazado nativo activado, Python puede abortar durante la limpieza del controlador al salir del proceso. Deja MSSQL_TDS_TRACE sin configurar en Linux.
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. La limpieza de sentencias preparadas utiliza el tiempo límite de consulta de la sentencia, pero un tiempo de espera cero deja esa limpieza sin límites. Busca solo las filas que necesitas, por ejemplo con TOP, y configura Connection.timeout antes de crear el cursor.
Decodificación personalizada de caracteres narrow El controlador nativo utiliza la página de códigos ANSI de Windows en Windows y la página de códigos de la configuración regional del proceso en Linux y macOS para texto no Unicode. Una decodificación explícita en Python que no coincida con esa página de códigos puede producir texto incorrecto o bytes. Utiliza la decodificación predeterminada de caracteres anchos: conn.setdecoding(mssql_python.SQL_CHAR).
Connection.getinfo() Algunos valores de capacidad y límites basados en el tamaño del paquete difieren de msodbcsql18. SQL_USER_NAME informa de la entidad de seguridad principal de la base de datos en lugar de la cadena de conexión UID. Consulta los metadatos específicos del servidor cuando una capacidad o límite reportado sea relevante para tu aplicación.
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 Las lecturas fragmentadas de datos varchar(max) y nvarchar(max) pueden ser más lentas que con msodbcsql18. (#473) Realice pruebas de rendimiento de su carga de trabajo.

Informar de problemas

Si te encuentras con un error, reprodúcelo con msodbcsql18 y anota si ocurre con ambos proveedores. Para las instrucciones para cambiar, consulta Activar el controlador.

Incluye la salida de mssql_python.get_native_provider_info(), tu sistema operativo, las versiones de Python y controladores, y el lote y mensaje de error de T-SQL que falla en tu informe:

En Windows, configura estas variables en PowerShell antes de iniciar Python para recopilar diagnósticos del controlador nativo. Reproduce el problema con mssql-odbc seleccionado:

$env:MSSQL_TDS_TRACE = "true"
$env:MSSQL_TDS_TRACE_LEVEL = "debug"
$env:MSSQL_TDS_TRACE_DIR = ".\traces"

MSSQL_TDS_TRACE activa el trazado, MSSQL_TDS_TRACE_LEVEL selecciona el nivel de registro y MSSQL_TDS_TRACE_DIR selecciona el directorio para archivos de traza por proceso desde el controlador ODBC nativo en lugar de la salida estándar de error. El paquete complementario de Rust también crea archivos de registro en mssql_python_logs del directorio actual.

Las trazas pueden contener texto T-SQL y valores de parámetros. Oculta datos sensibles antes de compartir extractos. Tras el diagnóstico, elimina estas variables y reinicia Python para desactivar el trazado.

Contenido relacionado

  • Se actualizó por última vez el