SQL Server Express LocalDB header and version information

Applies to: SQL Server

There's no separate header file for the SQL Server Express LocalDB instance API; the LocalDB function signatures and error codes are defined in the Microsoft OLE DB Driver for SQL Server header file (msoledbsql.h). To use the LocalDB instance API, you must include the msoledbsql.h header file in your project. This article no longer references the SQL Server Native Client header file (sqlncli.h).

LocalDB versioning

The LocalDB installation uses a single set of binaries per major SQL Server version. These LocalDB versions are maintained and patched independently. This means that the user has to specify which LocalDB baseline release (that is, major SQL Server version) they're using. The version is specified in the standard version format defined by the .NET Framework System.Version class:

<major>.<minor>[.<build>[.<revision>]]

The first two numbers in the version string (<major> and <minor>) are mandatory. The last two numbers in the version string (<build> and <revision>) are optional and default to zero if the user leaves them out. This means that if the user specifies only 12.2 as the LocalDB version number, it's treated as if the user specified 12.2.0.0.

The version for the LocalDB installation is defined in the MSSQLServer\CurrentVersion registry key under the SQL Server instance registry key, for example:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft SQL Server\MSSQL13E.LOCALDB\ MSSQLServer\CurrentVersion: "CurrentVersion"="12.0.2531.0"

Multiple LocalDB versions on the same workstation are supported side-by-side. However, user code always uses the latest available SQLUserInstance DLL on the local computer to connect to LocalDB instances.

Locate the SQLUserInstance DLL

To locate the SQLUserInstance DLL, the client provider uses the following registry key:

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft SQL Server Local DB\Installed Versions]

Under this key there's a list of keys, one for each version of LocalDB installed on the computer. Each of these keys is named with the LocalDB version number in the format <major-version>.<minor-version> (for example, the key for SQL Server 2014 (12.x) is named 13.0). Under each version key there's an InstanceAPIPath name-value pair that defines the full path to the SQLUserInstance.dll file installed with that version. The following example shows the registry entries for a computer that has LocalDB versions 11.0 and 13.0 installed:

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft SQL Server Local DB\Installed Versions\11.0]
"InstanceAPIPath"="C:\\Program Files\\Microsoft SQL Server\\110\\LocalDB\\Binn\\SqlUserInstance.dll"
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft SQL Server Local DB\Installed Versions\13.0]
"InstanceAPIPath"="C:\\Program Files\\Microsoft SQL Server\\130\\LocalDB\\Binn\\SqlUserInstance.dll"

The client provider must find the latest version among all installed versions and load the SQLUserInstance DLL file from the associated InstanceAPIPath value.

WOW64 mode on 64-bit Windows

64-bit installations of LocalDB have an extra set of registry keys to allow 32-bit applications running in Windows-32-on-Windows-64 (WOW64) mode to use LocalDB. Specifically, on 64-bit Windows, the LocalDB MSI creates the following registry keys:

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Wow6432Node\Microsoft SQL Server Local DB\Installed Versions\13.0]
"InstanceAPIPath"="C:\\Program Files (x86)\\Microsoft SQL Server\\130\\LocalDB\\Binn\\SqlUserInstance.dll"
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Wow6432Node\Microsoft SQL Server Local DB\Installed Versions\13.0]
"InstanceAPIPath"="C:\\Program Files (x86)\\Microsoft SQL Server\\130\\LocalDB\\Binn\\SqlUserInstance.dll"

64-bit programs reading the Installed Versions key see values pointing to 64-bit versions of the SQLUserInstance DLL, while 32-bit programs (running on 64-bit Windows in WOW64 mode) are automatically redirected to an Installed Versions key located under the Wow6432Node hive. This key contains values pointing to 32-bit versions of the SQLUserInstance DLL.

Use LOCALDB_DEFINE_PROXY_FUNCTIONS

The LocalDB instance API defines a constant named LOCALDB_DEFINE_PROXY_FUNCTIONS that automates the discovery and loading of the SqlUserInstance DLL.

The section of code enabled by this constant provides an implementation of proxies for each of the LocalDB APIs. The proxy implementations use a common function to bind to entry points in the latest installed SqlUserInstance DLL, and then forward the requests.

The proxy functions are enabled only if the constant LOCALDB_DEFINE_PROXY_FUNCTIONS is defined in the user code before including the msoledbsql.h file. The constant should be defined in only one source module (.cpp file) because it defines external function names for all of the API entry points. It provides an implementation of proxies for each of the LocalDB APIs.

The following code example shows how to use the macro from the native C++ code:

// Define the LOCALDB_DEFINE_PROXY_FUNCTIONS constant to enable the LocalDB proxy functions
// The #define has to take place BEFORE the API header file (msoledbsql.h) is included
#define LOCALDB_DEFINE_PROXY_FUNCTIONS
#include <msoledbsql.h>
...
HRESULT hr = S_OK;

// Create LocalDB instance by calling the create API proxy function included by macro
if (FAILED(hr = LocalDBCreateInstance( L"12.0", L"name", 0)))
{
...
}
...