다음을 통해 공유


Write-SqlTableData

SQL 데이터베이스의 테이블에 데이터를 씁니다.

구문

Write-SqlTableData
     [-Force]
     -InputData <PSObject>
     [-Passthru]
     [-Timeout <Int32>]
     [[-Path] <String[]>]
     [-AccessToken <PSObject>]
     [-TrustServerCertificate]
     [-HostNameInCertificate <String>]
     [-Encrypt <String>]
     [-ProgressAction <ActionPreference>]
     [<CommonParameters>]
Write-SqlTableData
     [-DatabaseName <String>]
     [-SchemaName <String>]
     [-TableName <String>]
     [-IgnoreProviderContext]
     [-SuppressProviderContextWarning]
     [-Force]
     -InputData <PSObject>
     [-Passthru]
     [-Timeout <Int32>]
     [-ConnectToDatabase]
     [[-ServerInstance] <String[]>]
     [-Credential <PSCredential>]
     [-ConnectionTimeout <Int32>]
     [-AccessToken <PSObject>]
     [-TrustServerCertificate]
     [-HostNameInCertificate <String>]
     [-Encrypt <String>]
     [-ProgressAction <ActionPreference>]
     [<CommonParameters>]
Write-SqlTableData
     [-Force]
     -InputData <PSObject>
     [-Passthru]
     [-Timeout <Int32>]
     [-InputObject] <Table[]>
     [-AccessToken <PSObject>]
     [-TrustServerCertificate]
     [-HostNameInCertificate <String>]
     [-Encrypt <String>]
     [-ProgressAction <ActionPreference>]
     [<CommonParameters>]

Description

Write-SqlTableData cmdlet은 SQL 데이터베이스의 테이블에 데이터를 삽입합니다. 이 cmdlet은 다음 입력 형식을 다음과 같은 출력 형식으로 허용합니다.

  • System.Data.DataSet
  • System.Data.DataTable
  • System.Data.DateRow 개체
  • 개체 컬렉션

DataSet제공하는 경우 데이터 세트의 첫 번째 테이블만 데이터베이스에 기록됩니다.

Windows PowerShell SQL 공급자와 함께 이 cmdlet을 사용할 수 있습니다.

이 cmdlet은 현재 경로에서 서버, 데이터베이스, 스키마 및 테이블과 같은 정보를 유추할 수 있습니다.

이 cmdlet은 테이블이 존재할 것으로 예상합니다. 기본적으로 cmdlet은 해당 테이블에 데이터를 추가합니다.

Force 매개 변수를 지정하면 cmdlet은 데이터베이스, 테이블 스키마 및 테이블 자체를 포함하는 누락된 개체를 생성합니다. 이 사용을 사용하면 데이터를 데이터베이스로 빠르게 전송할 수 있습니다. cmdlet은 데이터에서 테이블의 스키마를 유추합니다. 결과가 최적이 아닐 수 있습니다. 예를 들어 문자열은 NVARCHAR(MAX)에 매핑됩니다.

예제

예제 1: 테이블에 프로세스에 대한 정보 작성

PS C:\> (Get-Process | Select-Object -Property Id,ProcessName,StartTime,UserProcessorTime,WorkingSet,Description) |
         Write-SqlTableData -ServerInstance "MyServer\MyInstance" -DatabaseName "MyDatabase" -SchemaName "dbo" -TableName "TaskManagerDump" -Force

이 예제에서는 시스템에서 실행되는 프로세스에 대한 정보를 가져오고 테이블에 씁니다.

현재 cmdlet은 MyServer\MyInstanceMyDatabase.dbo.TaskManagerDump 데이터를 씁니다. Force 매개 변수를 지정하기 때문에 데이터베이스, 스키마 및 테이블이 없으면 이 cmdlet을 만듭니다.

예제 2: 테이블에 데이터 쓰기

PS C:\> cd SQLSERVER:\SQL\MyServer\MyInstance\Databases\MyDatabase\Tables
PS SQLSERVER:\SQL\MyServer\MyInstance\Databases\MyDatabase\Tables> $Table = Write-SqlTableData -TableName "KeyValuePairs" -SchemaName "dbo" -InputData @{ cca=10; cac='Hello'; aac=1.2 } -PassThru
PS SQLSERVER:\SQL\MyServer\MyInstance\Databases\MyDatabase\Tables> Read-SqlTableData -InputObject $Table

WARNING: Using provider context. Server = MyServer\MyInstance, Database = [MyDatabase]. 

Key Value
--- -----
aac   1.2
cac Hello
cca    10

첫 번째 명령은 위치를 SQLSERVER 공급자의 위치로 변경합니다. 명령 프롬프트는 새 위치를 반영합니다. 자세한 내용은 Get-Help about_Providers 입력합니다.

마지막 명령은 Read-SqlTableData cmdlet을 사용하여 $Table 변수의 내용을 표시합니다.

예제 3: 파일에서 테이블로 데이터 가져오기

PS C:\> ,(Import-Csv -Path ".\a.csv" -Header "Id","Name","Amount") | Write-SqlTableData -ServerInstance "MyServer\MyInstance" -DatabaseName "MyDatabase" -SchemaName "dbo" -TableName "CSVTable" -Force
PS C:\> Read-SqlTableData -ServerInstance "MyServer\MyInstance" -DatabaseName "MyDatabase" -SchemaName "dbo" -TableName "CSVTable"

Id Name  Amount
-- ----  ------
10 AAAA  -1.2
11 BBBB   1.2
12 CCCC  -1.0

The first command imports the contents of a file by using the Import-Csv cmdlet. The file contains the following content:
    
10,AAAA,-1.2
11,BBBB,1.2
12,CCCC,-1.0

이 예제는 파일 프롬프트에서 완전히 실행됩니다. 컨텍스트 정보를 사용할 수 없습니다. 따라서 모든 관련 매개 변수를 지정해야 합니다.

줄 앞에 있는 ""의 사용: PowerShell이 파일의 전체 콘텐츠를 Write-SqlTableData cmdlet에 직접 전달하도록 강제하는 것입니다. 그러면 대량 삽입을 수행할 수 있습니다(행 삽입으로 행보다 훨씬 성능이 높음).

예제 4: 한 인스턴스에서 데이터를 검색하고 다른 인스턴스의 데이터베이스 테이블에 푸시

PS C:\> (Invoke-Sqlcmd -query "SELECT @@SERVERNAME AS 'ServerName', DB_NAME(dbid) AS 'Database',
                              name, CONVERT(BIGINT, size) * 8 AS 'size_in_kb', filename
                              FROM master..sysaltfiles" `
   -ServerInstance MyServer\MyInstance -database master -OutputAs DataTables) |
   Write-SqlTableData -ServerInstance MyServer\MyOtherInstance -Database ServerStats -SchemaName dbo -TableName DatabasesSizes -Force

이 예제에서는 Invoke-SqlCmd cmdlet을 사용하여 한 인스턴스에서 데이터베이스 파일 크기에 대한 정보를 가져오고 결과 행을 SQL Server의 다른 인스턴스에 있는 데이터베이스에 삽입합니다. 이 예제에서는 동일한 컴퓨터의 SQL Server 인스턴스 간에 데이터를 이동하지만 인스턴스는 완전히 다른 두 서버에 있을 수 있습니다.

예제 5: Azure SQL Database의 기존 테이블(또는 SQL 인증을 사용하는 모든 데이터베이스)에 데이터 쓰기

Import-Module SqlServer

# Set your connection string to Azure SQL DB.
# If your server is not in Azure, just tweak the 'Data Source' field to point to your server.
# Warning: putting clear text passwords in your scripts is highly discoraged, so instead
# of using "User ID" and "Password" in the connection string, we prompt for the credentials.
$cred = Get-Credential -Message "Enter your SQL Auth credentials"
$cred.Password.MakeReadOnly()

# Get access to the SMO Server object.
$srv = Get-SqlInstance -ServerInstance "<your_server_name>.database.windows.net" -Credential $cred

# Get access to table 'MyTable1' on database 'MyDB'.
# Note: both objects are assumed to exists already.
$db = $srv.Databases["MyDB"]
$table = $db.Tables["MyTable1"]

# Write the first 4 integers into the table.
# Note: 'MyTable1' has a column 'Col1' of type 'int'
Write-SqlTableData -InputData (1..4) -InputObject $table

# Now, we read the data back to verify all went ok.
Read-SqlTableData -InputObject $table

# Output:
#
# Col1
# ----
#   1
#   2
#   3
#   4

이 예제에서는 SQL 인증에서 Write-SqlTableData cmdlet을 사용하는 방법을 보여줍니다. 대부분의 코드는 -InputOject 매개 변수를 통해 cmdlet에 전달되는 필요한 개체(대상 테이블을 나타내는 SMO Table 개체)를 만드는 데 필요한 ADO.Net SMO 상용구입니다.

예제 6: Azure VM의 관리 ID를 사용하여 Azure SQL Database의 기존 테이블에 데이터를 쓰고 읽습니다.

Import-Module Az.Accounts,SQLServer

# Change these 3 variables to match your configuration.
# The example assumes you have a SQL Azure DB with the AdventureWorksLT sample DB on server sql-240627023957.
$Server = 'sql-240627023957.database.windows.net'
$Database = 'AdventureWorksLT'

# Connect to Azure using the system managed identify of the Azure VM this script is running on...
Add-AzAccount -Identity

# ... and fetch an access token to get to the DB.
$AccessToken = (Get-AzAccessToken -ResourceUrl 'https://database.windows.net').Token

# The assumption here is that the Microsoft Entra Admin on the server granted access
# to the managed identity of the VM by running something like:
#   CREATE USER [<Name of the VM>] FROM EXTERNAL PROVIDER
#   ALTER ROLE db_owner ADD MEMBER [<Name of the VM>]
# on the database ($Database).

# Insert a new record into the SalesLT.ProductDescription table
# Note that we are using -ConnectToDatabase to connect directly to the database, since it is unlikely for the
# managed identity of the VM to have access to anything but such database.
Write-SqlTableData -ServerInstance $Server -Database $Database -AccessToken $AccessToken -SchemaName SalesLT -TableName ProductDescription -InputData @{ Description = 'Hello SQLServer' } -ConnectToDatabase

# Confirm that the new record was successfully added
# Note that -ConnectToDatabase it not necessary in this case, as the connection if done directly to the database.
Read-SqlTableData -ServerInstance $Server -Database $Database -AccessToken $AccessToken -SchemaName SalesLT -TableName ProductDescription -OrderBy ModifiedDate -TopN 1 -ColumnOrderType DESC

# Output:
#
# ProductDescriptionID Description     rowguid                              ModifiedDate
# -------------------- -----------     -------                              ------------
#                 2011 Hello SQLServer f5f43821-aacd-4748-9d14-4a525c6a036b 6/30/2024 10:19:26 AM
#

매개 변수

-AccessToken

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

예를 들어 Service Principal 또는 Managed Identity사용하여 SQL Azure DB 연결하고 SQL Azure Managed Instance 데 사용할 수 있습니다.

사용할 매개 변수는 토큰을 나타내는 문자열이거나 Get-AzAccessToken -ResourceUrl https://database.windows.net실행하여 반환된 PSAccessToken 개체일 수 있습니다.

이 매개 변수는 모듈의 v22에서 새로 생성됩니다.

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

-ConnectionTimeout

시간 제한 오류가 발생하기 전에 서버 연결을 대기할 시간(초)을 지정합니다. 제한 시간 값은 0에서 65534 사이의 정수여야 합니다. 0을 지정하면 연결 시도가 시간 초과되지 않습니다.

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

-ConnectToDatabase

연결을 설정할 때 cmdlet이 전달된 데이터베이스(-DatabaseName)를 초기 카탈로그로 사용하도록 합니다. 이 매개 변수는 권한이 낮은 사용자가 쓰기 작업을 위해 기존 데이터베이스에 연결할 수 있도록 하는 데 유용할 수 있습니다. 데이터베이스를 만들어야 하는 경우 사용하지 마세요.

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

-Credential

SQL Server 연결에 대한 PSCredential 개체를 지정합니다. 자격 증명 개체를 가져오려면 Get-Credential cmdlet을 사용합니다. 자세한 내용은 get-credential Get-Help 입력합니다.

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

-DatabaseName

테이블을 포함하는 데이터베이스의 이름을 지정합니다.

cmdlet은 값 따옴표를 지원합니다. 특수 문자를 인용하거나 이스케이프할 필요가 없습니다.

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

-Encrypt

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

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

모듈의 v22에서 기본값은 Optional(v21과의 호환성을 위해)입니다. 모듈의 v23+에서 기본값은 기존 스크립트에 대한 호환성이 손상되는 변경을 만들 수 있는 '필수'입니다.

이 매개 변수는 모듈의 v22에서 새로 생성됩니다.

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

-Force

이 cmdlet은 누락된 SQL Server 개체를 만듭니다. 여기에는 데이터베이스, 스키마 및 테이블이 포함됩니다. 이러한 개체를 만들려면 적절한 자격 증명이 있어야 합니다.

누락된 개체에 대해 이 매개 변수를 지정하지 않으면 cmdlet에서 오류를 반환합니다.

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

-HostNameInCertificate

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

이 매개 변수는 모듈의 v22에서 새로 생성됩니다.

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

-IgnoreProviderContext

이 cmdlet은 현재 컨텍스트를 사용하여 ServerInstance, DatabaseName, SchemaName및 tableName 매개 변수 값을 재정의하지 않음을 나타냅니다. 이 매개 변수를 지정하지 않으면 cmdlet은 가능한 경우 cmdlet을 실행하는 컨텍스트에 따라 이러한 매개 변수의 값을 무시합니다.

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

-InputData

데이터베이스에 쓸 데이터를 지정합니다.

일반적인 입력 데이터는 system.Data.DataTable있지만 System.Data.DataSet 또는 System.Data.DateRow* 개체를 지정할 수 있습니다.

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

-InputObject

이 cmdlet이 쓰는 테이블을 나타내는 SMO(SQL Server Management Objects) 개체의 배열을 지정합니다.

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

-Passthru

이 cmdlet이 SMO를 반환한다는 것을 나타냅니다. Table 개체입니다. 이 개체는 추가된 데이터를 포함하는 테이블을 나타냅니다. 쓰기 작업 후에 테이블에서 작업할 수 있습니다.

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

-Path

이 cmdlet이 데이터를 쓰는 테이블의 SQL 공급자 컨텍스트에서 전체 경로를 지정합니다.

형식:String[]
Position:1
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

-SchemaName

테이블의 스키마 이름을 지정합니다.

데이터베이스 또는 데이터베이스의 자식 항목 컨텍스트에서 이 cmdlet을 실행하는 경우 cmdlet은 이 매개 변수 값을 무시합니다. cmdlet의 IgnoreProviderContext 매개 변수를 지정하여 SchemaName 매개 변수의 값을 사용합니다.

cmdlet은 값 따옴표를 지원합니다. 특수 문자를 인용하거나 이스케이프할 필요가 없습니다.

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

-ServerInstance

SQL Server 인스턴스의 이름을 지정합니다. 기본 인스턴스의 경우 컴퓨터 이름을 지정합니다. 명명된 인스턴스의 경우 ComputerName\InstanceName형식을 사용합니다.

데이터베이스 또는 데이터베이스의 자식 항목 컨텍스트에서 이 cmdlet을 실행하는 경우 cmdlet은 이 매개 변수 값을 무시합니다. 어쨌든 ServerInstance 매개 변수의 값을 사용하도록 cmdlet에 대한 IgnoreProviderContext 매개 변수를 지정합니다.

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

-SuppressProviderContextWarning

이 cmdlet은 cmdlet이 공급자 컨텍스트를 사용한다는 경고 메시지를 표시하지 않습니다.

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

-TableName

이 cmdlet이 읽는 테이블의 이름을 지정합니다.

데이터베이스 또는 데이터베이스의 자식 항목 컨텍스트에서 이 cmdlet을 실행하는 경우 cmdlet은 이 매개 변수 값을 무시합니다. cmdlet에 대한 IgnoreProviderContext 매개 변수를 지정하여 TableName 매개 변수의 값을 사용합니다.

cmdlet은 값 따옴표를 지원합니다. 특수 문자를 인용하거나 이스케이프할 필요가 없습니다.

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

-Timeout

쓰기 작업에 대한 제한 시간 값(초)을 지정합니다. 값을 지정하지 않으면 cmdlet은 기본값(일반적으로 30초)을 사용합니다. 시간 제한을 방지하려면 0을 전달합니다. 시간 제한은 0에서 65535 사이의 정수 값이어야 합니다.

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

-TrustServerCertificate

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

모듈의 v22에서 기본값은 $true(v21과의 호환성을 위해)입니다. 모듈의 v23+에서 기본값은 '$false'이며, 이로 인해 기존 스크립트에 대한 호환성이 손상되는 변경이 발생할 수 있습니다.

이 매개 변수는 모듈의 v22에서 새로 생성됩니다.

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

입력

System.Management.Automation.PSObject

System.String[]

Microsoft.SqlServer.Management.Smo.Table[]