Upraviť

Install SQL Server Java Language Extension on Linux

Applies to: SQL Server 2019 (15.x) on Linux and later versions

Learn how to install the Java Language Extension component for SQL Server on Linux. The Java Language Extension is part of SQL Server Language Extensions and an add-on to the Database Engine.

Although you can install the Database Engine and Language Extensions concurrently, it's a best practice to install and configure the SQL Server Database Engine first so that you can resolve any issues before adding more components.

Prerequisites

  • The Java extensions package is in the SQL Server Linux source repositories. If you already configured source repositories for the Database Engine installation, run the mssql-server-extensibility-java package install commands by using the same repo registration.

  • Language Extensions is also supported on Linux containers. Prebuilt containers with Language Extensions aren't available, but you can create one from the SQL Server containers by using an example template available on GitHub.

  • Language Extensions and Machine Learning Services are installed by default on SQL Server Big Data Clusters. If you use Big Data Clusters, you don't need to follow the steps in this article.

Package list

On an internet-connected device, you download and install packages independently of the Database Engine by using the package installer for each operating system. The following table describes all available packages.

Package name Applies to Description
mssql-server-extensibility All languages Extensibility framework used for the Java language extension
mssql-server-extensibility-java Java Extensibility framework used for the Java language extension and includes a supported Java runtime

Applies to: SQL Server 2019 (15.x) on Linux only

Install Java language extension

To install Language Extensions and Java on Linux, install the mssql-server-extensibility-java package. The package automatically installs JRE 11 (if it isn't already installed) and adds the JVM path to an environment variable called JRE_HOME.

To enable the Java Language Extension, build a custom binary by following the instructions from the Java Language Extension page on GitHub.

Note

On an internet-connected server, package dependencies are downloaded and installed as part of the main package installation. If your server isn't connected to the internet, see more details in the offline setup.

You can download and install any Java runtime, including the latest Microsoft Build of OpenJDK or an officially licensed Java runtime. Starting with SQL Server 2022 (16.x), SQL Server Setup doesn't install a Java runtime.

To enable the Java Language Extension, build a custom binary by following the instructions from the Java Language Extension page on GitHub.

Red Hat install command

To install Language Extensions for Java on Red Hat, use the following command.

Tip

If possible, run yum clean all to refresh packages on the system before installation.

# Install as root or sudo
sudo yum install mssql-server-extensibility-java

Ubuntu install command

To install Language Extensions for Java on Ubuntu, use the following command.

Tip

If possible, run apt-get update to refresh packages on the system before installation. Some Ubuntu Docker images don't include the apt-transport-https package. To install it, run apt-get install apt-transport-https.

# Install as root or sudo
sudo apt-get install mssql-server-extensibility-java

SUSE install command

To install Language Extensions for Java on SUSE, use the following command.

# Install as root or sudo
sudo zypper install mssql-server-extensibility-java

Post-install configuration (required)

  1. Grant permissions on Linux

    You don't need to perform this step if you use external libraries. External libraries are the recommended approach. For help with creating an external library from your jar file, see CREATE EXTERNAL LIBRARY.

    If you aren't using external libraries, you need to provide SQL Server with permissions to execute the Java classes in your jar.

    To grant read and execute access to a jar file, run the following chmod command on the jar file. Always put your class files in a jar when you work with SQL Server. For help with creating a jar, see Create a Java .jar file from class files.

    chmod ug+rx <MyJarFile.jar>

    You also need to give mssql_satellite permissions to read and execute the jar file.

    chown mssql_satellite:mssql_satellite <MyJarFile.jar>

    Additional configuration is primarily through the mssql-conf tool.

  2. Add the mssql user account used to run the SQL Server service. This step is required if you haven't run the setup previously.

    sudo /opt/mssql/bin/mssql-conf setup

  3. Enable outbound network access. Outbound network access is disabled by default. To enable outbound requests, set the outboundnetworkaccess Boolean property with the mssql-conf tool. For more information, see Configure SQL Server on Linux with mssql-conf.

    # Run as SUDO or root
# Enable outbound requests over the network
sudo /opt/mssql/bin/mssql-conf set extensibility outboundnetworkaccess 1

  4. Restart the SQL Server Launchpad service and the Database Engine instance to read the updated values from the INI file. A restart message reminds you whenever you modify an extensibility-related setting.

    systemctl restart mssql-launchpadd
systemctl restart mssql-server.service

  5. Enable external script execution. You can connect to an instance of SQL Server using any familiar SQL Server client tool, such as sqlcmd, SQL Server Management Studio (SSMS), or the MSSQL extension for Visual Studio Code.

    EXECUTE sp_configure 'external scripts enabled', 1;

RECONFIGURE WITH OVERRIDE;

  6. Restart the mssql-launchpadd service again.

  7. For each database where you want to use language extensions, register the external language with CREATE EXTERNAL LANGUAGE. See the next section for steps.

Register external language

For each database where you want to use language extensions, register the external language with CREATE EXTERNAL LANGUAGE.

The following example adds an external language called Java to a database on SQL Server on Linux.

CREATE EXTERNAL LANGUAGE Java
FROM (
    CONTENT = N'/opt/mssql-extensibility/lib/java-lang-extension.tar.gz',
    FILE_NAME = 'javaextension.so',
    ENVIRONMENT_VARIABLES = N'{"JRE_HOME":"/opt/mssql/lib/zulu-jre-11"}'
);

For the Java extension, the environment variable JRE_HOME determines the path to find and initialize the JVM.

The CREATE EXTERNAL LANGUAGE DDL provides an ENVIRONMENT_VARIABLES parameter to set environment variables for the process that hosts the extension. Use this parameter to set environment variables that external language extensions require.

For more information, see CREATE EXTERNAL LANGUAGE.

Verify installation

Java feature integration doesn't include libraries, but you can run grep -r JRE_HOME /etc to confirm the JRE_HOME environment variable exists.

To validate installation, run a T-SQL script that executes a system stored procedure invoking Java. You need a query tool for this task. You can connect to an instance of SQL Server using any familiar SQL Server client tool, such as sqlcmd, SQL Server Management Studio (SSMS), or the MSSQL extension for Visual Studio Code.

Full install of SQL Server and Java Language Extension

To install and configure the Database Engine and Java Language Extension in one procedure, append Java packages and parameters to a command that installs the Database Engine.

  1. Provide a command line that includes the Database Engine, plus language extension features.

    The following command adds Java extensibility to a Database Engine install.

    sudo yum install -y mssql-server mssql-server-extensibility-java

  2. Accept license agreements and complete the post-install configuration. Use the mssql-conf tool.

    sudo /opt/mssql/bin/mssql-conf setup

    This step prompts you to accept the license agreement for the Database Engine, choose an edition, and set the administrator password.

  3. Restart the service if prompted.

    sudo systemctl restart mssql-server.service

Unattended installation

Use the unattended install for the Database Engine and add the packages for mssql-server-extensibility-java.

Offline installation

To install the packages, follow the Offline installation instructions. Find your download site, and then download the specific packages listed later in this section.

Tip

Several package management tools provide commands that help you determine package dependencies. For yum, use sudo yum deplist [package]. For Ubuntu, use sudo apt-get install --reinstall --download-only [package name] followed by dpkg -I [package name].deb.

Download site

Download the packages from https://packages.microsoft.com/. The site hosts all Java packages alongside the Database Engine package.

Download paths

Package Distribution Download location
mssql/extensibility-java packages Red Hat 8 https://packages.microsoft.com/rhel/8/mssql-server-2019/
mssql/extensibility-java packages SUSE v15 https://packages.microsoft.com/sles/15/mssql-server-2019/
mssql/extensibility-java packages Ubuntu 20.04 https://packages.microsoft.com/ubuntu/20.04/mssql-server-2019/pool/main/m/

Package list

Depending on which extensions you want to use, download the packages necessary for a specific language. Exact filenames include platform information in the suffix, but the following file names help you determine which files to get.

  • Core packages

    • mssql-server-15.0.1000
    • mssql-server-extensibility-15.0.1000

  • Java

    • mssql-server-extensibility-java-15.0.1000

Limitations

Implied authentication isn't available on Linux. Java code running in the external process can't connect back to the server to access data or other resources.

Resource governance

Linux and Windows have parity for resource governance for external resource pools, but the statistics for sys.dm_resource_governor_external_resource_pools currently have different units on Linux.

Note

The statistics in the following table are sourced from the specified Control Groups (cgroups) subsystems.

Column name Description Value on Linux
peak_memory_kb The maximum memory the resource pool uses. On Linux, this statistic is sourced from the memory subsystem, where the value is memory.max_usage_in_bytes
write_io_count The total write IOs issued since the last reset of Resource Governor statistics. On Linux, this statistic is sourced from the blkio subsystem, where the value on the write row is blkio.throttle.io_serviced
read_io_count The total read IOs issued since the last reset of Resource Governor statistics. On Linux, this statistic is sourced from the blkio subsystem, where the value on the read row is blkio.throttle.io_serviced
total_cpu_kernel_ms The cumulative CPU user kernel time in milliseconds since the last reset of Resource Governor statistics. On Linux, this statistic is sourced from the cpuacct subsystem, where the value on the user row is cpuacct.stat
total_cpu_user_ms The cumulative CPU user time in milliseconds since the last reset of Resource Governor statistics. On Linux, this statistic is sourced from the cpuacct subsystem, where the value on the system row is cpuacct.stat
active_processes_count The number of external processes running at the moment of the request. On Linux, this statistic is sourced from the pids subsystem, where the value is pids.current

Related content

  • Last updated on