Install SQL Server Java Language Extension on Linux

Applies to: SQL Server 2019 (15.x) - 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 Linux version must be supported by SQL Server, but doesn't include the Docker Engine. Supported versions include:

  • Red Hat Enterprise Linux (RHEL)
  • SUSE Linux Enterprise Server (SLES)
  • Ubuntu

• You should have a tool for running Transact-SQL (T-SQL) commands. A query editor is necessary for post-install configuration and validation. We recommend Azure Data Studio, a free download that runs on Linux.

• Language Extensions is also supported on Linux containers. We don't provide prebuilt containers with Language Extensions, but you can create one from the SQL Server containers 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. For more information, see Run Python and R scripts with Machine Learning Services on SQL Server 2019 Big Data Clusters.

Package list

On an internet-connected device, packages are downloaded and installed independently of the Database Engine 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	Applies to: SQL Server 2019 (15.x) on Linux only Extensibility framework used for the Java language extension and includes a supported Java runtime

Install Java language extension

You can download and install any Java runtime as desired, including the latest Microsoft Build of OpenJDK or 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.

Post-install config (required)

1. Grant permissions on Linux

   You don't need to perform this step if you use external libraries. The recommended way of working is using external libraries. 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. We recommend always putting 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 the jar file to read/execute.

   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 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 using 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 an extensibility-related setting is modified.

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

5. Enable external script execution using Azure Data Studio, or another tool like SQL Server Management Studio (Windows only), that runs T-SQL.

   EXECUTE sp_configure 'external scripts enabled', 1;
   
   RECONFIGURE WITH OVERRIDE;
   

6. Restart the mssql-launchpadd service again.

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

Register external language

For each database you want to use language extensions in, you need to 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 is used to determine the path to find and initialize the JVM from.

The CREATE EXTERNAL LANGUAGE DDL provides a parameter (ENVIRONMENT_VARIABLES) to set environment variables specifically for the process hosting the extension. This process is the recommended and most effective way to set environment variables required by external language extensions.

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 creation of the JAVA_HOME environment variable.

To validate installation, run a T-SQL script that executes a system stored procedure invoking Java. You need a query tool for this task. Azure Data Studio is a good choice. Other commonly used tools such as SQL Server Management Studio is Windows-only. If you have a Windows computer with these tools, use it to connect to your Linux installation of the Database Engine.

Limitations

Implied authentication is currently not available on Linux at this time, which means you can't connect back to the server from in-progress Java to access data or other resources.

Resource governance

There's parity between Linux and Windows 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

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 amount of memory used for the resource pool.	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 Resource Governor statistics were reset.	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 Resource Governor statistics were reset.	On Linux, this statistic is sourced from the blkio subsystem, where value on the read row is blkio.throttle.io_serviced
total_cpu_kernel_ms	The cumulative CPU user kernel time in milliseconds since the Resource Governor statistics were reset.	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 Resource Governor statistics were reset.	On Linux, this statistic is sourced from the cpuacct subsystem, where the value on the system row value 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

• Tutorial: Search for a string using regular expressions (regex) in Java