sqlcmd 유틸리티의 명령

적용 대상:SQL 서버Azure SQL DatabaseAzure SQL Managed InstanceAzure Synapse Analytics분석 플랫폼 시스템(PDW)Microsoft Fabric의 SQL 데이터베이스

sqlcmd 유틸리티는 Transact-SQL 문, 시스템 프로시저 및 스크립트 파일을 허용합니다.

sqlcmd 내의 Transact-SQL 문 외에도 다음 명령을 사용합니다.

• GO [ <count> ]
• :List
• [:]RESET
• :Error
• [:]ED ¹
• :Out
• [:]!!
• :Perftrace
• [:]QUIT
• :Connect
• [:]EXIT
• :On Error
• :r
• :Help
• :ServerList ¹
• :XML [ ON | OFF ] ¹
• :Setvar
• :Listvar

¹ Linux 또는 macOS에서는 지원되지 않습니다.

sqlcmd 명령을 사용하는 경우 다음 사항에 유의하세요.

• 를 제외한 모든 GO 명령은 콜론(:)으로 시작해야 합니다.

  Important

  기존 osql 스크립트와의 이전 버전과의 호환성을 유지하기 위해 일부 명령은 콜론 없이 작동합니다(표시 [:]됨).

• sqlcmd 는 명령이 줄의 시작 부분에 표시되는 경우에만 인식합니다.

• 모든 sqlcmd 명령은 대/소문자를 구분하지 않습니다.

• 각 명령을 별도의 줄에 입력해야 합니다. Transact-SQL 문이나 다른 명령을 사용하여 명령을 따를 수 없습니다.

• 명령은 즉시 실행됩니다. Transact-SQL 문과 같이 실행 버퍼에 배치되지 않습니다.

명령어 편집

[:]ED

텍스트 편집기를 시작합니다. 이 편집기를 사용하여 현재 Transact-SQL 일괄 처리 또는 마지막 실행 일괄 처리를 편집합니다. 마지막 실행 일괄 처리를 편집하려면 마지막 일괄 처리가 ED 실행을 완료한 직후에 명령을 입력합니다.

환경 변수는 SQLCMDEDITOR 텍스트 편집기를 정의합니다. 기본 편집기는 Edit입니다. 편집기를 변경하려면 SQLCMDEDITOR 환경 변수를 설정합니다. 예를 들어 편집기를 Microsoft 메모장에서 설정하려면 다음 명령을 입력합니다.

SET SQLCMDEDITOR=notepad

[:]RESET

문장 캐시를 지웁니다.

:List

문장 캐시의 내용을 출력합니다.

Variables

:Setvar <var> [ "value" ]

sqlcmd 스크립팅 변수를 정의합니다. 스크립팅 변수의 형식은 다음과 같습니다. $(VARNAME)

변수 이름은 대/소문자를 구분하지 않습니다.

스크립팅 변수는 다음과 같은 방법으로 설정할 수 있습니다.

• 명령줄 옵션을 사용하여 암시적으로 설정합니다. 예를 들어 -l 옵션은 SQLCMDLOGINTIMEOUTsqlcmd 변수를 설정합니다.
• :Setvar 명령을 사용하여 명시적으로 설정합니다.
• sqlcmd를 실행하기 전에 환경 변수를 정의합니다.

:Setvar를 사용하여 정의된 변수와 환경 변수의 이름이 같으면 :Setvar를 사용하여 정의된 변수가 우선합니다.

변수 이름에는 빈 공백 문자가 포함되어서는 안 됩니다.

변수 이름은 $(var) 등의 변수 식과 다른 형식이어야 합니다.

스크립팅 변수의 문자열 값에 빈 공백이 포함된 경우 값을 인용 부호로 묶습니다. 스크립팅 변수의 값을 지정하지 않으면 스크립팅 변수가 삭제됩니다.

:Listvar

현재 설정된 스크립팅 변수 목록을 표시합니다.

출력 명령

:Error <filename> | STDERR | STDOUT

오류 출력 전체를 filename으로 지정한 파일이나 stderr, 또는 stdout로 리디렉션합니다. 스크립트에서 :Error 명령이 여러 번 나타날 수 있습니다. 기본적으로 오류 출력은 stderr로 전송됩니다.

• filename

  출력을 받는 파일을 만들고 엽니다. 기존 파일은 0바이트로 잘립니다. 사용 권한 또는 기타 이유로 인해 파일을 사용할 수 없는 경우 출력이 전환되지 않고 마지막으로 지정된 대상 또는 기본 대상은 오류 출력을 받습니다.

• STDERR

  오류 출력을 stderr 스트림으로 전환합니다. 출력이 리디렉션되면 스트림이 리디렉션되는 대상은 오류 출력을 받습니다.

• STDOUT

  오류 출력을 stdout 스트림으로 전환합니다. 출력이 리디렉션되면 스트림이 리디렉션되는 대상은 오류 출력을 받습니다.

:Out <파일 이름> | STDERR | STDOUT

모든 쿼리 결과를 생성하여 filename, stderr, 또는 stdout로 리디렉션합니다. 기본적으로 출력은 stdout로 지정됩니다. 파일이 이미 있는 경우 0바이트로 잘립니다. 스크립트에서 :Out 명령이 여러 번 나타날 수 있습니다.

:Perftrace <파일명> | STDERR | STDOUT

파일 이름, stderr 또는 stdout에 지정된 파일로 모든 성능 추적 정보를 생성하고 리디렉션합니다. 기본적으로 성능 추적의 출력은 stdout로 이동합니다. 기존 파일은 0바이트로 잘립니다. 스크립트에서 :Perftrace 명령이 여러 번 나타날 수 있습니다.

실행 제어 명령

:오류 발생 시 [ 종료 | 무시 ]

스크립트 또는 일괄 처리 실행 중에 오류가 발생할 때 수행할 작업을 설정합니다.

이 exit 옵션을 사용하면 sqlcmd 가 적절한 오류 값으로 종료됩니다.

이 ignore 옵션을 사용하면 sqlcmd 에서 오류를 무시하고 일괄 처리 또는 스크립트를 계속 실행합니다. 기본적으로 sqlcmd 는 오류 메시지를 출력합니다.

[:]QUIT

sqlcmd가 종료됩니다.

[:]EXIT [ ( 명령문 ) ]

문 결과를 SELECT의 반환 값으로 사용합니다. 숫자인 경우 마지막 결과 행의 첫 번째 열이 4바이트 정수(long)로 변환됩니다. MS-DOS, Linux, macOS는 하위 바이트를 부모 프로세스 또는 운영 체제 오류 수준에 전달합니다. Windows 2000 이상 버전에서는 전체 4바이트 정수를 전달합니다. 구문은 :EXIT(query)입니다.

다음은 그 예입니다.

:EXIT(SELECT @@ROWCOUNT)

배치 파일의 일부로 :EXIT 매개 변수를 포함할 수도 있습니다. 예를 들어 명령 프롬프트에서 다음을 입력합니다.

sqlcmd -Q ":EXIT(SELECT COUNT(*) FROM '%1')"

sqlcmd 유틸리티는 괄호(()) 안의 모든 항목을 서버로 보냅니다. 시스템 저장 프로시저가 집합을 선택하고 값을 반환하는 경우 선택 항목만 반환됩니다. 괄호 안에 아무 것도 없는 :EXIT() 문은 그 앞에 있는 모든 명령을 실행하고, 반환 값 없이 종료됩니다.

잘못된 쿼리를 지정하면 sqlcmd 가 반환 값 없이 종료됩니다.

다음은 EXIT 형식 목록입니다.

• :EXIT

  일괄 처리를 실행하지 않고 즉시 종료하고 값을 반환하지 않습니다.

• :EXIT( )

  일괄 처리를 실행한 다음 종료하고 값을 반환하지 않습니다.

• :EXIT(query)

  쿼리를 포함하는 일괄 처리를 실행한 다음 쿼리 결과를 반환한 후 종료합니다.

RAISERROR 스크립트 내에서 사용하고 상태를 127로 올리면 sqlcmd가 종료되고 메시지 ID가 클라이언트에 다시 반환됩니다. 다음은 그 예입니다.

RAISERROR(50001, 10, 127)

이 오류가 발생하면 sqlcmd 스크립트가 종료되고 메시지 ID 50001이 클라이언트에 반환됩니다.

SQL Server에서 반환 값 -1에서 -99까지는 예약되어 있고, sqlcmd는 추가 반환 값을 정의합니다.

GO [개수]

GO는 배치의 끝과 캐시된 Transact-SQL 명령문의 실행을 모두 신호합니다. 일괄 처리는 별도의 일괄 처리로 여러 번 실행됩니다. 단일 배치에서 변수를 두 번 이상 선언할 수 없습니다.

기타 명령

:r <파일 이름>

filename으로 지정된 파일에서 추가적인 Transact-SQL 문과 sqlcmd 명령을 구문 분석하여 문 캐시에 저장합니다. sqlcmd는 시작 디렉터리를 기준으로 파일 이름을 읽습니다.

파일에 Transact-SQL 문이 포함되어 있고 뒤에 GO가 오지 않을 경우 GO 뒤에 오는 줄에 :r를 입력해야 합니다.

sqlcmd 는 일괄 처리 종결자를 발견한 후 파일을 읽고 실행합니다. 여러 :r 명령을 실행할 수 있습니다. 이 파일에는 일괄 처리 종결자를 비롯한 GO 명령이 포함될 수 있습니다.

:ServerList

로컬로 구성된 서버와 네트워크에서 브로드캐스팅 중인 서버의 이름을 나열합니다.

:Connect server_name[\instance_name] [-l timeout] [-U user_name [-P password]] [-N[s|m|o]] [-F hostname_in_certificate]

SQL Server 인스턴스에 연결합니다. 또한 현재 연결을 종료합니다.

• 암호화 옵션(-N[s|m|o]):

  암호화된 연결을 요청하려면 이 옵션을 사용합니다. 포함하지 않는 경우에는 -N, -Nm용 mandatory가 기본값입니다. 이 옵션은 SQL Server 2022(16.x) 및 이전 버전과 호환되지 않게 만드는 변경 사항입니다. 이 경우 -No (대신 optional)가 기본값으로 설정됩니다.

  Value	Description
  -Ns	엄격
  -Nm(기본값)	필수
  -No	선택적

• 인증서의 호스트 이름(-F hostname_in_certificate)

  서버 인증서 유효성 검사 중에 사용할 다른 예상 CN(일반 이름) 또는 SAN(주체 대체 이름)을 지정합니다. 이 옵션이 없으면 인증서 유효성 검사를 통해 인증서의 CN 또는 SAN이 연결 중인 서버 이름과 일치하는지 확인합니다. 예를 들어 DNS 별칭을 사용하는 경우 서버 이름이 CN 또는 SAN과 일치하지 않는 경우 이 매개 변수를 채울 수 있습니다.

• 시간 제한 옵션:

  Value	Behavior
  0	영원히 기다립니다.
  n>0	n 초 동안 대기

  SQLCMDSERVER 스크립팅 변수는 현재 활성 연결을 반영합니다.

  시간 제한을 지정하지 않으면 SQLCMDLOGINTIMEOUT 변수의 값이 기본값입니다.

옵션 또는 환경 변수로 user_name 만 지정하면 sqlcmd 에서 암호를 입력하라는 메시지가 표시됩니다. 사용자에게 SQLCMDUSER 또는 SQLCMDPASSWORD 환경 변수가 설정되어 있는 경우 묻는 메시지가 표시되지 않습니다. 옵션 또는 환경 변수를 제공하지 않으면 Windows 인증 모드를 사용하여 로그인합니다. 예를 들어 통합 보안을 사용하여 SQL Server instance1의 인스턴스인 myserver에 연결하려면 다음 명령을 사용합니다.

:connect myserver\instance1

스크립팅 변수를 사용하는 기본 인스턴스에 myserver 연결하려면 다음 설정을 사용합니다.

:setvar myusername test
:setvar myservername myserver
:connect $(myservername) $(myusername)

[:]!! command

운영 체제 명령을 실행합니다. 운영 체제 명령을 실행하려면 두 개의 느낌표(!!) 뒤에 운영 체제 명령이 있는 줄을 시작합니다. 다음은 그 예입니다.

:!! dir

:XML [ 켜기 | 끄기 ]

자세한 내용은 이 문서의 XML 출력 형식 및 JSON 출력 형식을 참조하세요.

:Help

각 명령에 대한 간단한 설명과 함께 sqlcmd 명령을 나열합니다.

sqlcmd 파일 이름

옵션 또는 명령을 사용하여 -i 입력 파일을 지정합니다:r. 옵션 또는 -o, :Error및 :Out 명령을 사용하여 :Perftrace 출력 파일을 지정합니다. 이러한 파일을 사용하는 경우 다음 지침을 사용합니다.

• 각 , :Error, 및 :Out에 대해 별도의 :Perftrace 값을 사용합니다. 동일한 파일 이름을 사용하는 경우 명령이 입력을 혼합할 수 있습니다.

• 로컬 컴퓨터의 sqlcmd 에서 원격 서버에 있는 입력 파일을 호출하고 파일에 드라이브 파일 경로가 :Out c:\OutputFile.txt포함된 경우 sqlcmd 는 원격 서버가 아닌 로컬 컴퓨터에 출력 파일을 만듭니다.

• 유효한 파일 경로에는 C:\<filename>, \\<Server>\<Share$>\<filename>, "C:\Some Folder\<file name>"이 포함됩니다. 경로에 공백이 있는 경우 인용 부호를 사용합니다.

• 각각의 새 sqlcmd 세션은 이름이 같은 기존 파일을 덮어씁니다.

정보 메시지

sqlcmd 는 서버에서 보내는 모든 정보 메시지를 출력합니다. 다음 예제에서는 sqlcmd 가 Transact-SQL 문을 실행한 후 정보 메시지를 출력합니다.

sqlcmd를 시작합니다. sqlcmd 명령 프롬프트에서 쿼리를 입력합니다.

USE AdventureWorks2025;
GO

Enter 키를 누르면 sqlcmd에서 다음 정보 메시지를 출력합니다.

Changed database context to 'AdventureWorks2025'.

Transact-SQL 쿼리의 출력 형식

sqlcmd는 먼저 선택 목록에서 지정한 열 이름이 포함된 열 머리글을 출력합니다. 열 이름은 SQLCMDCOLSEP 문자로 구분됩니다. 기본적으로 이 열 구분 기호는 공백입니다. 열 이름이 열 너비보다 짧으면 sqlcmd 는 출력을 다음 열까지 공백으로 채 깁니다.

sqlcmd 는 일련의 대시 문자인 구분선을 인쇄합니다. 다음은 출력 예제입니다.

sqlcmd를 시작합니다. sqlcmd 명령 프롬프트에서 쿼리를 입력합니다.

USE AdventureWorks2025;

SELECT TOP (2) BusinessEntityID,
               FirstName,
               LastName
FROM Person.Person;
GO

Enter 키를 누르면 sqlcmd에서 다음 결과 집합을 반환합니다.

BusinessEntityID FirstName    LastName
---------------- ------------ ----------
285              Syed         Abbas
293              Catherine    Abel
(2 row(s) affected)

열 너비 BusinessEntityID 는 4자일 뿐이지만 더 긴 열 이름을 수용하도록 확장됩니다. 기본적으로 sqlcmd 는 출력을 80자로 종료합니다. -w 옵션을 사용하거나 SQLCMDCOLWIDTH 스크립팅 변수를 설정하여 이 너비를 변경할 수 있습니다.

XML 출력 형식

XML 출력은 FOR XML 절의 결과로, 형식이 지정되지 않고 연속 스트림으로 출력됩니다.

XML 출력이 예상되면 :XML ON 명령을 사용합니다.

XML 모드를 해제로 설정하려면 :XML OFF 명령을 사용합니다.

GO 명령은 :XML OFF 명령이 실행되기 전에 나타나서는 안 됩니다. 왜냐하면 :XML OFF 명령은 명령이 발행되면 sqlcmd를 행 기반 출력으로 전환하기 때문입니다.

XML(스트리밍) 데이터 및 행 집합 데이터는 혼합할 수 없습니다. XML 스트림을 :XML ON 출력하는 Transact-SQL 명령문이 실행되기 전에 명령이 실행되지 않은 경우 출력이 왜곡됩니다. 명령이 :XML ON 실행되면 일반 행 집합을 출력하는 Transact-SQL 문을 실행할 수 없습니다.

JSON 출력 형식

JSON 출력이 예상되면 :XML ON 명령을 사용합니다. 그렇지 않으면 출력에 열 이름과 JSON 텍스트가 모두 포함됩니다. 이 출력은 유효한 JSON이 아닙니다.

XML 모드를 해제로 설정하려면 :XML OFF 명령을 사용합니다.

자세한 내용은 이 문서의 XML 출력 형식을 참조하세요.

Microsoft Entra 인증 사용

Microsoft Entra 인증을 사용하는 예제:

sqlcmd -S Target_DB_or_DW.testsrv.database.windows.net  -G  -l 30
sqlcmd -S Target_DB_or_DW.testsrv.database.windows.net -G -U bob@contoso.com -P MyAzureADPassword -l 30

sqlcmd -S Target_DB_or_DW.testsrv.database.windows.net  -G  -l 30
sqlcmd -S Target_DB_or_DW.testsrv.database.windows.net -G -U bob@contoso.com -P MyAzureADPassword -l 30

sqlcmd -S Target_DB_or_DW.testsrv.database.windows.net  -G  -l 30
sqlcmd -S Target_DB_or_DW.testsrv.database.windows.net -G -U bob@contoso.com -P MyAzureADPassword -l 30

관련 콘텐츠

• sqlcmd 유틸리티
• sqlcmd 유틸리티의 설치된 버전 확인
• sqlcmd 유틸리티 시작
• sqlcmd를 사용하여 스크립트 파일에서 T-SQL 실행
• sqlcmd 사용