diff --git a/docs/backends/mssql.qmd b/docs/backends/mssql.qmd index 4340ed831aa4..353a72857ca5 100644 --- a/docs/backends/mssql.qmd +++ b/docs/backends/mssql.qmd @@ -71,14 +71,32 @@ con = ibis.mssql.connect() # <1> ### `ibis.mssql.connect` +::: {.panel-tabset} + +## Windows + +```python +con = ibis.mssql.connect( + user="username", + password="password", + host="hostname", + driver="SQL Server", +) +``` + +## OSX / Linux + ```python con = ibis.mssql.connect( user="username", password="password", host="hostname", + driver="FreeTDS", # if you are using unixODBC ) ``` +::: + ::: {.callout-note} `ibis.mssql.connect` is a thin wrapper around [`ibis.backends.mssql.Backend.do_connect`](#ibis.backends.mssql.Backend.do_connect). ::: @@ -102,6 +120,19 @@ passing a properly-formatted MSSQL connection URL to `ibis.connect`: con = ibis.connect(f"mssql://{user}:{password}@{host}:{port}") ``` +### Using Integrated Authentication + +Integrated Authentication allows users to log in via NTLM or Kerberos. +To make use of integrated authentication, use `ibis.mssql.connect` as documented +above, but do not specify values for `user` or `password`. The PyODBC driver +will then default to Integrated Authentication. + +Some environments may require you to set additional keywords to connect. +Additional information is available at the following pages: + +- https://learn.microsoft.com/en-us/aspnet/web-api/overview/security/integrated-windows-authentication +- https://learn.microsoft.com/en-us/sql/connect/odbc/linux-mac/using-integrated-authentication + ```{python} #| echo: false BACKEND = "MSSQL" diff --git a/ibis/backends/mssql/__init__.py b/ibis/backends/mssql/__init__.py index e112d9acc218..1ccd8765f529 100644 --- a/ibis/backends/mssql/__init__.py +++ b/ibis/backends/mssql/__init__.py @@ -76,6 +76,43 @@ def do_connect( driver: str | None = None, **kwargs: Any, ) -> None: + """Connect to MSSQL database. + + Parameters + ---------- + host + Address of MSSQL server to connect to. + user + Username. Leave blank to use Integrated Authentication. + password + Password. Leave blank to use Integrated Authentication. + port + Port of MSSQL server to connect to. + database + The MSSQL database to connect to. + driver + ODBC Driver to use. + + On Mac and Linux this is usually 'FreeTDS'. + + On Windows, it is usually one of: + + - ODBC Driver 11 for SQL Server + - ODBC Driver 13 for SQL Server (for both 13 and 13.1) + - ODBC Driver 17 for SQL Server + - ODBC Driver 18 for SQL Server + + See https://learn.microsoft.com/en-us/sql/connect/odbc/windows/system-requirements-installation-and-driver-files + kwargs + Additional keyword arguments to pass to PyODBC. + """ + + # If no user/password given, assume Windows Integrated Authentication + # and set "Trusted_Connection" accordingly + # see: https://learn.microsoft.com/en-us/sql/connect/odbc/linux-mac/using-integrated-authentication + if user is None and password is None: + kwargs.setdefault("Trusted_Connection", "yes") + con = pyodbc.connect( user=user, server=host,