PSql

2.0.0-alpha02

en-US/PSql.dll-help.xml

<?xml version="1.0" encoding="utf-8" ?>
<helpItems schema="maml"
            xmlns="http://msh"
       xmlns:maml="http://schemas.microsoft.com/maml/2004/10"
    xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10"
        xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
  <!--
    Copyright (C) 2020 Jeffrey Sharp
 
    Permission to use, copy, modify, and distribute this software for any
    purpose with or without fee is hereby granted, provided that the above
    copyright notice and this permission notice appear in all copies.
 
    THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
    WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
    MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
    ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
    WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
    ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
    OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
    Documentation:
    https://docs.microsoft.com/en-us/powershell/developer/help/how-to-create-the-cmdlet-help-file
  -->
 
  <command:command>
    <command:details>
      <command:name>Invoke-Sql</command:name>
      <command:verb>Invoke</command:verb>
      <command:noun>Sql</command:noun>
      <maml:description>
        <maml:para>Runs SQL scripts on SQL Server or Azure SQL Database.</maml:para>
      </maml:description>
    </command:details>
 
    <maml:description>
      <maml:para>
        The Invoke-Sql cmdlet runs SQL scripts on SQL Server or Azure SQL Database and outputs each result row as a PowerShell custom object. Additionally, the Invoke-Sql cmdlet receives messages sent by the server and writes them to the information or warning streams, depending on severity.
      </maml:para>
      <maml:para>
        Invoke-Sql supports a limited subset of SQLCMD preprocessing features:
      </maml:para>
      <maml:list>
        <maml:listItem>
          <maml:para>GO batch separator</maml:para>
        </maml:listItem>
        <maml:listItem>
          <maml:para>$() sqlcmd variable expansion</maml:para>
        </maml:listItem>
        <maml:listItem>
          <maml:para>:setvar set a sqlcmd variable</maml:para>
        </maml:listItem>
        <maml:listItem>
          <maml:para>:r include a file</maml:para>
        </maml:listItem>
      </maml:list>
      <maml:para><!-- HACK: Get-Help does not put a blank line after the <list> --></maml:para>
      <maml:para>
        Use the -NoPreprocessing switch to disable preprocessing.
      </maml:para>
      <maml:para>
        By default, Invoke-Sql executes each SQL batch using an error-handling wrapper that prints the offending SQL batch if an error occurs, greatly improving the diagnostic experience. However, the wrapper conflicts with a few specific scenarios:
      </maml:para>
      <maml:list>
        <maml:listItem>
          <maml:para>
            Beginning a transaction without committing it in the same batch: this causes an error when using the wrapper.
          </maml:para>
        </maml:listItem>
        <maml:listItem>
          <maml:para>
            Committing a transaction that was not started in the same batch: this causes an error when using the wrapper.
          </maml:para>
        </maml:listItem>
        <maml:listItem>
          <maml:para>
            Creating a temporary table: the temporary table vanishes at the end of the batch when using the wrapper.
          </maml:para>
        </maml:listItem>
      </maml:list>
      <maml:para><!-- HACK: Get-Help does not put a blank line after the <list> --></maml:para>
      <maml:para>
        To support these scenarios, disable the error-handling wrapper when required. To disable the wrapper for a single SQL batch, include the line '--# NOWRAP' (without the quotes) anywhere in the batch. To disable the wrapper for all batches, use the -NoErrorHandling switch.
      </maml:para>
      <maml:para>
        After execution of each batch, if an error occurred, Invoke-Sql writes an object to the error stream.
      </maml:para>
    </maml:description>
 
    <command:syntax>
      <command:syntaxItem>
        <maml:name>Invoke-Sql</maml:name>
        <command:parameter required="true" position="0" aliases="none" pipelineInput="true (ByValue)" globbing="false">
          <maml:name>Sql</maml:name>
          <command:parameterValue required="true">string[]</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" position="1" pipelineInput="false" globbing="false" >
          <maml:name>Define</maml:name>
          <command:parameterValue required="true">hashtable</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" position="named" pipelineInput="false" globbing="false">
          <maml:name>Context</maml:name>
          <command:parameterValue required="true">SqlContext</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" position="named" pipelineInput="false" globbing="false">
          <maml:name>NoPreprocessing</maml:name>
        </command:parameter>
        <command:parameter required="false" position="named" pipelineInput="false" globbing="false">
          <maml:name>NoErrorHandling</maml:name>
        </command:parameter>
        <command:parameter required="false" position="named" pipelineInput="false" globbing="false">
          <maml:name>UseSqlTypes</maml:name>
        </command:parameter>
      </command:syntaxItem>
      <command:syntaxItem>
        <maml:name>Invoke-Sql</maml:name>
        <command:parameter required="true" position="0" aliases="none" pipelineInput="true (ByValue)" globbing="false">
          <maml:name>Sql</maml:name>
          <command:parameterValue required="true">string[]</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" position="1" pipelineInput="false" globbing="false" >
          <maml:name>Define</maml:name>
          <command:parameterValue required="true">hashtable</command:parameterValue>
        </command:parameter>
        <command:parameter required="true" position="named" pipelineInput="false" globbing="false">
          <maml:name>Connection</maml:name>
          <command:parameterValue required="true">SqlConnection</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" position="named" pipelineInput="false" globbing="false">
          <maml:name>NoPreprocessing</maml:name>
        </command:parameter>
        <command:parameter required="false" position="named" pipelineInput="false" globbing="false">
          <maml:name>NoErrorHandling</maml:name>
        </command:parameter>
        <command:parameter required="false" position="named" pipelineInput="false" globbing="false">
          <maml:name>UseSqlTypes</maml:name>
        </command:parameter>
      </command:syntaxItem>
    </command:syntax>
 
    <command:parameters>
      <command:parameter required="true" position="0" pipelineInput="true (ByValue)" globbing="false">
        <maml:name>Sql</maml:name>
        <maml:description>
          <maml:para>The SQL scripts(s) to run.</maml:para>
        </maml:description>
        <command:parameterValue required="true">string[]</command:parameterValue>
        <dev:defaultValue>None</dev:defaultValue>
        <dev:type>string[]</dev:type>
      </command:parameter>
      <command:parameter required="false" position="named" pipelineInput="false" globbing="false">
        <maml:name>Define</maml:name>
        <maml:description>
          <maml:para>SQLCMD preprocessor variables to define.</maml:para>
        </maml:description>
        <command:parameterValue required="true">hashtable</command:parameterValue>
        <dev:defaultValue>None</dev:defaultValue>
        <dev:type>hashtable</dev:type>
      </command:parameter>
      <command:parameter required="false" position="named" pipelineInput="false" globbing="false">
        <maml:name>Context</maml:name>
        <maml:description>
          <maml:para>An object specifying how to connect to the database. Obtain via the New-SqlContext cmdlet.</maml:para>
        </maml:description>
        <command:parameterValue required="true">SqlContext</command:parameterValue>
        <dev:defaultValue>Default SQL Server instance on the local machine</dev:defaultValue>
        <dev:type>SqlContext</dev:type>
      </command:parameter>
      <command:parameter required="false" position="named" pipelineInput="false" globbing="false">
        <maml:name>Connection</maml:name>
        <maml:description>
          <maml:para>The SQL connection on which to execute commands.</maml:para>
        </maml:description>
        <command:parameterValue required="true">SqlConnection</command:parameterValue>
        <dev:defaultValue>None</dev:defaultValue>
        <dev:type>SqlConnection</dev:type>
      </command:parameter>
      <command:parameter required="false" position="named" pipelineInput="false" globbing="false">
        <maml:name>NoPreprocessing</maml:name>
        <maml:description>
          <maml:para>Disables SQLCMD preprocessing support.</maml:para>
        </maml:description>
        <command:parameterValue required="false">SwitchParameter</command:parameterValue>
        <dev:defaultValue>false</dev:defaultValue>
        <dev:type>SwitchParameter</dev:type>
      </command:parameter>
      <command:parameter required="false" position="named" pipelineInput="false" globbing="false">
        <maml:name>NoErrorHandling</maml:name>
        <maml:description>
          <maml:para>Disables the error-handling wrapper.</maml:para>
        </maml:description>
        <command:parameterValue required="false">SwitchParameter</command:parameterValue>
        <dev:defaultValue>false</dev:defaultValue>
        <dev:type>SwitchParameter</dev:type>
      </command:parameter>
    </command:parameters>
 
    <command:inputTypes>
      <command:inputType>
        <dev:type>
          <maml:name>string[]</maml:name>
          <maml:uri/>
          <maml:description/>
        </dev:type>
        <maml:description>
          <maml:para>SQL scripts(s) to run.</maml:para>
        </maml:description>
      </command:inputType>
    </command:inputTypes>
 
    <command:returnValues>
      <command:returnValue>
        <dev:type>
          <maml:name>PSCustomObject[]</maml:name>
          <maml:uri/>
          <maml:description/>
        </dev:type>
        <maml:description>
          <maml:para>Result rows of the invoked scripts. The cmdlet converts each row to a PSCustomObject by mapping columns to properties.</maml:para>
        </maml:description>
      </command:returnValue>
    </command:returnValues>
 
    <maml:relatedLinks>
      <maml:navigationLink>
        <maml:linkText>PSql:</maml:linkText>
        <maml:uri>https://github.com/sharpjs/PSql</maml:uri>
      </maml:navigationLink>
      <maml:navigationLink>
        <maml:linkText>sqlcmd Utility:</maml:linkText>
        <maml:uri>https://docs.microsoft.com/en-us/sql/tools/sqlcmd-utility</maml:uri>
      </maml:navigationLink>
    </maml:relatedLinks>
 
  </command:command>
 
  <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
 
  <command:command>
    <command:details>
      <command:name>New-SqlContext</command:name>
      <command:verb>New</command:verb>
      <command:noun>SqlContext</command:noun>
      <maml:description>
        <maml:para>Creates an object specifying how to connect to a SQL Server or compatible database.</maml:para>
      </maml:description>
    </command:details>
 
    <maml:description>
      <maml:para>
        The PSql New-SqlContext cmdlet accepts parameters specifying how to connect to a SQL Server, Azure SQL Database, or compatible database, and outputs a context object containing the supplied values. Pass the context object to other PSql cmdlets via their -Context parameter to work with the specified database.
      </maml:para>
    </maml:description>
 
    <command:syntax>
      <command:syntaxItem>
        <maml:name>New-SqlContext</maml:name>
        <command:parameter required="false" position="0" pipelineInput="true (ByPropertyName)" globbing="false" >
          <maml:name>ServerName</maml:name>
          <command:parameterValue required="true">string</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" position="1" pipelineInput="true (ByPropertyName)" globbing="false" >
          <maml:name>DatabaseName</maml:name>
          <command:parameterValue required="true">string</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" position="2" pipelineInput="true (ByPropertyName)" globbing="false" >
            <maml:name>Credential</maml:name>
          <command:parameterValue required="true">PSCredential</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" position="named" pipelineInput="true (ByPropertyName)" globbing="false" >
            <maml:name>EncryptionMode</maml:name>
          <command:parameterValue required="true">{ Default | None }</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" position="named" pipelineInput="false" globbing="false">
          <maml:name>ReadOnlyIntent</maml:name>
        </command:parameter>
        <command:parameter required="false" position="named" pipelineInput="true (ByPropertyName)" globbing="false" >
          <maml:name>ClientName</maml:name>
          <command:parameterValue required="true">string</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" position="named" pipelineInput="true (ByPropertyName)" globbing="false" >
          <maml:name>ApplicationName</maml:name>
          <command:parameterValue required="true">string</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" position="named" pipelineInput="true (ByPropertyName)" globbing="false" >
          <maml:name>ConnectTimeout</maml:name>
          <command:parameterValue required="true">TimeSpan</command:parameterValue>
        </command:parameter>
      </command:syntaxItem>
      <command:syntaxItem>
        <maml:name>New-SqlContext</maml:name>
        <command:parameter required="true" position="named" aliases="none" pipelineInput="true (ByPropertyName)" globbing="false">
          <maml:name>Azure</maml:name>
        </command:parameter>
        <command:parameter required="true" position="1" pipelineInput="true (ByPropertyName)" globbing="false" >
          <maml:name>ResourceGroupName</maml:name>
          <command:parameterValue required="true">string</command:parameterValue>
        </command:parameter>
        <command:parameter required="true" position="2" pipelineInput="true (ByPropertyName)" globbing="false" >
          <maml:name>ServerName</maml:name>
          <command:parameterValue required="true">string</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" position="3" pipelineInput="true (ByPropertyName)" globbing="false" >
          <maml:name>DatabaseName</maml:name>
          <command:parameterValue required="true">string</command:parameterValue>
        </command:parameter>
        <command:parameter required="true" position="4" pipelineInput="true (ByPropertyName)" globbing="false" >
            <maml:name>Credential</maml:name>
          <command:parameterValue required="true">PSCredential</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" position="named" pipelineInput="true (ByPropertyName)" globbing="false">
          <maml:name>ReadOnlyIntent</maml:name>
        </command:parameter>
        <command:parameter required="false" position="named" pipelineInput="true (ByPropertyName)" globbing="false" >
          <maml:name>ClientName</maml:name>
          <command:parameterValue required="true">string</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" position="named" pipelineInput="true (ByPropertyName)" globbing="false" >
          <maml:name>ApplicationName</maml:name>
          <command:parameterValue required="true">string</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" position="named" pipelineInput="true (ByPropertyName)" globbing="false" >
          <maml:name>ConnectTimeout</maml:name>
          <command:parameterValue required="true">TimeSpan</command:parameterValue>
        </command:parameter>
      </command:syntaxItem>
    </command:syntax>
 
    <command:parameters>
      <command:parameter required="false" position="named" pipelineInput="true (ByPropertyName)" globbing="false">
        <maml:name>Azure</maml:name>
        <maml:description>
          <maml:para>Specifies that the database is an Azure SQL Database resource.</maml:para>
        </maml:description>
        <command:parameterValue required="false">SwitchParameter</command:parameterValue>
        <dev:defaultValue>false</dev:defaultValue>
        <dev:type>SwitchParameter</dev:type>
      </command:parameter>
      <command:parameter required="false" position="1" pipelineInput="true (ByPropertyName)" globbing="false">
        <maml:name>ResourceGroupName</maml:name>
        <maml:description>
          <maml:para>The name of the Azure resource group containing the virtual database server. Requires the -Azure switch.</maml:para>
        </maml:description>
        <command:parameterValue required="true">string</command:parameterValue>
        <dev:defaultValue>None</dev:defaultValue>
        <dev:type>string</dev:type>
      </command:parameter>
      <command:parameter required="false" position="2" pipelineInput="true (ByPropertyName)" globbing="false">
        <maml:name>ServerName</maml:name>
        <maml:description>
          <maml:para>The name of the database server.</maml:para>
          <maml:para>When -Azure is specified, this parameter specifies the Azure resource name of the virtual database server.</maml:para>
          <maml:para>Otherwise, this parameter specifies the DNS name of the database server, optionally suffixed by a backslash and a database engine instance name. Examples: db.example.com, db.example.com\instance2</maml:para>
        </maml:description>
        <command:parameterValue required="true">string</command:parameterValue>
        <dev:defaultValue>None with -Azure; otherwise, a value specifying the default instance on the local machine</dev:defaultValue>
        <dev:type>string</dev:type>
      </command:parameter>
      <command:parameter required="false" position="3" pipelineInput="true (ByPropertyName)" globbing="false">
        <maml:name>DatabaseName</maml:name>
        <maml:description>
          <maml:para>The name of the database.</maml:para>
          <maml:para>If not specified, connections will attempt to open in the default database of the authenticated user.</maml:para>
        </maml:description>
        <command:parameterValue required="true">string</command:parameterValue>
        <dev:defaultValue>None</dev:defaultValue>
        <dev:type>string</dev:type>
      </command:parameter>
      <command:parameter required="false" position="2" pipelineInput="true (ByPropertyName)" globbing="false">
        <maml:name>Credential</maml:name>
        <maml:description>
          <maml:para>The credential to use to authenticate with the database server.</maml:para>
          <maml:para>If not specified, connections will attempt to use integrated authentication.</maml:para>
        </maml:description>
        <command:parameterValue required="true">PSCredential</command:parameterValue>
        <dev:defaultValue>None</dev:defaultValue>
        <dev:type>PSCredential</dev:type>
      </command:parameter>
      <command:parameter required="false" position="named" pipelineInput="true (ByPropertyName)" globbing="false">
        <maml:name>EncryptionMode</maml:name>
        <maml:description>
          <maml:para>The transport encryption to use for connections.</maml:para>
        </maml:description>
        <command:parameterValue required="true">PSql.EncryptionMode</command:parameterValue>
        <dev:defaultValue>None</dev:defaultValue>
        <dev:type>PSql.EncryptionMode</dev:type>
        <dev:possibleValues>
          <dev:possibleValue>
            <dev:value>Default</dev:value>
            <maml:description>
              <maml:para>
                The default encrption mode. Equivalent to None for connections to the local machine, and Full for all other connections.
              </maml:para>
            </maml:description>
          </dev:possibleValue>
          <dev:possibleValue>
            <dev:value>None</dev:value>
            <maml:description>
              <maml:para>
                No connection encryption or server identity check. Data sent over the connection is exposed to other network devices. A malicious device could masquerade as a server. This encryption mode is appropriate for same-machine connections only.
              </maml:para>
            </maml:description>
          </dev:possibleValue>
          <dev:possibleValue>
            <dev:value>Unverified</dev:value>
            <maml:description>
              <maml:para>
                Connections are encrypted, but server identities are not verified. A malicious device could masquerade as a server. This encryption mode is appropriate only when the server uses a self-signed certificate.
              </maml:para>
            </maml:description>
          </dev:possibleValue>
          <dev:possibleValue>
            <dev:value>Full</dev:value>
            <maml:description>
              <maml:para>
                Connections are encrypted, and server identities are verified. This is the most secure encryption mode.
              </maml:para>
            </maml:description>
          </dev:possibleValue>
        </dev:possibleValues>
      </command:parameter>
      <command:parameter required="false" position="named" pipelineInput="true (ByPropertyName)" globbing="false">
        <maml:name>ClientName</maml:name>
        <maml:description>
          <maml:para>The name of the client device.</maml:para>
        </maml:description>
        <command:parameterValue required="true">string</command:parameterValue>
        <dev:defaultValue>None</dev:defaultValue>
        <dev:type>string</dev:type>
      </command:parameter>
      <command:parameter required="false" position="named" pipelineInput="true (ByPropertyName)" globbing="false">
        <maml:name>ApplicationName</maml:name>
        <maml:description>
          <maml:para>The name of the client application.</maml:para>
        </maml:description>
        <command:parameterValue required="true">string</command:parameterValue>
        <dev:defaultValue>None</dev:defaultValue>
        <dev:type>string</dev:type>
      </command:parameter>
      <command:parameter required="false" position="named" pipelineInput="true (ByPropertyName)" globbing="false">
        <maml:name>ConnectTimeout</maml:name>
        <maml:description>
          <maml:para>The duration after which a connection attempt times out.</maml:para>
        </maml:description>
        <command:parameterValue required="true">TimeSpan</command:parameterValue>
        <dev:defaultValue>None</dev:defaultValue>
        <dev:type>TimeSpan</dev:type>
      </command:parameter>
    </command:parameters>
 
    <command:returnValues>
      <command:returnValue>
        <dev:type>
          <maml:name>PSql.SqlContext</maml:name>
          <maml:uri/>
          <maml:description/>
        </dev:type>
        <maml:description>
          <maml:para>An object specifying how to connect to a SQL Server or compatible database.</maml:para>
        </maml:description>
      </command:returnValue>
    </command:returnValues>
 
    <maml:relatedLinks>
      <maml:navigationLink>
        <maml:linkText>PSql:</maml:linkText>
        <maml:uri>https://github.com/sharpjs/PSql</maml:uri>
      </maml:navigationLink>
    </maml:relatedLinks>
   </command:command>
</helpItems>