Instalación de Microsoft ODBC Driver for SQL Server (macOS)

En este artículo se explica cómo instalar Microsoft ODBC Driver for SQL Server en macOS. También se incluyen instrucciones para las herramientas de línea de comandos opcionales para SQL Server (bcp y sqlcmd), y los encabezados de desarrollo de unixODBC.

En este artículo se proporcionan comandos para instalar el controlador ODBC desde el shell de Bash. Si quiere descargar directamente los paquetes, vea Descarga del controlador ODBC para SQL Server.

Elige una versión del controlador

Utilice el controlador 18 para nuevas aplicaciones. El controlador 17 sigue siendo compatible con aplicaciones que requieren comportamiento de versión 17. Antes de actualizar una aplicación del controlador 17 al controlador 18, revise las principales diferencias de versión, incluido el cambio a los valores predeterminados de cifrado. Para conocer las fechas de soporte, consulte el ciclo de vida del soporte.

La siguiente tabla muestra las fórmulas de paquete del controlador y las herramientas de línea de comandos utilizadas en los comandos de este artículo:

Versión Fórmula del controlador Fórmula de herramientas opcionales
18 msodbcsql18 mssql-tools18
17 msodbcsql17 mssql-tools

Nota:

Las versiones de controladores hasta la 17.7 en macOS son solo x64. A partir del controlador 17.8, los paquetes de macOS soportan tanto x64 como Apple ARM64. La fórmula Homebrew detecta la arquitectura e instala el paquete correspondiente. Si tu símbolo del sistema está funcionando en modo de emulación x64 en ARM64, Homebrew instala el paquete x64.

Usa unixODBC en instalaciones de Homebrew. Las fórmulas para el controlador 17 y el controlador 18 instalan unixODBC como dependencia. Si otra configuración utiliza iODBC, asegúrese de que la biblioteca de controladores y el gestor de controladores tengan como objetivo la misma arquitectura. Una incompatibilidad de arquitectura puede producir un error como incompatible architecture (have 'arm64', need 'x86_64').

Prepara Homebrew

Si Homebrew no está instalado, sigue las instrucciones de instalación de Homebrew. Tras la instalación, siga las instrucciones de configuración del shell impresas por el instalador y luego ejecute brew --version para confirmar que brew está disponible. El prefijo predeterminado de Homebrew en Apple Silicon es /opt/homebrew.

Microsoft ODBC 18

Para instalar Microsoft ODBC Driver 18 for SQL Server en macOS, ejecute los comandos siguientes:

brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18 mssql-tools18

Si Homebrew se niega a cargar una fórmula desde un tap no confiable, verifica el nombre canónico de la fórmula y el tap antes de conceder confianza. Para confiar únicamente en las fórmulas del Driver 18, ejecute:

brew trust --formula microsoft/mssql-release/msodbcsql18
brew trust --formula microsoft/mssql-release/mssql-tools18

A continuación, vuelva a intentar la instalación.

Actualizar o verificar la instalación de un controlador

Para actualizar un controlador, actualiza Homebrew y actualiza la fórmula para la misma versión principal. Sustituya msodbcsql18 por msodbcsql17 para actualizar Driver 17. Para cambiar entre versiones principales, instale la otra fórmula y configure su aplicación para usar su nombre de controlador. Ambas fórmulas pueden instalarse al mismo tiempo.

brew update && HOMEBREW_ACCEPT_EULA=Y brew upgrade msodbcsql18

Establezca driver_version como 17 o 18, luego compruebe la versión de formula instalada, el registro de unixODBC, la arquitectura de macOS y la arquitectura de la biblioteca de controladores:

Versión del controlador driver_formula driver_name Biblioteca de pilotos
18 msodbcsql18 ODBC Driver 18 for SQL Server libmsodbcsql.18.dylib
17 msodbcsql17 ODBC Driver 17 for SQL Server libmsodbcsql.17.dylib
set -e
driver_version=18
driver_formula="msodbcsql${driver_version}"
driver_name="ODBC Driver ${driver_version} for SQL Server"
driver_library="$(brew --prefix "$driver_formula")/lib/libmsodbcsql.${driver_version}.dylib"

brew list --versions "$driver_formula"
odbcinst -q -d -n "$driver_name"
uname -m
file "$driver_library"

Los comandos informan de la versión de la fórmula instalada, el nombre del controlador registrado, la arquitectura de macOS y la arquitectura de la biblioteca de controladores. Por defecto, la fórmula Homebrew registra el controlador. Si instalaste la fórmula con la --without-registration opción, la consulta de registro falla y el bloque se detiene antes de que la arquitectura se compruebe.

Retire o vuelva a instalar Driver 17 o Driver 18

Cierre las aplicaciones que usen el controlador antes de eliminarlo. Si has instalado las herramientas opcionales, desinstálalas primero. Para el controlador 17, sustituya mssql-tools18 por mssql-tools:

HOMEBREW_NO_AUTOREMOVE=1 brew uninstall mssql-tools18

Homebrew puede eliminar automáticamente dependencias no utilizadas durante brew uninstall. Configure HOMEBREW_NO_AUTOREMOVE=1 en ambos comandos de desinstalación para mantener unixODBC disponible hasta que anule el registro del controlador y lo verifique. Si ejecutas brew autoremove, espera hasta después de esa verificación.

Luego desinstala el controlador. Sustituya msodbcsql18 por msodbcsql17 para eliminar Driver 17:

HOMEBREW_NO_AUTOREMOVE=1 brew uninstall msodbcsql18

Si Homebrew informa que otra fórmula depende del controlador, revisa esa dependencia antes de continuar. No fuerces la retirada de un controlador necesario por las herramientas instaladas.

Después de desinstalar una fórmula que registró el controlador, elimine su registro. Para el controlador 17, sustituya 18 por 17:

odbcinst -u -d -n "ODBC Driver 18 for SQL Server"

Después de retirar el registro, ejecuta odbcinst -q -d. Si aparecen nombres de controladores, confirma que el nombre eliminado no aparece en la lista. Si informa SQLGetPrivateProfileString failed, ejecuta odbcinst -j y comprueba la ruta DRIVERS que indica. Si el archivo de configuración de controladores existe, es legible y no contiene registros de controladores, no quedan controladores registrados. Si el archivo falta, es ilegible o aún contiene la entrada del controlador eliminado, resuelve ese problema de configuración antes de considerar la eliminación como completada. Para reinstalar, repita los comandos de instalación para la misma versión principal y luego repita la verificación. Eliminar un controlador puede impedir que las aplicaciones que solicitan su nombre de controlador se conecten. No elimine manualmente bibliotecas de controladores ni archivos de configuración del administrador de controladores.

Microsoft ODBC 17

Para instalar Microsoft ODBC Driver 17 for SQL Server en macOS, ejecute los comandos siguientes:

brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql17 mssql-tools

Si Homebrew se niega a cargar una fórmula desde un tap no confiable, verifica el nombre canónico de la fórmula y el tap antes de conceder confianza. Para confiar únicamente en las fórmulas del Driver 17, ejecute:

brew trust --formula microsoft/mssql-release/msodbcsql17
brew trust --formula microsoft/mssql-release/mssql-tools

A continuación, vuelva a intentar la instalación.

Puedes instalar las fórmulas de controlador msodbcsql17 y msodbcsql18 una junto a la otra. Las fórmulas mssql-tools y mssql-tools18 proporcionan sqlcmd y bcp, así que Homebrew no puede vincular ambos. Si mssql-tools18 está instalado, el comando anterior instala mssql-tools pero informa que el paso brew link no se completó, y sqlcmd y bcp continúan ejecutando las herramientas de la versión 18. Para añadir el controlador 17 mientras las herramientas del controlador 18 están instaladas, instale solo el controlador:

HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql17

Importante

Si instalaste el paquete v17 msodbcsql disponible brevemente, elimínalo antes de instalarlo msodbcsql17 para evitar conflictos. Puedes instalar msodbcsql17 en paralelo con el paquete v13 msodbcsql.

Versiones anteriores

La siguiente sección proporciona instrucciones de instalación para el controlador 13.1.

ODBC 13.1

Estos comandos documentan la ruta histórica del controlador 13.1 para OS X 10.11 (El Capitan) y macOS 10.12 (Sierra). Los requisitos actuales de Homebrew para instalaciones soportadas incluyen macOS Sequoia (15) o posterior; no incluyen estos sistemas antiguos.

brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
brew install msodbcsql@13.1.9.2 mssql-tools@14.0.6.0

Archivos de controlador

Los archivos clave del controlador ODBC en macOS incluyen:

Componente Descripción
libmsodbcsql.18.dylib, libmsodbcsql.17.dylib, o libmsodbcsql.13.dylib La biblioteca principal de controladores. La biblioteca del Driver 18 está bajo $(brew --prefix msodbcsql18)/lib/; la biblioteca del Driver 17 está bajo $(brew --prefix msodbcsql17)/lib/. La biblioteca histórica de Driver 13.1 está bajo /usr/local/lib/.
msodbcsqlr18.rll, msodbcsqlr17.rll, o msodbcsqlr13.rll El archivo de recursos para la biblioteca de controladores. Para el Driver 18, está bajo $(brew --prefix msodbcsql18)/share/msodbcsql18/resources/en_US/; para el Driver 17, está bajo $(brew --prefix msodbcsql17)/share/msodbcsql17/resources/en_US/. El archivo histórico del controlador 13.1 está bajo /usr/local/share/msodbcsql/resources/en_US/.
msodbcsql.h El archivo de encabezado que contiene definiciones del controlador. No puedes hacer referencia a msodbcsql.h y odbcss.h en el mismo programa. El encabezado del Driver 18 está en $(brew --prefix msodbcsql18)/include/msodbcsql18/; el encabezado del Driver 17 está en $(brew --prefix msodbcsql17)/include/msodbcsql17/. El encabezado histórico del controlador 13.1 está bajo /usr/local/include/msodbcsql/.
LICENSE.txt El Acuerdo de licencia de usuario final. Está bajo $(brew --prefix msodbcsql18)/share/doc/msodbcsql18/ para el Driver 18 y $(brew --prefix msodbcsql17)/share/doc/msodbcsql17/ para el Driver 17. El archivo histórico del controlador 13.1 está bajo /usr/local/share/doc/msodbcsql/.
RELEASE_NOTES Las notas de lanzamiento. Están bajo $(brew --prefix msodbcsql18)/share/doc/msodbcsql18/ para el Driver 18 y $(brew --prefix msodbcsql17)/share/doc/msodbcsql17/ para el Driver 17. El archivo histórico del controlador 13.1 está bajo /usr/local/share/doc/msodbcsql/.

Cargar el archivo de recursos

El controlador necesita el archivo de recursos para funcionar. Su ubicación es relativa a la biblioteca de controladores, como se muestra en la tabla anterior. A partir de la versión 17.1, el controlador también comprueba su directorio de recursos predeterminado si la búsqueda relativa falla.

Solución de problemas

Si una conexión falla con un Can't open lib error, compruebe qué archivos de configuración lee unixODBC:

odbcinst -j

Si el directorio reportado no es el directorio de configuración de Homebrew, configura ODBCSYSINI para el shell que inicia tu aplicación y luego revisa las rutas de nuevo:

export ODBCSYSINI="$(brew --prefix)/etc"
odbcinst -j

Para más información sobre problemas de conexión, consulte el artículo sobre problemas conocidos sobre solucionar problemas de conexión.

Si Homebrew no encuentra las fórmulas, añade el tap de Microsoft:

brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release