Invoke-Sqlcmd

참조

모듈:: SQLServer

SQL Server SQLCMD 유틸리티에서 지원하는 문이 포함된 스크립트를 실행합니다.

구문

Invoke-Sqlcmd
      [-ServerInstance <PSObject>]
      [-Database <String>]
      [-Encrypt <String>]
      [-EncryptConnection]
      [-Username <String>]
      [-AccessToken <String>]
      [-Password <String>]
      [-Credential <PSCredential>]
      [[-Query] <String>]
      [-QueryTimeout <Int32>]
      [-ConnectionTimeout <Int32>]
      [-ErrorLevel <Int32>]
      [-SeverityLevel <Int32>]
      [-MaxCharLength <Int32>]
      [-MaxBinaryLength <Int32>]
      [-AbortOnError]
      [-DedicatedAdministratorConnection]
      [-DisableVariables]
      [-DisableCommands]
      [-HostName <String>]
      [-ApplicationName <String>]
      [-ApplicationIntent <ApplicationIntent>]
      [-MultiSubnetFailover]
      [-FailoverPartner <String>]
      [-HostNameInCertificate <String>]
      [-TrustServerCertificate]
      [-NewPassword <String>]
      [-Variable <PSObject>]
      [-InputFile <String>]
      [-OutputSqlErrors <Boolean>]
      [-IncludeSqlUserErrors]
      [-SuppressProviderContextWarning]
      [-IgnoreProviderContext]
      [-OutputAs <OutputType>]
      [-StatisticsVariable <String>]
      [-ProgressAction <ActionPreference>]
      [<CommonParameters>]

Invoke-Sqlcmd
      [-AccessToken <String>]
      [[-Query] <String>]
      [-QueryTimeout <Int32>]
      [-ErrorLevel <Int32>]
      [-SeverityLevel <Int32>]
      [-MaxCharLength <Int32>]
      [-MaxBinaryLength <Int32>]
      [-AbortOnError]
      [-DisableVariables]
      [-DisableCommands]
      [-Variable <PSObject>]
      [-InputFile <String>]
      [-OutputSqlErrors <Boolean>]
      [-IncludeSqlUserErrors]
      [-OutputAs <OutputType>]
      -ConnectionString <String>
      [-KeyVaultAccessToken <String>]
      [-ManagedHsmAccessToken <String>]
      [-StatisticsVariable <String>]
      [-ProgressAction <ActionPreference>]
      [<CommonParameters>]

Description

Invoke-Sqlcmd cmdlet은 SQL Server SQLCMD 유틸리티에서 지원하는 언어 및 명령을 포함하는 스크립트를 실행합니다.

지원되는 명령은 Transact-SQL 문과 데이터베이스 엔진에서 지원하는 XQuery 구문의 하위 집합입니다.

또한 이 cmdlet은 GO 및 QUIT과 같은 SQLCMD에서 기본적으로 지원되는 많은 명령을 허용합니다.

이 cmdlet은 SQLCMDUSER와 같은 SQLCMD 스크립팅 변수도 허용합니다. 기본적으로 이 cmdlet은 SQLCMD 스크립팅 변수를 설정하지 않습니다.

이 cmdlet은 주로 대화형 스크립트 편집과 관련된 명령의 사용을 지원하지 않습니다.

지원되지 않는 명령에는 :!, :connect, :error, :out, :ed, :list, :listvar, :reset, :p erftrace 및 :serverlist가 포함됩니다.

이 cmdlet을 실행하면 스크립트가 반환하는 첫 번째 결과 집합이 서식이 지정된 테이블로 표시됩니다.

후속 결과 집합에 첫 번째와 다른 열 목록이 포함되어 있으면 해당 결과 집합이 표시되지 않습니다.

첫 번째 집합 이후의 결과 집합에 동일한 열 목록이 있는 경우 해당 행은 첫 번째 결과 집합에서 반환된 행을 포함하는 형식이 지정된 테이블에 추가됩니다.

자세한 정보 표시 매개 변수를 지정하여 SQL PRINT 문에서 생성된 것과 같은 SQL Server 메시지 출력을 표시할 수 있습니다.

예제

예제 1: 명명된 인스턴스에 연결하고 스크립트 실행

Invoke-Sqlcmd -Query "SELECT GETDATE() AS TimeOfQuery" -ServerInstance "MyComputer\MainInstance"

TimeOfQuery
-----------
9/21/2017 2:48:24 PM

이 명령은 컴퓨터에서 SQL Database 엔진의 명명된 인스턴스에 연결하고 기본 Transact-SQL 스크립트를 실행합니다.

예제 2: 스크립트 파일에서 명령을 호출하고 텍스트 파일에 출력 저장

Invoke-Sqlcmd -InputFile "C:\ScriptFolder\TestSqlCmd.sql" | Out-File -FilePath "C:\ScriptFolder\TestSqlCmd.rpt"
Output sent to TestSqlCmd.rpt.

이 명령은 Transact-SQL 문 및 SQLCMD 명령이 포함된 파일을 읽고, 파일을 실행하고, 출력을 다른 파일에 씁니다.

출력 파일에는 독점 정보가 포함될 수 있으므로 적절한 NTFS 권한으로 출력 파일을 보호해야 합니다.

예제 3: 스크립트 호출 및 문자열의 변수 값 전달

$StringArray = "MYVAR1='String1'", "MYVAR2='String2'"
Invoke-Sqlcmd -Query "SELECT `$(MYVAR1) AS Var1, `$(MYVAR2) AS Var2" -Variable $StringArray

Var1     Var2
----     ----
String1  String2

이 명령은 변수 매개 변수에 대한 입력으로 문자열 배열을 사용합니다.

배열은 여러 SQLCMD 변수를 정의합니다.

SQLCMD 변수를 식별하는 SELECT 문의 $ 기호는 백틱(') 문자를 사용하여 이스케이프됩니다.

예제 4: 스크립트 호출 및 SQL 데이터베이스 엔진에서 변수 전달

Set-Location "SQLSERVER:\SQL\MyComputer\MainInstance"
PS SQLSERVER:\SQL\MyComputer\MainInstance> Invoke-Sqlcmd -Query "SELECT SERVERPROPERTY('MachineName') AS ComputerName" -ServerInstance (Get-Item .)

ComputerName
------------
MyComputer

이 명령은 Set-Location 사용하여 SQL Database 엔진 인스턴스에 대한 SQL ServerWindows PowerShell 공급자 경로로 이동합니다.

그런 다음 Get-Item 호출하여 Invoke-Sqlcmd의 ServerInstance 매개 변수로 사용할 SQL Management 개체 서버 개체를 검색합니다.

예제 5: 쿼리 실행 및 자세한 정보 출력 표시

Set-Location "SQLSERVER:\SQL\MyComputer\MainInstance"
Invoke-SqlCmd -Query "PRINT N'abc'" -Verbose
VERBOSE: abc

이 명령은 Windows PowerShellVerbose 매개 변수를 사용하여 SQL PRINT 명령의 메시지 출력을 반환합니다.

예제 6: 위치 문자열을 입력으로 사용하여 명령 호출

Set-Location "SQLSERVER:\SQL\MyComputer\MainInstance\Databases\MyDatabase"
PS SQLSERVER:\SQL\MyComputer\MainInstance> Invoke-Sqlcmd "SELECT DB_NAME() AS DatabaseName"
WARNING: Using provider context. Server = MyComputer\MainInstance, Database = MyDatabase.

DatabaseName
------------
MyDatabase

이 명령은 위치 문자열을 사용하여 쿼리 매개 변수에 입력을 제공합니다.

또한 Invoke-Sqlcmd 현재 경로를 사용하여 데이터베이스 컨텍스트를 MyDatabase로 설정하는 방법을 보여 줍니다.

예제 7: DataSet 개체에 데이터 캡처

$DS = Invoke-Sqlcmd -ServerInstance "MyComputer" -Query "SELECT  ID, Item FROM MyDB.dbo.MyTable" -As DataSet
$DS.Tables[0].Rows | %{ echo "{ $($_['ID']), $($_['Item']) }" }

{ 10, AAA }
{ 20, BBB }
{ 30, CCC }

이 명령은 As DataSet 매개 변수를 사용하여 데이터를 .Net System.Data.DataSet 개체에 캡처하고 결과를 '$DS' 변수에 저장합니다. 개체를 추가 처리에 사용할 수 있습니다.

예제 8: 특정 열 집합 가져오기

$Tables = Invoke-Sqlcmd -ServerInstance "MyComputer" -Query "SELECT  Item, id FROM MyDatabase.dbo.MyTable; SELECT GETDATE() AS T" -As DataTables
$Tables[0].Rows | %{ echo $_.ID }
$Tables[1].Rows | %{ echo $_.T.DayOfWeek }

10
20
30

Monday

첫 번째 명령은 As DataTables 매개 변수를 사용하여 데이터를 .Net System.Data.DataTable 개체의 컬렉션으로 캡처합니다. 이 명령은 서로 다른 열 집합을 가진 두 개의 테이블을 가져옵니다.

각 테이블은 자체 스키마에 따라 개별적으로 처리할 수 있습니다.

예제 9: 연결의 모든 권한 얻기

Invoke-Sqlcmd -Query "SELECT COUNT(*) AS Count FROM MyTable" -ConnectionString "Data Source=MYSERVER;Initial Catalog=MyDatabase;Integrated Security=True;ApplicationIntent=ReadOnly"
Count
-----
127432

이 명령은 -ConnectionString 매개 변수를 사용하여 명령줄에 전달된 매개 변수를 기반으로 연결 문자열을 빌드하는 Invoke-Sqlcmd 대신 이 cmdlet이 설정하는 연결을 완전히 제어할 수 있습니다.

이는 사용하려는 덜 일반적인 속성에 유용합니다.

예제 10: 저장 프로시저 실행 및 SQL 오류 캡처

$script_sp_with_errors = @'
CREATE PROCEDURE [dbo].[TestProcedure3]
AS 
BEGIN 
  CREATE TABLE [dbo].[TestTable] (col INT NOT NULL);
  INSERT INTO [dbo].[TestTable] VALUES (NULL); -- will cause an error
END
GO
'@

# Create a test database
Invoke-SqlCmd -ServerInstance MyServer -Query 'CREATE DATABASE TestDB'
# ... adds a stored procedure that has errors in it...
Invoke-SqlCmd -ServerInstance MyServer -Database 'TestDB' -Query $script_sp_with_errors
# ... executes the SP and collected the errors
Invoke-SqlCmd -ServerInstance MyServer -Database 'TestDB' -Query 'EXEC TestProcedure3' -OutputSqlErrors $true

Here's the output:
Invoke-SqlCmd : Cannot insert the value NULL into column 'col', table 'TestDB.dbo.TestTable'; column does not allow nulls. INSERT fails.
The statement has been terminated.
 Msg 515, Level 16, State 2, Procedure TestProcedure3, Line 5.
At line:1 char:1
...

이 명령은 -OutputSqlErrors 매개 변수를 사용하여 사용자에게 오류를 보고합니다. 이 경우 오류 메시지는 SP 이름 및 오류가 발생한 줄 번호와 같은 추가 정보를 제공합니다.

예제 11: 액세스 토큰을 사용하여 Azure SQL Database(또는 Managed Instance)에 연결

Import-Module SQLServer
Import-Module Az.Accounts -MinimumVersion 2.2.0

# Note: the sample assumes that you or your DBA configured the server to accept connections using
#       that Service Principal and has granted it access to the database (in this example at least
#       the SELECT permission).

### Obtain the Access Token: this will bring up the login dialog
Connect-AzAccount
$access_token = (Get-AzAccessToken -ResourceUrl https://database.windows.net).Token

# Now that we have the token, we use it to connect to the database 'mydb' on server 'myserver'
Invoke-Sqlcmd -ServerInstance myserver.database.windows.net -Database mydb -AccessToken $access_token`
              -query 'select * from Table1'

예제 12: 서비스 주체를 사용하여 Azure SQL Database(또는 Managed Instance)에 연결

Import-Module SQLServer

# Note: the sample assumes that you or your DBA configured the server to accept connections using
#       that Service Principal and has granted it access to the database (in this example at least
#       the SELECT permission).

$clientid = "enter application id that corresponds to the Service Principal" # Do not confuse with its display name
$tenantid = "enter the tenant ID of the Service Principal"
$secret = "enter the secret associated with the Service Principal"

$request = Invoke-RestMethod -Method POST `
           -Uri "https://login.microsoftonline.com/$tenantid/oauth2/token"`
           -Body @{ resource="https://database.windows.net/"; grant_type="client_credentials"; client_id=$clientid; client_secret=$secret }`
           -ContentType "application/x-www-form-urlencoded"
$access_token = $request.access_token

# Now that we have the token, we use it to connect to the database 'mydb' on server 'myserver'
Invoke-Sqlcmd -ServerInstance myserver.database.windows.net -Database mydb -AccessToken $access_token`
              -query 'select * from Table1'

예제 13: SAMI(시스템 할당 관리 ID)를 사용하여 Azure SQL Database(또는 Managed Instance)에 연결

Import-Module SQLServer

# Note: the sample assumes that you or your DBA configured the server to accept connections using
#       that VM Identity you are running on and has granted it access to the database (in this 
#       example at least the SELECT permission).

Connect-AzAccount -Identity
$access_token = (Get-AzAccessToken -ResourceUrl https://database.windows.net).Token

# Now that we have the token, we use it to connect to the database 'mydb' on server 'myserver'
Invoke-Sqlcmd -ServerInstance myserver.database.windows.net -Database mydb -AccessToken $access_token `
              -query 'select * from Table1'

예제 14: UAMI(사용자 할당 관리 ID)를 사용하여 Azure SQL Database(또는 Managed Instance)에 연결

Import-Module SQLServer

# Note: the sample assumes that you or your DBA configured the server to accept connections using
#       that VM Identity you are running on and has granted it access to the database (in this 
#       example at least the SELECT permission).

Connect-AzAccount -Identity -AccountId '<your-user-assigned-managed-identity-client-id>'
$access_token = (Get-AzAccessToken -ResourceUrl https://database.windows.net).Token

# Now that we have the token, we use it to connect to the database 'mydb' on server 'myserver'
Invoke-Sqlcmd -ServerInstance myserver.database.windows.net -Database mydb -AccessToken $access_token `
              -query 'select * from Table1'

예제 15: -ApplicationIntent 사용하여 Read-Only 라우팅에 대해 구성된 가용성 그룹에 연결

# In the following example:
# - MT_2009250511 is a listener for an AG configured for Read-Only Routing (port 5555)
# - AGDB_2_1 is the DB in the AG
# - VLM00226138 is the primary replica configured to only allow ReadWrite connections 
# - VLM00226137 is the secondary replica
# 
Invoke-Sqlcmd -ServerInstance "MT_2009250511,5555" -Database AGDB_2_1 `
     -HostName "PowershellBox1" -ApplicationName "ReadWrite" -ApplicationIntent ReadWrite `
     -Query "select HOST_NAME() AS HostName, APP_NAME() AS ApplicationIntent, @@SERVERNAME AS ServerName"

Invoke-Sqlcmd -ServerInstance "MT_2009250511,5555" -Database AGDB_2_1 `
     -HostName "PowershellBox2" -ApplicationName "ReadOnly" -ApplicationIntent ReadOnly `
     -Query "select HOST_NAME() AS HostName, APP_NAME() AS ApplicationIntent, @@SERVERNAME AS ServerName"  

# When you run the 2 cmdlets above, the output is going to be something like this:  
#  
# HostName       ApplicationIntent ServerName  
# --------       ----------------- ----------  
# PowershellBox1 ReadWrite         VLM00226138  
#  
# HostName       ApplicationIntent ServerName  
# --------       ----------------- ----------  
# PowershellBox2 ReadOnly          VLM00226137

이는 -ApplicationIntent 매개 변수의 값에 따라 연결이 AG의 다른 서버로 라우팅됨을 보여줍니다. 또한 -ApplicationName 및 -HostName 매개 변수의 사용을 관찰하여 두 결과를 시각적으로 구분합니다. 이는 여기에 설명된 -ApplicationIntent 예제를 넘어 연결 및 해당 의도를 추적하는 데 사용할 수 있는 일반적인 기술입니다.

예제 16: -StatisticsVariable 매개 변수를 통해 연결 통계 캡처

Import-Module SQLServer
Invoke-Sqlcmd -ServerInstance localhost -StatisticsVariable stats `
              -Query 'CREATE TABLE #Table (ID int); INSERT INTO #Table VALUES(1), (2); INSERT INTO #Table VALUES(3); SELECT * FROM #Table'

Write-Host "Number of rows affected......: $($stats.IduRows)"
Write-Host "Number of insert statements..: $($stats.IduCount)"
Write-Host "Number of select statements..: $($stats.SelectCount)"
Write-Host "Total execution time.........: $($stats.ExecutionTime)ms"

# When you run the code fragment above, is going to be something like this:  
#
# Number of rows affected......: 3
# Number of insert statements..: 2
# Number of select statements..: 1
# Total execution time.........: 5ms

이 예제에서는 -StatisticsVariable 매개 변수를 사용하여 연결, 실행된 문 및 임시 테이블을 만들고, 일부 값을 삽입하고, 마지막으로 삽입된 모든 행을 가져오기 위한 선택을 실행하는 일부 T-SQL을 실행할 때의 실행 시간에 대한 정보를 캡처하는 방법을 보여 줍니다.

참고: 여러 서버에 대해 동일한 쿼리를 실행할 때(예: cmdlet을 통해 서버 이름을 파이핑하여) StatisticsVariable 각 연결에 대해 하나씩 통계 배열을 캡처합니다. 그런 다음, ($stats.IduRows | Measure-Object -Sum).Sum등을 사용하여 결과를 집계할 수 있습니다.

사용 가능한 통계에 대한 자세한 내용은 SQL Server 공급자 통계를 참조하세요.

예제 17: Always Encrypted를 사용하여 암호화된 열에서 검색된 데이터의 암호를 해독하는 쿼리를 실행합니다. 열 마스터 키가 Azure Key Vault의 키 자격 증명 모음에 저장된다고 가정합니다.

# Connect to Azure account.
Import-Module Az.Accounts -MinimumVersion 2.2.0
Connect-AzAccount

# Obtain an access token for key vaults. 
$keyVaultAccessToken = (Get-AzAccessToken -ResourceUrl https://vault.azure.net).Token

# Pass the token to the cmdlet, so that it can use it to authenticate to Azure when decrypting data protected with Always Encrypted.
$connString = 'Data Source=MYSERVER;Initial Catalog=MyDatabase;Integrated Security=True;ApplicationIntent=ReadOnly;Column Encryption Setting=Enabled'
Invoke-Sqlcmd -Query 'SELECT COUNT(*) AS Count FROM MyTable' -ConnectionString $connString -KeyVaultAccessToken $keyVaultAccessToken

매개 변수

-AbortOnError

이 cmdlet이 SQL Server 명령을 중지하고 이 cmdlet에 오류가 발생하면 Windows PowerShell ERRORLEVEL 변수에 오류 수준을 반환합니다.

오류의 심각도가 10보다 높은 경우 반환되는 오류 수준은 1이고 오류 심각도는 10 이하인 경우 오류 수준은 0입니다.

ErrorLevel 매개 변수도 지정된 경우 이 cmdlet은 오류 메시지 심각도가 ErrorLevel에 지정된 값과 같거나 높은 경우에만 1을 반환합니다.

형식:	SwitchParameter
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-AccessToken

사용자/암호 또는 Windows 인증 대신 SQL Server에 인증하는 데 사용되는 액세스 토큰입니다.

예를 들어 Service Principal 또는 Managed Identity 사용하여 SQL Azure DB 연결하고 SQL Azure Managed Instance 데 사용할 수 있습니다(이 페이지의 맨 아래에 있는 참조 참조 참조).

일반적인 시나리오에서 이 매개 변수는 (Get-AzAccessToken -ResourceUrl https://database.windows.net).Token(Az.Account 모듈 필요)와 같이 가져옵니다.

이 매개 변수를 사용하는 경우 UserName, 암호또는 자격 증명 지정하지 마세요.

형식:	String
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-ApplicationIntent

SQL Server 가용성 그룹의 데이터베이스에 연결할 때의 애플리케이션 워크로드 유형입니다.

허용되는 값은 ReadOnly 및 ReadWrite입니다.

형식:	ApplicationIntent
허용되는 값:	ReadWrite, ReadOnly
Position:	Named
Default value:	ReadWrite
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-ApplicationName

연결과 연결된 애플리케이션의 이름입니다.

형식:	String
Position:	Named
Default value:	.NET SqlClient Data Provider
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-ConnectionString

서버에 연결할 연결 문자열을 지정합니다.

형식:	String
Position:	Named
Default value:	None
필수:	True
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-ConnectionTimeout

데이터베이스 엔진 인스턴스에 성공적으로 연결할 수 없는 경우 이 cmdlet의 시간이 초과되는 시간(초)을 지정합니다. 시간 제한 값은 0에서 65534 사이의 정수 값이어야 합니다. 0을 지정하면 연결 시도가 시간 초과되지 않습니다.

형식:	Int32
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-Credential

사용자 이름 및 암호 필드를 사용하여 SQL 인스턴스에 연결하는 PSCredential 개체입니다.

형식:	PSCredential
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-Database

데이터베이스의 이름을 지정합니다. 이 cmdlet은 ServerInstance 매개 변수에 지정된 인스턴스에서 이 데이터베이스에 연결합니다.

Database 매개 변수를 지정하지 않으면 사용되는 데이터베이스는 현재 경로가 SQLSERVER:\SQL 폴더와 데이터베이스 이름을 모두 지정하는지 여부에 따라 달라집니다. 경로가 SQL 폴더와 데이터베이스 이름을 모두 지정하는 경우 이 cmdlet은 경로에 지정된 데이터베이스에 연결됩니다. 경로가 SQL 폴더를 기반으로 하지 않거나 경로에 데이터베이스 이름이 없는 경우 이 cmdlet은 현재 로그인 ID의 기본 데이터베이스에 연결합니다. IgnoreProviderContext 매개 변수 스위치를 지정하는 경우 이 cmdlet은 현재 경로에 지정된 데이터베이스를 고려하지 않으며 현재 로그인 ID의 기본값으로 정의된 데이터베이스에 연결합니다.

형식:	String
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-DedicatedAdministratorConnection

이 cmdlet은 DAC(관리자 전용 연결)를 사용하여 데이터베이스 엔진의 인스턴스에 연결한다는 것을 나타냅니다.

DAC는 시스템 관리자가 새 표준 연결을 허용하지 않는 인스턴스 문제 해결과 같은 작업에 사용됩니다.

DAC를 지원하도록 인스턴스를 구성해야 합니다.

DAC를 사용하지 않는 경우 이 cmdlet은 오류를 보고하며 실행되지 않습니다.

형식:	SwitchParameter
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-DisableCommands

이 cmdlet은 일괄 처리 파일에서 실행할 때 보안을 손상시킬 수 있는 일부 sqlcmd 기능을 해제했음을 나타냅니다.

Windows PowerShell 변수가 Invoke-Sqlcmd 스크립트에 전달되지 않도록 합니다.

SQLCMDINI 스크립팅 변수에 지정된 시작 스크립트가 실행되지 않습니다.

형식:	SwitchParameter
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-DisableVariables

이 cmdlet은 sqlcmd 스크립팅 변수를 무시함을 나타냅니다. 이는 스크립트에 $(variable_name)와 같은 변수와 형식이 같은 문자열을 포함할 수 있는 많은 INSERT 문이 포함된 경우에 유용합니다.

형식:	SwitchParameter
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-Encrypt

SQL Server에 연결할 때 사용할 암호화 유형입니다.

이 값은 Microsoft.Data.SqlClient 드라이버의 SqlConnection 개체에 있는 Encrypt 속성 SqlConnectionEncryptOption 매핑됩니다.

지정하지 않으면 기본값은 Mandatory.

이 매개 변수는 모듈의 v22에서 새로 생성됩니다. 자세한 내용은 관련 링크아래의 Strict Connection Encryption 참조하세요.

형식:	String
허용되는 값:	Mandatory, Optional, Strict
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-EncryptConnection

이 cmdlet은 ServerInstance 매개 변수에 지정된 데이터베이스 엔진 인스턴스에 대한 연결에 SSL/TLS(Secure Sockets Layer) 암호화를 사용한다는 것을 나타냅니다.

모듈의 v22부터 이 매개 변수는 더 이상 사용되지 않습니다. 연결은 기본적으로 암호화됩니다. 대신 새 -Encrypt 매개 변수를 사용하는 것이 좋습니다. 자세한 내용은 관련 링크아래의 Strict Connection Encryption 참조하세요.

형식:	SwitchParameter
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-ErrorLevel

이 cmdlet은 심각도 수준이 지정된 값보다 크거나 같은 오류 메시지만 표시하도록 지정합니다. 이 매개 변수를 지정하지 않거나 0으로 설정하면 모든 오류 메시지가 표시됩니다. 데이터베이스 엔진 오류 심각도 범위는 1에서 24까지입니다.

형식:	Int32
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-FailoverPartner

주 서버가 다운된 경우 연결할 파트너 서버의 이름 또는 주소입니다.

형식:	String
Position:	Named
Default value:	""
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-HostName

워크스테이션 이름을 지정합니다. 워크스테이션 이름은 sp_who 시스템 저장 프로시저와 sys.processes 카탈로그 뷰의 호스트 이름 열에서 보고됩니다. 이 매개 변수를 지정하지 않으면 기본값은 Invoke-Sqlcmd 실행되는 컴퓨터의 이름입니다. 이 매개 변수는 다른 Invoke-Sqlcmd 세션을 식별하는 데 사용할 수 있습니다.

형식:	String
별칭:	WorkstationID
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-HostNameInCertificate

SQL Server TLS/SSL 인증서의 유효성을 검사하는 데 사용할 호스트 이름입니다. SQL Server 인스턴스가 Force Encryption을 사용하도록 설정되어 있고 호스트 이름/짧은 이름을 사용하여 인스턴스에 연결하려는 경우 이 매개 변수를 전달해야 합니다. 이 매개 변수를 생략하면 강제 암호화를 사용하도록 설정된 SQL Server 인스턴스에 연결하려면 FQDN(정규화된 도메인 이름)을 -ServerInstance 전달해야 합니다.

이 매개 변수는 모듈의 v22에서 새로 생성됩니다. 자세한 내용은 관련 링크아래의 Strict Connection Encryption 참조하세요.

형식:	String
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-IgnoreProviderContext

이 cmdlet은 현재 SQLSERVER:\SQL 경로에 의해 설정된 데이터베이스 컨텍스트를 무시함을 나타냅니다. Database 매개 변수를 지정하지 않으면 이 cmdlet은 현재 로그인 ID 또는 Windows 계정에 대한 기본 데이터베이스를 사용합니다.

형식:	SwitchParameter
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-IncludeSqlUserErrors

이 cmdlet은 기본적으로 무시되는 SQL 사용자 스크립트 오류를 반환합니다. 이 매개 변수를 지정하면 이 cmdlet은 sqlcmd 유틸리티의 기본 동작과 일치합니다.

형식:	SwitchParameter
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-InputFile

이 cmdlet에 대한 쿼리 입력으로 사용할 파일을 지정합니다. 파일에는 Transact-SQL 문, XQuery 문, sqlcmd 명령 및 스크립팅 변수가 포함될 수 있습니다. 파일의 전체 경로를 지정합니다. 이 파일은 UTF-8을 사용하여 인코딩되어야 합니다.

신뢰할 수 있는 원본에서만 스크립트를 실행해야 합니다. 모든 입력 스크립트가 적절한 NTFS 권한으로 보호되는지 확인합니다.

형식:	String
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-KeyVaultAccessToken

Azure Key Vault의 키 자격 증명 모음에 대한 액세스 토큰을 지정합니다. 쿼리할 열이 Azure Key Vault의 키 자격 증명 모음에 저장된 열 마스터 키를 사용하여 Always Encrypted로 보호되는 경우 이 매개 변수를 사용합니다. 또는 이 cmdlet을 호출하기 전에 Add-SqlAzureAuthenticationContext 사용하여 Azure에 인증할 수 있습니다.

형식:	String
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-ManagedHsmAccessToken

Azure Key Vault에서 관리형 HSM에 대한 액세스 토큰을 지정합니다. 쿼리할 열이 Azure Key Vault의 관리형 HSM에 저장된 열 마스터 키를 사용하여 Always Encrypted로 보호되는 경우 이 매개 변수를 사용합니다. 또는 이 cmdlet을 호출하기 전에 Add-SqlAzureAuthenticationContext 사용하여 Azure에 인증할 수 있습니다.

형식:	String
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-MaxBinaryLength

이진 및 varbinary와 같은 이진 문자열 데이터 형식이 있는 열에 대해 반환되는 최대 바이트 수를 지정합니다. 기본값은 1,024바이트입니다.

형식:	Int32
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-MaxCharLength

문자 또는 유니코드 데이터 형식(예: char, nchar, varchar 및 nvarchar)이 있는 열에 대해 반환되는 최대 문자 수를 지정합니다. 기본값은 4,000자입니다.

형식:	Int32
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-MultiSubnetFailover

애플리케이션이 다른 서브넷의 AlwaysOn AG(가용성 그룹)에 연결하는 경우 이 매개 변수를 전달하면 (현재) 활성 서버에 대한 빠른 검색 및 연결을 제공합니다.

참고: .NET Framework 4.6.1 이상 버전에서는 -MultiSubnetFailover 전달할 필요가 없습니다.

형식:	SwitchParameter
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-NewPassword

SQL Server 인증 로그인 ID에 대한 새 암호를 지정합니다. 이 cmdlet은 암호를 변경한 다음 종료합니다. 로그인의 현재 암호를 지정하는 암호와 함께 사용자 이름 및 암호 매개 변수도 지정해야 합니다.

형식:	String
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-OutputAs

이 cmdlet이 가져오는 결과의 형식을 지정합니다.

이 매개 변수의 값을 지정하지 않으면 cmdlet은 값을 DataRows로 설정합니다.

형식:	OutputType
별칭:	As
허용되는 값:	DataSet, DataTables, DataRows
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-OutputSqlErrors

이 cmdlet은 Invoke-Sqlcmd 출력에 오류 메시지를 표시합니다.

형식:	Boolean
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-Password

Username 매개 변수에 지정된 SQL Server 인증 로그인 ID의 암호를 지정합니다. 암호는 대/소문자를 구분합니다. 가능하면 Windows 인증을 사용합니다. 가능한 경우 강력한 암호를 사용하여 빈 암호를 사용하지 마세요.

암호 매개 변수 뒤에 암호를 지정하면 모니터를 볼 수 있는 모든 사용자에게 암호가 표시됩니다.

.ps1 스크립트에서 암호 뒤에 암호를 코딩하는 경우 스크립트 파일을 읽는 모든 사용자에게 암호가 표시됩니다.

다른 사용자가 파일을 읽을 수 없도록 파일에 적절한 NTFS 권한을 할당합니다.

형식:	String
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-ProgressAction

powerShell이 스크립트, cmdlet 또는 공급자(예: Write-Progress cmdlet에서 생성된 진행률 표시줄)에 의해 생성된 진행률 업데이트에 응답하는 방법을 결정합니다. Write-Progress cmdlet은 명령의 상태를 표시하는 진행률 표시줄을 만듭니다.

형식:	ActionPreference
별칭:	proga
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-Query

이 cmdlet이 실행되는 하나 이상의 쿼리를 지정합니다. 쿼리는 Transact-SQL 또는 XQuery 문 또는 sqlcmd 명령일 수 있습니다. 세미콜론으로 구분된 여러 쿼리를 지정할 수 있습니다. sqlcmd GO 구분 기호를 지정하지 마세요. 문자열에 포함된 큰따옴표를 이스케이프합니다. "MyTable"과 같이 따옴표 붙은 식별자 대신 [MyTable]과 같은 대괄호로 묶인 식별자를 사용하는 것이 좋습니다.

형식:	String
Position:	0
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-QueryTimeout

쿼리 시간이 초과되기 전의 시간(초)을 지정합니다. 시간 제한 값을 지정하지 않으면 쿼리 시간이 초과되지 않습니다. 시간 제한은 1에서 65535 사이의 정수 값이어야 합니다.

형식:	Int32
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-ServerInstance

데이터베이스 엔진 인스턴스의 이름을 지정하는 문자열 또는 SMO(SQL Server Management Objects) 개체를 지정합니다. 기본 인스턴스의 경우 컴퓨터 이름인 MyComputer만 지정합니다. 명명된 인스턴스의 경우 ComputerName\InstanceName 형식을 사용합니다.

형식:	PSObject
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	True
와일드카드 문자 허용:	False

-SeverityLevel

이 cmdlet이 ERRORLEVEL Windows PowerShell 변수로 반환하는 오류 메시지 심각도 수준에 대한 하한을 지정합니다.

이 cmdlet은 심각도가 SeverityLevel 매개 변수에 지정된 것보다 크거나 같은 경우 실행되는 쿼리에서 생성된 오류 메시지에서 가장 높은 심각도 수준을 반환합니다.

SeverityLevel을 지정하지 않거나 0으로 설정하면 이 cmdlet은 0을 ERRORLEVEL로 반환합니다.

데이터베이스 엔진 오류 메시지의 심각도 수준은 1에서 24까지입니다.

이 cmdlet은 심각도가 10인 정보 메시지에 대한 심각도를 보고하지 않습니다.

형식:	Int32
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-StatisticsVariable

cmdlet이 실행될 때 SQL Server 런타임 통계가 할당될 PowerShell 변수의 이름을 지정합니다.

이 매개 변수의 일반적인 용도는 ExecutionTime(공급자가 cmdlet을 처리하는 데 소요된 누적 시간(밀리초) 또는 IduRows(INSERT, DELETE 및 UPDATE 문의 영향을 받는 총 행 수)을 캡처하는 것입니다.

자세한 내용은 SQL Server공급자 통계를 참조하세요.

형식:	String
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-SuppressProviderContextWarning

이 cmdlet은 이 cmdlet이 현재 SQLSERVER:\SQL 경로 설정의 데이터베이스 컨텍스트에서 cmdlet에 대한 데이터베이스 컨텍스트를 설정하는 데 사용한 경고를 표시하지 않습니다.

형식:	SwitchParameter
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-TrustServerCertificate

신뢰의 유효성을 검사하기 위해 인증서 체인을 건너뛰는 동안 채널이 암호화되는지 여부를 나타냅니다.

이 매개 변수는 모듈의 v22에서 새로 생성됩니다. 자세한 내용은 관련 링크아래의 Strict Connection Encryption 참조하세요.

형식:	SwitchParameter
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-Username

데이터베이스 엔진 인스턴스에 대한 SQL Server 인증 연결을 만들기 위한 로그인 ID를 지정합니다.

암호 매개 변수를 통해 암호를 지정해야 합니다.

사용자 이름 및 암호를 지정하지 않으면 이 cmdlet은 Windows PowerShell 세션을 실행하는 Windows 계정을 사용하여 Windows 인증 연결을 시도합니다. 가능하면 Windows 인증을 사용합니다.

형식:	String
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

-Variable

sqlcmd 스크립트에서 사용할 sqlcmd 스크립팅 변수 집합을 지정하고 변수에 대한 값을 설정합니다.

Windows PowerShell 배열을 사용하여 여러 변수 및 해당 값을 지정합니다. 또는 키가 변수 이름과 변수 값 값을 나타내는 Hashtable 사용합니다.

배열을 사용하는 경우 매개 변수 값이 잘립니다. 이 동작은 v21과의 이전 버전과의 호환성을 위해 모듈의 v22에서 유지되었습니다. 모듈의 향후 주 버전에서 변경될 수 있는 이 동작을 사용하지 않는 것이 좋습니다.

Hashtable 형식의 매개 변수는 모듈의 v22 이상에서만 사용할 수 있습니다.

형식:	PSObject
Position:	Named
Default value:	None
필수:	False
파이프라인 입력 허용:	False
와일드카드 문자 허용:	False

입력

System.Management.Automation.PSObject

출력

System.Object

다음을 통해 공유

Invoke-Sqlcmd

구문

Description

예제

예제 1: 명명된 인스턴스에 연결하고 스크립트 실행

예제 2: 스크립트 파일에서 명령을 호출하고 텍스트 파일에 출력 저장

예제 3: 스크립트 호출 및 문자열의 변수 값 전달

예제 4: 스크립트 호출 및 SQL 데이터베이스 엔진에서 변수 전달

예제 5: 쿼리 실행 및 자세한 정보 출력 표시

예제 6: 위치 문자열을 입력으로 사용하여 명령 호출

예제 7: DataSet 개체에 데이터 캡처

예제 8: 특정 열 집합 가져오기

예제 9: 연결의 모든 권한 얻기

예제 10: 저장 프로시저 실행 및 SQL 오류 캡처

예제 11: 액세스 토큰을 사용하여 Azure SQL Database(또는 Managed Instance)에 연결

예제 12: 서비스 주체를 사용하여 Azure SQL Database(또는 Managed Instance)에 연결

예제 13: SAMI(시스템 할당 관리 ID)를 사용하여 Azure SQL Database(또는 Managed Instance)에 연결

예제 14: UAMI(사용자 할당 관리 ID)를 사용하여 Azure SQL Database(또는 Managed Instance)에 연결

예제 15: -ApplicationIntent 사용하여 Read-Only 라우팅에 대해 구성된 가용성 그룹에 연결

예제 16: -StatisticsVariable 매개 변수를 통해 연결 통계 캡처

예제 17: Always Encrypted를 사용하여 암호화된 열에서 검색된 데이터의 암호를 해독하는 쿼리를 실행합니다. 열 마스터 키가 Azure Key Vault의 키 자격 증명 모음에 저장된다고 가정합니다.

매개 변수

-AbortOnError

-AccessToken

-ApplicationIntent

-ApplicationName

-ConnectionString

-ConnectionTimeout

-Credential

-Database

-DedicatedAdministratorConnection

-DisableCommands

-DisableVariables

-Encrypt

-EncryptConnection

-ErrorLevel

-FailoverPartner

-HostName

-HostNameInCertificate

-IgnoreProviderContext

-IncludeSqlUserErrors

-InputFile

-KeyVaultAccessToken

-ManagedHsmAccessToken

-MaxBinaryLength

-MaxCharLength

-MultiSubnetFailover

-NewPassword

-OutputAs

-OutputSqlErrors

-Password

-ProgressAction

-Query

-QueryTimeout

-ServerInstance

-SeverityLevel

-StatisticsVariable

-SuppressProviderContextWarning

-TrustServerCertificate

-Username

-Variable

입력

출력

관련 링크

피드백

추가 리소스