Nota
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
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 |
Este artículo trata sobre el proveedor mssql-odbc incluido en la versión mssql-python-rs 0.5.0 y en qué se diferencia de msodbcsql18.
Note
Use msodbcsql18 para las cargas de trabajo 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) |
Habilitar 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_PROVIDERtiene prioridad sobrenative_provider. Si se establece el atributo en un proveedor en conflicto, se emiteRuntimeWarning. - Antes de que cargue el controlador, pon
native_providerenNonepara 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 anative_providergenera 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_providera otro proveedor emiteRuntimeWarningy no tiene ningún 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 utiliza MultiSubnetFailover=yes de forma predeterminada para las conexiones TCP elegibles. Configure MultiSubnetFailover=no para intentos secuenciales. Para cambiar el valor predeterminado de despliegue, establezca MSSQL_RS_MULTISUBNET_FAILOVER_DEFAULT en true o false (sin distinción de mayúsculas y minúsculas) antes del primer uso del controlador. Otros valores provocan un error a menos que se anulen para esa conexión.
La palabra clave connection-string anula el valor predeterminado del entorno. El atributo pre-connect SQL_COPT_SS_MULTISUBNET_FAILOVER (1248) anula ambos.
El valor predeterminado excluye transportes no TCP, espejado de bases de datos e instancias nombradas que requieren descubrimiento de SQL Server Browser. Estas opciones también rechazan el MultiSubnetFailover=yes explícito.
En Windows, el valor predeterminado también está deshabilitado para destinos locales simples como localhost.
Un prefijo o puerto TCP explícito, como tcp:localhost o localhost,1433, evita esta exclusión de destino local. Un valor explícito MultiSubnetFailover=yes también lo anula. 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). |
| Resiliencia de la red | Las conexiones TCP elegibles utilizan intentos de dirección paralela por defecto. El modo paralelo no prioriza direcciones por IpAddressPreference y rechaza más de 64 direcciones resueltas. Para intentos secuenciales y ordenación por familias de direcciones, consulte Valores predeterminados de conmutación por error de varias subredes. El algoritmo separado de Resolución IP de Red Transparente (TNIR) no está implementado. El almacenamiento en caché asistido por servidor del Sistema de Nombres de Dominio (DNS) permite el mecanismo de respaldo con direcciones en caché ante fallos de DNS tras un inicio de sesión exitoso, cuando el servidor permite el almacenamiento en caché. Se utiliza enrutamiento mejorado cuando se negocia con el servidor. |
| 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 más información, consulte Problemas conocidos. |
| Seguridad de la capa de transporte (TLS) |
Encrypt, TrustServerCertificate, HostnameInCertificate y ServerCertificate. En macOS, Encrypt=Strict las conexiones TCP pueden negociar TLS 1.3 con un servidor compatible. |
| 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 | Grandes parámetros de texto y binarios fluyen al servidor siguiendo la ruta de enlace ordinaria. Las vinculaciones explícitas SQL_SS_XML y SQL_SS_UDT a través de setinputsizes() también se transmiten en flujo cuando Python selecciona datos en ejecución: el tamaño declarado debe superar 4000 para str o 8000 para bytes o bytearray. La vinculación de tipo definido por el usuario (UDT) requiere que el servidor describa el tipo del parámetro. Algunas asignaciones personalizadas y mixtas aún se almacenan en búfer. Para más información, consulte Problemas conocidos. |
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 en flujo 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(), incluidos los resultados producidos por los arrays de parámetros. |
| Transactions | Confirmación automática, confirmación, reversión y los niveles de aislamiento lectura no confirmada, lectura confirmada, lectura repetible, serializable e instantánea. Con la confirmación automática desactivada, el administrador del contexto de conexión confirma al salir correctamente y revierte en caso de 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=...). |
| Tiempo de espera para operaciones de conexión |
conn.set_attr(mssql_python.SQL_ATTR_CONNECTION_TIMEOUT, seconds) Se aplica a solicitudes de red propiedad de la conexión, incluyendo confirmación, reversión y cambios de catálogo y aislamiento. El restablecimiento agrupado aplaza el restablecimiento del servidor hasta la siguiente solicitud de configuración de aislamiento; tanto esa solicitud como cualquier reversión anterior utilizan este tiempo de espera.
0 deja esas peticiones sin límites. Este tiempo de espera es independiente de los tiempos de espera de inicio de sesión y consultas y no es un plazo total para obtener una conexión del pool. La limpieza de cancelación puede aumentar el tiempo de llamada transcurrido. |
| Limpieza del cursor | Cerrar un cursor cancela el trabajo pendiente del servidor cuando es necesario en lugar de leer todos los resultados restantes. La limpieza de sentencias preparadas respeta el tiempo de espera de la consulta. La limpieza de cancelaciones tiene un presupuesto de espera adicional igual al tiempo de espera de la conexión, o 120 segundos cuando ese tiempo de espera es 0. |
| Agrupación de conexiones | El grupo integrado mssql-python, incluido el restablecimiento de la conexión antes de reutilizarla. Para ver el aislamiento del grupo específico de la autenticación, consulte Aislamiento de identidad. |
| Multihilo | Conexiones y consultas concurrentes con una conexión y cursor separados por trabajador. No compartas cursores entre hilos. |
| API de metadatos |
tables(), rowIdColumns(), rowVerColumns(), procedures(), getTypeInfo(), getinfo(), statistics(), foreignKeys(), primaryKeys() y columns().
SQL_USER_NAME muestra el usuario de la base de datos en lugar de la cadena de conexión UID. Los valores de capacidades y los límites basados en tamaño de paquete pueden diferir de msodbcsql18: SQL_NEED_LONG_DATA_LEN informes "N" porque la entrada larga no requiere una longitud total declarada. Utilice las capacidades y límites devueltos. |
| Codificación y convertidores | La codificación predeterminada de caracteres amplios, los convertidores de salida, los parámetros no Unicode conscientes de la ordenación y los resultados de caracteres estrechos resultan en la codificación del cliente de la plataforma. La decodificación personalizada de caracteres estrechos debe coincidir con esa codificación; una descoincidencia puede producir texto incorrecto o bytes. Úsase conn.setdecoding(mssql_python.SQL_CHAR) para restaurar la decodificación predeterminada de caracteres anchos. Para la sustitución de parámetros no Unicode, 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.
Si una recuperación está en ejecución cuando cierras un arrow_reader(), close() cancela la recuperación y regresa una vez que esta se detiene. Cerrar un lector de una consulta anterior no afecta a una consulta posterior con el mismo cursor. Para más información, véase integración con Apache Arrow.
Tipos de datos
El controlador devuelve los valores xml, json y vector como objetos str de Python, con vector representado como una matriz de JavaScript Object Notation (JSON).
Devuelve los tipos de common language runtime (CLR), como geometry, geography y hierarchyid, como objetos bytes de Python. Para más información, consulta Mapeos de tipos de datos y Problemas conocidos.
Problemas conocidos
Compruebe estas limitaciones antes de migrar una carga de trabajo desde msodbcsql18.
La siguiente tabla marca exclusiones intencionadas.
| Problema | Details | Workaround |
|---|---|---|
| Autenticación con contraseña de Microsoft Entra ID (exclusión intencionada) |
Authentication=ActiveDirectoryPassword no se soporta, y no se planifica soporte porque 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 Configuraciones |
El selector numérico de autenticación (SQL_COPT_SS_AUTHENTICATION) y el atributo de intención de aplicación siguen sin soportar. Se implementan conmutaciones por error multi-subred y atributos de seguridad integrada. La coincidencia de identificadores de metadatos (SQL_ATTR_METADATA_ID) tampoco es compatible. |
Utilice las palabras clave de cadena de conexión Authentication y ApplicationIntent cuando corresponda. |
Después de conectar fork() |
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. |
| Rastreo 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. |
| Uso de memoria con enlaces personalizados de gran tamaño | Los valores de datos en tiempo de ejecución vinculados como de ancho SQL_CHARfijo, SQL_WCHAR o SQL_BINARY se almacenan en búfer para la conversión. Mezclar parámetros en búfer y en streaming también puede almacenar en búfer valores grandes anteriores mientras se espera un valor almacenado en búfer posterior. |
Prefiere las vinculaciones predeterminadas de longitud variable. Evite sobreescrituras grandes de ancho fijo mediante setinputsizes() cuando importe el uso de memoria. |
| Sustitución de caracteres no Unicode | Para caracteres fuera de la página de códigos de destino de un parámetro no Unicode, el controlador puede sustituir ? por msodbcsql18 si utiliza un carácter de mejor ajuste. |
Prefiere tipos SQL Unicode y las asignaciones de cadena predeterminadas de Python cuando el texto debe preservarse. |
| Cambios de aislamiento después de SQL en bruto | Después de la versión en raw SET TRANSACTION ISOLATION LEVEL, establecer el atributo de conexión al nivel en caché del controlador puede devolver el éxito sin restaurar ese nivel en el servidor. (#798) |
Evita mezclar SQL en bruto y cambios de aislamiento basados en atributos. Usa un SET TRANSACTION ISOLATION LEVEL explícito al restaurar el nivel. |
| 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. Los resultados dependen de la plataforma y de la carga de trabajo. (#473) |
Realice pruebas de rendimiento de su carga de trabajo. |
Esta lista no es exhaustiva.
Notificar problemas
Si te encuentras con un error, reprodúcelo con msodbcsql18 y anota si ocurre con ambos proveedores. Para ver las instrucciones de cambio, consulte Habilitar 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:
- Problemas con el controlador de Rust: https://github.com/microsoft/mssql-rs/issues
-
mssql-pythonProblemas: https://github.com/microsoft/mssql-python/issues
En Windows, configura estas variables en PowerShell antes de iniciar Python para recopilar diagnósticos del controlador nativo. Reproduzca el problema con mssql-odbc seleccionado.
En Linux, deje MSSQL_TDS_TRACE sin establecer debido al fallo de salida del proceso descrito en Problemas conocidos.
$env:MSSQL_TDS_TRACE = "true"
$env:MSSQL_TDS_TRACE_LEVEL = "debug"
$env:MSSQL_TDS_TRACE_DIR = "./traces"
$env:MSSQL_TDS_TRACE_MAX_FILE_SIZE_MB = "100"
MSSQL_TDS_TRACE habilita el rastreo, MSSQL_TDS_TRACE_LEVEL selecciona el filtro de registro y MSSQL_TDS_TRACE_DIR selecciona el directorio para archivos de rastreo por proceso desde el controlador ODBC nativo en lugar de la salida estándar de error.
MSSQL_TDS_TRACE_MAX_FILE_SIZE_MB establece el umbral de rotación por archivo (100 MiB por defecto; acepta de 1 a 1024). No es un límite total de espacio en disco: los archivos individuales pueden superar el umbral y los archivos antiguos no se eliminan.
El paquete complementario de Rust también crea archivos de registro en mssql_python_logs en el directorio actual. Reinicia Python después de cambiar estos ajustes.
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.