Connecting to SQL Server

For information on the available WHL files for supported environments, and how to install the appropriate file for your Python distribution, see Package Installation.

For information on the module to import, and how to configure the necessary connection properties in a connection string, see Establishing a Connection.

Other available connection properties can be used to configure other aspects of the connector capabilities.

Python Version Support

The CData Python Connector for SQL Server can be installed and used in Python 3.10 or newer.

SQL Server Version Support

The connector enables connectivity to SQL Server through the TDS protocol. SQL Server versions 2008, 2012, 2014, 2016, 2017, 2019, and 2022 are suppported.

Connections to Azure SQL Server and Azure Data Warehouse instances are supported as well.

See Also

• Using the Connector: Establish connections and query SQL Server through Python code.
• From SQLAlchemy: Use SQLAlchemy to establish a connection with dialect URL, and interact with SQL Server data using mapped classes and Sessions.

Dependencies

The Python connectors require that Python 3.10 or newer be installed.

Installation

The CData Python Connector for SQL Server is available as a WHL file for Windows, Linux, and Mac. Each connector is built using the Python 3.10 Stable ABI (indicated by the abi3 tag in the filename), so a single wheel supports any Python 3.10 or newer installation — there is no need to match your exact Python minor version. Use the "pip install" command with the appropriate WHL file for your platform.

Windows:

pip install cdata_sql_connector-26.0.9655-cp310-abi3-win_amd64.whl

Linux:

pip install cdata_sql_connector-26.0.9655-cp310-abi3-linux_x86_64.whl

macOS:

pip install cdata_sql_connector-26.0.9655-cp310-abi3-macosx_12_0_arm64.whl

The macOS wheel supports arm64 (Apple Silicon) architectures only on macOS 12 and newer.

Regardless of the environment, certain distributions might require that the "pip3 install" command be used instead, to differentiate from a Python 2 distribution that might exist already. After installation, confirm whether the connector is successfully installed by running the "pip list" command. If "cdata_sql_connector" is present in the list output by the command, then the installation was successful.

Upgrading

When upgrading, "pip install" does not automatically clean up old JRE files. To avoid leftover files that could cause JVM errors, uninstall the previous version before installing the new one.

Licensing

After the installation is complete, a separate step is needed to activate a license for the connector. Among the CData assets in the distribution's site packages, there is an install-license tool that activates this license. From within the distribution's site-packages folder, after navigating to the "cdata/installlic_sql" folder, simply use a command like the below to activate the license. Omitting the <key> argument activates a trial license:

• Windows:
  

  ./install-license.exe <key>

• Linux / Mac:
  

  ./install-license.sh <key>

Sometimes, file access issues may cause pip to install the connector in a fallback file path that is not the python distribution's main or primary site-packages location. This can make it difficult to find where the connector was installed, and from there, the license activator. In that event, this python script below will print out the full file path of the connector's native file. This file will be stored in the mentioned cdata folder, from which the installlic_sql folder is trivial to find:

import os
import cdata.sql
path = os.path.abspath(cdata.sql.__file__)
print(path)

Uninstallation

If the connector needs to be uninstalled for any reason, do so by running the pip uninstall command, as in the example below:

pip uninstall cdata-sql-connector

The objects available within our connector are accessible from the "cdata.sql" module. To use the module's objects directly:

1. Import the module as follows:
   

   import cdata.sql as mod

2. To establish a connection string, call the connect() method from the connector object using an appropriate connection string, such as:
   

   mod.connect("user=myuser;password=mypassword;Server=localhost;Database=Northwind;")

Connecting to SQL Server

You can use the CData Python Connector for SQL Server to connect to any instance of Microsoft SQL Server, Azure SQL Server, or Azure Data Warehouse.

Microsoft SQL Server

Set the following connection properties to connect to SQL Server:

• Server: The name of the server running SQL Server.
• Database: The name of the SQL Server database.

Azure SQL Server or AZure Data Warehouse

Set the following connection properties to connect to Azure SQL Server or Azure Data Warehouse:

• Server: The server running Azure. You can find this by logging into the Azure portal and navigating to SQL databases (or SQL data warehouses) > Select your database > Overview > Server name.
• Database: The name of the database, as seen in the Azure portal on the SQL databases (or SQL warehouses) page.

Authenticating to SQL Server

The connector supports authenticating to SQL Server using SQL Server authentication, Windows Authentication, or Kerberos authentication.

Microsoft SQL Server

To authenticate to Microsoft SQL Server using your SQL Server user login credentials, set the following:

• AuthScheme: Set this to Password.
• User: The username provided for authentication with SQL Server.
• Password: The password associated with the authenticating user.

Windows

To enable the connector to obtain login credentials automatically from the identity of the windows user running the process, set the following:

• AuthScheme: Set this to NTLM.
• IntegratedSecurity: Set this to true.

Kerberos

To authenticate to SQL Server with Kerberos, set AuthScheme to KERBEROS.

Authenticating to SQL Server via Kerberos requires you to define authentication properties and to choose how Kerberos should retrieve authentication tickets.

Retrieve Kerberos Tickets

Kerberos tickets are used to authenticate the requester's identity. The use of tickets instead of formal logins/passwords eliminates the need to store passwords locally or send them over a network. Users are reauthenticated (tickets are refreshed) whenever they log in at their local computer or enter kinit USER at the command prompt.

The connector provides three ways to retrieve the required Kerberos ticket, depending on whether or not the KRB5CCNAME and/or KerberosKeytabFile variables exist in your environment.

MIT Kerberos Credential Cache File

This option enables you to use the MIT Kerberos Ticket Manager or kinit command to get tickets. With this option there is no need to set the User or Password connection properties.

This option requires that KRB5CCNAME has been created in your system.

To enable ticket retrieval via MIT Kerberos Credential Cache Files:

1. Ensure that the KRB5CCNAME variable is present in your environment.
2. Set KRB5CCNAME to a path that points to your credential cache file. (For example, C:\krb_cache\krb5cc_0 or /tmp/krb5cc_0.) The credential cache file is created when you use the MIT Kerberos Ticket Manager to generate your ticket.
3. To obtain a ticket:
   1. Open the MIT Kerberos Ticket Manager application.
   2. Click Get Ticket.
   3. Enter your principal name and password.
   4. Click OK.

   If the ticket is successfully obtained, the ticket information appears in Kerberos Ticket Manager and is stored in the credential cache file.

The connector uses the cache file to obtain the Kerberos ticket to connect to SQL Server.

Note: If you would prefer not to edit KRB5CCNAME, you can use the KerberosTicketCache property to set the file path manually. After this is set, the connector uses the specified cache file to obtain the Kerberos ticket to connect to SQL Server.

Keytab File

If your environment lacks the KRB5CCNAME environment variable, you can retrieve a Kerberos ticket using a Keytab File.

To use this method, set the User property to the desired username, and set the KerberosKeytabFile property to a file path pointing to the keytab file associated with the user.

User and Password

If your environment lacks the KRB5CCNAME environment variable and the KerberosKeytabFile property has not been set, you can retrieve a ticket using a user and password combination.

To use this method, set the User and Password properties to the user/password combination that you use to authenticate with SQL Server.

Enabling Cross-Realm Authentication

More complex Kerberos environments can require cross-realm authentication where multiple realms and KDC servers are used. For example, they might use one realm/KDC for user authentication, and another realm/KDC for obtaining the service ticket.

To enable this kind of cross-realm authentication, set the KerberosRealm and KerberosKDC properties to the values required for user authentication. Also, set the KerberosServiceRealm and KerberosServiceKDC properties to the values required to obtain the service ticket.

NTLM

You can authenticate with a username and password using the NTLM authentication mechanism.

To authenticate, set the following:

• AuthScheme: NTLM
• User: The name of the authenticating user.
• Password: The password associated with the authenticating user.

Alternatively, you can use OAuth by setting AuthScheme to AzureAd, AzurePassword, or AzureMSI. All OAuth connections require setting the AzureTenant connection property to the Id of the tenant the SQL Server database is hosted on.

Entra ID (Azure AD)

Note: Microsoft has rebranded Azure AD as Entra ID. In topics that require the user to interact with the Entra ID Admin site, we use the same names Microsoft does. However, there are still CData connection properties whose names or values reference "Azure AD".

Microsoft Entra ID is a multi-tenant, cloud-based identity and access management platform. It supports OAuth-based authentication flows that enable the driver to access SQL Server endpoints securely.

Authentication to Entra ID via a web application always requires that you first create and register a custom OAuth application. This enables your application to define its own redirect URI, manage credential scope, and comply with organization-specific security policies.

For full instructions on how to create and register a custom OAuth application, see Creating a Custom Azure AD Application.

After setting AuthScheme to AzureAD, the steps to authenticate vary, depending on the environment. For details on how to connect from desktop applications, web-based workflows, or headless systems, see the following sections.

Desktop Applications

You can authenticate from a desktop application using either the driver's embedded OAuth application or a custom OAuth application registered in Microsoft Entra ID.

Option 1: Use the Embedded OAuth Application

This is a pre-registered application, included with the driver. It simplifies setup and eliminates the need to register your own credentials and is ideal for development environments, single-user tools, or any setup where quick and easy authentication is preferred.

Set the following connection properties:

• AuthScheme: AzureAD
• InitiateOAuth:
  • GETANDREFRESH – Use for the initial login. Launches the login page and saves tokens.
  • REFRESH – Use this setting when you have already obtained valid access and refresh tokens. Reuses stored tokens without prompting the user again.

When you connect, the driver opens the Microsoft Entra sign-in page in your default browser. After signing in and granting access, the driver retrieves the access and refresh tokens and saves them to the path specified by OAuthSettingsLocation.

Option 2: Use a Custom OAuth Application

If your organization requires more control, such as managing security policies, redirect URIs, or application branding, you can instead register a custom OAuth application in Microsoft Entra ID and provide its values during connection.

During registration, record the following values:

• OAuthClientId: The client Id that was generated when you registered your custom OAuth application.
• OAuthClientSecret: The client secret that was that was generated when you registered your custom OAuth application.
• CallbackURL: A redirect URI you defined during application registration.

For full instructions on how to register a custom OAuth application and configure redirect URIs, see Creating a Custom Azure AD Application.

Set the following connection properties:

• AuthScheme: AzureAD
• InitiateOAuth:
  • GETANDREFRESH – Use for the initial login. Launches the login page and saves tokens.
  • REFRESH – Use this setting when you have already obtained valid access and refresh tokens. Reuses stored tokens without prompting the user again.
• OAuthClientId: The client Id that was generated when you registered your custom OAuth application.
• OAuthClientSecret: The client secret that was generated when you registered your custom OAuth application.
• CallbackURL: A redirect URI you defined during application registration.

After authentication, tokens are saved to OAuthSettingsLocation. These values persist across sessions and are used to automatically refresh the access token when it expires, so you don't need to log in again on future connections.

Web Applications

To authenticate from a web application, you must register a custom OAuth application in Microsoft Entra ID (formerly Azure Active Directory). Embedded OAuth apps are not supported in this context because web-based flows require a registered redirect URI and centralized credential management.

This approach is designed for hosted, multi-user environments where access must be delegated through a secure, standards-compliant OAuth workflow. It gives your organization control over the OAuth client, redirect URI, branding, and permissions scope.

Before you begin: Register a custom OAuth application in the Azure portal. During registration, collect the following values:

• OAuthClientId: The client Id that was generated when you registered your custom OAuth application.
• OAuthClientSecret: The client secret that was generated when you registered your custom OAuth application.
• CallbackURL: A redirect URI you defined during application registration.

For full instructions on how to register a custom OAuth application and configure redirect URIs, see Creating a Custom Azure AD Application.

To authenticate using AzureAD in a web application, configure the following connection properties:

• AuthScheme: AzureAD
• InitiateOAuth: OFF – Disables automatic login prompts.
• OAuthClientId: The client Id that was generated when you registered your custom OAuth application.
• OAuthClientSecret: The client secret that was generated when you registered your custom OAuth application.
• CallbackURL: A redirect URI you defined during application registration.

Because web applications typically manage OAuth flows manually on the server-side, InitiateOAuth must be set to OFF. This allows you to explicitly control when and how tokens are retrieved and exchanged using stored procedures.

After configuring these properties, follow the steps below to obtain and exchange OAuth tokens:

1. Call the GetOAuthAuthorizationUrl stored procedure:
   • CallbackURL: Set to your registered redirect URI
2. Open the returned URL in a browser. Sign in with a Microsoft Entra ID account and grant access.
3. After signing in, you are redirected to your CallbackURL with a code parameter in the query string.
4. Extract the code and pass it to the GetOAuthAccessToken stored procedure:
   • AuthMode: WEB
   • Verifier: The authorization code from the CallbackURL
5. The procedure returns:
   • OAuthAccessToken: Used for authentication.
   • OAuthRefreshToken: Used to refresh the access token.
   • ExpiresIn: The lifetime of the access token in seconds.

To enable automatic token refresh, configure the following connection properties:

• InitiateOAuth: REFRESH
• OAuthRefreshToken: Your previously obtained refresh token

When InitiateOAuth is set to REFRESH, the driver uses the provided refresh token to request a new access token automatically.

After a successful connection, the driver saves the updated access and refresh tokens to the file specified by OAuthSettingsLocation.

You only need to repeat the full OAuth authorization flow if the refresh token expires, is revoked, or becomes invalid.

For more background on OAuth flows in Microsoft Entra ID, see Microsoft Entra Authentication Overview.

Headless Machines

Headless environments like CI/CD pipelines, background services, or server-based integrations do not have an interactive browser. To authenticate using AzureAD, you must complete the OAuth flow on a separate device with a browser and transfer the authentication result to the headless system.

Setup options:

• Obtain and exchange a verifier code
  • Use another device to sign in and retrieve a verifier code, which the headless system uses to request tokens.
• Transfer an OAuth settings file
  • Authenticate on another device, then copy the stored token file to the headless environment.

Using a Verifier Code

1. On a device with a browser:
   • If using a custom OAuth app, set the following properties:
     • InitiateOAuth: OFF
     • OAuthClientId: The client Id that was generated when you registered your custom OAuth application.
     • OAuthClientSecret: The client secret that was generated when you registered your custom OAuth application.
   • Call the GetOAuthAuthorizationUrl stored procedure to generate a sign-in URL.
   • Open the returned URL in a browser. Sign in and grant permissions to the driver. You are redirected to the callback URL, which contains the verifier code.
   • After signing in, save the value of the code parameter from the redirect URL. You will use this later to set the OAuthVerifier connection property.
2. On the headless machine:
   • Set the following properties:
     • AuthScheme: AzureAD
     • InitiateOAuth: REFRESH
     • OAuthVerifier: The verifier code you saved.
     • OAuthSettingsLocation: The path of the file that holds the OAuth token values.
     • For custom applications:
       • OAuthClientId: The client Id that was generated when you registered your custom OAuth application.
       • OAuthClientSecret: The client secret that was generated when you registered your custom OAuth application.
   • After tokens are saved, reuse them by setting:
     • InitiateOAuth: REFRESH
     • OAuthSettingsLocation: Make sure this location grants read and write permissions to the driver to enable the automatic refreshing of the access token.
     • For custom applications:
       • OAuthClientId: The client Id that was generated when you registered your custom OAuth application.
       • OAuthClientSecret: The client secret that was generated when you registered your custom OAuth application.

Transferring OAuth Settings

1. On a device with a browser:
   • Connect using the instructions in the Desktop Applications section.
   • After connecting, tokens are saved to the file path in OAuthSettingsLocation. The default filename is OAuthSettings.txt.

2. On the headless machine:
   • Copy the OAuth settings file to the machine.
   • Set the following properties:
     • AuthScheme: AzureAD
     • InitiateOAuth: REFRESH
     • OAuthSettingsLocation: Make sure this location grants read and write permissions to the driver to enable the automatic refreshing of the access token.
     • For custom applications:
       • OAuthClientId: The client Id that was generated when you registered your custom OAuth application.
       • OAuthClientSecret: The client secret that was generated when you registered your custom OAuth application.

After setup, the driver uses the stored tokens to refresh the access token automatically, no browser or manual login is required.

Azure Service Principal

Note: Microsoft has rebranded Azure AD as Entra ID. In topics that require the user to interact with the Entra ID Admin site, we use the same names Microsoft does. However, there are still CData connection properties whose names or values reference "Azure AD".

Service principals are security objects within a Microsoft Entra ID (Azure AD) application that define what that application can do within a specific tenant. Service principals are created in the Entra admin center, also accessible through the Azure portal. As part of the creation process we also specify whether the service principal will access Entra resources via a client secret or a certificate.

Depending on the service you are connecting to, a tenant administrator may need to enable Service Principal authentication or assign the Service Principal to the appropriate roles or security groups.

Instead of being tied to a particular user, service principal permissions are based on the roles assigned to them. These roles determine which resources the application can access and which operations it can perform.

When authenticating using a service principal, you must register an application with an Entra tenant, as described in Creating a Service Principal App in Entra ID (Azure AD).

This subsection describes properties you must set before you can connect. These vary, depending on whether you will authenticate via a client secret or a certificate.

Authentication with Client Secret

• AuthScheme: AzureServicePrincipal.
• AzureTenant: The Azure AD tenant to which you will connect.
• OAuthClientId: The client ID in your application settings.
• OAuthClientSecret: The client secret in your application settings.
• InitiateOAuth: GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.

Authentication with Certificate

• AuthScheme: AzureServicePrincipalCert.
• AzureTenant: The Azure AD tenant to which you will connect.
• OAuthClientId: The client Id in your application settings.
• OAuthJWTCert: The JWT Certificate store.
• OAuthJWTCertType: The JWT Certificate store type.
• InitiateOAuth: GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.

Azure Password

To authenticate directly to Azure Active Directory using your Azure credentials, specify the following connection properties:

• AuthScheme: AzurePassword.
• User: The account for the authenticating Azure user.
• Password: The authenticating Azure user's password.
• AzureTenant: The Directory (tenant) ID of the custom Azure AD application used to authenticate to SQL Server on Azure. To find this, go to the custom application's Overview page.

Managed Service Identity (MSI)

If you are running SQL Server on an Azure VM and want to automatically obtain Managed Service Identity (MSI) credentials to connect, set AuthScheme to AzureMSI.

User-Managed Identities

To obtain a token for a managed identity, use the OAuthClientId property to specify the managed identity's client_id.

If your VM has multiple user-assigned managed identities, you must also specify OAuthClientId.

Java Native Interface (JNI) is a standard programming interface for writing Java native methods and embedding the Java virtual machine into native applications.

The connector leverages the JNI for improved performance on Mac and Linux.

Configure the Config INI File

The Linux and Mac editions of the SQL Server python connector are configured with an ini file. This file is used to set several parameters, including JNI behavior. This file is to be located in:

{path_to_distribution_site-packages}/cdata/config.ini

Ensure that any configuration properties you set in the ini file fall under the following section name (adjust the 311 number if you are using an different python version from 3.11):

• For Linux:
  

  [sql.cpython-311-x86_64-linux-gnu.so]

• For Mac:
  

  [sql.cpython-311-darwin.so]

Configure the JNI connector's behavior by editing the properties in the connector's config.ini file. The connector can be configured as follows:

• LOGFILE: Set this the same way as the CDATA_LOGFILE envrionment variable below.
• JAVA_HOME: Configure the path to the JVM library location used to launch the JVM.
• CLASS_PATH: Use a colon-separated list to configure the paths to the third-party jar libraries.

Configure Environment Variables

Additionally, set the following environment variables:

• CDATA_JAVA_HOME: Configure the path to the JVM library location used to launch the JVM.
• CDATA_JVM_OPTIONS: Place JVM options here.
• CDATA_LOGFILE: Set this in the following scheme: <SCHEME>://<TAG>[|<LEVEL>]
  • SCHEME: The options are STDOUT, FILE.
    • STDOUT: Both the native wrapper and odbc core log into stdout. The Logfile and Verbosity properties can override the behavior of ODBC core.
    • FILE: The native wrapper logs into <FILENAME> while the odbc core logs into <FILENAME>.driver.log. The Logfile and Verbosity properties can override the behavior of ODBC core.
  • TAG
    • For STDOUT, set this to 1. For FILE, set this to the filename.
  • LEVEL
    • Set to one of: FATAL | ERROR | WARNING | INFO | DEBUG

The following are some examples of this syntax:

• STDOUT://1|DEBUG
• FILE:///tmp/my_py.log|DEBUG

Custom Logger

The Python connector supports a custom logging mechanism for redirecting log output to any destination, such as a cloud storage service or logging framework. Use setCustomLoggerFactory() to register a factory function that creates a logger instance for each connection.

The factory function receives the context string from the Logfile connection property (the portion after CUSTOM://) and must return an object with a writeLog(verbosity, message) method.

To enable custom logging:

1. Call setCustomLoggerFactory() with your factory function before opening connections.
2. Set Logfile to CUSTOM:// followed by a context string to identify the connection.
3. Set Verbosity to the desired log level.

The following example demonstrates a custom logger factory that creates a separate logger instance per connection:

import cdata.sql as mod
import time

class MyLogger:
    def __init__(self, loggerId):
        self.loggerId = loggerId
    def writeLog(self, verbosity, message):
        print("[MyLogger " + self.loggerId + "] " + message)

def createLogger(context):
    return MyLogger(context[len("MyLoggerId="):])

mod.setCustomLoggerFactory(createLogger)

conn1 = mod.connect("...;Logfile=CUSTOM://MyLoggerId=1;Verbosity=2;")
# do something with conn1
time.sleep(1)  # Wait for logs to flush from conn1

conn2 = mod.connect("...;Logfile=CUSTOM://MyLoggerId=2;Verbosity=2;")
# do something with conn2
time.sleep(1)  # Wait for logs to flush from conn2

Creating an Entra ID (Azure AD) Application

Note: Microsoft has rebranded Azure AD as Entra ID. In topics that require the user to interact with the Entra ID Admin site, we use the same names Microsoft does. However, there are still CData connection properties whose names or values reference "Azure AD".

SQL Server supports OAuth-based authentication using Microsoft Entra ID. If you will connect via a web application and want to authenticate via Entra ID, you must first register a custom OAuth application in the Entra Admin Center, as described below.

Registering the Application

To register an OAuth application in Microsoft Entra ID, follow these steps:

1. Go to https://portal.azure.com.
2. In the left-hand navigation pane, select Microsoft Entra ID > App registrations.
3. Click New registration.
4. Enter a name for the application.
5. Specify the types of accounts this application should support:
   • For private-use applications, select Accounts in this organization directory only.
   • For distributed applications, select one of the multi-tenant options.

   Note: If you select Accounts in this organizational directory only, when you connect with CData Python Connector for SQL Server, you must set AzureTenant to the tenant's ID (either GUID or verified domain). Otherwise, authentication will fail.

6. Set Select a platform to Web, and set the redirect URI to http://localhost:33333 (default), or use another URI appropriate for your deployment. When using a custom redirect URI set a CallbackURL connection property; in those cases, set it to match this URI exactly.
7. Click Register. The application management screen opens. Record these values for later use:
   • Application (client) ID is used for OAuthClientId
   • Directory (tenant) ID is used for AzureTenant
8. Go to Certificates & Secrets. Click New Client Secret, set the desired expiration, and save the generated value. This value will only be shown once — record it to use with OAuthClientSecret.

9. To confirm, click Add permissions.

Creating an Entra ID (Azure AD) Application

Note: Microsoft has rebranded Azure AD as Entra ID. In topics that require the user to interact with the Entra ID Admin site, we use the same names Microsoft does. However, there are still CData connection properties whose names or values reference "Azure AD".

SQL Server supports OAuth-based authentication using Microsoft Entra ID. If you will connect via a web application and want to authenticate via Entra ID, you must first register a custom OAuth application in the Entra Admin Center, as described below.

Registering the Application

To register an OAuth application in Microsoft Entra ID, follow these steps:

1. Go to https://portal.azure.com.
2. In the left-hand navigation pane, select Microsoft Entra ID > App registrations.
3. Click New registration.
4. Enter a name for the application.
5. Specify the types of accounts this application should support:
   • For private-use applications, select Accounts in this organization directory only.
   • For distributed applications, select one of the multi-tenant options.

   Note: If you select Accounts in this organizational directory only, when you connect with CData Python Connector for SQL Server, you must set AzureTenant to the tenant's ID (either GUID or verified domain). Otherwise, authentication will fail.

6. Set Select a platform to Web, and set the redirect URI to http://localhost:33333 (default), or use another URI appropriate for your deployment. When using a custom redirect URI set a CallbackURL connection property; in those cases, set it to match this URI exactly.
7. Click Register. The application management screen opens. Record these values for later use:
   • Application (client) ID is used for OAuthClientId
   • Directory (tenant) ID is used for AzureTenant
8. Go to Certificates & Secrets. Click New Client Secret, set the desired expiration, and save the generated value. This value will only be shown once — record it to use with OAuthClientSecret.

9. To confirm, click Add permissions.

General Changes

Date	Version	Source	Category	Type	Description
2026-05-27	26.0.9643	General	Connection	Removed	Removed the deprecated ReplaceInvalidTypesWithNull connection property. Use the ReplaceInvalidValuesWithNull property instead.
2026-05-22	26.0.9638	Python		Removed	Remove support for Intel x64 architecture on macOS
2026-05-13	26.0.9629	SQL Server	Connection	Removed	Removed Auto as a supported value for the AuthScheme connection property.
2026-05-07	26.0.9623	General	Data Model	Added	Added the ColumnCapabilities column to the sys_tablecolumns system table. This column is a bit mask denoting the column's write capabilities.
2026-05-07	26.0.9623	Python		Changed	Updated embedded JRE to jre-17.0.19+10 (Linux x64 / MacOs x64).
2026-04-15	26.0.9601	General	Query Exec	Changed	String comparisons using GREATER, LESS, and CONTAINS operators are now case-insensitive by default.
2026-04-02	26.0.9588	SQL Server	Connection	Removed	The following properties have been removed: AutoCache CacheConnection CacheDriver CacheLocation CacheMetadata CacheProvider CacheSchema CacheTolerance Offline
2026-02-13	25.0.9540	SQL Server		Changed	The NTLM Version connection property now defaults to "2" instead of "1".
2026-01-13	25.0.9509	General		Added	Added support for the REGEXP_REPLACE() string function.
2025-12-21	25.0.9486	Python		Added	Added support for custom loggers in Python connectors on Linux and macOS.
2025-12-05	25.0.9470	General		Added	Added support for the INSERT INTO SELECT statement, with driver-side execution for providers that do not support the operation natively.
2025-11-13	25.0.9448	SQL Server		Added	Added the MultiSubnetFailover and DNSServer connection properties to enable resolving all IP addresses from DNS and attempting connections in sequence.
2025-10-30	25.0.9434	Python		Changed	Updated embedded JRE to jre-17.0.17+10 (Linux x64 / MacOs x64).
2025-10-06	25.0.9410	General		Added	Support for parsing datetime formats using ".S" and ",S" for milliseconds and nanoseconds.
2025-09-12	25.0.9386	General		Added	Added the IsInsertable, IsUpdateable, and IsDeleteable columns to the sys_tables table.
2025-09-10	25.0.9384	General		Changed	All columns in statically defined Views are now reported as read-only.
2025-09-03	25.0.9377	General		Changed	Corrected the behavior when IN criteria with NULL values are used in the projection part. It now returns NULL instead of 0. For example, "NULL IN (1,2)" returns "NULL".
2025-09-01	25.0.9375	General		Added	Added support for using the CAST function with infinity values. This function can cast "inf" and "-inf" to DOUBLE, FLOAT, or REAL.
2025-08-21	25.0.9364	General		Changed	Report behavior change: Fixed inconsistent string value comparisons in non-table queries. For example, "SELECT 'A' = 'a'" previously returned false, but it now returns true.
2025-08-13	25.0.9356	General		Changed	Changed the maximum number of pages held in memory from 15 to 5 for the page providers to decrease heap usage.
2025-07-18	25.0.9330	SQL Server		Removed	Removed the OAuthGrantType property. The grant type is now set implicitly through the 'AuthScheme' property. For example, you can use the 'OAuthPassword' AuthScheme instead of AuthScheme=OAuth with OAuthGrantType=Password.
2025-07-07	25.0.9319	Python		Removed	Removed the 32-bit version of Windows Python.
2025-07-02	25.0.9314	Python		Removed	Removed support for Python 3.9.
2025-06-25	25.0.9307	General		Removed	Removed the "ADLS Gen 1" value from the ConnectionType property.
2025-06-25	25.0.9307	Python		Added	Added support for Python 3.13 in Windows, Linux, and Mac editions.
2025-06-25	25.0.9307	Python		Removed	Removed support for Python 3.8 as it is no longer supported.
2025-06-20	25.0.9302	General		Added	Created the following functions: TEXT_ENCODE: encodes a string into a different charset (UTF8 → UTF7 and returns a binary array as the result). TEXT_DECODE: takes a binary array and decodes it back into a string when provided the charset. BASE64_ENCODE: takes a binary array and encodes it as a base64 string (varchar). BASE64_DECODE: takes a base 64-encoded string and decodes it into a binary array.
2025-06-18	25.0.9300	General		Changed	The internal code for exception handling has been refactored. Exception messages returned during certain error conditions may now have different wording or formatting.
2025-05-27	25.0.9278	General		Removed	Removed the "Proprietary" enum option from ProxyAuthscheme.
2025-05-12	25.0.9263	Python		Changed	Updated embedded JRE to jre-17.0.15+6 (Linux x64 / MacOS x64) and jre-17.0.15+6 (MacOS aarch64).
2025-02-15	24.0.9177	General		Added	Added support for converting unsigned integer types to the nearest signed data type that has enough precision to hold the unsigned value.This is done for JDBC only because it does not have support for unsigned data types.
2024-11-27	24.0.9097	General		Added	Added ThreadId to LogModule output. Logfile lines now include the Thread ID associated with the action being performed.
2024-06-05	24.0.8922	Python		Added	Added support for Python 3.12.
2024-05-09	24.0.8895	General		Changed	The ROUND function previously did not accept negative precision values. That feature has now been restored.
2024-04-24	23.0.8880	SQL Server		Added	Added support for bulkcopy, which can be enabled by setting "BatchMode=BCP".
2024-03-21	23.0.8846	SQL Server		Changed	Support new encryption type "Strict" in the property 'Encrypt', it enforces good security practices and makes SQL Server traffic manageable by standard network appliances.
2024-03-15	23.0.8840	General		Added	Created a new SQL function called STRING_COMPARE that provides java's String.compare() ability to SQL queries. Returns a number representative of the compared value of two strings
2024-01-24	23.0.8789	SQL Server		Added	Added support for synonyms as TableType when retrieving tables metadata.
2023-11-29	23.0.8733	General		Changed	The ROUND function doesn't accept the negative precision values anymore.
2023-11-29	23.0.8733	General		Changed	The returning types of the FDMonth, FDQuarter, FDWeek, LDMonth, LDQuarter, LDWeek functions are changed from Timestamp to Date. The return type of the ABS function will be consistent with the parameter value type.
2023-11-28	23.0.8732	General		Added	Added the HMACSHA256 formatter to allow for secrets to be decoded if it is in base64 format
2023-08-29	23.0.8641	Python		Added	Added support for SQLAlchemy 2.0.
2023-05-26	23.0.8546	SQL Server		Added	Introduced a connection property "IncludeSystemSchemas" to specify whether to query the system schemas, including 'guest' and those whose names start with 'db_'.
2023-05-19	23.0.8539	Python		Added	Added support for Python 3.11 on Windows, Linux and Mac.
2023-05-16	23.0.8536	Python		Removed	Removed support for Python 3.7 on Windows and Linux
2023-04-25	23.0.8515	General		Removed	Removed support for the SELECT INTO CSV statement. The core code doesn't support it anymore.
2022-11-15	22.0.8354	Python		Changed	Updated embedded JRE to jre8u345-b01(Linux x64 / MacOS x64) and jre-17.0.5+8(MacOS aarch64).
2022-07-20	22.0.8236	SQL Server		Added	Introduced a hidden connection property "DateTimeOffsetTypeScheme" to toggle the conversion for MS SQL Server DateTimeOffset type. When setting "DateTimeOffsetTypeScheme=LOCAL", the DateTime object will be based on local time zone.
2022-05-18	22.0.8173	Python		Added	Added support for Python 3.10 on Windows, Linux, and Mac Added support for Python 3.9 on Mac Added support for Mac M1
2022-05-18	22.0.8173	Python		Removed	Removed support for Python 3.6 on Windows and Linux
2022-02-15	21.0.8081	SQL Server		Changed	Encoded database name internally while retrieving schemas. Fixes an issue with retrieving databases with special characters in the name, such as hyphens.
2021-09-02	21.0.7915	General		Added	Added support for the STRING_SPLIT table-valued function in the CROSS APPLY clause.
2021-07-23	21.0.7874	General		Changed	Updated the Literal Function Names for relative date/datetime functions. Previously, relative date/datetime functions resolved to a different value when used in the projection as opposed to the predicate. For example: SELECT LAST_MONTH() AS lm, Col FROM Table WHERE Col > LAST_MONTH(). Formerly, the two LAST_MONTH() methods would resolve to different datetimes. Now, they will match. As a replacement for the previous behavior, the relative date/datetime functions in the criteria may have an 'L' appended to them. For example: WHERE col > L_LAST_MONTH(). This will continue to resolve to the same values that were previously calculated in the criteria. Note that the "L_" prefix will only work in the predicate - it not available for the projection.
2021-07-08	21.0.7859	General		Added	Added the TCP Logging Module for the logging information happening on the TCP wire protocol. The transport bytes that are incoming and ongoing will be logged at verbosity=5.
2021-06-05	21.0.7826	SQL Server		Added	Added support for the AzureServicePrinciple authentication scheme. Added support to authenticate submitting JWT certs instead of the OAuthClientSecret for the AzureServicePrinciple and AzureAD authentication schemes.
2021-04-25	21.0.7785	General		Added	Added support for handling client side formulas during insert / update. For example: UPDATE Table SET Col1 = CONCAT(Col1, " - ", Col2) WHERE Col2 LIKE 'A%'
2021-04-23	21.0.7783	General		Changed	Updated how display sizes are determined for varchar primary key and foreign key columns so they will match the reported length of the column.
2021-04-16	21.0.7776	General		Added	Non-conditional updates between two columns is now available to all drivers. For example: UPDATE Table SET Col1=Col2
2021-04-16	21.0.7776	General		Changed	Reduced the length to 255 for varchar primary key and foreign key columns.
2021-04-16	21.0.7776	General		Changed	Updated index naming convention to avoid duplicates.
2021-04-15	21.0.7775	General		Changed	Kerberos authentication is updated to use TCP by default, but will fall back to UDP if a TCP connection cannot be established.

This section provides a walk-through for writing SQL Server data access code in Python script.

For more information on the available data source entities and how to query them with SQL, see Data Model.

Connecting from Code

For information on how to deploy the connector and configure the connection to SQL Server, see Package Installation and Establishing a Connection.

For information on how to connect with the sql.connector module and its related classes, see Connecting.

Executing SQL

The connection's cursor object is used to directly execute SQL queries. For information on how to execute SELECT statements and process the returned result sets, see Querying Data. For information on to modify the data in SQL Server with INSERT, UPDATE, and DELETE statements, see Modifying Data .

Executing Stored Procedures

You can call stored procedures by using the EXECUTE statement. For further information, see Calling Stored Procedures.

Batch Processing

For information about how to modify several rows of SQL Server data at once using parameterized INSERT, UPDATE, and DELETE statements, see Batch Processing.

Connecting with the cdata.sql Module:

The connector's module is used directly to establish a connection with the data source. It does this by using a connection string as its argument. For example:

import cdata.sql as mod
conn = mod.connect("user=myuser;password=mypassword;Server=localhost;Database=Northwind;")

Once the connection is created, you can use it to execute subsequent SQL queries.

After connecting as described in Connecting, you can use the open connection to execute SQL statements.

Executing Queries

To execute SQL statements that return data, use the execute() method. Once a query is executed, the result set is fetched from the cursor. This result set can then be iterated over to process the records individually.

For example:

cur = conn.execute("SELECT Id, ProductName FROM \"SampleDB\".\"Sample\".Products")
rs = cur.fetchall()
for row in rs:
	print(row)

Parameterized Queries

Various Python collections, such as arrays and tuples, can act as additional arguments for the execute() method. This enables you to parameterize the queries executed and help to prevent SQL Injection.

For example:

cmd = "SELECT Id, ProductName FROM \"SampleDB\".\"Sample\".Products WHERE ProductName = ?"
params = ["Konbu"]
cur = conn.execute(cmd, params)
rs = cur.fetchall()
for row in rs:
	print(row)

The connection is also used to issue INSERT, UPDATE, and DELETE commands to the data source. Parameters can be used with these statements if desired.

Note that the connector does not support transactions. As with normal write operations, all SQL statements executed by this connector affect the data source immediately. Call the connection's commit() method following the execution.

Insert

The following example adds a new record to the table:

cmd = "INSERT INTO \"SampleDB\".\"Sample\".Products (Id, ProductName) VALUES (?, ?)"
params = ["Ikura", "Konbu"]
cur = conn.execute(cmd, params)
print("Records affected: ", cur.rowcount)

Update

The following example modifies an existing record in the table:

cmd = "UPDATE \"SampleDB\".\"Sample\".Products SET ProductName = ? WHERE Id = ?"
params = ["Konbu", "22"]
cur = conn.execute(cmd, params)
print("Records affected: ", cur.rowcount)

Delete

The following example removes an existing record from the table:

cmd = "DELETE FROM \"SampleDB\".\"Sample\".Products WHERE Id = ?"
params = ["22"]
cur = conn.execute(cmd, params)
print("Records affected: ", cur.rowcount)

You can execute stored procedures using either the execute() or callproc() method of the connection.

Calling Stored Procedures Using Execute()

When you call stored procedures by issuing EXECUTE commands, the stored procedure arguments are parameterized. For example:

cmd = "EXECUTE SearchSuppliers Country = ?"
params = ["US"]
conn.execute(cmd, params)

Calling Stored Procedures Using Callproc()

When you call stored procedured by issuing the callproc() method, the stored procedure arguments are a procedure name and a list of parameters. For example:

cur = conn.cursor()
params = ["US"]
cur.callproc("SearchSuppliers", params)

This Python connector also supports writing to the data source via batch processing, using the cursor object's executemany() method. This requires both a SQL statement string and a data frame of values that act as a series of parameters for executing the SQL statement.

Note that the connector does not support transactions. As with normal write operations, all SQL statements executed by this connector affect the data source immediately. Call the connection's commit() method following the execution.

Insert

The following example adds new records to the table:

cur = conn.cursor()
cmd = "INSERT INTO \"SampleDB\".\"Sample\".Products (Id, ProductName) VALUES (?, ?)"
params = [["Ikura", "Konbu"], ["Ikura", "Konbu"]]
cur.executemany(cmd, params)
print("Records affected: ", cur.rowcount)

Update

The following example modifies existing records in the table:

cur = conn.cursor()
cmd = "UPDATE \"SampleDB\".\"Sample\".Products SET ProductName = ? WHERE Id = ?"
params = [["Konbu", "22"], ["Konbu", "22"]]
cur.executemany(cmd, params)
print("Records affected: ", cur.rowcount)

Delete

The following example removes existing records from the table:

cur = conn.cursor()
cmd = "DELETE FROM \"SampleDB\".\"Sample\".Products WHERE Id = ?"
params = [["22"], ["22"]]
cur.executemany(cmd, params)
print("Records affected: ", cur.rowcount)

The connector is integrated with other tools and packages within Python.

Python Integration Guides

The following sections show how to create and use connections with the connector in common packages in Python:

• From SQLAlchemy
• From Pandas
• From Matplotlib
• From Petl

Complete List of SQL Server Integration Quickstarts

For information on connecting from other applications, see SQL Server integration guides.

The CData Python Connector for SQL Server includes a Dialect class that enables integration with SQLAlchemy. Bear in mind that several aspects of connector functionality are not currently supported in SQLAlchemy 2.0 or above. If necessary, downgrade SQLAlchemy to version 1.4 or 1.3 before using this connector.

The following sections detail various aspects of this integration:

Connecting From SQLAlchemy

To construct a URL with which SQLAlchemy loads and uses the appropriate connector automatically, see Connecting

Reflecting Metadata With SQLAlchemy

To learn how to model SQL Server tables with mapped classes, see Reflecting Metadata.

Querying Data From SQLAlchemy

To learn how to use mapped classes to query the associated tables, see Querying Data.

Modifying Data From SQLAlchemy

The connector provides INSERT/UPDATE/DELETE functionality in SQLAlchemy. To learn how to call the session's execute() method to affect the data in the data source, see Modifying Data.

Connecting With a Dialect URL

Establishing a connection using SQLAlchemy requires a specific URL format. For this connector, you can create the engine using either of the following URL formats:

Format 1

from sqlalchemy import create_engine
engine = create_engine("cdata_sql:///?user=myuser;password=mypassword;Server=localhost;Database=Northwind;")

Format 2

from sqlalchemy import create_engine
engine = create_engine("cdata_sql://User:Password@MyServer/Database/")

For SQLAlchemy 2.0, the dialect name is sql_2. To establish a connection, use the following URL format:

from sqlalchemy import create_engine
engine = create_engine("sql_2:///?user=myuser;password=mypassword;Server=localhost;Database=Northwind;")

SQLAlchemy can act as an Object-relational Map (ORM). This enables you to treat records of a database table as instantiable records. To leverage this functionality, you must reflect the underlying metadata in one of the following ways.

Note: The following examples employ SQLAlchemy 1.4.

Modeling Data Using a Mapping Class

Use "sqlalchemy.ext.declarative.declarative_base" to declare a mapping class for the table you wish to model in the ORM. A known table in the data model is modeled either partially or completely, as shown in the following example:

from sqlalchemy.ext.declarative import declarative_base
Base = declarative_base()
class "SampleDB"."Sample".Products(Base):
	__tablename__ = "\"SampleDB\".\"Sample\".Products"
	Id = Column(String, primary_key=True)
	Id = Column(String)
	ProductName = Column(String)

Automatically Reflecting Metadata

Rather than mapping tables manually, SQLAlchemy can discover the metadata for one or more tables automatically. To accomplish this across the entire data model, use automap_base:

from sqlalchemy import MetaData
from sqlalchemy.ext.automap import automap_base
meta = MetaData()
abase = automap_base(metadata=meta)
abase.prepare(autoload_with=engine)
"SampleDB"."Sample".Products = abase.classes."SampleDB"."Sample".Products

You can also reflect a single table with an inspector. When reflecting this way, providing a list of specific columns to map is optional:

from sqlalchemy import MetaData, Table
from sqlalchemy import inspect
meta = MetaData()
insp = inspect(engine)
"SampleDB"."Sample".Products_table = Table("\"SampleDB\".\"Sample\".Products", meta)
insp.reflect_table("SampleDB"."Sample".Products_table, ["Id","ProductName"])

After you use the steps in Connecting to connect, and use one of the methods in Reflecting Metadata to reflect some of the metadata, you can use a session object to query data.

Querying Data Using the Query Method

If the mapping class has been prepared, use it with a session object to query the data source. After binding the engine to the session, provide the mapping class to the session's query method.

For example:

engine = create_engine("cdata_sql:///?user=myuser;password=mypassword;Server=localhost;Database=Northwind;")
factory = sessionmaker(bind=engine)
session = factory()
for instance in session.query("SampleDB"."Sample".Products).filter_by(ProductName="Konbu"):
	print("Id: ", instance.Id)
	print("Id: ", instance.Id)
	print("ProductName: ", instance.ProductName)
	print("---------")

Querying Data Using the Execute Method

The session object can also run the query with the execute() method alongside the appropriate Table object. Assuming you have an active session, the following is just as viable:

"SampleDB"."Sample".Products_table = "SampleDB"."Sample".Products.metadata.tables["\"SampleDB\".\"Sample\".Products"]
for instance in session.execute("SampleDB"."Sample".Products_table.select().where("SampleDB"."Sample".Products_table.c.ProductName == "Konbu")):
	print("Id: ", instance.Id)
	print("FullName: ", instance.Name)
	print("City: ", instance.BillingCity)
	print("---------")

Implicit Joining

If mapped classes of related SQL Server objects have a singular foreign key relationship, the classes are implicitly joined. After importing the necessary objects, a relationship is established between your two mapped classes, as in the example below:

from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy import Column, String, Integer, DateTime, ForeignKey
from sqlalchemy.orm import sessionmaker, relationship

Base = declarative_base()
class Contact(Base):
	__tablename__ = "Contact"
	Id = Column(Integer, primary_key=True)
	Name = Column(String)
	Email = Column(String)
	BirthDate = Column(DateTime)
	AccountId = Column(String, ForeignKey("Account.Id"))
	Account_Link = relationship("Account", back_populates="Contact_Link")

class Account(Base):
	__tablename__ = "Account"
	Id = Column(String, primary_key=True)
	Name = Column(String)
	BillingCity = Column(String)
	NumberOfEmployees = Column(Integer)
	Contact_Link = relationship("Contact", order_by=Contact.Id, back_populates="Account_Link")

Once the relationship is established, the tables are queried simultaneously using the session's query() method. For example:

rs = session.query(Account, Contact).filter(Account.Id == Contact.AccountId)
for Ac, Ct in rs:
  print("AccountId: ", Ac.Id)
  print("AccountName: ", Ac.Name)
  print("ContactId: ", Ct.Id)
  print("ContactName: ", Ct.Name)

Other Join Forms

In situations where mapped classes have either no foreign keys or multiple foreign keys, you may need different forms of the JOIN query to accommodate them. Using the earlier classes as examples, the following JOIN queries are possible as well:

• Explicit condition (necessary if there are no foreign keys in your mapped classes):
  

  rs = session.query(Account, Contact).join(Contact, Account.Id == Contact.AccountId)
  for Ac, Ct in rs:

• Left-to-right relationship:
  

  rs = session.query(Account, Contact).join(Account.Contact_Link)
  for Ac, Ct in rs:

• Left-to-right relationship with explicit target:
  

  rs = session.query(Account, Contact).join(Contact, Account.Contact_Link)
  for Ac, Ct in rs:

• String form of a left-to-right relationship:
  

  rs = session.query(Account, Contact).join("Contact_Link")
  for Ac, Ct in rs:

SQLAlchemy ORM also exposes support for other clauses in SQL, such as ORDER BY, GROUP BY, LIMIT, and OFFSET. All of these are supported by this connector:

ORDER BY

The following example sorts by a specified column using the session object's query() method:

rs = session.query("SampleDB"."Sample".Products).order_by("SampleDB"."Sample".Products.Price)
for instance in rs:
	print("Id: ", instance.Id)
	print("Id: ", instance.Id)
	print("ProductName: ", instance.ProductName)
	print("---------")

You can also use the session object's execute() method perform an ORDER BY. For example:

rs = session.execute("SampleDB"."Sample".Products_table.select().order_by("SampleDB"."Sample".Products_table.c.Price))
for instance in rs:

GROUP BY

The following example uses the session object's query() method to group records with a specified column:

rs = session.query(func.count("SampleDB"."Sample".Products.Id).label("CustomCount"), "SampleDB"."Sample".Products.Id).group_by("SampleDB"."Sample".Products.Id)
for instance in rs:
	print("Count: ", instance.CustomCount)
	print("Id: ", instance.Id)
	print("---------")

You can also use the session object's execute() method to perform a GROUP BY:

rs = session.execute("SampleDB"."Sample".Products_table.select().with_only_columns([func.count("SampleDB"."Sample".Products_table.c.Id).label("CustomCount"), "SampleDB"."Sample".Products_table.c.Id]).group_by("SampleDB"."Sample".Products_table.c.Id))
for instance in rs:

LIMIT and OFFSET

The following example uses the session object's query() method to skip the first 100 records and fetch the following 25:

rs = session.query("SampleDB"."Sample".Products).limit(25).offset(100)
for instance in rs:
	print("Id: ", instance.Id)
	print("Id: ", instance.Id)
	print("ProductName: ", instance.ProductName)
	print("---------")

You can also use the session object's execute() method to set a LIMIT or OFFSET:

rs = session.execute("SampleDB"."Sample".Products_table.select().limit(25).offset(100))
for instance in rs:

Certain aggregate functions can also be used within SQLAlchemy by using the func module.

To import this module, execute:

from sqlalchemy.sql import func

Once func is imported, the following aggregate functions are available:

COUNT

The following example counts the number of records in a set of groups using the session object's query() method.

rs = session.query(func.count("SampleDB"."Sample".Products.Id).label("CustomCount"), "SampleDB"."Sample".Products.Id).group_by("SampleDB"."Sample".Products.Id)
for instance in rs:
	print("Count: ", instance.CustomCount)
	print("Id: ", instance.Id)
	print("---------")

You can also execute COUNT using the session object's execute() method:

rs = session.execute("SampleDB"."Sample".Products_table.select().with_only_columns([func.count("SampleDB"."Sample".Products_table.c.Id).label("CustomCount"), "SampleDB"."Sample".Products_table.c.Id])group_by("SampleDB"."Sample".Products_table.c.Id))
for instance in rs:

SUM

This example calculates the cumulative amount of a numeric column in a set of groups.

rs = session.query(func.sum("SampleDB"."Sample".Products.Price).label("CustomSum"), "SampleDB"."Sample".Products.Id).group_by("SampleDB"."Sample".Products.Id)
for instance in rs:
	print("Sum: ", instance.CustomSum)
	print("Id: ", instance.Id)
	print("---------")

You can also invoke SUM using the session object's execute() method.

rs = session.execute("SampleDB"."Sample".Products_table.select().with_only_columns([func.sum("SampleDB"."Sample".Products_table.c.Price).label("CustomSum"), "SampleDB"."Sample".Products_table.c.Id]).group_by("SampleDB"."Sample".Products_table.c.Id))
for instance in rs:

AVG

This example uses the session object's query() method to calculate the average amount of a numeric column in a set of groups:

rs = session.query(func.avg("SampleDB"."Sample".Products.Price).label("CustomAvg"), "SampleDB"."Sample".Products.Id).group_by("SampleDB"."Sample".Products.Id)
for instance in rs:
	print("Avg: ", instance.CustomAvg)
	print("Id: ", instance.Id)
	print("---------")

You can also use the session object's execute() method to invoke AVG:

rs = session.execute("SampleDB"."Sample".Products_table.select().with_only_columns([func.avg("SampleDB"."Sample".Products_table.c.Price).label("CustomAvg"), "SampleDB"."Sample".Products_table.c.Id]).group_by("SampleDB"."Sample".Products_table.c.Id))
for instance in rs:

MAX and MIN

This example finds the maximum value and minimum value of a numeric column in a set of groups.

rs = session.query(func.max("SampleDB"."Sample".Products.Price).label("CustomMax"), func.min("SampleDB"."Sample".Products.Price).label("CustomMin"), "SampleDB"."Sample".Products.Id).group_by("SampleDB"."Sample".Products.Id)
for instance in rs:
	print("Max: ", instance.CustomMax)
	print("Min: ", instance.CustomMin)
	print("Id: ", instance.Id)
	print("---------")

You can also use the session object's execute() method to invoke MAX and MIN:

rs = session.execute("SampleDB"."Sample".Products_table.select().with_only_columns([func.max("SampleDB"."Sample".Products_table.c.Price).label("CustomMax"), func.min("SampleDB"."Sample".Products_table.c.Price).label("CustomMin"), "SampleDB"."Sample".Products_table.c.Id]).group_by("SampleDB"."Sample".Products_table.c.Id))
for instance in rs:

Commands can be executed individually by the session with a call to "execute()".

Obtaining the Table Object

The query supplied to this method is constructed using the associated Table object of a mapped class. This Table object is obtained from the mapped class's metadata field, as below:

"SampleDB"."Sample".Products_table = "SampleDB"."Sample".Products.metadata.tables["\"SampleDB\".\"Sample\".Products"]

Once the table object is obtained, the write operations are executed in the following ways. The queries are executed immediately without the need for a call to "commit()":

Insert

The following example adds a new record to the table:

session.execute("SampleDB"."Sample".Products_table.insert(), {"Id": "Ikura", "ProductName": "Konbu"})

Update

The following example modifies an existing record in the table:

session.execute("SampleDB"."Sample".Products_table.update().where("SampleDB"."Sample".Products_table.c.Id == "22").values(Id="Ikura", ProductName="Konbu"))

Delete

The following example removes an existing record from the table:

session.execute("SampleDB"."Sample".Products_table.delete().where("SampleDB"."Sample".Products_table.c.Id == "22"))

When combined with the connector, Pandas can be used to generate data frames that contain your SQL Server data. Once created, a data frame can be passed to various other Python packages.

Connecting

Pandas relies on an SQLAlchemy engine to execute queries. Before you can use Pandas you must import it:

import pandas as pd
from sqlalchemy import create_engine
engine = create_engine("cdata_sql:///?user=myuser;password=mypassword;Server=localhost;Database=Northwind;")

Querying Data

In Pandas, SELECT queries are provided in a call to the read_sql() method, alongside a relevant connection object. Pandas executes the query on that connection, and returns the results in the form of a data frame, which can be used for a variety of purposes.

df = pd.read_sql("""
	SELECT
	   Id,
	   ProductName,
     $exNumericCol;
	FROM "SampleDB"."Sample".Products;""", engine)
print(df)

Modifying Data

To insert new records into a table, create a new data frame, and define its fields accordingly. When that is done, call to_sql() on the data frame to perform the INSERT operation with the connector, as shown in the example below. You must set the "if _exists" argument to "append" to prevent Pandas from attempting building the table from scratch. To prevent Pandas from writing the data frame index as a column, set index=False.

df = pd.DataFrame({"Id": ["Ikura"], "ProductName": ["Konbu"]})
df.to_sql("\"SampleDB\".\"Sample\".Products", con=engine, if_exists="append", index=False)

Matplotlib contains a number of tools that can graphically model SQL Server data after being fed a data frame From Pandas.

Using PyPlot

Before any Matplotlib tool, such as pyplot, can be used, it must be imported:

from matplotlib import pyplot as plt

Once a Pandas data frame is obtained, it can be used to create a plot visualizing SQL Server data. For example, the following plot generates and displays a bar graph relating Id and Price values:

df.plot(kind="bar", x="Id", y=["Price"])
plt.show()

The connector can be used to create ETL applications and pipelines for CSV data in Python using Petl.

Install Required Modules

Install the Petl modules using the pip utility.

pip install petl

Connecting

After you import the modules, including the CData Python Connector for SQL Server, you can use the connector's connect function to create a connection using a valid SQL Server connection string. If you prefer not to use a direct connection, you can use a SQLAlchemy engine.

import petl as etl
import cdata.sql as mod
cnxn = mod.connect("user=myuser;password=mypassword;Server=localhost;Database=Northwind;")

Extract, Transform, and Load the SQL Server Data

Create a SQL query string and store the query results in a DataFrame.

sql = "SELECT	Id, ProductName FROM \"SampleDB\".\"Sample\".Products "
table1 = etl.fromdb(cnxn,sql)

Loading Data

With the query results stored in a DataFrame, you can load your data into any supported Petl destination. The following example loads the data into a CSV file.

etl.tocsv(table1,'output.csv')

Modifying Data

Insert new rows into SQL Server tables using Petl's appenddb function.

table1 = [['Id','ProductName'],['Ikura','Konbu']]
etl.appenddb(table1,cnxn,'\"SampleDB\".\"Sample\".Products')

The extension supports schema discovery by using SQL queries to available System Tables.

Using SQL

The following sections describe the discovery of metadata through several System Tables:

• Tables and Views
• Columns
• Procedures

The connector possesses system tables that are used to discover the tables and views available in the data model. Of these system tables, "sys_tables" and "sys_views" are used to fetch information about the available tables and views respectively:

Tables

import cdata.sql as mod
conn = mod.connect("user=myuser;password=mypassword;Server=localhost;Database=Northwind;")
cur = conn.cursor()
cmd = "SELECT * FROM sys_tables"
cur.execute(cmd)
rs = cur.fetchall()
for row in rs:
	print(row)

Views

import cdata.sql as mod
conn = mod.connect("user=myuser;password=mypassword;Server=localhost;Database=Northwind;")
cur = conn.cursor()
cmd = "SELECT * FROM sys_views"
cur.execute(cmd, params)
rs = cur.fetchall()
for row in rs:
	print(row)

The available columns for any given table are fetched from a system table called "sys_tablecolumns". A specific table name is provided in the WHERE criteria to restrict the table from which the column information is fetched:

import cdata.sql as mod
conn = mod.connect("user=myuser;password=mypassword;Server=localhost;Database=Northwind;")
cur = conn.cursor()
cmd = "SELECT * FROM sys_tablecolumns WHERE TableName = '\"SampleDB\".\"Sample\".Products'"
cur.execute(cmd)
rs = cur.fetchall()
for row in rs:
	print(row)

Procedures

A system table called "sys_procedures" is queried to obtain the available stored procedures that are executed:

import cdata.sql as mod
conn = mod.connect("user=myuser;password=mypassword;Server=localhost;Database=Northwind;")
cur = conn.cursor()
cmd = "SELECT * FROM sys_procedures"
cur.execute(cmd)
rs = cur.fetchall()
for row in rs:
	print(row)

Parameters

The input parameters of any stored procedure are similarly obtained from the "sys_procedureparameters" system table:

import cdata.sql as mod
conn = mod.connect("user=myuser;password=mypassword;Server=localhost;Database=Northwind;")
cur = conn.cursor()
cmd = "SELECT * FROM sys_procedureparameters WHERE ProcedureName = 'SearchSuppliers'"
cur.execute(cmd)
rs = cur.fetchall()
for row in rs:
	print(row)

This section details a selection of advanced features of the SQL Server connector.

SSL Configuration

Use SSL Configuration to adjust how connector handles TLS/SSL certificate negotiations. You can choose from various certificate formats;. For further information, see the SSLServerCert property under "Connection String Options" .

Firewall and Proxy

Configure the connector for compliance with Firewall and Proxy, including Windows proxies and HTTP proxies. You can also set up tunnel connections.

Logging

For an overview of configuration settings that can be used to refine CData logging, see Logging. Only two connection properties are required for basic logging, but there are numerous features that support more refined logging, which enables you to use the LogModules connection property to specify subsets of information to be logged.

Exception Handling

For an overview of how exceptions are reported and the components of an exception, see Exception Handling.

Customizing the SSL Configuration

To enable TLS, set Encrypt to True.

With this configuration, the connector attempts to negotiate TLS with the server. The server certificate is validated against the default system trusted certificate store. You can override how the certificate gets validated using the SSLServerCert connection property.

To specify another certificate, see the SSLServerCert connection property.

Client SSL Certificates

The SQL Server connector also supports setting client certificates. Set the following to connect using a client certificate.

• SSLClientCert: The name of the certificate store for the client certificate.
• SSLClientCertType: The type of key store containing the TLS/SSL client certificate.
• SSLClientCertPassword: The password for the TLS/SSL client certificate.
• SSLClientCertSubject: The subject of the TLS/SSL client certificate.

Connecting Through a Firewall or Proxy

HTTP Proxies

Note: The connector uses the system proxy settings by default, without further configuration needed. If you want to connect to other proxies, set ProxyAutoDetect to False and read further.

To authenticate to an HTTP proxy, set the following:

• ProxyServer: the hostname or IP address of the proxy server that you want to route HTTP traffic through.
• ProxyPort: the TCP port that the proxy server is running on.
• ProxyAuthScheme: the authentication method the connector uses when authenticating to the proxy server.
• ProxyUser: the username of a user account registered with the proxy server.
• ProxyPassword: the password associated with the ProxyUser.

Other Proxies

Set the following properties:

• To use a proxy-based firewall, set FirewallType, FirewallServer, and FirewallPort.
• To tunnel the connection, set FirewallType to TUNNEL.
• To authenticate, specify FirewallUser and FirewallPassword.
• To authenticate to a SOCKS proxy, additionally set FirewallType to SOCKS5.

Logging

Capturing connector logging can be very helpful when diagnosing error messages or other unexpected behavior.

Basic Logging

To begin capturing connector logging, set these properties:

• Logfile: A filepath that designates the name and location of the log file.
• Verbosity: A numerical value (1-5) that determines the amount of detail in the log. See the page in the Connection Properties section for an explanation of the five levels.
• MaxLogFileSize: When the limit is hit, a new log is created in the same folder with the date and time appended to the end. The default limit is 100 MB. Values lower than 100 kB will use 100 kB as the value instead.
• MaxLogFileCount: A string specifying the maximum file count of log files. When the limit is hit, a new log is created in the same folder with the date and time appended to the end and the oldest log file will be deleted. Minimum supported value is 2. A value of 0 or a negative value indicates no limit on the count.

Once these properties are set, the connector populates the log file as it carries out various tasks, such as when authentication is performed or queries are executed. If the specified file doesn't already exist, it is created.

Log Verbosity

The verbosity level determines the amount of detail that the connector reports to the Logfile. Supported Verbosity levels range from 1 to 5.

The following list describes each level:

1	Setting Verbosity to 1 logs the query, the number of rows returned by it, the start of execution and the time taken, and any errors.
2	Setting Verbosity to 2 logs everything included in Verbosity 1 and additional information about the request.
3	Setting Verbosity to 3 also logs HTTP headers, as well as the body of the request and the response.
4	Setting Verbosity to 4 also logs transport-level communication with the data source. This includes SSL negotiation.
5	Setting Verbosity to 5 also logs communication with the data source and additional details that may be helpful in troubleshooting problems. This includes interface commands.

For normal operations, Verbosity should not be set to greater than 1. At higher verbosities you can log substantial amounts of data, which can delay execution times.

To refine the logged content further by showing/hiding specific categories of information, see LogModules.

Sensitive Data

Verbosity levels of 3 and higher may capture information that you do not want shared outside of your organization. The following lists information of concern for each level:

• Verbosity 3: The full body of the request and the response, which includes all the data returned by the connector
• Verbosity 4: SSL certificates
• Verbosity 5: Any extra transfer data not included at Verbosity 3, such as non human-readable binary transfer data

Note: Although we mask sensitive values, such as passwords, in the connection string and any request in the log, it is always best practice to review the logs for any sensitive information before sharing outside your organization.

Advanced Logging

You may want to refine the exact information that is recorded to the log file. This can be accomplished using the LogModules property. This property allows you to filter the logging using a semicolon-separated list of logging modules.

Example property value:

LogModules=INFO;EXEC;SSL;SQL;META;

Note that the logfile filtering triggered by the Verbosity connection property takes precedence over the filtering imposed by this connection property. This means that operations of a higher verbosity level than the level specified in the Verbosity connection property are not printed in the logfile, even if they belong to one of the modules specified in this connection property.

The available modules and submodules are:

Module Name	Module Description	Submodules
INFO	General Information. Includes the connection string, product version (build number), and initial connection messages.	Connec – Information related to creating or destroying connections. Messag – Generic label for messages pertaining to connections, the connection string, and product version. These messages are typically specific to the connector, rather than being received and passed along directly from the service.
EXEC	Query Execution. Includes execution messages for user-written SQL queries, parsed SQL queries, and normalized SQL queries. Success/failure messages for queries and query pages appear here as well.	Messag – Messages pertaining to query execution. These messages are typically specific to the connector, rather than being received and passed along directly from the service. Normlz – Query normalization steps. Query normalization is when the product takes the user-submitted query and rewrites the query to get the same results with optimal performance. Origin – This label applies to any messages recording a user's original query (the exact, unaltered, non-normalized query executed by the user). Page – Messages related to query paging. Parsed – Query parsing steps. Parsing is the process of converting the user-submitted query into a standardized format for easier processing.
HTTP	HTTP protocol messages. Includes HTTP requests/responses (including POST messages), as well as Kerberos related messages.	KERB – HTTP requests related to Kerberos. Messag – Messages pertaining to HTTP protocols. These messages are typically specific to the connector, rather than being received and passed along directly from the service. Unpack – This label applies to messages about zipped data being returned from the service API and unpacked by the product. Res – Messages containing HTTP responses. Req – Messages containing HTTP requests.
WSDL	Messages pertaining to the generation of WSDL/XSD files.	—
SSL	SSL certificate messages.	Certif – Messages pertaining to SSL certificates.
AUTH	Authentication related failure/success messages.	Messag – Messages pertaining to authentication. These messages are typically specific to the connector, rather than being received and passed along directly from the service. OAuth – Messages related to OAuth authentication. Krbros – Kerberos-related authentication messages.
SQL	Includes SQL transactions, SQL bulk transfer messages, and SQL result set messages.	Bulk – Messages pertaining to bulk query execution. Cache – Messages related to reading row data from and writing row data to the product's cache for better performance. Messag – Messages pertaining to SQL transactions. These messages are typically specific to the connector, rather than being received and passed along directly from the service. ResSet – Query resultsets. Transc – Messages related to handling transactions, including information about the number of jobs executed and backup table handling.
META	Metadata cache and schema messages.	Cache – Messages related to reading from and modifying column and table definitions in the product's cache for better performance. Schema – Messages related to retrieving metadata from or modifying the service schema. MemSto – Messages related to writing to or reading from in-memory metadata cache. Storag – Messages relating to storing metadata on disk or in an external data store, rather than in memory.
FUNC	Information related to executing SQL functions.	Errmsg – Error messages related to executing SQL functions.
TCP	Incoming and outgoing raw bytes on TCP transport layer messages.	Send – Raw data sent via the TCP protocol. Receiv – Raw data received via the TCP protocol.
FTP	Messages pertaining to the File Transfer Protocol.	Info – Status messages related to communication in the FTP protocol. Client – Messages related to actions taken by the FTP client (the product) during FTP communication. Server – Messages related to actions taken by the FTP server during FTP communication.
SFTP	Messages pertaining to the Secure File Transfer Protocol.	Info – Status messages related to communication in the SFTP protocol. To_Server – Messages related to actions taken by the SFTP client (the product) during SFTP communication. From_Server – Messages related to actions taken by the SFTP server during SFTP communication.
POP	Messages pertaining to data transferred via the Post Office Protocol.	Client – Messages related to actions taken by the POP client (the product) during POP communication. Server – Messages related to actions taken by the POP server during POP communication. Status – Status messages related to communication in the POP protocol.
SMTP	Messages pertaining to data transferred via the Simple Mail Transfer Protocol.	Client – Messages related to actions taken by the SMTP client (the product) during SMTP communication. Server – Messages related to actions taken by the SMTP server during SMTP communication. Status – Status messages related to communication in the SMTP protocol.
CORE	Messages relating to various internal product operations not covered by other modules.	—
DEMN	Messages related to SQL remoting.	—
CLJB	Messages about bulk data uploads (cloud job).	Commit – Submissions for bulk data uploads.
SRCE	Miscellaneous messages produced by the product that don't belong in any other module.	—
TRANCE	Advanced messages concerning low-level product operations.	—

Exception Handling

Exceptions can be surfaced from either the API or the CData Python Connector for SQL Server. Each exception will have an error code, an error message, and a SQL state.

Error Codes

The error code classifies the type of error.

0	NONE	Used for unclassified errors and internally handled errors. This code also covers data source-specific errors that do not fit in any specific category.
65537	TCP_UNKNOWN_HOST	Unable to resolve a hostname (DNS failure).
65538	TCP_CONNECTION_REFUSED	Could not connect to the remote port.
65539	TCP_AUTH_FAILED	Login failed when using a binary authentication protocol. Use this for auth errors when the protocol is not HTTP (LDAP, SASL, Kerberos, ...).
65540	TCP_TIMEOUT	Did not receive a response after sending a request to the server.
65541	TCP_PROTOCOL	For wire protocol drivers. Either the server sent a bad packet that we are unable to process, or we cannot construct a packet to send.
131073	TLS_SERVER_UNTRUSTED	Could not verify SSL server certificate.
131074	TLS_CLIENT_UNTRUSTED	Server did not accept the client certificate we sent.
196609	OAUTH_DECRYPT_FAILED	OAuthEncryptKey did not decrypt the OAuthSettings file.
196610	OAUTH_MISSING_CLIENT_INFO	OAuthClientId / OAuthClientSecret / OAuthJWTCert is missing.
196611	OAUTH_MISSING_PROP	General OAuth property missing. OAUTH_MISSING_CLIENT_INFO is used for missing client ID/secret and JWT cert.
196612	OAUTH_NO_ACCESS_TOKEN	Unable to retrieve access token. Only use this when getting a token in GetOAuthAccessToken / RefreshOAuthAccessToken.
196613	OAUTH_TOKEN_EXPIRED	The access token expired. Normally used with a RefreshOAuth/OAuthException behavior.
196614	OAUTH_INVALID_PROP	OAuth property has an invalid value. OAUTH_MISSING_CLIENT_INFO / OAUTH_MISSING_PROP is used if the value is not set.
262145	HTTP_REQUEST_TIMEOUT	Did not receive a response from the HTTP server.
262146	HTTP_CLIENT_ERROR	Generic HTTP 4xx error. Only use for 4xx errors not covered by other codes.
262147	HTTP_AUTH_FAILED	HTTP 401 error.
262148	HTTP_LIMIT_EXCEEDED	HTTP 429 error.
262149	HTTP_SERVER_ERROR	HTTP 5xx error.
262150	HTTP_NOT_FOUND_ERROR	HTTP 404 error.
327681	CORE_TIMEOUT	General timeout. Not related to a specific network request.
327682	CORE_OP_NOT_ALLOWED	Operation blocked by provider permissions.
327683	CORE_CONNECTION_CONFIG	Connection configuration is not valid.
327684	CORE_SERIALIZE	Failed to encode data into a specific format (XML, JSON, CSV, ...).
327685	CORE_DESERIALIZE	Failed to decode data from a specific format (XML, JSON, CSV, ...).
393217	SQL_SYNTAX_ERROR	Unable to parse a SQL query.
393218	SQL_MISSING_COLUMNS	Query did not include required columns.
393219	SQL_MISSING_PARAMS	Stored procedure call did not include required parameters.
393220	SQL_QUERY_NOT_SUPPORTED	A part of the query is not allowed in the current context.
458753	SSH_SERVER_UNTRUSTED	Could not verify SSH server.
524289	STORAGE_LIST_EXCEPTION	Issue listing storage resources.
524290	STORAGE_RESOURCE_NOT_FOUND	Issue finding storage resources.
524291	STORAGE_ROOT_RESOURCE_NOT_FOUND	The root resource (bucket/share/drive) was not found; cannot create it in flat file drivers.
524292	STORAGE_RESOURCE_NOT_A_DIRECTORY	Storage resource is not a directory.
524293	STORAGE_RESOURCE_NOT_A_FILE	Storage resource is not a file.
524294	STORAGE_PERMISSIONS_DENIED	Storage permissions denied.

SQL State

The SQL state is used when throwing generic provider errors to the wrapper and indicates the success or failure of a call.

Some of the common SQL states are listed below:

07007	REQUIRED_CLAUSE	Class Code 07: Dynamic SQL Error.
08001	OPEN_CONNECTION	Class Code 08: Connection Exception. The connection was unable to be established to the application server or other server.
08004	REJECT_CONNECTION	The application server rejected establishment of the connection.
42501	PRIVILEGE_IDENTIFIED_OBJECT	Class Code 42: Syntax Error or Access Rule Violation. The authorization ID does not have the privilege to perform the specified operation on the identified object.
42506	AUTH_FAILED	Owner authorization failure occurred.
42601	SQL_SYNTAX	A character, token, or clause is invalid or missing.

Error Message

The error message provides more detailed reasoning about why the error occurred. It provides an explanation of the issue, and may include steps on how to resolve it.

In addition to modeling data directly from SQL Server, the CData Python Connector for SQL Server also includes a few built in stored procedures designed for assisting with OAuth connections against Azure hosted SQL Server. The stored procedures are listed here.

Data Type Mappings

The connector maps types from the data source to the corresponding data type available in the schema. The table below documents these mappings.

SQL Server	CData Schema
bigint	long
bigint identity	long
binary	binary
bit	bool
char	string
date	date
datetime	datetime
datetimeoffset	datetime
datetime2	datetime
decimal	decimal
decimal identity	decimal
float	float
geography	binary
geometry	binary
hierarchyid	binary
image	binary
int	int
int identity	int
money	decimal
nchar	string
ntext	string
nvarchar	string
numeric	decimal
numeric identity	decimal
real	float
rowversion	binary
smalldatetime	datetime
smallint	short
smallint identity	short
smallmoney	decimal
sql_variant	binary
table	string
text	string
time	time
timestamp	binary
tinyint	byte
tinyint identity	byte
uniqueidentifier	string
varbinary	binary
varchar	string
xml	string

Stored procedures are function-like interfaces that extend the functionality of the connector beyond simple SELECT/INSERT/UPDATE/DELETE operations with SQL Server.

Stored procedures accept a list of parameters, perform their intended function, and then return any relevant response data from SQL Server, along with an indication of whether the procedure succeeded or failed.

CData Python Connector for SQL Server Stored Procedures

Name	Description
GetOAuthAccessToken	Gets an authentication token from AzureAD.
GetOAuthAuthorizationUrl	Gets an authorization URL from the data source. The authorization URL can be used to generate a verifier required to obtain the OAuth token.
RefreshOAuthAccessToken	Refreshes the OAuth access token used for authentication with AzureDataCatalog.

Gets an authentication token from AzureAD.

Input

Name	Type	Description
AuthMode	String	The allowed values are APP, WEB. The default value is APP.
Verifier	String	A verifier returned by the service that must be input to return the access token. Needed only when using the Web auth mode. Obtained by navigating to the URL returned in GetOAuthAuthorizationUrl.
Scope	String	The default value is https://database.windows.net//.default offline_access.
CallbackUrl	String
State	String	Indicates any state which may be useful to your application upon receipt of the response. Your application receives the same value it sent, as this parameter makes a round-trip to the AzureDataCatalog authorization server and back. Uses include redirecting the user to the correct resource in your site, nonces, and cross-site-request-forgery mitigations.
Prompt	String	Defaults to 'select_account' which prompts the user to select account while authenticating. Set to 'None', for no prompt, 'login' to force user to enter their credentials or 'consent' to trigger the OAuth consent dialog after the user signs in, asking the user to grant permissions to the app.

Result Set Columns

Name	Type	Description
OAuthAccessToken	String	The access token used for communication with Azure AD.
OAuthRefreshToken	String	The OAuth refresh token. This is the same as the access token in the case of Azure AD.
ExpiresIn	String	The remaining lifetime on the access token. A -1 denotes that it will not expire.

Gets an authorization URL from the data source. The authorization URL can be used to generate a verifier required to obtain the OAuth token.

Input

Name	Type	Description
CallbackURL	String	The URL the user will be redirected to after authorizing your application.
Scope	String	The default value is https://database.windows.net//.default.
State	String	This field indicates any state that may be useful to your application upon receipt of the response. Your application receives the same value it sent, as this parameter makes a round-trip to Dynamics authorization server and back. Uses include redirecting the user to the correct resource in your site, using nonces, and mitigating cross-site request forgery.
Prompt	String	Defaults to 'select_account' which prompts the user to select account while authenticating. Set to 'None', for no prompt, 'login' to force user to enter their credentials or 'consent' to trigger the OAuth consent dialog after the user signs in, asking the user to grant permissions to the app.

Result Set Columns

Name	Type	Description
Url	String	The authorization url that will need to be opened for the user to authorize your app.

Refreshes the OAuth access token used for authentication with AzureDataCatalog.

Input

Name	Type	Description
OAuthRefreshToken	String	Set this to the token value that expired.

Result Set Columns

Name	Type	Description
OAuthAccessToken	String	The authentication token returned from AzureDataCatalog. This can be used in subsequent calls to other operations for this particular service.
OAuthRefreshToken	String	This is the same as the access token.
ExpiresIn	String	The remaining lifetime on the access token.

The connection string properties are the various options that can be used to establish a connection. This section provides a complete list of the options you can configure in the connection string for this provider. Click the links for further details.

For more information on establishing a connection, see Establishing a Connection.

Authentication

---

Property	Description
AuthScheme	Specifies the scheme used to authenticate the connection to SQL Server.
Server	Specifies the name or network address of the SQL Server instance to connect to.
Port	Specifies the network port used to connect to the SQL Server instance.
Database	Specifies the name of the SQL Server database to connect to.
User	Specifies the authenticating user's user ID.
Password	Specifies the authenticating user's password.
Domain	Specifies the Windows domain used for NTLM authentication.
IntegratedSecurity	Specifies whether to use Windows Integrated Security instead of SQL Server authentication.
NTLMVersion	Specifies the version of the NTLM protocol to use for Windows authentication.
Encrypt	Specifies whether to enable TLS/SSL encryption for the connection to SQL Server.
DNSServer	Specify the DNS server to resolve the AG Listener's IP address list.

Bulk

---

Property	Description
BatchMode	Specifies the mode used for executing batch operations when inserting data into SQL Server.

Azure Authentication

---

Property	Description
AzureTenant	Identifies the SQL Server tenant being used to access data. Accepts either the tenant's domain name (for example, contoso.onmicrosoft.com ) or its directory (tenant) ID.
AzureEnvironment	Specifies the Azure network environment to which you will connect. Must be the same network to which your Azure account was added.

OAuth

---

Property	Description
InitiateOAuth	Specifies the process for obtaining or refreshing the OAuth access token, which maintains user access while an authenticated, authorized user is working.
OAuthClientId	Specifies the client ID (also known as the consumer key) assigned to your custom OAuth application. This ID is required to identify the application to the OAuth authorization server during authentication.
OAuthClientSecret	Specifies the client secret assigned to your custom OAuth application. This confidential value is used to authenticate the application to the OAuth authorization server. (Custom OAuth applications only.).
OAuthAccessToken	Specifies the OAuth access token used to authenticate requests to the data source. This token is issued by the authorization server after a successful OAuth exchange.
OAuthSettingsLocation	Specifies the location of the settings file where OAuth values are saved.
CallbackURL	Identifies the URL users return to after authenticating to SQL Server via OAuth (Custom OAuth applications only).
Scope	Specifies the scope of the authenticating user's access to the application, to ensure they get appropriate access to data. If a custom OAuth application is needed, this is generally specified at the time the application is created.
OAuthVerifier	Specifies a verifier code returned from the OAuthAuthorizationURL . Used when authenticating to OAuth on a headless server, where a browser can't be launched. Requires both OAuthSettingsLocation and OAuthVerifier to be set.
OAuthRefreshToken	Specifies the OAuth refresh token used to request a new access token after the original has expired.
OAuthExpiresIn	Specifies the duration in seconds, of an OAuth Access Token's lifetime. The token can be reissued to keep access alive as long as the user keeps working.
OAuthTokenTimestamp	Displays a Unix epoch timestamp in milliseconds that shows how long ago the current access token was created.

JWT OAuth

---

Property	Description
OAuthJWTCert	Supplies the name of the client certificate's JWT Certificate store.
OAuthJWTCertType	Identifies the type of key store containing the JWT Certificate.
OAuthJWTCertPassword	Provides the password for the OAuth JWT certificate used to access a password-protected certificate store. If the certificate store does not require a password, leave this property blank.
OAuthJWTCertSubject	Identifies the subject of the OAuth JWT certificate used to locate a matching certificate in the store. Supports partial matches and the wildcard '*' to select the first certificate.

Kerberos

---

Property	Description
KerberosKDC	Identifies the Kerberos Key Distribution Center (KDC) service used to authenticate the user. (SPNEGO or Windows authentication only).
KerberosRealm	Identifies the Kerberos Realm used to authenticate the user.
KerberosSPN	Identifies the service principal name (SPN) for the Kerberos Domain Controller.
KerberosUser	Confirms the principal name for the Kerberos Domain Controller, which uses the format host/user@realm.
KerberosKeytabFile	Identifies the Keytab file containing your pairs of Kerberos principals and encrypted keys.
KerberosServiceRealm	Identifies the service's Kerberos realm. (Cross-realm authentication only).
KerberosServiceKDC	Identifies the service's Kerberos Key Distribution Center (KDC).
KerberosTicketCache	Specifies the full file path to an MIT Kerberos credential cache file.

SSL

---

Property	Description
SSLClientCert	Specifies the TLS/SSL client certificate store for SSL Client Authentication (2-way SSL). This property works in conjunction with other SSL-related properties to establish a secure connection.
SSLClientCertType	Specifies the type of key store containing the TLS/SSL client certificate for SSL Client Authentication. Choose from a variety of key store formats depending on your platform and certificate source.
SSLClientCertPassword	Specifes the password required to access the TLS/SSL client certificate store. Use this property if the selected certificate store type requires a password for access.
SSLClientCertSubject	Specifes the subject of the TLS/SSL client certificate to locate it in the certificate store. Use a comma-separated list of distinguished name fields, such as CN=www.server.com, C=US. The wildcard * selects the first certificate in the store.
SSLServerCert	Specifies the certificate to be accepted from the server when connecting using TLS/SSL.

SSH

---

Property	Description
SSHAuthMode	The authentication method used when establishing an SSH Tunnel to the service.
SSHClientCert	A certificate to be used for authenticating the SSHUser.
SSHClientCertPassword	The password of the SSHClientCert key if it has one.
SSHClientCertSubject	The subject of the SSH client certificate.
SSHClientCertType	The type of SSHClientCert private key.
SSHServer	The SSH server.
SSHPort	The SSH port.
SSHUser	The SSH user.
SSHPassword	The SSH password.
SSHServerFingerprint	The SSH server fingerprint.
UseSSH	Whether to tunnel the SQL Server connection over SSH. Use SSH.

Firewall

---

Property	Description
FirewallType	Specifies the protocol the provider uses to tunnel traffic through a proxy-based firewall.
FirewallServer	Identifies the IP address, DNS name, or host name of a proxy used to traverse a firewall and relay user queries to network resources.
FirewallPort	Specifies the TCP port to be used for a proxy-based firewall.
FirewallUser	Identifies the user ID of the account authenticating to a proxy-based firewall.
FirewallPassword	Specifies the password of the user account authenticating to a proxy-based firewall.

Proxy

---

Property	Description
ProxyAutoDetect	Specifies whether the provider checks your system proxy settings for existing proxy server configurations, rather than using a manually specified proxy server.
ProxyServer	Identifies the hostname or IP address of the proxy server through which you want to route HTTP traffic.
ProxyPort	Identifies the TCP port on your specified proxy server that has been reserved for routing HTTP traffic to and from the client.
ProxyAuthScheme	Specifies the authentication method the provider uses when authenticating to the proxy server specified in the ProxyServer connection property.
ProxyUser	Provides the username of a user account registered with the proxy server specified in the ProxyServer connection property.
ProxyPassword	Specifies the password of the user specified in the ProxyUser connection property.
ProxySSLType	Specifies the SSL type to use when connecting to the proxy server specified in the ProxyServer connection property.
ProxyExceptions	Specifies a semicolon-separated list of destination hostnames or IPs that are exempt from connecting through the proxy server set in the ProxyServer connection property.

Logging

---

Property	Description
Logfile	Specifies the file path to the log file where the provider records its activities, such as authentication, query execution, and connection details.
Verbosity	Specifies the verbosity level of the log file, which controls the amount of detail logged. Supported values range from 1 to 5.
LogModules	Specifies the core modules to include in the log file. Use a semicolon-separated list of module names. By default, all modules are logged.
MaxLogFileSize	Specifies the maximum size of a single log file in bytes. For example, '10 MB'. When the file reaches the limit, the provider creates a new log file with the date and time appended to the name.
MaxLogFileCount	Specifies the maximum number of log files the provider retains. When the limit is reached, the oldest log file is deleted to make space for a new one.

Schema

---

Property	Description
Location	Specifies the location of a directory containing schema files that define tables, views, and stored procedures. Depending on your service's requirements, this may be expressed as either an absolute path or a relative path.
BrowsableSchemas	Optional setting that restricts the schemas reported to a subset of all available schemas. For example, BrowsableSchemas=SchemaA,SchemaB,SchemaC .
Tables	Optional setting that restricts the tables reported to a subset of all available tables. For example, Tables=TableA,TableB,TableC .
Views	Optional setting that restricts the views reported to a subset of the available tables. For example, Views=ViewA,ViewB,ViewC .

Miscellaneous

---

Property	Description
ApplicationIntent	Specifies whether the application intends to access a read-only or read-write version of an availability group database.
ApplicationName	Specifies the name of the client application connecting to SQL Server.
IncludeSystemSchemas	Specifies whether to include system schemas such as guest, sys, INFORMATION_SCHEMA, and schemas prefixed with db_ during schema discovery.
IncludeTableTypes	Specifies whether to query SQL Server for the object types of individual tables and views.
MaxRows	Specifies the maximum number of rows returned for queries that do not include either aggregation or GROUP BY.
MultiSubnetFailover	Enable the MultiSubnetFailover property to resolve the AG Listener's DNS name when connecting to a multi-subnet Always On availability group.
Other	Specifies advanced connection properties for specialized scenarios. Use this property only under the guidance of our Support team to address specific issues.
QueryPassthrough	This option passes the query to the SQL Server server as is.
Readonly	Toggles read-only access to SQL Server from the provider.
RTK	Specifies the runtime key for licensing the provider. If unset or invalid, the provider defaults to the standard licensing method. This property is only required in environments where the standard licensing method is unsupported or requires a runtime key.
Timeout	Specifies the number of seconds the provider waits before timing out an operation.

This section provides a complete list of the Authentication properties you can configure in the connection string for this provider.

---

Property	Description
AuthScheme	Specifies the scheme used to authenticate the connection to SQL Server.
Server	Specifies the name or network address of the SQL Server instance to connect to.
Port	Specifies the network port used to connect to the SQL Server instance.
Database	Specifies the name of the SQL Server database to connect to.
User	Specifies the authenticating user's user ID.
Password	Specifies the authenticating user's password.
Domain	Specifies the Windows domain used for NTLM authentication.
IntegratedSecurity	Specifies whether to use Windows Integrated Security instead of SQL Server authentication.
NTLMVersion	Specifies the version of the NTLM protocol to use for Windows authentication.
Encrypt	Specifies whether to enable TLS/SSL encryption for the connection to SQL Server.
DNSServer	Specify the DNS server to resolve the AG Listener's IP address list.

Specifies the scheme used to authenticate the connection to SQL Server.

Possible Values

Password, NTLM, Kerberos, AzurePassword, AzureAD, AzureMSI, AzureServicePrincipal, AzureServicePrincipalCert, AKSWorkloadI

Data Type

string

Default Value

"Password"

Remarks

This property determines how the driver authenticates with SQL Server. It must be used in combination with the User and Password properties, except when using methods that rely on identity-based authentication, such as AzureMSI.

Authentication schemes control which credentials or tokens are expected and how they're validated by the server.

The following values are supported:

• Password: Set this to use your SQL Server Password.
• NTLM: Set this to use NTLM authentication.
• Kerberos: Set this to use Kerberos authentication.
• AzurePassword: Set this to use Azure Active Directory Password authentication.
• AzureAD: Set this to use Azure Active Directory OAuth authentication.
• AzureMSI: Set this to use Azure Active Directory Managed Service Identity authentication.
• AzureServicePrincipal: Set this to authenticate as an Azure Service Principal.
• AzureServicePrincipalCert: Set this to authenticate as an Azure Service Principal using a certificate.
• AKSWorkloadI: Set this to use Workload Identity Federation authentication.

Additional Information

Some authentication schemes, such as AzureMSI or AzureServicePrincipalCert, may require additional properties (such as OAuthClientId and OAuthClientSecret). See individual property descriptions for details.

Specifies the name or network address of the SQL Server instance to connect to.

Data Type

string

Default Value

""

Remarks

This property identifies the location of the SQL Server you want to connect to. You can provide a hostname, IP address, or fully qualified domain name (FQDN). If connecting to a named instance, you can use the server\instance format. For example: sqlhost\sqlexpress.

If the server is hosted in the cloud or behind a load balancer, use the appropriate address or endpoint provided by your database administrator or hosting provider.

If connecting to a local instance, you can use localhost, 127.0.0.1, or . (dot). If you're unsure of the server name, you can find it in SQL Server Management Studio under the Connect to Server dialog.

Specifies the network port used to connect to the SQL Server instance.

Data Type

string

Default Value

"1433"

Remarks

This property identifies the TCP port that the SQL Server instance is listening on. The default SQL Server port is 1433, which is used in most standard installations.

If your SQL Server is configured to use a non-default port (for example, in a custom or cloud-hosted setup), you must set this property to the appropriate value. The Port must match the configuration of the Server and Database properties to successfully establish a connection.

Note: If the server is configured for dynamic ports, you may need to obtain the correct port number from your database administrator or SQL Server Configuration Manager.

Specifies the name of the SQL Server database to connect to.

Data Type

string

Default Value

""

Remarks

This property defines the specific SQL Server database the connector should connect to on the target server. SQL Server instances can host multiple databases, and specifying the correct one is required to access the intended data.

The database must exist on the SQL Server instance specified in the Server property. If this property is not set, the connection may fail or default to a system database such as master, depending on server settings and permissions.

This property is useful for targeting the appropriate database in multi-database environments.

Use myDatabaseName in your connection string to connect to a specific database.

Note: Make sure the user credentials supplied have the appropriate permissions to access the specified database.

Specifies the authenticating user's user ID.

Data Type

string

Default Value

""

Remarks

The authenticating server requires both User and Password to validate the user's identity.

Specifies the authenticating user's password.

Data Type

string

Default Value

""

Remarks

The authenticating server requires both User and Password to validate the user's identity.

Specifies the Windows domain used for NTLM authentication.

Data Type

string

Default Value

""

Remarks

This property is used when authenticating to SQL Server with NTLM (Windows) authentication. It specifies the domain name associated with the user account.

In NTLM authentication, a domain is a logical grouping of computers and user accounts managed under the same Windows security policies. This property helps the provider validate credentials in the correct domain context.

This property is useful when connecting to a SQL Server instance that requires Windows domain credentials.

If left blank, the connector may attempt to authenticate using the local machine domain.

Note: This property is only applicable when AuthScheme is set to NTLM. It is not used with other authentication methods such as Password, Kerberos, or AzureAD.

Specifies whether to use Windows Integrated Security instead of SQL Server authentication.

Data Type

bool

Default Value

false

Remarks

When this property is set to true, the connector uses the current Windows user identity to authenticate with SQL Server. This is commonly referred to as Windows authentication and is typically used in domain environments or when SQL Server is configured for integrated logins.

When set to false, the connector uses SQL Server authentication, which requires explicit User and Password values in the connection.

This property is only applicable when AuthScheme is set to NTLM.

This property is useful in corporate or on-premises environments where SQL Server is configured for domain-based authentication and user credentials are managed through Active Directory.

Set this property to true to avoid passing explicit credentials and rely on the Windows account context of the running application.

Note: Ensure your SQL Server instance is configured to support Windows authentication when using this property.

Specifies the version of the NTLM protocol to use for Windows authentication.

Possible Values

1, 2

Data Type

string

Default Value

"2"

Remarks

This property determines which version of the NTLM (NT LAN Manager) protocol is used when AuthScheme is set to NTLM. NTLM is a Microsoft authentication protocol commonly used for domain-based and Windows Integrated Security scenarios.

Accepted values:

• 1: Uses NTLMv1, which is an older version and less secure.
• 2: Uses NTLMv2 which is more secure and recommended when supported.

NTLMv2 offers stronger encryption and improved security features. However, some legacy systems may only support NTLMv1.

This property is useful when connecting to environments with specific security requirements or compatibility constraints.

Set NTLMVersion=2 to enable more secure authentication, unless you're working with a system that explicitly requires NTLMv1.

This property is only applicable when AuthScheme is set to NTLM. Ensure the SQL Server and network infrastructure support the selected version of NTLM.

Specifies whether to enable TLS/SSL encryption for the connection to SQL Server.

Possible Values

True, False, Strict

Data Type

string

Default Value

"False"

Remarks

This property controls whether the provider uses TLS/SSL encryption when establishing a connection with SQL Server. Encryption protects data in transit and helps meet compliance or security requirements.

Accepted values:

• False: Disables TLS/SSL encryption.
• True: Enables TLS/SSL encryption. The connector attempts to verify the server's certificate using the system's trusted certificate store.
• Strict: Enables TLS/SSL encryption and enforces stricter security standards. This mode requires that the server's certificate be fully validated and uses stronger protocols that are more compatible with modern network appliances and security policies.

If encryption is enabled and you need to specify a custom trusted certificate, use the SSLServerCert property.

This property is useful for securing database traffic between the client and SQL Server.

Specify the DNS server to resolve the AG Listener's IP address list.

Data Type

string

Default Value

""

Remarks

Specify the DNS server to resolve the AG Listener's IP address list.

This section provides a complete list of the Bulk properties you can configure in the connection string for this provider.

---

Property	Description
BatchMode	Specifies the mode used for executing batch operations when inserting data into SQL Server.

Specifies the mode used for executing batch operations when inserting data into SQL Server.

Possible Values

BCP, STANDARD

Data Type

string

Default Value

"STANDARD"

Remarks

This property controls how the connector performs bulk inserts into SQL Server.

It supports two modes:

• STANDARD: Uses standard SQL INSERT, UPDATE, and DELETE statements for batch operations. This mode provides broad compatibility and supports full SQL functionality.
• BCP: Uses SQL Server’s native BulkCopy (BCP) protocol to transfer data directly through a lower-level TCP connection. This method supports only INSERT operations and can offer improved performance for large data loads.

The BCP mode is limited to inserting data and does not support updates or deletes. Additionally, some environments may have firewall or network rules that restrict the lower-level communication BCP requires.

This property is useful for controlling the performance and behavior of bulk data operations. Use BCP when performance is critical and only insert operations are needed. Use STANDARD for broader SQL support, including updates and deletes.

Additional Information

BCP mode may require additional server configuration to allow TCP-level bulk transfers. Ensure that firewall settings and SQL Server permissions support BCP access if you choose this mode.

This section provides a complete list of the Azure Authentication properties you can configure in the connection string for this provider.

---

Property	Description
AzureTenant	Identifies the SQL Server tenant being used to access data. Accepts either the tenant's domain name (for example, contoso.onmicrosoft.com ) or its directory (tenant) ID.
AzureEnvironment	Specifies the Azure network environment to which you will connect. Must be the same network to which your Azure account was added.

Identifies the SQL Server tenant being used to access data. Accepts either the tenant's domain name (for example, contoso.onmicrosoft.com ) or its directory (tenant) ID.

Data Type

string

Default Value

""

Remarks

A tenant is a digital container for your organization's users and resources, managed through Microsoft Entra ID (formerly Azure AD). Each tenant is associated with a unique directory ID, and often with a custom domain (for example, microsoft.com or contoso.onmicrosoft.com).

To find the directory (tenant) ID in the Microsoft Entra Admin Center, navigate to Microsoft Entra ID > Properties and copy the value labeled "Directory (tenant) ID".

This property is required in the following cases:

• When AuthScheme is set to AzureServicePrincipal or AzureServicePrincipalCert
• When AuthScheme is AzureAD and the user account belongs to multiple tenants

You can provide the tenant value in one of two formats:

• A domain name (for example, contoso.onmicrosoft.com)
• A directory (tenant) ID in GUID format (for example, c9d7b8e4-1234-4f90-bc1a-2a28e0f9e9e0)

Specifying the tenant explicitly ensures that the authentication request is routed to the correct directory, which is especially important when a user belongs to multiple tenants or when using service principal–based authentication.

If this value is omitted when required, authentication may fail or connect to the wrong tenant. This can result in errors such as unauthorized or resource not found.

Specifies the Azure network environment to which you will connect. Must be the same network to which your Azure account was added.

Possible Values

GLOBAL, CHINA, USGOVT, USGOVTDOD

Data Type

string

Default Value

"GLOBAL"

Remarks

Required if your Azure account is part of a different network than the Global network, such as China, USGOVT, or USGOVTDOD.

This section provides a complete list of the OAuth properties you can configure in the connection string for this provider.

---

Property	Description
InitiateOAuth	Specifies the process for obtaining or refreshing the OAuth access token, which maintains user access while an authenticated, authorized user is working.
OAuthClientId	Specifies the client ID (also known as the consumer key) assigned to your custom OAuth application. This ID is required to identify the application to the OAuth authorization server during authentication.
OAuthClientSecret	Specifies the client secret assigned to your custom OAuth application. This confidential value is used to authenticate the application to the OAuth authorization server. (Custom OAuth applications only.).
OAuthAccessToken	Specifies the OAuth access token used to authenticate requests to the data source. This token is issued by the authorization server after a successful OAuth exchange.
OAuthSettingsLocation	Specifies the location of the settings file where OAuth values are saved.
CallbackURL	Identifies the URL users return to after authenticating to SQL Server via OAuth (Custom OAuth applications only).
Scope	Specifies the scope of the authenticating user's access to the application, to ensure they get appropriate access to data. If a custom OAuth application is needed, this is generally specified at the time the application is created.
OAuthVerifier	Specifies a verifier code returned from the OAuthAuthorizationURL . Used when authenticating to OAuth on a headless server, where a browser can't be launched. Requires both OAuthSettingsLocation and OAuthVerifier to be set.
OAuthRefreshToken	Specifies the OAuth refresh token used to request a new access token after the original has expired.
OAuthExpiresIn	Specifies the duration in seconds, of an OAuth Access Token's lifetime. The token can be reissued to keep access alive as long as the user keeps working.
OAuthTokenTimestamp	Displays a Unix epoch timestamp in milliseconds that shows how long ago the current access token was created.

Specifies the process for obtaining or refreshing the OAuth access token, which maintains user access while an authenticated, authorized user is working.

Possible Values

OFF, REFRESH, GETANDREFRESH

Data Type

string

Default Value

"OFF"

Remarks

OAuth is an authorization framework that enables applications to obtain limited access to user accounts on an HTTP service. The OAuth flow defines the method to be used for:

• Logging in users.
• Exchanging user credentials for an OAuth access token to be used for authentication.
• Providing limited access to applications.

The options for initiating and maintaining OAuth access are named for the parts of that flow that the connector handles:

OFF	The connector provides no automatic OAuth flow initiation. The OAuth flow is handled entirely by the user. This means that the user must refresh the token manually, and reconnect with an updated OAuthAccessToken property when the current token expires.
GETANDREFRESH	The connector handles the entire OAuth flow (both GET and REFRESH). This means that if a token already exists, the connector refreshes it when necessary; if no token currently exists, the connector obtains it by prompting the user to login.
REFRESH	The user obtains the OAuth Access Token and sets up the sequence for refreshing the OAuth Access Token. (The user is never prompted to log in to authenticate.) After the user logs in, the connector handles the refresh of the OAuth Access Token.

For more information on how to set up OAuth and use this property when configuring a connection, see Establishing a Connection.

Specifies the client ID (also known as the consumer key) assigned to your custom OAuth application. This ID is required to identify the application to the OAuth authorization server during authentication.

Data Type

string

Default Value

""

Remarks

This property is required in two cases:

• When using a custom OAuth application, such as in web-based authentication flows, service-based authentication, or certificate-based flows that require application registration.
• If the driver does not provide embedded OAuth credentials.

(When the driver provides embedded OAuth credentials, this value may already be provided by the connector and thus not require manual entry.)

OAuthClientId is generally used alongside other OAuth-related properties such as OAuthClientSecret and OAuthSettingsLocation when configuring an authenticated connection.

OAuthClientId is one of the key connection parameters that need to be set before users can authenticate via OAuth. You can usually find this value in your identity provider’s application registration settings. Look for a field labeled Client ID, Application ID, or Consumer Key.

While the client ID is not considered a confidential value like a client secret, it is still part of your application's identity and should be handled carefully. Avoid exposing it in public repositories or shared configuration files.

For more information on how this property is used when configuring a connection, see Establishing a Connection.

Specifies the client secret assigned to your custom OAuth application. This confidential value is used to authenticate the application to the OAuth authorization server. (Custom OAuth applications only.).

Data Type

string

Default Value

""

Remarks

This property (sometimes called the application secret or consumer secret) is required when using a custom OAuth application in any flow that requires secure client authentication, such as web-based OAuth, service-based connections, or certificate-based authorization flows. It is not required when using an embedded OAuth application.

The client secret is used during the token exchange step of the OAuth flow, when the driver requests an access token from the authorization server. If this value is missing or incorrect, authentication fails with either an invalid_client or an unauthorized_client error.

OAuthClientSecret is one of the key connection parameters that need to be set before users can authenticate via OAuth. You can obtain this value from your identity provider when registering the OAuth application.

Notes:

• This value should be stored securely and never exposed in public repositories, scripts, or unsecured environments.
• Client secrets may also expire after a set period. Be sure to monitor expiration dates and rotate secrets as needed to maintain uninterrupted access.

For more information on how this property is used when configuring a connection, see Establishing a Connection

Specifies the OAuth access token used to authenticate requests to the data source. This token is issued by the authorization server after a successful OAuth exchange.

Data Type

string

Default Value

""

Remarks

OAuthAccessToken is a temporary credential that authorizes access to protected resources. It is typically returned by the identity provider after the user or client application completes an OAuth authentication flow. This property is most commonly used in automated workflows or custom OAuth implementations where you want to manage token handling outside of the driver.

The OAuth access token has a server-dependent timeout, limiting user access. The timeout is set using the OAuthExpiresIn property. However, it can be reissued between requests to keep access alive as long as the user keeps working.

If InitiateOAuth is set to REFRESH, we recommend that you also set both OAuthExpiresIn and OAuthTokenTimestamp. The connector uses these properties to determine when the token expires so it can refresh most efficiently. If OAuthExpiresIn and OAuthTokenTimestamp are not specified, the connector refreshes the token immediately.

Note: Access tokens should be treated as sensitive credentials and stored securely. Avoid exposing them in logs, scripts, or configuration files that are not access-controlled.

For more information on how this property is used when configuring a connection, see Establishing a Connection.

Specifies the location of the settings file where OAuth values are saved.

Data Type

string

Default Value

"%APPDATA%\\CData\\SQL Data Provider\\OAuthSettings.txt"

Remarks

Storing OAuth settings in a central location avoids the need for users to enter OAuth connection properties manually each time they log in. It also enables credentials to be shared across connections or processes.

You can store OAuth values in a central file for shared access to those values, in either of the following ways:

• Set InitiateOAuth to either GETANDREFRESH or REFRESH and specify a filepath to the OAuth settings file.
• Use memory storage to load the credentials into static memory.

The following sections provide more detail on each of these methods.

Specifying the OAuthSettingsLocation Filepath

The default OAuth setting location is %APPDATA%\\CData\\SQL Data Provider\\OAuthSettings.txt, with %APPDATA% set to the user's configuration directory. Default values vary, depending on the user's operating system.

• Windows (ODBC and Power BI): registry://%DSN%
• Windows: %APPDATA%CDataSQL Data Provider\OAuthSettings.txt
• Mac: %APPDATA%/CData/SQL Data Provider/OAuthSettings.txt
• Linux: %APPDATA%/CData/SQL Data Provider/OAuthSettings.txt

Loading Credentials Via Memory Storage

Memory locations are specified by using a value starting with memory://, followed by a unique identifier for that set of credentials (for example, memory://user1). The identifier can be anything you choose, but it should be unique to the user.

Unlike file-based storage, where credentials persist across connections, memory storage loads the credentials into static memory and the credentials are shared between connections using the same identifier for the life of the process. To persist credentials outside the current process, you must manually store the credentials prior to closing the connection. This enables you to set them in the connection when the process is started again.

To retrieve OAuth property values, query the sys_connection_props system table. If there are multiple connections using the same credentials, the properties are read from the previously closed connection.

Supported Storage Types

• memory://: Stores OAuth tokens in-memory (unique identifier, shared within same process, etc.)
• registry://: Only supported in the Windows ODBC and Power BI editions. Stores OAuth tokens in the registry under the DSN settings. Must end in a DSN name like registry://CData Python Connector for SQL Server Data Source, or registry://%DSN%.
• %DSN%: The name of the DSN you are connecting with.
• Default (no prefix): Stores OAuth tokens within files. The value can be either an absolute path, or a path starting with %APPDATA% or %PROGRAMFILES%.

For more information on how this property is used when configuring a connection, see Establishing a Connection.

Identifies the URL users return to after authenticating to SQL Server via OAuth (Custom OAuth applications only).

Data Type

string

Default Value

""

Remarks

If you created a custom OAuth application, the OAuth authorization server redirects the user to this URL during the authentication process. This value must match the callback URL you specified when you configured the custom OAuth application.

Specifies the scope of the authenticating user's access to the application, to ensure they get appropriate access to data. If a custom OAuth application is needed, this is generally specified at the time the application is created.

Data Type

string

Default Value

""

Remarks

Scopes are set to define what kind of access the authenticating user will have; for example, read, read and write, restricted access to sensitive information. System administrators can use scopes to selectively enable access by functionality or security clearance.

When InitiateOAuth is set to GETANDREFRESH, you must use this property if you want to change which scopes are requested.

When InitiateOAuth is set to either REFRESH or OFF, you can change which scopes are requested using either this property or the Scope input.

Specifies a verifier code returned from the OAuthAuthorizationURL . Used when authenticating to OAuth on a headless server, where a browser can't be launched. Requires both OAuthSettingsLocation and OAuthVerifier to be set.

Data Type

string

Default Value

""

Remarks

For detailed instructions about how to obtain the OAuthVerifier value, see Establishing a Connection.

Specifies the OAuth refresh token used to request a new access token after the original has expired.

Data Type

string

Default Value

""

Remarks

The refresh token is used to obtain a new access token when the current one expires. It enables seamless authentication for long-running or automated workflows without requiring the user to log in again. This property is especially important in headless, CI/CD, or server-based environments where interactive authentication is not possible.

The refresh token is typically obtained during the initial OAuth exchange by calling the GetOAuthAccessToken stored procedure. After that, it can be set using this property to enable automatic token refresh, or passed to the RefreshOAuthAccessTokenproc; stored procedure if you prefer to manage the refresh manually.

When InitiateOAuth is set to REFRESH, the driver uses this token to retrieve a new access token automatically. After the first refresh, the driver saves updated tokens in the location defined by OAuthSettingsLocation, and uses those values for subsequent connections.

Note: The OAuthRefreshToken should be handled securely and stored in a trusted location. Like access tokens, refresh tokens can expire or be revoked depending on the identity provider’s policies.

For more information on how this property is used when configuring a connection, see Establishing a Connection.

Specifies the duration in seconds, of an OAuth Access Token's lifetime. The token can be reissued to keep access alive as long as the user keeps working.

Data Type

string

Default Value

""

Remarks

The OAuth Access Token is assigned to an authenticated user, granting that user access to the network for a specified period of time. The access token is used in place of the user's login ID and password, which stay on the server.

An access token created by the server is only valid for a limited time. OAuthExpiresIn is the number of seconds the token is valid from when it was created. For example, a token generated at 2024-01-29 20:00:00 UTC that expires at 2024-01-29 21:00:00 UTC (an hour later) would have an OAuthExpiresIn value of 3600, no matter what the current time is.

To determine how long the user has before the Access Token will expire, check OAuthTokenTimestamp.

Displays a Unix epoch timestamp in milliseconds that shows how long ago the current access token was created.

Data Type

string

Default Value

""

Remarks

The OAuth access token is assigned to an authenticated user, granting that user access to the network for a specified period of time. The access token is used in place of the user's login ID and password, which stay on the server.

An access token created by the server is only valid for a limited time. OAuthTokenTimestamp is the Unix timestamp when the server created the token. For example, OAuthTokenTimestamp=1706558400 indicates the OAuthAccessToken was generated by the server at 2024-01-29 20:00:00 UTC.

This section provides a complete list of the JWT OAuth properties you can configure in the connection string for this provider.

---

Property	Description
OAuthJWTCert	Supplies the name of the client certificate's JWT Certificate store.
OAuthJWTCertType	Identifies the type of key store containing the JWT Certificate.
OAuthJWTCertPassword	Provides the password for the OAuth JWT certificate used to access a password-protected certificate store. If the certificate store does not require a password, leave this property blank.
OAuthJWTCertSubject	Identifies the subject of the OAuth JWT certificate used to locate a matching certificate in the store. Supports partial matches and the wildcard '*' to select the first certificate.

Supplies the name of the client certificate's JWT Certificate store.

Data Type

string

Default Value

""

Remarks

The OAuthJWTCertType field specifies the type of the certificate store specified in OAuthJWTCert. If the store is password-protected, use OAuthJWTCertPassword to supply the password..

OAuthJWTCert is used in conjunction with the OAuthJWTCertSubject field in order to specify client certificates. If OAuthJWTCert has a value, and OAuthJWTCertSubject is set, the CData Python Connector for SQL Server initiates a search for a certificate. For further information, see OAuthJWTCertSubject.

Designations of certificate stores are platform-dependent.

Notes

• The most common User and Machine certificate stores in Windows include:
  • MY: A certificate store holding personal certificates with their associated private keys.
  • CA: Certifying authority certificates.
  • ROOT: Root certificates.
  • SPC: Software publisher certificates.
• In Java, the certificate store normally is a file containing certificates and optional private keys.
• When the certificate store type is PFXFile, this property must be set to the name of the file.
• When the type is PFXBlob, the property must be set to the binary contents of a PFX file (i.e. PKCS12 certificate store).

Identifies the type of key store containing the JWT Certificate.

Possible Values

USER, MACHINE, PFXFILE, PFXBLOB, JKSFILE, JKSBLOB, PEMKEY_FILE, PEMKEY_BLOB, PUBLIC_KEY_FILE, PUBLIC_KEY_BLOB, SSHPUBLIC_KEY_FILE, SSHPUBLIC_KEY_BLOB, P7BFILE, PPKFILE, XMLFILE, XMLBLOB, BCFKSFILE, BCFKSBLOB

Data Type

string

Default Value

"USER"

Remarks

Value	Description	Notes
USER	A certificate store owned by the current user.	Only available in Windows.
MACHINE	A machine store.	Not available in Java or other non-Windows environments.
PFXFILE	A PFX (PKCS12) file containing certificates.
PFXBLOB	A string (base-64-encoded) representing a certificate store in PFX (PKCS12) format.
JKSFILE	A Java key store (JKS) file containing certificates.	Only available in Java.
JKSBLOB	A string (base-64-encoded) representing a certificate store in Java key store (JKS) format.	Only available in Java.
PEMKEY_FILE	A PEM-encoded file that contains a private key and an optional certificate.
PEMKEY_BLOB	A string (base64-encoded) that contains a private key and an optional certificate.
PUBLIC_KEY_FILE	A file that contains a PEM- or DER-encoded public key certificate.
PUBLIC_KEY_BLOB	A string (base-64-encoded) that contains a PEM- or DER-encoded public key certificate.
SSHPUBLIC_KEY_FILE	A file that contains an SSH-style public key.
SSHPUBLIC_KEY_BLOB	A string (base-64-encoded) that contains an SSH-style public key.
P7BFILE	A PKCS7 file containing certificates.
PPKFILE	A file that contains a PPK (PuTTY Private Key).
XMLFILE	A file that contains a certificate in XML format.
XMLBLOB	Astring that contains a certificate in XML format.
BCFKSFILE	A file that contains an Bouncy Castle keystore.
BCFKSBLOB	A string (base-64-encoded) that contains a Bouncy Castle keystore.

Provides the password for the OAuth JWT certificate used to access a password-protected certificate store. If the certificate store does not require a password, leave this property blank.

Data Type

string

Default Value

""

Remarks

This property specifies the password needed to open a password-protected certificate store. To determine if a password is necessary, refer to the documentation or configuration for your specific certificate store.

Identifies the subject of the OAuth JWT certificate used to locate a matching certificate in the store. Supports partial matches and the wildcard '*' to select the first certificate.

Data Type

string

Default Value

"*"

Remarks

The value of this property is used to locate a matching certificate in the store. The search process works as follows:

• If an exact match for the subject is found, the corresponding certificate is selected.
• If no exact match is found, the store is searched for certificates whose subjects contain the property value.
• If no match is found, no certificate is selected.

You can set the value to '*' to automatically select the first certificate in the store. The certificate subject is a comma-separated list of distinguished name fields and values. For example: CN=www.server.com, OU=test, C=US, E=support@cdata.com.

Common fields include:

Field	Meaning
CN	Common Name. This is commonly a host name like www.server.com.
O	Organization
OU	Organizational Unit
L	Locality
S	State
C	Country
E	Email Address

If a field value contains a comma, enclose it in quotes. For example: "O=ACME, Inc.".

This section provides a complete list of the Kerberos properties you can configure in the connection string for this provider.

---

Property	Description
KerberosKDC	Identifies the Kerberos Key Distribution Center (KDC) service used to authenticate the user. (SPNEGO or Windows authentication only).
KerberosRealm	Identifies the Kerberos Realm used to authenticate the user.
KerberosSPN	Identifies the service principal name (SPN) for the Kerberos Domain Controller.
KerberosUser	Confirms the principal name for the Kerberos Domain Controller, which uses the format host/user@realm.
KerberosKeytabFile	Identifies the Keytab file containing your pairs of Kerberos principals and encrypted keys.
KerberosServiceRealm	Identifies the service's Kerberos realm. (Cross-realm authentication only).
KerberosServiceKDC	Identifies the service's Kerberos Key Distribution Center (KDC).
KerberosTicketCache	Specifies the full file path to an MIT Kerberos credential cache file.

Identifies the Kerberos Key Distribution Center (KDC) service used to authenticate the user. (SPNEGO or Windows authentication only).

Data Type

string

Default Value

""

Remarks

The Kerberos properties are used when using SPNEGO or Windows Authentication. The connector requests session tickets and temporary session keys from the Kerberos KDC service, which is usually co-located with the domain controller.

If KerberosKDC is not specified, the connector tries to detect these properties automatically from the following locations:

• KRB5 Config File (krb5.ini/krb5.conf): If the KRB5_CONFIG environment variable is set and the file exists, the connector obtains the KDC from the specified file. If it is not found there, the connector tries to read from the default MIT location based on the OS: C:\ProgramData\MIT\Kerberos5\krb5.ini (Windows) or /etc/krb5.conf (Linux).
• Domain Name and Host: If the Kerberos Realm and Kerberos KDC cannot be inferred from another location, the connector infers them from the configured domain name and host.

Identifies the Kerberos Realm used to authenticate the user.

Data Type

string

Default Value

""

Remarks

A realm is a logical network, similar to a domain, that defines a group of systems under the same master KDC. Some realms are hierarchical, where one realm is a superset of the other realm, but usually realms are nonhierarchical (or “direct”) and the mapping between the two realms must be defined. Kerberos cross-realm authentication enables authentication across realms. Each realm only needs to have a principal entry for the other realm in its KDC.

The Kerberos properties are used when using SPNEGO or Windows Authentication. The connector requests session tickets and temporary session keys from the Kerberos KDC service, which is usually co-located with the domain controller. The Kerberos Realm can be configured by an administrator to be any string, but it is usually based on the domain name.

If Kerberos Realm is not specified, the connector will attempt to detect these properties automatically from the following locations:

• KRB5 Config File (krb5.ini/krb5.conf): If the KRB5_CONFIG environment variable is set and the file exists, the connector will obtain the default realm from the specified file. Otherwise, it will attempt to read from the default MIT location based on the OS: C:\ProgramData\MIT\Kerberos5\krb5.ini (Windows) or /etc/krb5.conf (Linux)
• Domain Name and Host: If the Kerberos Realm and Kerberos KDC could not be inferred from another location, the connector will infer them from the user-configured domain name and host. This might work in some Windows environments.

Identifies the service principal name (SPN) for the Kerberos Domain Controller.

Data Type

string

Default Value

""

Remarks

If the SPN on the Kerberos Domain Controller is not the same as the URL that you are authenticating to, use this property to set the SPN to the KDC's URL.

Confirms the principal name for the Kerberos Domain Controller, which uses the format host/user@realm.

Data Type

string

Default Value

""

Remarks

If there is a Kerberos principal, that Kerberos principal name should always be used to authenticate to the database.

Identifies the Keytab file containing your pairs of Kerberos principals and encrypted keys.

Data Type

string

Default Value

""

Remarks

A keytab (short for “key table”) stores long-term keys for one or more principals. In most cases, end users authenticate to the KDC using their client secret (password). However, in situations where authentication or re-authentication happen using automated scripts and applications, it may be more efficient to use a keytab, which sends passwords to the KDC in encrypted form, automatically.

Keytabs are normally represented by files in a standard format, and named using the format type:value. Usually type is FILE and value is the absolute pathname of the file. The other possible value for type is MEMORY, which indicates a temporary keytab stored in the memory of the current process.

A keytab contains one or more entries, where each entry consists of a timestamp (indicating when the entry was written to the keytab), a principal name, a key version number, an encryption type, and the encryption key itself. They can be generated using kutil.

For example:

[admin@myhost]# ktutil

ktutil: addent -password -p starlord/myhost.galaxy.com@GALAXY.COM -k 1 -e aes256-cts-hmac-sha1-96
Password for starlord/myhost.galaxy.com:

ktutil: addent -password -p starlord/myhost.galaxy.com@GALAXY.COM -k 1 -e aes128-cts-hmac-sha1-96
Password for starlord/myhost.galaxy.com:

ktutil: addent -password -p starlord/myhost.galaxy.com@GALAXY.COM -k 1 -e des3-cbc-sha1
Password for starlord/myhost.galaxy.com:

ktutil: wkt /path/to/starlord.keytab

Note: You must create principals for all authentication methods (encryption types) you want to support.

To display a keytab, use klist -k.

Identifies the service's Kerberos realm. (Cross-realm authentication only).

Data Type

string

Default Value

""

Remarks

The KerberosServiceRealm is used to specify a service's KerberosRealm when using cross-realm Kerberos authentication.

In most cases, a single realm and KDC machine are used to perform the Kerberos authentication, which means that this property would not be required. However, the property is available for complex setups where a different realm and KDC machine are used to obtain an authentication ticket (AS request) and a service ticket (TGS request).

Identifies the service's Kerberos Key Distribution Center (KDC).

Data Type

string

Default Value

""

Remarks

The KerberosServiceKDC is used to specify the service Kerberos KDC when using cross-realm Kerberos authentication.

In most cases, a single realm and KDC machine are used to perform the Kerberos authentication, which means that this property would not be required. However, the property is available for complex setups where a different realm and KDC machine are used to obtain an authentication ticket (AS request) and a service ticket (TGS request).

Specifies the full file path to an MIT Kerberos credential cache file.

Data Type

string

Default Value

""

Remarks

Set this property if you want to use a credential cache file that was created using the MIT Kerberos Ticket Manager or kinit command.

This section provides a complete list of the SSL properties you can configure in the connection string for this provider.

---

Property	Description
SSLClientCert	Specifies the TLS/SSL client certificate store for SSL Client Authentication (2-way SSL). This property works in conjunction with other SSL-related properties to establish a secure connection.
SSLClientCertType	Specifies the type of key store containing the TLS/SSL client certificate for SSL Client Authentication. Choose from a variety of key store formats depending on your platform and certificate source.
SSLClientCertPassword	Specifes the password required to access the TLS/SSL client certificate store. Use this property if the selected certificate store type requires a password for access.
SSLClientCertSubject	Specifes the subject of the TLS/SSL client certificate to locate it in the certificate store. Use a comma-separated list of distinguished name fields, such as CN=www.server.com, C=US. The wildcard * selects the first certificate in the store.
SSLServerCert	Specifies the certificate to be accepted from the server when connecting using TLS/SSL.

Specifies the TLS/SSL client certificate store for SSL Client Authentication (2-way SSL). This property works in conjunction with other SSL-related properties to establish a secure connection.

Data Type

string

Default Value

""

Remarks

This property specifies the client certificate store for SSL Client Authentication. Use this property alongside SSLClientCertType, which defines the type of the certificate store, and SSLClientCertPassword, which specifies the password for password-protected stores. When SSLClientCert is set and SSLClientCertSubject is configured, the driver searches for a certificate matching the specified subject.

Certificate store designations vary by platform. On Windows, certificate stores are identified by names such as MY (personal certificates), while in Java, the certificate store is typically a file containing certificates and optional private keys.

The following are designations of the most common User and Machine certificate stores in Windows:

MY	A certificate store holding personal certificates with their associated private keys.
CA	Certifying authority certificates.
ROOT	Root certificates.
SPC	Software publisher certificates.

For PFXFile types, set this property to the filename. For PFXBlob types, set this property to the binary contents of the file in PKCS12 format.

Specifies the type of key store containing the TLS/SSL client certificate for SSL Client Authentication. Choose from a variety of key store formats depending on your platform and certificate source.

Possible Values

USER, MACHINE, PFXFILE, PFXBLOB, JKSFILE, JKSBLOB, PEMKEY_FILE, PEMKEY_BLOB, PUBLIC_KEY_FILE, PUBLIC_KEY_BLOB, SSHPUBLIC_KEY_FILE, SSHPUBLIC_KEY_BLOB, P7BFILE, PPKFILE, XMLFILE, XMLBLOB, BCFKSFILE, BCFKSBLOB

Data Type

string

Default Value

"USER"

Remarks

This property determines the format and location of the key store used to provide the client certificate. Supported values include platform-specific and universal key store formats. The available values and their usage are:

USER - default	For Windows, this specifies that the certificate store is a certificate store owned by the current user. Note that this store type is not available in Java.
MACHINE	For Windows, this specifies that the certificate store is a machine store. Note that this store type is not available in Java.
PFXFILE	The certificate store is the name of a PFX (PKCS12) file containing certificates.
PFXBLOB	The certificate store is a string (base-64-encoded) representing a certificate store in PFX (PKCS12) format.
JKSFILE	The certificate store is the name of a Java key store (JKS) file containing certificates. Note that this store type is only available in Java.
JKSBLOB	The certificate store is a string (base-64-encoded) representing a certificate store in JKS format. Note that this store type is only available in Java.
PEMKEY_FILE	The certificate store is the name of a PEM-encoded file that contains a private key and an optional certificate.
PEMKEY_BLOB	The certificate store is a string (base64-encoded) that contains a private key and an optional certificate.
PUBLIC_KEY_FILE	The certificate store is the name of a file that contains a PEM- or DER-encoded public key certificate.
PUBLIC_KEY_BLOB	The certificate store is a string (base-64-encoded) that contains a PEM- or DER-encoded public key certificate.
SSHPUBLIC_KEY_FILE	The certificate store is the name of a file that contains an SSH-style public key.
SSHPUBLIC_KEY_BLOB	The certificate store is a string (base-64-encoded) that contains an SSH-style public key.
P7BFILE	The certificate store is the name of a PKCS7 file containing certificates.
PPKFILE	The certificate store is the name of a file that contains a PuTTY Private Key (PPK).
XMLFILE	The certificate store is the name of a file that contains a certificate in XML format.
XMLBLOB	The certificate store is a string that contains a certificate in XML format.
BCFKSFILE	The certificate store is the name of a file that contains an Bouncy Castle keystore.
BCFKSBLOB	The certificate store is a string (base-64-encoded) that contains a Bouncy Castle keystore.

Specifes the password required to access the TLS/SSL client certificate store. Use this property if the selected certificate store type requires a password for access.

Data Type

string

Default Value

""

Remarks

This property provides the password needed to open a password-protected certificate store. This property is necessary when using certificate stores that require a password for decryption, as is often recommended for PFX or JKS type stores.

If the certificate store type does not require a password, for example USER or MACHINE on Windows, this property can be left blank. Ensure that the password matches the one associated with the specified certificate store to avoid authentication errors.

Specifes the subject of the TLS/SSL client certificate to locate it in the certificate store. Use a comma-separated list of distinguished name fields, such as CN=www.server.com, C=US. The wildcard * selects the first certificate in the store.

Data Type

string

Default Value

"*"

Remarks

This property determines which client certificate to load based on its subject. The connector searches for a certificate that exactly matches the specified subject. If no exact match is found, the connector looks for certificates containing the value of the subject. If no match is found, no certificate is selected.

The subject should follow the standard format of a comma-separated list of distinguished name fields and values. For example, CN=www.server.com, OU=Test, C=US. Common fields include the following:

Field	Meaning
CN	Common Name. This is commonly a host name like www.server.com.
O	Organization
OU	Organizational Unit
L	Locality
S	State
C	Country
E	Email Address

Note: If any field contains special characters, such as commas, the value must be quoted. For example: CN="Example, Inc.", C=US.

Specifies the certificate to be accepted from the server when connecting using TLS/SSL.

Data Type

string

Default Value

""

Remarks

If you are using a TLS/SSL connection, use this property to specify the TLS/SSL certificate to be accepted from the server. If you specify a value for this property, all other certificates that are not trusted by the machine are rejected.

This property can take the following forms:

Description	Example
A full PEM Certificate (example shortened for brevity)	-----BEGIN CERTIFICATE----- MIIChTCCAe4CAQAwDQYJKoZIhv......Qw== -----END CERTIFICATE-----
A path to a local file containing the certificate	C:\cert.cer
The public key (example shortened for brevity)	-----BEGIN RSA PUBLIC KEY----- MIGfMA0GCSq......AQAB -----END RSA PUBLIC KEY-----
The MD5 Thumbprint (hex values can also be either space- or colon-separated)	ecadbdda5a1529c58a1e9e09828d70e4
The SHA1 Thumbprint (hex values can also be either space- or colon-separated)	34a929226ae0819f2ec14b4a3d904f801cbb150d

Note: It is possible to use '*' to signify that all certificates should be accepted, but due to security concerns this is not recommended.

This section provides a complete list of the SSH properties you can configure in the connection string for this provider.

---

Property	Description
SSHAuthMode	The authentication method used when establishing an SSH Tunnel to the service.
SSHClientCert	A certificate to be used for authenticating the SSHUser.
SSHClientCertPassword	The password of the SSHClientCert key if it has one.
SSHClientCertSubject	The subject of the SSH client certificate.
SSHClientCertType	The type of SSHClientCert private key.
SSHServer	The SSH server.
SSHPort	The SSH port.
SSHUser	The SSH user.
SSHPassword	The SSH password.
SSHServerFingerprint	The SSH server fingerprint.
UseSSH	Whether to tunnel the SQL Server connection over SSH. Use SSH.

The authentication method used when establishing an SSH Tunnel to the service.

Possible Values

None, Password, Public_Key

Data Type

string

Default Value

"Password"

Remarks

• None: No authentication is performed. The current SSHUser value is ignored, and the connection is logged in as anonymous.
• Password: The connector uses the values of SSHUser and SSHPassword to authenticate the user.
• Public_Key: The connector uses the values of SSHUser and SSHClientCert to authenticate the user. SSHClientCert must have a private key available for this authentication method to succeed.

A certificate to be used for authenticating the SSHUser.

Data Type

string

Default Value

""

Remarks

SSHClientCert must contain a valid private key in order to use public key authentication. A public key is optional, if one is not included then the connector generates it from the private key. The connector sends the public key to the server and the connection is allowed if the user has authorized the public key.

The SSHClientCertType field specifies the type of the key store specified by SSHClientCert. If the store is password protected, specify the password in SSHClientCertPassword.

Some types of key stores are containers which may include multiple keys. By default the connector will select the first key in the store, but you can specify a specific key using SSHClientCertSubject.

The password of the SSHClientCert key if it has one.

Data Type

string

Default Value

""

Remarks

This property is required for SSH tunneling when using certificate-based authentication. If the SSH certificate is in a password-protected key store, provide the password using this property to access the certificate.

The subject of the SSH client certificate.

Data Type

string

Default Value

"*"

Remarks

When loading a certificate the subject is used to locate the certificate in the store.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks the first certificate in the certificate store.

The certificate subject is a comma separated list of distinguished name fields and values. For instance "CN=www.server.com, OU=test, C=US, E=support@cdata.com". Common fields and their meanings are displayed below.

Field	Meaning
CN	Common Name. This is commonly a host name like www.server.com.
O	Organization
OU	Organizational Unit
L	Locality
S	State
C	Country
E	Email Address

If a field value contains a comma it must be quoted.

The type of SSHClientCert private key.

Possible Values

USER, MACHINE, PFXFILE, PFXBLOB, JKSFILE, JKSBLOB, PEMKEY_FILE, PEMKEY_BLOB, PPKFILE, PPKBLOB, XMLFILE, XMLBLOB

Data Type

string

Default Value

"PEMKEY_FILE"

Remarks

This property can take one of the following values:

Types	Description	Allowed Blob Values
MACHINE/USER		Blob values are not supported.
JKSFILE/JKSBLOB		base64-only
PFXFILE/PFXBLOB	A PKCS12-format (.pfx) file. Must contain both a certificate and a private key.	base64-only
PEMKEY_FILE/PEMKEY_BLOB	A PEM-format file. Must contain an RSA, DSA, or OPENSSH private key. Can optionally contain a certificate matching the private key.	base64 or plain text.
PPKFILE/PPKBLOB	A PuTTY-format private key created using the puttygen tool.	base64-only
XMLFILE/XMLBLOB	An XML key in the format generated by the .NET RSA class: RSA.ToXmlString(true).	base64 or plain text.

The SSH server.

Data Type

string

Default Value

""

Remarks

The SSH server.

The SSH port.

Data Type

string

Default Value

"22"

Remarks

The SSH port.

The SSH user.

Data Type

string

Default Value

""

Remarks

The SSH user.

The SSH password.

Data Type

string

Default Value

""

Remarks

The SSH password.

The SSH server fingerprint.

Data Type

string

Default Value

""

Remarks

The SSH server fingerprint.

Whether to tunnel the SQL Server connection over SSH. Use SSH.

Data Type

bool

Default Value

false

Remarks

By default the connector will attempt to connect directly to SQL Server. When this option is enabled, the connector will instead establish an SSH connection with the SSHServer and tunnel the connection to SQL Server through it.

This section provides a complete list of the Firewall properties you can configure in the connection string for this provider.

---

Property	Description
FirewallType	Specifies the protocol the provider uses to tunnel traffic through a proxy-based firewall.
FirewallServer	Identifies the IP address, DNS name, or host name of a proxy used to traverse a firewall and relay user queries to network resources.
FirewallPort	Specifies the TCP port to be used for a proxy-based firewall.
FirewallUser	Identifies the user ID of the account authenticating to a proxy-based firewall.
FirewallPassword	Specifies the password of the user account authenticating to a proxy-based firewall.

Specifies the protocol the provider uses to tunnel traffic through a proxy-based firewall.

Possible Values

NONE, TUNNEL, SOCKS4, SOCKS5

Data Type

string

Default Value

"NONE"

Remarks

A proxy-based firewall (or proxy firewall) is a network security device that acts as an intermediary between user requests and the resources they access. The proxy accepts the request of an authenticated user, tunnels through the firewall, and transmits the request to the appropriate server.

Because the proxy evaluates and transfers data backets on behalf of the requesting users, the users never connect directly with the servers, only with the proxy.

Note: By default, the connector connects to the system proxy. To disable this behavior and connect to one of the following proxy types, set ProxyAutoDetect to false.

The following table provides port number information for each of the supported protocols.

Protocol	Default Port	Description
TUNNEL	80	The port where the connector opens a connection to SQL Server. Traffic flows back and forth via the proxy at this location.
SOCKS4	1080	The port where the connector opens a connection to SQL Server. SOCKS 4 then passes theFirewallUser value to the proxy, which determines whether the connection request should be granted.
SOCKS5	1080	The port where the connector sends data to SQL Server. If the SOCKS 5 proxy requires authentication, set FirewallUser and FirewallPassword to credentials the proxy recognizes.

To connect to HTTP proxies, use ProxyServer and ProxyPort. To authenticate to HTTP proxies, use ProxyAuthScheme, ProxyUser, and ProxyPassword.

Identifies the IP address, DNS name, or host name of a proxy used to traverse a firewall and relay user queries to network resources.

Data Type

string

Default Value

""

Remarks

A proxy-based firewall (or proxy firewall) is a network security device that acts as an intermediary between user requests and the resources they access. The proxy accepts the request of an authenticated user, tunnels through the firewall, and transmits the request to the appropriate server.

Because the proxy evaluates and transfers data backets on behalf of the requesting users, the users never connect directly with the servers, only with the proxy.

Specifies the TCP port to be used for a proxy-based firewall.

Data Type

int

Default Value

0

Remarks

A proxy-based firewall (or proxy firewall) is a network security device that acts as an intermediary between user requests and the resources they access. The proxy accepts the request of an authenticated user, tunnels through the firewall, and transmits the request to the appropriate server.

Because the proxy evaluates and transfers data backets on behalf of the requesting users, the users never connect directly with the servers, only with the proxy.

Identifies the user ID of the account authenticating to a proxy-based firewall.

Data Type

string

Default Value

""

Remarks

A proxy-based firewall (or proxy firewall) is a network security device that acts as an intermediary between user requests and the resources they access. The proxy accepts the request of an authenticated user, tunnels through the firewall, and transmits the request to the appropriate server.

Because the proxy evaluates and transfers data backets on behalf of the requesting users, the users never connect directly with the servers, only with the proxy.

Specifies the password of the user account authenticating to a proxy-based firewall.

Data Type

string

Default Value

""

Remarks

A proxy-based firewall (or proxy firewall) is a network security device that acts as an intermediary between user requests and the resources they access. The proxy accepts the request of an authenticated user, tunnels through the firewall, and transmits the request to the appropriate server.

Because the proxy evaluates and transfers data backets on behalf of the requesting users, the users never connect directly with the servers, only with the proxy.

This section provides a complete list of the Proxy properties you can configure in the connection string for this provider.

---

Property	Description
ProxyAutoDetect	Specifies whether the provider checks your system proxy settings for existing proxy server configurations, rather than using a manually specified proxy server.
ProxyServer	Identifies the hostname or IP address of the proxy server through which you want to route HTTP traffic.
ProxyPort	Identifies the TCP port on your specified proxy server that has been reserved for routing HTTP traffic to and from the client.
ProxyAuthScheme	Specifies the authentication method the provider uses when authenticating to the proxy server specified in the ProxyServer connection property.
ProxyUser	Provides the username of a user account registered with the proxy server specified in the ProxyServer connection property.
ProxyPassword	Specifies the password of the user specified in the ProxyUser connection property.
ProxySSLType	Specifies the SSL type to use when connecting to the proxy server specified in the ProxyServer connection property.
ProxyExceptions	Specifies a semicolon-separated list of destination hostnames or IPs that are exempt from connecting through the proxy server set in the ProxyServer connection property.

Specifies whether the provider checks your system proxy settings for existing proxy server configurations, rather than using a manually specified proxy server.

Data Type

bool

Default Value

true

Remarks

When this connection property is set to True, the connector checks your system proxy settings for existing proxy server configurations (no need to manually supply proxy server details).

This connection property takes precedence over other proxy settings. If you want to configure the connector to connect to a specific proxy server, set ProxyAutoDetect to False.

On Windows, the connector reads the proxy settings from the Internet Options in the registry, specifically the registry key HKCU\SOFTWARE\Microsoft\Windows\CurrentVersion\Internet Settings\. On Windows 10 and later, this corresponds to the Proxy Settings found in the Windows Settings.

Note that these settings apply only to the current user of the machine. If you're running an application as a service, the connector does not read your own user's settings. You must instead manually supply the proxy settings in the connector's connection properties.

On Mac, the connector reads proxy settings from the system-configured CFNetwork settings.

On Linux, this property is unsupported, and is set to False by default.

To connect to an HTTP proxy, see ProxyServer. For other proxies, such as SOCKS or tunneling, see FirewallType.

Identifies the hostname or IP address of the proxy server through which you want to route HTTP traffic.

Data Type

string

Default Value

""

Remarks

The connector only routes HTTP traffic through the proxy server specified in this connection property when ProxyAutoDetect is set to False.

If ProxyAutoDetect is set to True (the default), the connector instead routes HTTP traffic through the proxy server specified in your system proxy settings.

Identifies the TCP port on your specified proxy server that has been reserved for routing HTTP traffic to and from the client.

Data Type

int

Default Value

80

Remarks

The connector only routes HTTP traffic through the ProxyServer port specified in this connection property when ProxyAutoDetect is set to False.

If ProxyAutoDetect is set to True (the default), the connector instead routes HTTP traffic through the proxy server port specified in your system proxy settings.

For other proxy types, see FirewallType.

Specifies the authentication method the provider uses when authenticating to the proxy server specified in the ProxyServer connection property.

Possible Values

BASIC, DIGEST, NONE, NEGOTIATE, NTLM

Data Type

string

Default Value

"BASIC"

Remarks

Note: The connector only uses this ProxyAuthScheme when ProxyAutoDetect is set to False. If ProxyAutoDetect is set to True (the default), the connector instead uses the authentication method specified in your system proxy settings.

Supported authentication types :

• BASIC: The connector performs HTTP basic authentication.
• DIGEST: The connector performs HTTP digest authentication.
• NTLM: The connector retrieves an NTLM token.
• NEGOTIATE: The connector retrieves an NTLM or Kerberos token based on the applicable protocol for authentication.
• NONE: Signifies that the ProxyServer does not require authentication.

For all values other than NONE, you must also set the ProxyUser and ProxyPassword connection properties.

If you need to use another authentication type, such as SOCKS 5 authentication, see FirewallType.

Provides the username of a user account registered with the proxy server specified in the ProxyServer connection property.

Data Type

string

Default Value

""

Remarks

The ProxyUser and ProxyPassword connection properties are used to connect and authenticate against the HTTP proxy specified in ProxyServer.

After selecting one of the available authentication types in ProxyAuthScheme, set this property as follows:

ProxyAuthScheme Value	Value to set for ProxyUser
BASIC	The username of a user registered with the proxy server.
DIGEST	The username of a user registered with the proxy server.
NEGOTIATE	The username of a Windows user who is a valid user in the domain or trusted domain that the proxy server is part of, in the format user@domain or domain\user.
NTLM	The username of a Windows user who is a valid user in the domain or trusted domain that the proxy server is part of, in the format user@domain or domain\user.
NONE	Do not set the ProxyPassword connection property.

Note: The connector only uses this username if ProxyAutoDetect is set to False. If ProxyAutoDetect is set to True (the default), the connector instead uses the username specified in your system proxy settings.

Specifies the password of the user specified in the ProxyUser connection property.

Data Type

string

Default Value

""

Remarks

The ProxyUser and ProxyPassword connection properties are used to connect and authenticate against the HTTP proxy specified in ProxyServer.

After selecting one of the available authentication types in ProxyAuthScheme, set this property as follows:

ProxyAuthScheme Value	Value to set for ProxyPassword
BASIC	The password associated with the proxy server user specified in ProxyUser.
DIGEST	The password associated with the proxy server user specified in ProxyUser.
NEGOTIATE	The password associated with the Windows user account specified in ProxyUser.
NTLM	The password associated with the Windows user account specified in ProxyUser.
NONE	Do not set the ProxyPassword connection property.

For SOCKS 5 authentication or tunneling, see FirewallType.

Note: The connector only uses this password if ProxyAutoDetect is set to False. If ProxyAutoDetect is set to True (the default), the connector instead uses the password specified in your system proxy settings.

Specifies the SSL type to use when connecting to the proxy server specified in the ProxyServer connection property.

Possible Values

AUTO, ALWAYS, NEVER, TUNNEL

Data Type

string

Default Value

"AUTO"

Remarks

This property determines when to use SSL for the connection to the HTTP proxy specified by ProxyServer. You can set this connection property to the following values :

AUTO	Default setting. If ProxyServer is set to an HTTPS URL, the connector uses the TUNNEL option. If ProxyServer is set to an HTTP URL, the component uses the NEVER option.
ALWAYS	The connection is always SSL enabled.
NEVER	The connection is not SSL enabled.
TUNNEL	The connection is made through a tunneling proxy. The proxy server opens a connection to the remote host and traffic flows back and forth through the proxy.

Specifies a semicolon-separated list of destination hostnames or IPs that are exempt from connecting through the proxy server set in the ProxyServer connection property.

Data Type

string

Default Value

""

Remarks

The ProxyServer is used for all addresses, except for addresses defined in this property. Use semicolons to separate entries.

Note: The connector uses the system proxy settings by default, without further configuration needed. If you want to explicitly configure proxy exceptions for this connection, set ProxyAutoDetect to False.

This section provides a complete list of the Logging properties you can configure in the connection string for this provider.

---

Property	Description
Logfile	Specifies the file path to the log file where the provider records its activities, such as authentication, query execution, and connection details.
Verbosity	Specifies the verbosity level of the log file, which controls the amount of detail logged. Supported values range from 1 to 5.
LogModules	Specifies the core modules to include in the log file. Use a semicolon-separated list of module names. By default, all modules are logged.
MaxLogFileSize	Specifies the maximum size of a single log file in bytes. For example, '10 MB'. When the file reaches the limit, the provider creates a new log file with the date and time appended to the name.
MaxLogFileCount	Specifies the maximum number of log files the provider retains. When the limit is reached, the oldest log file is deleted to make space for a new one.

Specifies the file path to the log file where the provider records its activities, such as authentication, query execution, and connection details.

Data Type

string

Default Value

""

Remarks

This property specifies the location and name of the log file where the connector records its operations, including authentication events, query execution, and connection details. If the specified file does not exist, the connector creates it. Ensure that the user or the service running the connector has write access to the specified path or file. Without sufficient permissions, the log file is not created.

Sensitive information from the connection string, such as passwords and tokens, is automatically masked in the logs. However, sensitive information present in the data itself may not be masked.

If you specify a relative path for Logfile, and if the Location property is set, that directory is used as the base path for the log file.

Additional properties allow you to customize logging behavior:

• Use Verbosity to control the level of detail of the log file.
• Manage log file size with MaxLogFileSize and control the number of retained log files with MaxLogFileCount.
• Filter specific log modules by adjusting the LogModules property.

Specifies the verbosity level of the log file, which controls the amount of detail logged. Supported values range from 1 to 5.

Data Type

string

Default Value

"1"

Remarks

This property defines the level of detail the connector includes in the log file. Higher verbosity levels increase the detail of the logged information, but may also result in larger log files and slower performance due to the additional data being captured.

The default verbosity level is 1, which is recommended for regular operation. Higher verbosity levels are primarily intended for debugging purposes. For more information on each level, refer to Logging.

When combined with the LogModules property, Verbosity can refine logging to specific categories of information.

Specifies the core modules to include in the log file. Use a semicolon-separated list of module names. By default, all modules are logged.

Data Type

string

Default Value

""

Remarks

The connector writes details about each operation it performs into the logfile specified by the Logfile connection property.

Each of these logged operations are assigned to a themed category called a module, and each module has a corresponding short code used to labels individual connector operations as belonging to that module.

When this connection property is set to a semicolon-separated list of module codes, only operations belonging to the specified modules are written to the logfile. Note that this only affects which operations are logged moving forward and doesn't retroactively alter the existing contents of the logfile. For example: INFO;EXEC;SSL;META;

By default, logged operations from all modules are included.

You can explicitly exclude a module by prefixing it with a "-". For example: -HTTP

To apply filters to submodules, identify them with the syntax <module name>.<submodule name>. For example, the following value causes the connector to only log actions belonging to the HTTP module, and further refines it to exclude actions belonging to the Res submodule of the HTTP module: HTTP;-HTTP.Res

Note that the logfile filtering triggered by the Verbosity connection property takes precedence over the filtering imposed by this connection property. This means that operations of a higher verbosity level than the level specified in the Verbosity connection property are not printed in the logfile, even if they belong to one of the modules specified in this connection property.

The available modules and submodules are:

Module Name	Module Description	Submodules
INFO	General Information. Includes the connection string, product version (build number), and initial connection messages.	Connec – Information related to creating or destroying connections. Messag – Generic label for messages pertaining to connections, the connection string, and product version. These messages are typically specific to the connector, rather than being received and passed along directly from the service.
EXEC	Query Execution. Includes execution messages for user-written SQL queries, parsed SQL queries, and normalized SQL queries. Success/failure messages for queries and query pages appear here as well.	Messag – Messages pertaining to query execution. These messages are typically specific to the connector, rather than being received and passed along directly from the service. Normlz – Query normalization steps. Query normalization is when the product takes the user-submitted query and rewrites the query to get the same results with optimal performance. Origin – This label applies to any messages recording a user's original query (the exact, unaltered, non-normalized query executed by the user). Page – Messages related to query paging. Parsed – Query parsing steps. Parsing is the process of converting the user-submitted query into a standardized format for easier processing.
HTTP	HTTP protocol messages. Includes HTTP requests/responses (including POST messages), as well as Kerberos related messages.	KERB – HTTP requests related to Kerberos. Messag – Messages pertaining to HTTP protocols. These messages are typically specific to the connector, rather than being received and passed along directly from the service. Unpack – This label applies to messages about zipped data being returned from the service API and unpacked by the product. Res – Messages containing HTTP responses. Req – Messages containing HTTP requests.
WSDL	Messages pertaining to the generation of WSDL/XSD files.	—
SSL	SSL certificate messages.	Certif – Messages pertaining to SSL certificates.
AUTH	Authentication related failure/success messages.	Messag – Messages pertaining to authentication. These messages are typically specific to the connector, rather than being received and passed along directly from the service. OAuth – Messages related to OAuth authentication. Krbros – Kerberos-related authentication messages.
SQL	Includes SQL transactions, SQL bulk transfer messages, and SQL result set messages.	Bulk – Messages pertaining to bulk query execution. Cache – Messages related to reading row data from and writing row data to the product's cache for better performance. Messag – Messages pertaining to SQL transactions. These messages are typically specific to the connector, rather than being received and passed along directly from the service. ResSet – Query resultsets. Transc – Messages related to handling transactions, including information about the number of jobs executed and backup table handling.
META	Metadata cache and schema messages.	Cache – Messages related to reading from and modifying column and table definitions in the product's cache for better performance. Schema – Messages related to retrieving metadata from or modifying the service schema. MemSto – Messages related to writing to or reading from in-memory metadata cache. Storag – Messages relating to storing metadata on disk or in an external data store, rather than in memory.
FUNC	Information related to executing SQL functions.	Errmsg – Error messages related to executing SQL functions.
TCP	Incoming and outgoing raw bytes on TCP transport layer messages.	Send – Raw data sent via the TCP protocol. Receiv – Raw data received via the TCP protocol.
FTP	Messages pertaining to the File Transfer Protocol.	Info – Status messages related to communication in the FTP protocol. Client – Messages related to actions taken by the FTP client (the product) during FTP communication. Server – Messages related to actions taken by the FTP server during FTP communication.
SFTP	Messages pertaining to the Secure File Transfer Protocol.	Info – Status messages related to communication in the SFTP protocol. To_Server – Messages related to actions taken by the SFTP client (the product) during SFTP communication. From_Server – Messages related to actions taken by the SFTP server during SFTP communication.
POP	Messages pertaining to data transferred via the Post Office Protocol.	Client – Messages related to actions taken by the POP client (the product) during POP communication. Server – Messages related to actions taken by the POP server during POP communication. Status – Status messages related to communication in the POP protocol.
SMTP	Messages pertaining to data transferred via the Simple Mail Transfer Protocol.	Client – Messages related to actions taken by the SMTP client (the product) during SMTP communication. Server – Messages related to actions taken by the SMTP server during SMTP communication. Status – Status messages related to communication in the SMTP protocol.
CORE	Messages relating to various internal product operations not covered by other modules.	—
DEMN	Messages related to SQL remoting.	—
CLJB	Messages about bulk data uploads (cloud job).	Commit – Submissions for bulk data uploads.
SRCE	Miscellaneous messages produced by the product that don't belong in any other module.	—
TRANCE	Advanced messages concerning low-level product operations.	—

Specifies the maximum size of a single log file in bytes. For example, '10 MB'. When the file reaches the limit, the provider creates a new log file with the date and time appended to the name.

Data Type

string

Default Value

"100MB"

Remarks

For values lower than 100 KB, the connector uses 100 KB as the minimum allowable size.

To control the total number of log files retained, use the MaxLogFileCount property in conjunction with this property. Together, these properties allow you to manage the size and retention of log files effectively.

Specifies the maximum number of log files the provider retains. When the limit is reached, the oldest log file is deleted to make space for a new one.

Data Type

int

Default Value

-1

Remarks

Each log file name includes the date and time for easier identification.

This property accepts the following values:

• A value of 2 or higher sets the maximum number of log files retained.
• A value of 1 retains only one log file. When it reaches the maximum size, the file is deleted and replaced by a new one, leaving no history beyond the current log.
• A value of 0 or negative indicates no limit on the number of log files, and logging continues indefinitely.

To manage log file size, use the MaxLogFileSize property. The two properties work together to control the size and retention of log files in the logging folder.

This section provides a complete list of the Schema properties you can configure in the connection string for this provider.

---

Property	Description
Location	Specifies the location of a directory containing schema files that define tables, views, and stored procedures. Depending on your service's requirements, this may be expressed as either an absolute path or a relative path.
BrowsableSchemas	Optional setting that restricts the schemas reported to a subset of all available schemas. For example, BrowsableSchemas=SchemaA,SchemaB,SchemaC .
Tables	Optional setting that restricts the tables reported to a subset of all available tables. For example, Tables=TableA,TableB,TableC .
Views	Optional setting that restricts the views reported to a subset of the available tables. For example, Views=ViewA,ViewB,ViewC .

Specifies the location of a directory containing schema files that define tables, views, and stored procedures. Depending on your service's requirements, this may be expressed as either an absolute path or a relative path.

Data Type

string

Default Value

"%APPDATA%\\CData\\SQL Data Provider\\Schema"

Remarks

The Location property is only needed if you want to either customize definitions (for example, change a column name, ignore a column, etc.) or extend the data model with new tables, views, or stored procedures.

If left unspecified, the default location is %APPDATA%\\CData\\SQL Data Provider\\Schema, where %APPDATA% is set to the user's configuration directory:

Platform	%APPDATA%
Windows	The value of the APPDATA environment variable
Linux	~/.config

Optional setting that restricts the schemas reported to a subset of all available schemas. For example, BrowsableSchemas=SchemaA,SchemaB,SchemaC .

Data Type

string

Default Value

""

Remarks

Listing all available database schemas can take extra time, thus degrading performance. Providing a list of schemas in the connection string saves time and improves performance.

Optional setting that restricts the tables reported to a subset of all available tables. For example, Tables=TableA,TableB,TableC .

Data Type

string

Default Value

""

Remarks

Listing all available tables from some databases can take extra time, thus degrading performance. Providing a list of tables in the connection string saves time and improves performance.

If there are lots of tables available and you already know which ones you want to work with, you can use this property to restrict your viewing to only those tables. To do this, specify the tables you want in a comma-separated list. Each table should be a valid SQL identifier with any special characters escaped using square brackets, double-quotes or backticks. For example, Tables=TableA,[TableB/WithSlash],WithCatalog.WithSchema.`TableC With Space`.

Note: If you are connecting to a data source with multiple schemas or catalogs, you must specify each table you want to view by its fully qualified name. This avoids ambiguity between tables that may exist in multiple catalogs or schemas.

Optional setting that restricts the views reported to a subset of the available tables. For example, Views=ViewA,ViewB,ViewC .

Data Type

string

Default Value

""

Remarks

Listing all available views from some databases can take extra time, thus degrading performance. Providing a list of views in the connection string saves time and improves performance.

If there are lots of views available and you already know which ones you want to work with, you can use this property to restrict your viewing to only those views. To do this, specify the views you want in a comma-separated list. Each view should be a valid SQL identifier with any special characters escaped using square brackets, double-quotes or backticks. For example, Views=ViewA,[ViewB/WithSlash],WithCatalog.WithSchema.`ViewC With Space`.

Note: If you are connecting to a data source with multiple schemas or catalogs, you must specify each view you want to examine by its fully qualified name. This avoids ambiguity between views that may exist in multiple catalogs or schemas.

This section provides a complete list of the Miscellaneous properties you can configure in the connection string for this provider.

---

Property	Description
ApplicationIntent	Specifies whether the application intends to access a read-only or read-write version of an availability group database.
ApplicationName	Specifies the name of the client application connecting to SQL Server.
IncludeSystemSchemas	Specifies whether to include system schemas such as guest, sys, INFORMATION_SCHEMA, and schemas prefixed with db_ during schema discovery.
IncludeTableTypes	Specifies whether to query SQL Server for the object types of individual tables and views.
MaxRows	Specifies the maximum number of rows returned for queries that do not include either aggregation or GROUP BY.
MultiSubnetFailover	Enable the MultiSubnetFailover property to resolve the AG Listener's DNS name when connecting to a multi-subnet Always On availability group.
Other	Specifies advanced connection properties for specialized scenarios. Use this property only under the guidance of our Support team to address specific issues.
QueryPassthrough	This option passes the query to the SQL Server server as is.
Readonly	Toggles read-only access to SQL Server from the provider.
RTK	Specifies the runtime key for licensing the provider. If unset or invalid, the provider defaults to the standard licensing method. This property is only required in environments where the standard licensing method is unsupported or requires a runtime key.
Timeout	Specifies the number of seconds the provider waits before timing out an operation.

Specifies whether the application intends to access a read-only or read-write version of an availability group database.

Data Type

string

Default Value

"ReadWrite"

Remarks

This property is used in high-availability SQL Server environments that use availability groups, a feature that maintains multiple copies of a database across different servers.

In an availability group:

• The primary replica is the main server where all changes (read and write operations) are made.
• Secondary replicas are read-only copies that stay synchronized with the primary.

When ApplicationIntent is set to ReadOnly, the SQL Server listener may route the connection to a read-only secondary replica, if one is available. This can reduce load on the primary server by handling queries that don’t need to update data. If the property is set to ReadWrite, the connection is directed to the primary replica.

This property is useful for improving performance and scalability in environments with high read traffic, especially when availability groups with read-only replicas are configured.

• Use ReadOnly to offload reporting and analytics queries to a secondary replica.
• Use ReadWrite (or omit the property) to connect directly to the primary replica for full read/write access.

Additional Information

If the availability group is not configured for read-only routing, setting this property to ReadOnly may result in a failed connection. Always check with your database administrator or deployment configuration.

Specifies the name of the client application connecting to SQL Server.

Data Type

string

Default Value

""

Remarks

This property sets the application name that is sent to the server as part of the connection metadata. On SQL Server, this value is typically visible in monitoring or logging tools and can be helpful for identifying, auditing, or troubleshooting specific application connections.

While this value is not strictly required for the connection, setting a unique application name is a good practice when multiple apps or services access the same database.

This property is useful for environments where SQL Server administrators monitor or analyze incoming connections, as it helps distinguish one application from another.

Additional Information

This value is also used as the User-Agent when HTTP-based communication is involved, such as through web proxies or gateways that inspect headers.

Specifies whether to include system schemas such as guest, sys, INFORMATION_SCHEMA, and schemas prefixed with db_ during schema discovery.

Data Type

bool

Default Value

true

Remarks

When enabled, this property instructs the connector to query and expose system-defined schemas alongside user-defined schemas. System schemas typically contain metadata, built-in views, and internal database objects.

These schemas include:

• sys: Contains internal views and catalog information.
• INFORMATION_SCHEMA: Provides standard views for metadata queries.
• guest: Represents access for unauthenticated users.
• Schemas with names starting with db_. For example: db_owner and db_datareader.

Disabling this property can simplify the schema view by omitting internal structures that are not relevant for most data access scenarios.

This property is useful for controlling the visibility of internal SQL Server objects in environments where users only need to work with application data. Set this property to false to streamline metadata discovery or restrict what appears in tools like data explorers or schema browsers.

Specifies whether to query SQL Server for the object types of individual tables and views.

Data Type

bool

Default Value

true

Remarks

When enabled, the connector queries SQL Server to identify whether each object is a table or a view. This can help tools and applications distinguish between different object types during schema discovery.

When disabled, the connector skips this check which may improve metadata retrieval performance, but results in all objects being treated generically without specific type metadata.

This property is useful when an application needs to differentiate between tables and views, such as for filtering or organizing metadata. Set this property to false to potentially improve performance during schema discovery, especially in environments with many objects.

This setting affects only schema metadata and does not impact the ability to query or interact with the actual data.

Specifies the maximum number of rows returned for queries that do not include either aggregation or GROUP BY.

Data Type

int

Default Value

-1

Remarks

The default value for this property, -1, means that no row limit is enforced unless the query explicitly includes a LIMIT clause. (When a query includes a LIMIT clause, the value specified in the query takes precedence over the MaxRows setting.)

Setting MaxRows to a whole number greater than 0 ensures that queries do not return excessively large result sets by default.

This property is useful for optimizing performance and preventing excessive resource consumption when executing queries that could otherwise return very large datasets.

Enable the MultiSubnetFailover property to resolve the AG Listener's DNS name when connecting to a multi-subnet Always On availability group.

Data Type

bool

Default Value

false

Remarks

Enable the MultiSubnetFailover property to resolve the AG Listener's DNS name when connecting to a multi-subnet Always On availability group.

Specifies advanced connection properties for specialized scenarios. Use this property only under the guidance of our Support team to address specific issues.

Data Type

string

Default Value

""

Remarks

This property allows advanced users to configure hidden properties for specialized situations, with the advice of our Support team. These settings are not required for normal use cases but can address unique requirements or provide additional functionality. To define multiple properties, use a semicolon-separated list.

Note: It is strongly recommended to set these properties only when advised by the Support team to address specific scenarios or issues.

Integration and Formatting

Property	Description
DefaultColumnSize	Sets the default length of string fields when the data source does not provide column length in the metadata. The default value is 2000.
ConvertDateTimeToGMT=True	Converts date-time values to GMT, instead of the local time of the machine. The default value is False (use local time).
RecordToFile=filename	Records the underlying socket data transfer to the specified file.

This option passes the query to the SQL Server server as is.

Data Type

bool

Default Value

true

Remarks

When this is set, queries are passed through directly to SQL Server.

Toggles read-only access to SQL Server from the provider.

Data Type

bool

Default Value

false

Remarks

When set to True, the connector allows only SELECT queries. Attempting an INSERT, UPDATE, DELETE, or stored procedure query fails with an error message.

Specifies the runtime key for licensing the provider. If unset or invalid, the provider defaults to the standard licensing method. This property is only required in environments where the standard licensing method is unsupported or requires a runtime key.

Data Type

string

Default Value

""

Remarks

This property is typically unnecessary, as most configurations support a standard licensing mechanism.

Warning: The value of this property takes precedence over all existing licensing information. To avoid licensing errors, ensure the provided runtime key is correct.

Specifies the number of seconds the provider waits before timing out an operation.

Data Type

int

Default Value

30

Remarks

This property defines the maximum amount of time, in seconds, that the connector waits for a command to complete before raising a timeout error.

If Timeout is set to 0, operations do not time out. They continue running until they succeed or fail due to another error.

If Timeout is set to a positive integer, the connector cancels the operation and raises an error if it exceeds the specified duration.

Timeout applies to various operations such as executing queries, establishing connections, or reading data streams.

This property is useful for controlling long-running operations or setting safe execution limits in applications that require predictable behavior.

Note: Timeout behavior may vary depending on the command type like query or stored procedure, and network conditions. Always consider the typical response time of your database operations when configuring this value.

LZMA from 7Zip LZMA SDK

LZMA SDK is placed in the public domain.

Anyone is free to copy, modify, publish, use, compile, sell, or distribute the original LZMA SDK code, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.

LZMA2 from XZ SDK

Version 1.9 and older are in the public domain.

Xamarin.Forms

Xamarin SDK

The MIT License (MIT)

Copyright (c) .NET Foundation Contributors

All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

NSIS 3.10

Copyright (C) 1999-2025 Contributors THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS COMMON PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT.

1. DEFINITIONS

"Contribution" means:

a) in the case of the initial Contributor, the initial code and documentation distributed under this Agreement, and b) in the case of each subsequent Contributor:

i) changes to the Program, and

ii) additions to the Program;

where such changes and/or additions to the Program originate from and are distributed by that particular Contributor. A Contribution 'originates' from a Contributor if it was added to the Program by such Contributor itself or anyone acting on such Contributor's behalf. Contributions do not include additions to the Program which: (i) are separate modules of software distributed in conjunction with the Program under their own license agreement, and (ii) are not derivative works of the Program.

"Contributor" means any person or entity that distributes the Program.

"Licensed Patents " mean patent claims licensable by a Contributor which are necessarily infringed by the use or sale of its Contribution alone or when combined with the Program.

"Program" means the Contributions distributed in accordance with this Agreement.

"Recipient" means anyone who receives the Program under this Agreement, including all Contributors.

2. GRANT OF RIGHTS

a) Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, worldwide, royalty-free copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, distribute and sublicense the Contribution of such Contributor, if any, and such derivative works, in source code and object code form.

b) Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, worldwide, royalty-free patent license under Licensed Patents to make, use, sell, offer to sell, import and otherwise transfer the Contribution of such Contributor, if any, in source code and object code form. This patent license shall apply to the combination of the Contribution and the Program if, at the time the Contribution is added by the Contributor, such addition of the Contribution causes such combination to be covered by the Licensed Patents. The patent license shall not apply to any other combinations which include the Contribution. No hardware per se is licensed hereunder.

c) Recipient understands that although each Contributor grants the licenses to its Contributions set forth herein, no assurances are provided by any Contributor that the Program does not infringe the patent or other intellectual property rights of any other entity. Each Contributor disclaims any liability to Recipient for claims brought by any other entity based on infringement of intellectual property rights or otherwise. As a condition to exercising the rights and licenses granted hereunder, each Recipient hereby assumes sole responsibility to secure any other intellectual property rights needed, if any. For example, if a third party patent license is required to allow Recipient to distribute the Program, it is Recipient's responsibility to acquire that license before distributing the Program.

d) Each Contributor represents that to its knowledge it has sufficient copyright rights in its Contribution, if any, to grant the copyright license set forth in this Agreement.

3. REQUIREMENTS

A Contributor may choose to distribute the Program in object code form under its own license agreement, provided that:

a) it complies with the terms and conditions of this Agreement; and

b) its license agreement:

i) effectively disclaims on behalf of all Contributors all warranties and conditions, express and implied, including warranties or conditions of title and non-infringement, and implied warranties or conditions of merchantability and fitness for a particular purpose;

ii) effectively excludes on behalf of all Contributors all liability for damages, including direct, indirect, special, incidental and consequential damages, such as lost profits;

iii) states that any provisions which differ from this Agreement are offered by that Contributor alone and not by any other party; and

iv) states that source code for the Program is available from such Contributor, and informs licensees how to obtain it in a reasonable manner on or through a medium customarily used for software exchange.

When the Program is made available in source code form:

a) it must be made available under this Agreement; and

b) a copy of this Agreement must be included with each copy of the Program.

Contributors may not remove or alter any copyright notices contained within the Program.

Each Contributor must identify itself as the originator of its Contribution, if any, in a manner that reasonably allows subsequent Recipients to identify the originator of the Contribution.

4. COMMERCIAL DISTRIBUTION

Commercial distributors of software may accept certain responsibilities with respect to end users, business partners and the like. While this license is intended to facilitate the commercial use of the Program, the Contributor who includes the Program in a commercial product offering should do so in a manner which does not create potential liability for other Contributors. Therefore, if a Contributor includes the Program in a commercial product offering, such Contributor ("Commercial Contributor") hereby agrees to defend and indemnify every other Contributor ("Indemnified Contributor") against any losses, damages and costs (collectively "Losses") arising from claims, lawsuits and other legal actions brought by a third party against the Indemnified Contributor to the extent caused by the acts or omissions of such Commercial Contributor in connection with its distribution of the Program in a commercial product offering. The obligations in this section do not apply to any claims or Losses relating to any actual or alleged intellectual property infringement. In order to qualify, an Indemnified Contributor must: a) promptly notify the Commercial Contributor in writing of such claim, and b) allow the Commercial Contributor to control, and cooperate with the Commercial Contributor in, the defense and any related settlement negotiations. The Indemnified Contributor may participate in any such claim at its own expense.

For example, a Contributor might include the Program in a commercial product offering, Product X. That Contributor is then a Commercial Contributor. If that Commercial Contributor then makes performance claims, or offers warranties related to Product X, those performance claims and warranties are such Commercial Contributor's responsibility alone. Under this section, the Commercial Contributor would have to defend claims against the other Contributors related to those performance claims and warranties, and if a court requires any other Contributor to pay any damages as a result, the Commercial Contributor must pay those damages.

5. NO WARRANTY

EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Each Recipient is solely responsible for determining the appropriateness of using and distributing the Program and assumes all risks associated with its exercise of rights under this Agreement, including but not limited to the risks and costs of program errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and unavailability or interruption of operations.

6. DISCLAIMER OF LIABILITY

EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT NOR ANY CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

7. GENERAL

If any provision of this Agreement is invalid or unenforceable under applicable law, it shall not affect the validity or enforceability of the remainder of the terms of this Agreement, and without further action by the parties hereto, such provision shall be reformed to the minimum extent necessary to make such provision valid and enforceable.

If Recipient institutes patent litigation against a Contributor with respect to a patent applicable to software (including a cross-claim or counterclaim in a lawsuit), then any patent licenses granted by that Contributor to such Recipient under this Agreement shall terminate as of the date such litigation is filed. In addition, if Recipient institutes patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Program itself (excluding combinations of the Program with other software or hardware) infringes such Recipient's patent(s), then such Recipient's rights granted under Section 2(b) shall terminate as of the date such litigation is filed.

All Recipient's rights under this Agreement shall terminate if it fails to comply with any of the material terms or conditions of this Agreement and does not cure such failure in a reasonable period of time after becoming aware of such noncompliance. If all Recipient's rights under this Agreement terminate, Recipient agrees to cease use and distribution of the Program as soon as reasonably practicable. However, Recipient's obligations under this Agreement and any licenses granted by Recipient relating to the Program shall continue and survive.

Everyone is permitted to copy and distribute copies of this Agreement, but in order to avoid inconsistency the Agreement is copyrighted and may only be modified in the following manner. The Agreement Steward reserves the right to publish new versions (including revisions) of this Agreement from time to time. No one other than the Agreement Steward has the right to modify this Agreement. IBM is the initial Agreement Steward. IBM may assign the responsibility to serve as the Agreement Steward to a suitable separate entity. Each new version of the Agreement will be given a distinguishing version number. The Program (including Contributions) may always be distributed subject to the version of the Agreement under which it was received. In addition, after a new version of the Agreement is published, Contributor may elect to distribute the Program (including its Contributions) under the new version. Except as expressly stated in Sections 2(a) and 2(b) above, Recipient receives no rights or licenses to the intellectual property of any Contributor under this Agreement, whether expressly, by implication, estoppel or otherwise. All rights in the Program not expressly granted under this Agreement are reserved.

This Agreement is governed by the laws of the State of New York and the intellectual property laws of the United States of America. No party to this Agreement will bring a legal action under this Agreement more than one year after the cause of action arose. Each party waives its rights to a jury trial in any resulting litigation.

AdoptOpenJDK / Adoptium Temurin JRE 17.0.18_8

Copyright (c) Eclipse Foundation AISBL. All Rights Reserved.

Apache License, Version 2.0

TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.

"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.

"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.

"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.

"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.

"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.

"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).

"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.

"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."

"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.

2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.

3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.

4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:

1. You must give any other recipients of the Work or Derivative Works a copy of this License; and
2. You must cause any modified files to carry prominent notices stating that You changed the files; and
3. You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
4. If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.

You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.

5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.

6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.

7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.

8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.

9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.

END OF TERMS AND CONDITIONS

Eclipse Distribution License - v 1.0

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
• Neither the name of the Eclipse Foundation, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Eclipse Public License - v 2.0

THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT.

1. DEFINITIONS "Contribution" means:

• a) in the case of the initial Contributor, the initial content Distributed under this Agreement, and
• b) in the case of each subsequent Contributor:
  • i) changes to the Program, and
  • ii) additions to the Program;
  where such changes and/or additions to the Program originate from and are Distributed by that particular Contributor. A Contribution "originates" from a Contributor if it was added to the Program by such Contributor itself or anyone acting on such Contributor's behalf. Contributions do not include changes or additions to the Program that are not Modified Works.

"Contributor" means any person or entity that Distributes the Program. "Licensed Patents" mean patent claims licensable by a Contributor which are necessarily infringed by the use or sale of its Contribution alone or when combined with the Program.

"Program" means the Contributions Distributed in accordance with this Agreement.

"Recipient" means anyone who receives the Program under this Agreement or any Secondary License (as applicable), including Contributors.

"Derivative Works" shall mean any work, whether in Source Code or other form, that is based on (or derived from) the Program and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship.

"Modified Works" shall mean any work in Source Code or other form that results from an addition to, deletion from, or modification of the contents of the Program, including, for purposes of clarity any new file in Source Code form that contains any contents of the Program. Modified Works shall not include works that contain only declarations, interfaces, types, classes, structures, or files of the Program solely in each case in order to link to, bind by name, or subclass the Program or Modified Works thereof.

"Distribute" means the acts of a) distributing or b) making available in any manner that enables the transfer of a copy.

"Source Code" means the form of a Program preferred for making modifications, including but not limited to software source code, documentation source, and configuration files.

"Secondary License" means either the GNU General Public License, Version 2.0, or any later versions of that license, including any exceptions or additional permissions as identified by the initial Contributor.

2. GRANT OF RIGHTS

• a) Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, worldwide, royalty-free copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, Distribute and sublicense the Contribution of such Contributor, if any, and such Derivative Works.
• b) Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, worldwide, royalty-free patent license under Licensed Patents to make, use, sell, offer to sell, import and otherwise transfer the Contribution of such Contributor, if any, in Source Code or other form. This patent license shall apply to the combination of the Contribution and the Program if, at the time the Contribution is added by the Contributor, such addition of the Contribution causes such combination to be covered by the Licensed Patents. The patent license shall not apply to any other combinations which include the Contribution. No hardware per se is licensed hereunder.
• c) Recipient understands that although each Contributor grants the licenses to its Contributions set forth herein, no assurances are provided by any Contributor that the Program does not infringe the patent or other intellectual property rights of any other entity. Each Contributor disclaims any liability to Recipient for claims brought by any other entity based on infringement of intellectual property rights or otherwise. As a condition to exercising the rights and licenses granted hereunder, each Recipient hereby assumes sole responsibility to secure any other intellectual property rights needed, if any. For example, if a third party patent license is required to allow Recipient to Distribute the Program, it is Recipient's responsibility to acquire that license before distributing the Program.
• d) Each Contributor represents that to its knowledge it has sufficient copyright rights in its Contribution, if any, to grant the copyright license set forth in this Agreement.
• e) Notwithstanding the terms of any Secondary License, no Contributor makes additional grants to any Recipient (other than those set forth in this Agreement) as a result of such Recipient's receipt of the Program under the terms of a Secondary License (if permitted under the terms of Section 3).

3. REQUIREMENTS 3.1 If a Contributor Distributes the Program in any form, then:

• a) the Program must also be made available as Source Code, in accordance with section 3.2, and the Contributor must accompany the Program with a statement that the Source Code for the Program is available under this Agreement, and informs Recipients how to obtain it in a reasonable manner on or through a medium customarily used for software exchange; and
• b) the Contributor may Distribute the Program under a license different than this Agreement, provided that such license:
  • i) effectively disclaims on behalf of all other Contributors all warranties and conditions, express and implied, including warranties or conditions of title and non-infringement, and implied warranties or conditions of merchantability and fitness for a particular purpose;
  • ii) effectively excludes on behalf of all other Contributors all liability for damages, including direct, indirect, special, incidental and consequential damages, such as lost profits;
  • iii) does not attempt to limit or alter the recipients' rights in the Source Code under section 3.2; and
  • iv) requires any subsequent distribution of the Program by any party to be under a license that satisfies the requirements of this section 3.

3.2 When the Program is Distributed as Source Code:

• a) it must be made available under this Agreement, or if the Program (i) is combined with other material in a separate file or files made available under a Secondary License, and (ii) the initial Contributor attached to the Source Code the notice described in Exhibit A of this Agreement, then the Program may be made available under the terms of such Secondary Licenses, and
• b) a copy of this Agreement must be included with each copy of the Program.

3.3 Contributors may not remove or alter any copyright, patent, trademark, attribution notices, disclaimers of warranty, or limitations of liability (‘notices') contained within the Program from any copy of the Program which they Distribute, provided that Contributors may add their own appropriate notices.

4. COMMERCIAL DISTRIBUTION Commercial distributors of software may accept certain responsibilities with respect to end users, business partners and the like. While this license is intended to facilitate the commercial use of the Program, the Contributor who includes the Program in a commercial product offering should do so in a manner which does not create potential liability for other Contributors. Therefore, if a Contributor includes the Program in a commercial product offering, such Contributor ("Commercial Contributor") hereby agrees to defend and indemnify every other Contributor ("Indemnified Contributor") against any losses, damages and costs (collectively "Losses") arising from claims, lawsuits and other legal actions brought by a third party against the Indemnified Contributor to the extent caused by the acts or omissions of such Commercial Contributor in connection with its distribution of the Program in a commercial product offering. The obligations in this section do not apply to any claims or Losses relating to any actual or alleged intellectual property infringement. In order to qualify, an Indemnified Contributor must: a) promptly notify the Commercial Contributor in writing of such claim, and b) allow the Commercial Contributor to control, and cooperate with the Commercial Contributor in, the defense and any related settlement negotiations. The Indemnified Contributor may participate in any such claim at its own expense.

For example, a Contributor might include the Program in a commercial product offering, Product X. That Contributor is then a Commercial Contributor. If that Commercial Contributor then makes performance claims, or offers warranties related to Product X, those performance claims and warranties are such Commercial Contributor's responsibility alone. Under this section, the Commercial Contributor would have to defend claims against the other Contributors related to those performance claims and warranties, and if a court requires any other Contributor to pay any damages as a result, the Commercial Contributor must pay those damages.

5. NO WARRANTY EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, AND TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE PROGRAM IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Each Recipient is solely responsible for determining the appropriateness of using and distributing the Program and assumes all risks associated with its exercise of rights under this Agreement, including but not limited to the risks and costs of program errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and unavailability or interruption of operations.

6. DISCLAIMER OF LIABILITY EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, AND TO THE EXTENT PERMITTED BY APPLICABLE LAW, NEITHER RECIPIENT NOR ANY CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

7. GENERAL If any provision of this Agreement is invalid or unenforceable under applicable law, it shall not affect the validity or enforceability of the remainder of the terms of this Agreement, and without further action by the parties hereto, such provision shall be reformed to the minimum extent necessary to make such provision valid and enforceable.

If Recipient institutes patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Program itself (excluding combinations of the Program with other software or hardware) infringes such Recipient's patent(s), then such Recipient's rights granted under Section 2(b) shall terminate as of the date such litigation is filed.

All Recipient's rights under this Agreement shall terminate if it fails to comply with any of the material terms or conditions of this Agreement and does not cure such failure in a reasonable period of time after becoming aware of such noncompliance. If all Recipient's rights under this Agreement terminate, Recipient agrees to cease use and distribution of the Program as soon as reasonably practicable. However, Recipient's obligations under this Agreement and any licenses granted by Recipient relating to the Program shall continue and survive.

Everyone is permitted to copy and distribute copies of this Agreement, but in order to avoid inconsistency the Agreement is copyrighted and may only be modified in the following manner. The Agreement Steward reserves the right to publish new versions (including revisions) of this Agreement from time to time. No one other than the Agreement Steward has the right to modify this Agreement. The Eclipse Foundation is the initial Agreement Steward. The Eclipse Foundation may assign the responsibility to serve as the Agreement Steward to a suitable separate entity. Each new version of the Agreement will be given a distinguishing version number. The Program (including Contributions) may always be Distributed subject to the version of the Agreement under which it was received. In addition, after a new version of the Agreement is published, Contributor may elect to Distribute the Program (including its Contributions) under the new version.

Except as expressly stated in Sections 2(a) and 2(b) above, Recipient receives no rights or licenses to the intellectual property of any Contributor under this Agreement, whether expressly, by implication, estoppel or otherwise. All rights in the Program not expressly granted under this Agreement are reserved. Nothing in this Agreement is intended to be enforceable by any entity that is not a Contributor or Recipient. No third-party beneficiary rights are created under this Agreement.

Exhibit A – Form of Secondary Licenses Notice "This Source Code may also be made available under the following Secondary Licenses when the conditions for such availability set forth in the Eclipse Public License, v. 2.0 are satisfied: {name license(s), version(s), and exceptions or additional permissions here}."

Simply including a copy of this Agreement, including this Exhibit A is not sufficient to license the Source Code under Secondary Licenses.

If it is not possible or desirable to put the notice in a particular file, then You may include the notice in a location (such as a LICENSE file in a relevant directory) where a recipient would be likely to look for such a notice.

You may add additional accurate notices of copyright ownership.

GNU Classpath

Classpath is distributed under the terms of the GNU General Public License with the following clarification and special exception.

Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination.

As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.

As such, it can be used to run, create and distribute a large class of applications and applets. When GNU Classpath is used unmodified as the core class library for a virtual machine, compiler for the java languge, or for a program written in the java programming language it does not affect the licensing for distributing those programs directly.

OpenJDK Assembly Exception

The OpenJDK source code made available by Oracle America, Inc. (Oracle) at openjdk.java.net ("OpenJDK Code") is distributed under the terms of the GNU General Public License <http://www.gnu.org/copyleft/gpl.html> version 2 only ("GPL2"), with the following clarification and special exception.

Linking this OpenJDK Code statically or dynamically with other code is making a combined work based on this library. Thus, the terms and conditions of GPL2 cover the whole combination.

As a special exception, Oracle gives you permission to link this OpenJDK Code with certain code licensed by Oracle as indicated at http://openjdk.java.net/legal/exception-modules-2007-05-08.html ("Designated Exception Modules") to produce an executable, regardless of the license terms of the Designated Exception Modules, and to copy and distribute the resulting executable under GPL2, provided that the Designated Exception Modules continue to be governed by the licenses under which they were offered by Oracle.

As such, it allows licensees and sublicensees of Oracle's GPL2 OpenJDK Code to build an executable that includes those portions of necessary code that Oracle could not provide under GPL2 (or that Oracle has provided under GPL2 with the Classpath exception). If you modify or add to the OpenJDK code, that new GPL2 code may still be combined with Designated Exception Modules if the new code is made subject to this exception by its copyright holder.