CREATE EXTERNAL LIBRARY(Transact-SQL)

적용 대상: SQL Server 2017(14.x) 이상 버전 Azure SQL Managed Instance

지정된 바이트 스트림 또는 파일 경로에서 데이터베이스에 R, Python 또는 Java 패키지 파일을 업로드합니다. 이 문은 데이터베이스 관리자가 SQL Server에서 지원하는 새 외부 언어 런타임 및 OS 플랫폼에 필요한 아티팩트를 업로드하는 일반적인 메커니즘으로 사용됩니다.

참고 항목

SQL Server 2017(14.x)에서는 R 언어 및 Windows 플랫폼이 지원됩니다. Windows 및 Linux 플랫폼의 R, Python 및 외부 언어는 SQL Server 2019(15.x) 이상 버전에서 지원됩니다.

SQL Server 2019용 구문

CREATE EXTERNAL LIBRARY library_name
[ AUTHORIZATION owner_name ]
FROM <file_spec> [ ,...2 ]
WITH ( LANGUAGE = <language> )
[ ; ]

<file_spec> ::=
{
    (CONTENT = { <client_library_specifier> | <library_bits> }
    [, PLATFORM = <platform> ])
}

<client_library_specifier> :: =
{
    '[file_path\]manifest_file_name'
}

<library_bits> :: =
{
      varbinary_literal
    | varbinary_expression
}

<platform> :: =
{
      WINDOWS
    | LINUX
}

<language> :: =
{
      'R'
    | 'Python'
    | <external_language>
}

인수

LIBRARY_NAME

인스턴스에 업로드된 라이브러리는 퍼블릭 또는 프라이빗일 수 있습니다. 라이브러리가 멤버 dbo에 의해 만들어진 경우 라이브러리는 공용이며 모든 사용자와 공유할 수 있습니다. 그렇지 않으면 라이브러리는 해당 사용자에게만 프라이빗으로 제공됩니다.

라이브러리 이름은 특정 사용자 또는 소유자의 컨텍스트 내에서 고유해야 합니다. 예를 들어 두 명의 사용자가 RUser1RUser2 개별적으로 그리고 개별적으로 R 라이브러리 ggplot2를 업로드할 수 있습니다. 그러나 RUser1 최신 버전의 ggplot2를 업로드하려면 두 번째 인스턴스의 이름을 다르게 지정하거나 기존 라이브러리를 바꿔야 합니다.

라이브러리 이름은 임의로 할당할 수 없습니다. 라이브러리 이름은 외부 스크립트에서 라이브러리를 로드하는 데 필요한 이름과 동일해야 합니다.

OWNER_NAME

외부 라이브러리를 소유하는 사용자 또는 역할의 이름을 지정합니다. 값을 지정하지 않으면 현재 사용자에게 소유권이 부여됩니다.

데이터베이스 소유자가 소유한 라이브러리는 데이터베이스 및 런타임에 대한 전역으로 간주됩니다. 즉, 데이터베이스 소유자는 많은 사용자가 공유하는 공통 라이브러리 또는 패키지 집합을 포함하는 라이브러리를 만들 수 있습니다. 사용자가 아닌 사용자가 외부 라이브러리를 dbo 만들 때 외부 라이브러리는 해당 사용자에 대해서만 비공개입니다.

사용자가 RUser1 외부 스크립트를 실행하면 값 libPath 에 여러 경로가 포함될 수 있습니다. 첫 번째 경로는 항상 데이터베이스 소유자가 만든 공유 라이브러리의 경로입니다. 두 번째 부분은 libPath .에 의해 RUser1개별적으로 업로드된 패키지가 포함된 경로를 지정합니다.

FILE_SPEC

특정 플랫폼에 대한 패키지의 콘텐츠를 지정합니다. 플랫폼당 하나의 파일 아티팩트만 지원됩니다.

로컬 경로 또는 네트워크 경로 형식으로 파일을 지정할 수 있습니다.

SQL Server는 <client_library_specifier>지정된 파일에 액세스하려고 할 때 현재 Windows 로그인의 보안 컨텍스트를 가장합니다. UNC 경로(네트워크 위치)를 지정하는 경우 <client_library_specifier> 위임 제한으로 인해 현재 로그인의 가장이 네트워크 위치로 전달되지 않습니다. 이 경우에는 SQL Server 서비스 계정의 보안 컨텍스트를 사용하여 액세스합니다. 자세한 내용은 자격 증명(데이터베이스 엔진)을 참조하세요.

필요에 따라 파일에 대한 OS 플랫폼을 지정할 수 있습니다. 특정 언어 또는 런타임에 대해 각 OS 플랫폼에 대해 하나의 파일 아티팩트 또는 콘텐츠만 허용됩니다.

LIBRARY_BITS

패키지의 콘텐츠를 어셈블리와 유사한 16진수 리터럴로 지정합니다.

이 옵션은 라이브러리를 만들거나 기존 라이브러리를 변경해야 하지만(필요한 사용 권한이 있음) 서버의 파일 시스템이 제한되며 라이브러리 파일을 서버에서 액세스할 수 있는 위치에 복사할 수 없는 경우에 유용합니다.

플랫폼

라이브러리의 콘텐츠에 대한 플랫폼을 지정합니다. 이 값은 기본적으로 SQL Server가 실행 중인 호스트 플랫폼으로 설정됩니다. 따라서 사용자는 값을 지정할 필요가 없습니다. 여러 플랫폼이 지원되거나 사용자가 다른 플랫폼을 지정해야 하는 경우 필요합니다. SQL Server 2019(15.x)에서 Windows 및 Linux는 지원되는 플랫폼입니다.

LANGUAGE

패키지의 언어를 지정합니다. 값은 외부 언어의 이름일 수 있습니다RPython(CREATE EXTERNAL LANGUAGE 참조).

설명

R 언어의 경우 파일을 사용할 때 확장명에서 압축된 보관 파일 형식으로 .zip 패키지를 준비해야 합니다.

Python 언어의 경우 압축된 보관 파일 형식으로 파일 또는 .zip 파일의 패키지를 .whl 준비해야 합니다. 패키지가 이미 파일인 .zip 경우 새 .zip 파일에 포함되어야 합니다. 패키지를 직접 .whl 업로드하거나 .zip 파일을 업로드하는 것은 현재 지원되지 않습니다.

이 문은 CREATE EXTERNAL LIBRARY 라이브러리 비트를 데이터베이스에 업로드합니다. 라이브러리는 사용자가 sp_execute_external_script를 사용하여 외부 스크립트를 실행하고 패키지 또는 라이브러리를 호출할 때 설치됩니다.

인스턴스에 업로드된 라이브러리는 퍼블릭 또는 프라이빗일 수 있습니다. 라이브러리가 멤버 dbo에 의해 만들어진 경우 라이브러리는 공용이며 모든 사용자와 공유할 수 있습니다. 그렇지 않으면 라이브러리는 해당 사용자에게만 프라이빗으로 제공됩니다.

시스템 패키지라고 하는 여러 패키지는 SQL 인스턴스에 미리 설치됩니다. 시스템 패키지를 추가, 업데이트 또는 제거할 수 없습니다.

사용 권한

CREATE EXTERNAL LIBRARY 권한이 필요합니다. 기본적으로 db_owner 역할의 멤버인 dbo가 있는 모든 사용자에게는 외부 라이브러리를 만들 수 있는 권한이 있습니다. 다른 모든 사용자의 경우 권한 으로 지정 CREATE EXTERNAL LIBRARY 하여 GRANT 문을 사용하여 명시적으로 권한을 부여해야 합니다.

SQL Server 2019(15.x)에서는 사용 권한 외에도 CREATE EXTERNAL LIBRARY 외부 언어에 대한 외부 라이브러리를 만들려면 외부 언어에 대한 참조 권한도 필요합니다.

GRANT REFERENCES ON EXTERNAL LANGUAGE::Java to user
GRANT CREATE EXTERNAL LIBRARY to user

라이브러리를 수정하려면 별도의 권한이 ALTER ANY EXTERNAL LIBRARY필요합니다.

파일 경로를 사용하여 외부 라이브러리를 만들려면 사용자는 Windows 인증 로그인 또는 sysadmin 고정 서버 역할의 멤버여야 합니다.

예제

데이터베이스에 외부 라이브러리 추가

다음 예제에서는 데이터베이스에 호출 customPackage 된 외부 라이브러리를 추가합니다.

CREATE EXTERNAL LIBRARY customPackage
    FROM (CONTENT = 'C:\Program Files\Microsoft SQL Server\MSSQL14.MSSQLSERVER\customPackage.zip')
    WITH (LANGUAGE = 'R');

라이브러리가 인스턴스에 성공적으로 업로드되면 사용자가 프로시저를 sp_execute_external_script 실행하여 라이브러리를 설치합니다.

EXECUTE sp_execute_external_script
    @language = N'R',
    @script = N'library(customPackage)';

SQL Server 2019(15.x)의 Python 언어의 경우 이 예제는 .으로 'Python'바꿔 'R' 서도 작동합니다.

종속성이 있는 패키지 설치

설치하려는 패키지에 종속성이 있는 경우 첫 번째 수준 및 두 번째 수준 종속성을 모두 분석하고 대상 패키지를 설치 하기 전에 필요한 모든 패키지를 사용할 수 있는지 확인하는 것이 중요합니다.

예를 들어 새 패키지를 packageA설치하려는 경우:

• packageA 에 종속성이 있습니다. packageB
• packageB 에 종속성이 있습니다. packageC

설치packageA에 성공하려면 SQL Server에 추가하는 packageB 동시에 라이브러리를 packageCpackageA 만들어야 합니다. 필요한 패키지 버전도 확인해야 합니다.

실제로 인기 있는 패키지에 대한 패키지 종속성은 이 예제보다 더 복잡합니다. 예를 들어 ggplot2 에는 30개 이상의 패키지가 필요할 수 있으며 해당 패키지에는 서버에서 사용할 수 없는 추가 패키지가 필요할 수 있습니다. 누락된 패키지 또는 잘못된 패키지 버전을 사용하면 설치가 실패할 수 있습니다.

패키지 매니페스트를 보는 것만으로는 모든 종속성을 확인하기 어려울 수 있으므로 miniCRAN 과 같은 패키지를 사용하여 설치를 성공적으로 완료하는 데 필요한 모든 패키지를 식별합니다.

• 대상 패키지 및 해당 종속성을 업로드합니다. 모든 파일은 서버에서 액세스할 수 있는 폴더에 있어야 합니다.

  CREATE EXTERNAL LIBRARY packageA
  FROM (CONTENT = 'C:\Program Files\Microsoft SQL Server\MSSQL14.MSSQLSERVER\packageA.zip')
  WITH (LANGUAGE = 'R');
  GO
  
  CREATE EXTERNAL LIBRARY packageB FROM (CONTENT = 'C:\Program Files\Microsoft SQL Server\MSSQL14.MSSQLSERVER\packageB.zip')
  WITH (LANGUAGE = 'R');
  GO
  
  CREATE EXTERNAL LIBRARY packageC FROM (CONTENT = 'C:\Program Files\Microsoft SQL Server\MSSQL14.MSSQLSERVER\packageC.zip')
  WITH (LANGUAGE = 'R');
  GO
  

• 먼저 필요한 패키지를 설치합니다.

  필요한 패키지가 인스턴스에 이미 업로드된 경우 다시 추가할 필요는 없습니다. 기존 패키지가 올바른 버전인지 확인해야 합니다.

  필수 패키지 packageC 이며 packageB 패키지를 설치하기 위해 처음 실행되는 경우 sp_execute_external_script 올바른 순서로 설치 packageA됩니다.

  그러나 필요한 패키지를 사용할 수 없는 경우 대상 패키지 packageA 설치가 실패합니다.

  EXECUTE sp_execute_external_script
      @language = N'R',
      @script = N'
      # load the desired package packageA
      library(packageA)
      ';
  

SQL Server 2019(15.x)의 Python 언어의 경우 이 예제는 .으로 'Python'바꿔 'R' 서도 작동합니다.

바이트 스트림에서 라이브러리 만들기

서버의 위치에 패키지 파일을 저장할 수 없는 경우 패키지 내용을 변수에 전달할 수 있습니다. 다음 예제에서는 비트를 16진수 리터럴로 전달하여 라이브러리를 만듭니다.

CREATE EXTERNAL LIBRARY customLibrary FROM (CONTENT = 0xABC123...) WITH (LANGUAGE = 'R');

SQL Server 2019(15.x)의 Python 언어의 경우 이 예제는 .으로 Python바꿔 R 서도 작동합니다.

참고 항목

이 코드 샘플은 구문만 보여 줍니다. 이진 값 CONTENT = 은 가독성을 위해 잘리며 작업 라이브러리를 만들지 않습니다. 이진 변수의 실제 내용이 더 깁니다.

기존 패키지 라이브러리 변경

ALTER EXTERNAL LIBRARY DDL 문을 사용하여 새 라이브러리 콘텐츠를 추가하거나 기존 라이브러리 콘텐츠를 수정할 수 있습니다. 기존 라이브러리를 수정하려면 권한이 필요합니다 ALTER ANY EXTERNAL LIBRARY .

자세한 내용은 ALTER EXTERNAL LIBRARY를 참조하세요.

데이터베이스에 Java .jar 파일 추가

다음 예제에서는 데이터베이스에 호출 customJar 된 외부 .jar 파일을 추가합니다.

CREATE EXTERNAL LIBRARY customJar
    FROM (CONTENT = 'C:\Program Files\Microsoft SQL Server\MSSQL15.MSSQLSERVER\customJar.jar')
    WITH (LANGUAGE = 'Java');

라이브러리가 인스턴스에 성공적으로 업로드되면 사용자가 프로시저를 sp_execute_external_script 실행하여 라이브러리를 설치합니다.

EXECUTE sp_execute_external_script
    @language = N'Java',
    @script = N'customJar.MyCLass.myMethod',
    @input_data_1 = N'SELECT * FROM dbo.MyTable'
    WITH RESULT SETS
(
        (column1 INT)
);

Windows 및 Linux 모두에 대한 외부 패키지 추가

Windows용 하나와 Linux용 하나로 최대 두 개의 <file_spec>를 지정할 수 있습니다.

CREATE EXTERNAL LIBRARY lazyeval
    FROM (CONTENT = 'C:\Program Files\Microsoft SQL Server\MSSQL15.MSSQLSERVER\packageA.zip', PLATFORM = WINDOWS),(CONTENT = 'C:\Program Files\Microsoft SQL Server\MSSQL15.MSSQLSERVER\packageA.tar.gz', PLATFORM = LINUX)
    WITH (LANGUAGE = 'R');

패키지를 설치하는 데 사용하는 sp_execute_external_script 경우 SQL Server 인스턴스가 실행 중인 플랫폼에 따라 해당 플랫폼에 대한 라이브러리 콘텐츠가 사용됩니다.

EXECUTE sp_execute_external_script
    @LANGUAGE = N'R',
    @SCRIPT = N'
library(packageA)';

관련 콘텐츠

• ALTER EXTERNAL LIBRARY(Transact-SQL)
• DROP EXTERNAL LIBRARY(Transact-SQL)
• sys.external_library_files
• sys.external_libraries