sqlcmd 유틸리티의 명령

2025-07-04

적용 대상:SQL Server Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System (PDW)Microsoft Fabric의 SQL 데이터베이스

sqlcmd 유틸리티를 사용하면 Transact-SQL 문, 시스템 프로시저 및 스크립트 파일을 입력할 수 있습니다.

비고

시스템에 설치된 sqlcmd 의 변형 및 버전을 확인하려면 설치된 sqlcmd 버전의 sqlcmd 유틸리티 확인을 참조하세요. sqlcmd를 가져오는 방법에 대한 자세한 내용은 sqlcmd 유틸리티 다운로드 및 설치를 참조하세요.

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 명령은 콜론(:)으로 접두사를 지정해야합니다.

중요합니다

기존 osql 스크립트와의 이전 버전과의 호환성을 유지하기 위해 일부 명령은 콜론 없이 인식되며 :표시됩니다.
sqlcmd 명령은 줄 시작 부분에 나타난 경우에만 인식됩니다.
모든 sqlcmd 명령은 대/소문자를 구분하지 않습니다.
각 명령을 별도의 줄에 입력해야 합니다. 명령 다음에 Transact-SQL 문이나 다른 명령을 입력할 수 없습니다.
명령은 즉시 실행됩니다. Transact-SQL 문과 같이 실행 버퍼에 배치되지 않습니다.

편집 관련 명령어

[:]발기부전

텍스트 편집기를 시작합니다. 이 편집기를 사용하여 현재 Transact-SQL 배치 또는 마지막으로 실행된 배치를 편집할 수 있습니다. 마지막으로 실행된 배치를 편집하려면 마지막 배치 실행을 완료한 후 즉시 ED 명령을 입력해야 합니다.

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

SET SQLCMDEDITOR=notepad

[:]재설정

문장 캐시를 지웁니다.

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

변수

:Setvar <var> [ "value" ]

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

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

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

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

비고

-X 옵션을 지정하면 환경 변수가 sqlcmd에 전달되지 않습니다.

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

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

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

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

:Listvar

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

비고

sqlcmd에서 설정한 스크립팅 변수와 명령을 사용하여 :Setvar 설정된 변수만 표시됩니다.

출력 명령

:Error <filename> | STDERR | STDOUT

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

파일 이름

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

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

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

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

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

:Perftrace <파일명> | STDERR | STDOUT

성능 추적 정보를 만들고 파일 이름으로 지정된 파일, stderr 또는 stdout로 모두 리디렉션합니다. 기본적으로 성능 추적 출력은 stdout로 전달됩니다. 파일이 이미 있는 경우 0바이트로 잘립니다. 스크립트에서 :Perftrace 명령이 여러 번 나타날 수 있습니다.

실행 제어 명령

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

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

exit 옵션을 사용하면 sqlcmd가 적절한 오류 값과 함께 종료됩니다.

ignore 옵션을 사용하는 경우 sqlcmd는 오류를 무시하고 배치 또는 스크립트를 계속 실행합니다. 기본적으로 오류 메시지가 출력됩니다.

[:]종료

sqlcmd가 종료됩니다.

[:]EXIT [ ( 명령문 ) ]

SELECT 문 결과를 sqlcmd의 반환 값으로 사용할 수 있습니다. 숫자인 경우 마지막 결과 행의 첫 번째 열이 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는 다음과 같은 추가 반환 값을 정의합니다.

반환 값	설명
`-100`	반환 값을 선택하기 전에 오류가 발생했습니다.
`-101`	반환 값을 선택할 때 행을 찾을 수 없습니다.
`-102`	반환 값을 선택할 때 변환 오류가 발생했습니다.

시작 [count]

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

기타 명령

:r <파일 이름>

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

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

배치 종결자를 만난 후에 파일을 읽고 실행하게 됩니다. 여러 :r 명령을 실행할 수 있습니다. 이 파일에는 일괄 처리 종결자를 비롯한 GO 명령이 포함될 수 있습니다.

비고

대화형 모드로 표시되는 줄 수는 발생한 모든 :r 명령에 대해 하나씩 증가합니다. :r 명령은 목록 명령의 출력에 나타납니다.

:서버 목록

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

:Connect server_name[\instance_name] [-l timeout] [-U user_name [-P 비밀번호]]

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

시간 제한 옵션:

가치	행동
`0`	무기한 대기
`n>0`	n 초 동안 대기

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

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

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

:connect myserver\instance1

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

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

[:]!! 명령

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

:!! dir

비고

이 명령은 sqlcmd가 실행 중인 컴퓨터에서 실행됩니다.

:XML [ 켜기 | 끄기 ]

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

도움말

sqlcmd 명령과 각 명령에 대한 간단한 설명을 표시합니다.

sqlcmd 파일 이름

옵션 또는 -i 명령을 사용하여 :r 입력 파일을 지정할 수 있습니다. 출력 파일은 옵션 또는 -o, :Error및 :Out 명령을 사용하여 :Perftrace 지정할 수 있습니다. 다음은 이러한 파일 작업과 관련한 몇 가지 지침입니다.

:Error, :Out및 :Perftrace 별도의 파일 이름 값을 사용해야 합니다. 동일한 파일 이름 사용하는 경우 명령의 입력이 섞일 수 있습니다.
원격 서버에 있는 입력 파일을 로컬 컴퓨터에 있는 sqlcmd서 호출할 경우, 이 파일에 :Out c:\OutputFile.txt와 같은 드라이브 파일 경로가 포함되어 있으면 출력 파일이 원격 서버가 아닌 로컬 컴퓨터에서 생성됩니다.
유효한 파일 경로에는 C:\<filename>, \\<Server>\<Share$>\<filename>, "C:\Some Folder\<file name>"이 포함됩니다. 경로에 공백이 있는 경우 인용 부호를 사용합니다.
각각의 새 sqlcmd 세션은 이름이 같은 기존 파일을 덮어씁니다.

정보 메시지

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

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

USE AdventureWorks2022;
GO

Enter 키를 누르면 다음 정보 메시지가 출력됩니다.

Changed database context to 'AdventureWorks2022'.

Transact-SQL 쿼리의 출력 형식

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

이 줄 뒤에는 일련의 대시 문자인 구분 기호가 있습니다. 다음은 출력 예제입니다.

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

USE AdventureWorks2022;

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

Enter 키를 누르면 다음 결과 집합이 반환됩니다.

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

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

XML 출력 형식

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

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

비고

sqlcmd는 일반적인 형식으로 오류 메시지를 반환합니다. 오류 메시지는 XML 텍스트 스트림에서도 XML 형식으로 출력됩니다. :XML ON사용하면 sqlcmd 정보 메시지를 표시하지 않습니다.

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

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

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

비고

:XML 명령은 SET STATISTICS XML 문을 지원하지 않습니다.

JSON 출력 형식

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