Instalar a Extensão de Linguagem Java do SQL Server no Windows

  • Artigo

Aplica-se a: SQL Server 2019 (15.x) e versões posteriores

Saiba como instalar o componente Extensão de Linguagem Java para SQL Server no Windows. A Extensão de Linguagem Java faz parte das Extensões de Linguagem do SQL Server.

Observação

Este artigo aborda a instalação da Extensão de Linguagem Java para o SQL Server no Windows. Para Linux, confira Instalar Extensão de Linguagem Java do SQL Server no Linux. Para obter a extensão de linguagem C# no Windows, consulte Instalar a extensão de linguagem .NET do SQL Server no Windows.

Pré-requisitos

Observação

As funcionalidades de recursos e as opções de instalação variam entre as versões do SQL Server. Use a lista suspensa seletor de versão para escolher a versão apropriada do SQL Server.

  • A Instalação do SQL Server será necessária se você quiser instalar suporte para a Extensão de Linguagem Java.

  • Você pode baixar e instalar qualquer runtime Java conforme desejado, incluindo o build mais recente da Microsoft do OpenJDK ou o runtime Java licenciado oficialmente. No SQL Server 2022 (16.x) e versões posteriores, o runtime Java não é instalado pela configuração do SQL Server.

  • Uma instância do mecanismo de banco de dados é necessária. Não é possível instalar apenas os recursos da Extensão de Linguagem Java, embora você possa adicioná-los incrementalmente a uma instância existente.

  • Para fins de continuidade de negócios, há suporte a grupos de disponibilidade Always On para Extensões de Linguagem. Você precisa instalar extensões de linguagem e configurar pacotes em cada nó. Também há suporte para a instalação da Extensão de Linguagem Java em uma instância de cluster de failover no SQL Server.

  • Não instale Extensões de Linguagem do SQL Server nem a Extensão de Linguagem Java em um controlador de domínio. A parte da configuração das Extensões de Linguagem falhará.

  • As Extensões de Linguagem e os Serviços de Machine Learning são instalados por padrão em Clusters de Big Data do SQL Server. Se você usa Clusters de Big Data, não precisa seguir as etapas deste artigo. Para obter mais informações, consulte Executar scripts do Python e do R com serviços do Machine Learning em Clusters de Big Data do SQL Server 2019.

Importante

Após a conclusão da instalação, conclua as etapas de pós-configuração descritas neste artigo. Essas etapas incluem a habilitação do SQL Server para usar código externo e a adição de contas necessárias para o SQL Server executar o código Java em seu nome. Geralmente, as alterações na configuração exigem uma reinicialização da instância ou do serviço Launchpad.

Java JRE ou JDK

Observação

As funcionalidades de recursos e as opções de instalação variam entre as versões do SQL Server. Use a lista suspensa seletor de versão para escolher a versão apropriada do SQL Server.

Com o SQL Server 2022 (16.x), você pode baixar e instalar qualquer runtime do Java, incluindo o mais recente Build da Microsoft do OpenJDK ou o runtime do Java licenciado oficialmente.

No momento, o Java 11 é a versão com suporte no Windows. O JRE (Java Runtime Environment) é o requisito mínimo, mas o JDK (Java Development Kit) será útil se você precisar do compilador e dos pacotes de desenvolvimento Java. Como o JDK é totalmente inclusivo, se você instalar o JDK, o JRE não será necessário. No Windows, recomendamos instalar o JDK na pasta /Program Files/ padrão, se possível. Caso contrário, será necessária uma configuração adicional para conceder permissões a executáveis. Para obter mais informações, confira a seção conceder permissões (Windows) neste documento.

Há duas maneiras de instalar e usar o Java com o SQL Server 2019 (15.x) e versões posteriores:

  1. Use o runtime padrão do Java, que está incluído com a instalação do SQL Server.

    A tabela a seguir lista as versões padrão do Java incluídas na instalação:

    Versão do SQL Server Versão do Java padrão
    SQL Server 2019 (15.x) CU 23 e versões posteriores Microsoft Build do OpenJDK 11.0.19
    SQL Server 2019 (15.x) RTM - CU22 Azul Zulu JRE 11.0.3

  2. Usar a distribuição Java de sua preferência em vez do runtime do Java padrão.

    No momento, o Java 11 é a versão com suporte no Windows. O JRE (Java Runtime Environment) é o requisito mínimo, mas o JDK (Java Development Kit) será útil se você precisar do compilador e dos pacotes de desenvolvimento Java. Como o JDK é totalmente inclusivo, se você instalar o JDK, o JRE não será necessário. No Windows, recomendamos instalar o JDK na pasta /Program Files/ padrão, se possível. Caso contrário, será necessária uma configuração adicional para conceder permissões a executáveis. Para obter mais informações, confira a seção conceder permissões (Windows) neste documento.

Observação

Considerando que o Java é compatível com versões anteriores, tais versões podem funcionar, mas a versão compatível e testada para o SQL Server 2019 (15.x) é o Java 11.

Obtenha a mídia de instalação

O local de download para SQL Server depende da edição:

  • Edições SQL Server Enterprise, Standard e Express. Essas edições são licenciadas para uso em produção. Para as edições Enterprise e Standard, entre em contato com seu fornecedor de software para obter a mídia de instalação. Você pode encontrar informações de compra e um diretório de parceiros da Microsoft no site de compras da Microsoft.

  • A última edição gratuita.

Executar a instalação

Para instalações locais, você deve executar a Instalação como um administrador. Se você instalar o SQL Server de um compartilhamento remoto, deverá usar uma conta de domínio que tenha permissões de leitura e de execução no compartilhamento remoto.

  1. Inicie o assistente de instalação do SQL Server.

  2. Na guia Instalação, selecione Nova instalação autônoma do SQL Server ou adicionar recursos a uma instalação existente.

  1. Na página Seleção de Recursos , selecione estas opções:

    Serviços de mecanismo do banco de dados: para usar as Extensões de Linguagem com o SQL Server, você deverá instalar uma instância do mecanismo de banco de dados. Você pode usar uma instância padrão ou nomeada.

    Serviços de Machine Learning e Extensões de Linguagem: essa opção instala o componente Extensões de Linguagem que dá suporte à execução de código Java.

    Captura de tela das opções de funcionalidades para extensões de linguagem.

    1. Se você escolher Java na etapa anterior para instalar o runtime do Java padrão, a página Localização de Instalação do Java será exibida.

      Instale o Java padrão incluído nesta instalação. A opção para Fornecer a localização de uma versão diferente instalada neste computador não é usada para Extensões de Linguagem.

      Captura de tela do local de instalação do Java.

  1. Na página Seleção de Recursos , selecione estas opções:

    Serviços de mecanismo do banco de dados: para usar as Extensões de Linguagem com o SQL Server, você deverá instalar uma instância do mecanismo de banco de dados. Você pode usar uma instância padrão ou nomeada.

    Serviços de Machine Learning e Extensões de Linguagem: essa opção instala o componente Extensões de Linguagem que dá suporte à execução de código Java.

    Captura de tela das funcionalidades da instância.

  1. Na página Pronto para instalar, verifique se essas seleções estão incluídas e selecione Instalar.

    • Serviços do Mecanismo de Banco de Dados
    • Serviços de Machine Learning e Extensões de Linguagem

    Observação da localização da pasta no caminho ..\Setup Bootstrap\Log em que os arquivos de configuração são armazenados. Quando a instalação for concluída, você poderá examinar os componentes instalados no arquivo de Resumo.

  2. Após a conclusão da instalação, se você receber instruções para reiniciar o computador, faça-o agora. É importante ler a mensagem do assistente de instalação ao concluir a configuração. Para saber mais, veja Exibir e ler arquivos de log da Instalação do SQL Server.

Adicionar a variável JRE_HOME

JRE_HOME é uma variável de ambiente do sistema que especifica a localização do interpretador de Java. Nesta etapa, crie uma variável de ambiente do sistema para ela no Windows.

  1. Localize e copie o caminho inicial do JRE.

    Por exemplo, o caminho inicial do JRE do runtime do Java padrão Zulu JRE 11.0.3 é %ProgramFiles%\Microsoft SQL Server\MSSQL15.MSSQLSERVER\MSSQL\Binn\AZUL-OpenJDK-JRE\.

    Dependendo do seu caminho de instalação do SQL Server ou se você escolheu outro runtime do Java, sua localização do JDK ou JRE pode ser diferente do caminho no exemplo anterior. Mesmo se você tiver um JDK instalado, geralmente obterá uma subpasta do JRE como parte dessa instalação. Portanto, aponte para a pasta do JRE nesse caso. A extensão Java tenta carregar o jvm.dll do caminho %JRE_HOME%\bin\server.

  1. Localize e copie o caminho inicial do JRE.

    O caminho depende do runtime e das opções de instalação.

    A extensão Java tenta carregar o jvm.dll do caminho %JRE_HOME%\bin\server.

  1. No Painel de Controle, abra Sistema e Segurança, abra Sistema e selecione Propriedades Avançadas do Sistema.

  2. Selecione Variáveis de Ambiente.

  3. Crie uma variável do sistema para JRE_HOME com o valor do caminho JDK/JRE (encontrado na etapa 1).

  1. Reinicie Launchpad.

    1. Abra o SQL Server Configuration Manager.

    2. Em Serviços do SQL Server, clique com o botão direito do mouse no SQL Server Launchpad e selecione Reiniciar.

  1. Registrar a extensão de linguagem. Siga estas etapas para baixar e registrar a extensão de linguagem do Java, que é usada para o runtime personalizado do Java.

    1. Baixe o arquivo java-lang-extension-windows-release.zip da extensão de linguagem Java para o repositório GitHub do SQL Server. Baixar o arquivo mais recente do Windows java-lang-extension-windows.zip. Se você não tiver instalado o Java padrão a partir da Instalação do SQL Server, verifique se a versão do JRE corresponde àquela que foi baixada do GitHub. Caso prefira usar sua própria versão do JRE instalada, talvez seja necessário compilar java-lang-extension a partir do código-fonte do GitHub.

    2. Use o Azure Data Studio para se conectar à sua instância do SQL Server e execute o comando T-SQL a seguir para registrar a extensão de linguagem do Java com CREATE EXTERNAL LANGUAGE.

    3. Modifique o caminho na instrução de maneira a refletir a localização do arquivo zip da extensão de linguagem baixado (java-lang-extension-windows-release.zip) e a localização da sua instalação personalizada do Java (%ProgramFiles%\Python).

    CREATE EXTERNAL LANGUAGE [Java]
FROM (CONTENT = N'C:\path\to\java-lang-extension-windows-release.zip',
    FILE_NAME = 'javaextension.dll',
    ENVIRONMENT_VARIABLES = N'{"JAVAHOME": "C:\\Program Files\\Java"}');
GO

  2. Reinicie Launchpad.

    1. Abra o SQL Server Configuration Manager.

    2. Em Serviços do SQL Server, clique com o botão direito do mouse no SQL Server Launchpad e selecione Reiniciar.

Permitir acesso a uma pasta JRE não padrão

Se você não instalou o Java incluído com o SQL Server e não instalou o Java em /Program Files, será necessário executar as etapas a seguir.

Se você não instalou o Java em arquivos de programa, será necessário executar as etapas a seguir.

Execute os comandos icacls em uma linha com privilégios elevados para permitir acesso ao SQLRUsergroup e às contas de serviço do SQL Server (em ALL_APPLICATION_PACKAGES) para acessar o JRE. Os comandos permitem recursivamente acesso a todos os arquivos e pastas no caminho de diretório especificado.

  1. Conceder permissões SQLRUserGroup

    Para uma instância nomeada, acrescente o nome da instância a SQLRUsergroup (por exemplo, SQLRUsergroupINSTANCENAME).

    icacls "<PATH to JRE>" /grant "SQLRUsergroup":(OI)(CI)RX /T

    Você poderá ignorar esta etapa se tiver instalado o JDK/JRE na pasta padrão em arquivos de programas no Windows.

  2. Conceder permissões AppContainer. Este comando concede permissões para a SID S-1-15-2-1 do computador, que é equivalente a ALL APPLICATION PACKAGES em uma versão em inglês do Windows. Como alternativa, é possível usar icacls "<PATH to JRE>" /grant "ALL APPLICATION PACKAGES":(OI)(CI)RX /T em uma versão em inglês do Windows.

    icacls "<PATH to JRE>" /grant *S-1-15-2-1:(OI)(CI)RX /T

Reinicie o serviço.

Quando a instalação for concluída, reinicie o mecanismo de banco de dados antes de prosseguir para a próxima etapa, habilitando a execução do script.

Reiniciar o serviço também reinicia automaticamente o serviço SQL Server Launchpad relacionado.

Você pode reiniciar o serviço usando o clique com o botão direito do mouse no comando Reiniciar para a instância no SSMS com o painel Serviços no Painel de Controle ou usando o SQL Server Configuration Manager.

Habilitar a execução do script

  1. Abra o SQL Server Management Studio. Conecte-se à instância em que você instalou as Extensões de Linguagem, selecione Nova Consulta para abrir uma janela de consulta e execute o seguinte comando:

    EXEC sp_configure;

    O recurso está desativado (value é 0) por padrão e deve ser habilitado explicitamente por um administrador para que você possa executar o código Java.

  2. Para habilitar o recurso de script externo, execute a instrução a seguir:

    EXEC sp_configure 'external scripts enabled', 1
GO
RECONFIGURE WITH OVERRIDE

    Se você já habilitou o recurso para os Serviços de Machine Learning, não execute a reconfiguração uma segunda vez para as Extensões de Linguagem. A plataforma de extensibilidade subjacente dá suporte a ambos.

Registrar linguagem externa

Para cada banco de dados no qual você deseja usar extensões de linguagem, é necessário registrar a linguagem externa com CREATE EXTERNAL LANGUAGE.

O exemplo a seguir adiciona uma linguagem externa chamada Java a um banco de dados no SQL Server no Windows.

CREATE EXTERNAL LANGUAGE Java
FROM (CONTENT = N'<path-to-zip>', FILE_NAME = 'javaextension.dll');
GO

Para obter mais informações, confira CREATE EXTERNAL LANGUAGE.

Verifique a instalação

Verifique o status de instalação ad instância nos logs de instalação.

Use as etapas a seguir para verificar se todos os componentes usados para iniciar o script externo estão em execução.

  1. No SQL Server Management Studio ou o Azure Data Studio, abra uma nova janela de consulta e execute a instrução a seguir:

    EXEC sp_configure 'external scripts enabled';

    O run_value agora está definido como 1.

  2. Abra o painel Serviços ou o SQL Server Configuration Manager e verifique se o serviço SQL Server Launchpad está em execução. Você deve ter um serviço para cada instância do mecanismo de banco de dados que tem extensões de linguagem instaladas. Para obter mais informações sobre o serviço, confira Arquitetura de extensibilidade nas Extensões de Linguagem do SQL Server.

Configuração adicional

Se a etapa de verificação tiver sido bem-sucedida, você poderá executar o Código Java do SQL Server Management Studio, Azure Data Studio, Visual Studio Code ou de qualquer outro cliente que pode enviar instruções T-SQL para o servidor.

Se você receber um erro ao executar o comando, examine as etapas de configuração adicionais nesta seção. Talvez seja necessário realizar configurações apropriadas extras para o serviço ou banco de dados.

No nível da instância, a configuração adicional pode incluir:

No banco de dados, talvez você precise das seguintes atualizações de configuração:

Observação

Se a configuração adicional for necessária depende do seu esquema de segurança, em que você instalou o SQL Server e como você espera que os usuários se conectem ao banco de dados e executem scripts externos.

Otimizações sugeridas

Agora que tudo está funcionando, talvez convenha também otimizar o servidor para dar suporte à Extensão de Linguagem Java.

Otimizar o servidor para a Extensão de Linguagem Java

As configurações padrão da instalação do SQL Server destinam-se a otimizar o equilíbrio do servidor para uma variedade de serviços compatíveis com o mecanismo de banco de dados, que podem incluir processos ETL (incluir, transformar e carregar), relatórios, auditoria e aplicativos que usam os dados do SQL Server. Portanto, nas configurações padrão, você pode achar que esses recursos para extensões de linguagem estão algumas vezes restritos ou limitados, especialmente em operações com uso intensivo de memória.

Para verificar se os trabalhos de extensão de linguagem são priorizados e têm os recursos apropriados, recomendamos que você use o SQL Server Resource Governor para configurar um pool de recursos externo. Talvez seja interessante alterar a quantidade de memória alocada ao mecanismo de banco de dados ou aumentar o número de contas executadas no serviço SQL Server Launchpad.

Se você usa a Edição Standard e não tiver o Resource Governor, poderá usar DMVs (Exibições de Gerenciamento Dinâmico) e Eventos Estendidos, assim como o monitoramento de eventos do Windows, para ajudar a gerenciar os recursos do servidor.

Próxima etapa

Os desenvolvedores do Java podem começar com alguns exemplos simples e aprender os fundamentos de como o Java funciona com o SQL Server. Para a próxima etapa, confira o link a seguir:

Tutorial: Expressões regulares com Java