Merge pull request #23538 from dzsquared/dac-overview

more sqlpackage samples and common issues info

Author: liljack17

.openpublishing.redirection.json

@@ -59444,6 +59444,11 @@
       "source_path": "docs/ssms/scripting/transact-sql-debugger-quickwatch-dialog-box.md",
       "redirect_url": "/sql/ssms/scripting/transact-sql-debugger-information",
       "redirect_document_id": false
+    },
+    {
+      "source_path": "docs/tools/sqlpackage/troubleshooting-import-export-sqlpackage.md",
+      "redirect_url": "/sql/tools/sqlpackage/troubleshooting-issues-and-performance-with-sqlpackage",
+      "redirect_document_id": false
     }
   ]
 }

docs/toc.yml

@@ -10335,8 +10335,8 @@ items:
       href: tools/sqlpackage/sqlpackage-pipelines.md
     - name: SqlPackage for Azure Synapse Analytics
       href: tools/sqlpackage/sqlpackage-for-azure-synapse-analytics.md
-    - name: Troubleshooting Import/Export
-      href: tools/sqlpackage/troubleshooting-import-export-sqlpackage.md
+    - name: Troubleshooting SqlPackage
+      href: tools/sqlpackage/troubleshooting-issues-and-performance-with-sqlpackage.md
   - name: SQL Server Profiler
     href: tools/sql-server-profiler/sql-server-profiler.md
     items:

docs/tools/sqlpackage/sqlpackage-deploy-drift-report.md

@@ -138,7 +138,7 @@ SqlPackage {parameters}{properties}{SQLCMD Variables}
 |**/p:**|IgnoreWithNocheckOnForeignKeys=(BOOLEAN)|Specifies whether differences in the value of the WITH NOCHECK clause for foreign keys will be ignored or updated when you publish to a database.| 
 |**/p:**|IncludeCompositeObjects=(BOOLEAN)|Include all composite elements with the same database as part of a single publish operation.|
 |**/p:**|IncludeTransactionalScripts=(BOOLEAN)|Specifies whether transactional statements should be used where possible when you publish to a database.|
-|**/p:**|LongRunningCommandTimeout=(INT32)| Specifies the long running command timeout in seconds when executing queries against SQL Server. Use 0 to wait indefinitely.|
+|**/p:**|LongRunningCommandTimeout=(INT32 '0')| Specifies the long running command timeout in seconds when executing queries against SQL Server. Use 0 to wait indefinitely.|
 |**/p:**|NoAlterStatementsToChangeClrTypes=(BOOLEAN)|Specifies that publish should always drop and re-create an assembly if there is a difference instead of issuing an ALTER ASSEMBLY statement. |
 |**/p:**|PopulateFilesOnFileGroups=(BOOLEAN 'True')|Specifies whether a new file is also created when a new FileGroup is created in the target database. |
 |**/p:**|RegisterDataTierApplication=(BOOLEAN)|Specifies whether the schema is registered with the database server. 

docs/tools/sqlpackage/sqlpackage-download.md

@@ -57,13 +57,13 @@ Evergreen links are available for downloading the latest Sqlpackage versions:
 2. To extract the file and launch SqlPackage, open a new Terminal window and type the following commands:
 
    ```bash
-   $ cd ~
-   $ mkdir sqlpackage
-   $ unzip ~/Downloads/sqlpackage-linux-<version string>.zip -d ~/sqlpackage 
-   $ echo "export PATH=\"\$PATH:$HOME/sqlpackage\"" >> ~/.bashrc
-   $ chmod a+x ~/sqlpackage/sqlpackage
-   $ source ~/.bashrc
-   $ sqlpackage
+   cd ~
+   mkdir sqlpackage
+   unzip ~/Downloads/sqlpackage-linux-<version string>.zip -d ~/sqlpackage 
+   echo "export PATH=\"\$PATH:$HOME/sqlpackage\"" >> ~/.bashrc
+   chmod a+x ~/sqlpackage/sqlpackage
+   source ~/.bashrc
+   sqlpackage
    ```
 
    > [!NOTE]
@@ -72,26 +72,26 @@ Evergreen links are available for downloading the latest Sqlpackage versions:
    **Debian:**
 
    ```bash
-   $ sudo apt-get install libunwind8
+   sudo apt-get install libunwind8
    ```
 
    **Redhat:**
 
    ```bash
-   $ yum install libunwind
-   $ yum install libicu
+   yum install libunwind
+   yum install libicu
    ```
 
    **Ubuntu:**
 
    ```bash
-   $ sudo apt-get install libunwind8
+   sudo apt-get install libunwind8
 
    # install the libicu library based on the Ubuntu version
-   $ sudo apt-get install libicu55      # for 16.x
-   $ sudo apt-get install libicu57      # for 17.x
-   $ sudo apt-get install libicu60      # for 18.x
-   $ sudo apt-get install libicu66      # for 20.x
+   sudo apt-get install libicu55      # for 16.x
+   sudo apt-get install libicu57      # for 17.x
+   sudo apt-get install libicu60      # for 18.x
+   sudo apt-get install libicu66      # for 20.x
    ```
 
 ## macOS (.NET Core)
@@ -100,25 +100,25 @@ Evergreen links are available for downloading the latest Sqlpackage versions:
 2. To extract the file and launch SqlPackage, open a new Terminal window and type the following commands:
 
    ```bash
-   $ mkdir sqlpackage
-   $ unzip ~/Downloads/sqlpackage-osx-<version string>.zip -d ~/sqlpackage
-   $ chmod +x ~/sqlpackage/sqlpackage
-   $ echo 'export PATH="$PATH:~/sqlpackage"' >> ~/.bash_profile
-   $ source ~/.bash_profile
-   $ sqlpackage
+   mkdir sqlpackage
+   unzip ~/Downloads/sqlpackage-osx-<version string>.zip -d ~/sqlpackage
+   chmod +x ~/sqlpackage/sqlpackage
+   echo 'export PATH="$PATH:~/sqlpackage"' >> ~/.bash_profile
+   source ~/.bash_profile
+   sqlpackage
    ```
 
    > [!NOTE]
    > Security settings may require modification to run SqlPackage on macOS. Use the following commands to interact with Gatekeeper from the command line.
 
    **Before executing SqlPackage:**
    ```bash
-   $ sudo spctl --master-disable
+   sudo spctl --master-disable
    ```
 
    **After executing SqlPackage:**
    ```bash
-   $ sudo spctl --master-enable
+   sudo spctl --master-enable
    ```
 
 ## Windows (.NET Core)

docs/tools/sqlpackage/sqlpackage-export.md

@@ -37,6 +37,14 @@ SqlPackage /a:Export /ssn:"{yourserver}.database.windows.net,1433" /sdn:"Adventu
 # example export using Azure Active Directory Service Principal
 SqlPackage /Action:Export /TargetFile:"C:\AdventureWorksLT.bacpac" \
     /SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;Authentication=Active Directory Service Principal;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
+
+# example export connecting using Azure Active Directory username and password
+SqlPackage /Action:Export /TargetFile:"C:\AdventureWorksLT.bacpac" \
+    /SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;Authentication=Active Directory Password;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;User ID={yourusername};Password={yourpassword}"
+
+# example export connecting using Azure Active Directory universal authentication
+SqlPackage /Action:Export /TargetFile:"C:\AdventureWorksLT.bacpac" /UniversalAuthentication=True \
+    /SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
 ```
 
 ## Parameters for the Export action
@@ -74,7 +82,7 @@ SqlPackage /Action:Export /TargetFile:"C:\AdventureWorksLT.bacpac" \
 |**/p:**|DatabaseLockTimeout=(INT32 '60')| Specifies the database lock timeout in seconds when executing queries against SQLServer. Use -1 to wait indefinitely.|
 |**/p:**|HashObjectNamesInLogs=(BOOLEAN)|Specifies whether to replace all object names in logs with a random hash value.|
 |**/p:**|IgnoreIndexesStatisticsOnEnclaveEnabledColumns=(BOOLEAN)|Specifies whether indexes or statistics on columns encrypted using randomized encryption and enclave-enabled column encryption keys should be ignored (not included in the generated bacpac). By default (false) any index or a statistic on a column encrypted using randomized encryption and an enclave-enabled column encryption key will block the export action.|
-|**/p:**|LongRunningCommandTimeout=(INT32)| Specifies the long running command timeout in seconds when executing queries against SQL Server. Use 0 to wait indefinitely.|
+|**/p:**|LongRunningCommandTimeout=(INT32 '0')| Specifies the long running command timeout in seconds when executing queries against SQL Server. Use 0 to wait indefinitely.|
 |**/p:**|Storage=({File|Memory} )| Specifies the type of backing storage for the schema model used during extraction. 'Memory' is default for .NET Core version of SqlPackage. 'File' is only available and default for .NET Framework version of SqlPackage. |
 |**/p:**|TableData=(STRING[])|Indicates the table from which data will be extracted. Specify the table name with or without the brackets surrounding the name parts in the following format: schema_name.table_identifier. This option may be specified multiple times.|
 |**/p:**|TargetEngineVersion=({Default|Latest|V11|V12} 'Latest')|This property is deprecated and use is not recommended. Specifies the version the target engine for Azure SQL Database is expected to be.|
@@ -85,4 +93,4 @@ SqlPackage /Action:Export /TargetFile:"C:\AdventureWorksLT.bacpac" \
 ## Next Steps
 
 - Learn more about [SqlPackage](sqlpackage.md)
-- [Troubleshooting Import/Export with SqlPackage](./troubleshooting-import-export-sqlpackage.md)
+- [Troubleshooting with SqlPackage](./troubleshooting-issues-and-performance-with-sqlpackage.md)

docs/tools/sqlpackage/sqlpackage-extract.md

@@ -33,18 +33,28 @@ SqlPackage /Action:Extract {parameters} {properties}
 SqlPackage /Action:Extract /TargetFile:{filename}.dacpac /DiagnosticsFile:{logFile}.log /p:ExtractAllTableData=false /p:VerifyExtraction=true \
     /SourceServerName:{serverFQDN} /SourceDatabaseName:{databaseName} /SourceUser:{username} /SourcePassword:{password}
 
-
 # example extract to create a .sql file containing the schema definition of the database
 SqlPackage /Action:Extract /TargetFile:{filename}.dacpac /DiagnosticsFile:{logFile}.log /SourceServerName:{serverFQDN} \
     /SourceDatabaseName:{databaseName} /SourceUser:{username} /SourcePassword:{password} /p:ExtractTarget:File
 
+# example extract to create a .dacpac file with data connecting using SQL authentication
+SqlPackage /Action:Extract /TargetFile:{filename}.dacpac /DiagnosticsFile:{logFile}.log /p:ExtractAllTableData=true /p:VerifyExtraction=true \
+    /SourceServerName:{serverFQDN} /SourceDatabaseName:{databaseName} /SourceUser:{username} /SourcePassword:{password}
+
+
 # example extract to create a schema-only .dacpac file connecting using Active Directory Service Principal
 SqlPackage /Action:Extract /TargetFile:"C:\AdventureWorksLT.dacpac" \
     /SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;Authentication=Active Directory Service Principal;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
 
-# example extract to create a .dacpac file with data connecting using SQL authentication
-SqlPackage /Action:Extract /TargetFile:{filename}.dacpac /DiagnosticsFile:{logFile}.log /p:ExtractAllTableData=true /p:VerifyExtraction=true \
-    /SourceServerName:{serverFQDN} /SourceDatabaseName:{databaseName} /SourceUser:{username} /SourcePassword:{password}
+
+# example extract to create a schema-only .dacpac file connecting using Azure Active Directory username and password
+SqlPackage /Action:Extract /TargetFile:"C:\AdventureWorksLT.dacpac" \
+    /SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;Authentication=Active Directory Password;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;User ID={yourusername};Password={yourpassword}"
+
+
+# example extract to create a schema-only .dacpac file connecting using Azure Active Directory universal authentication
+SqlPackage /Action:Extract /TargetFile:"C:\AdventureWorksLT.dacpac" /UniversalAuthentication=True \
+    /SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
 ```
 
 ## Parameters for the Extract action
@@ -97,7 +107,7 @@ SqlPackage /Action:Extract /TargetFile:{filename}.dacpac /DiagnosticsFile:{logFi
 |**/p:**|IgnoreExtendedProperties=(BOOLEAN)|Specifies whether extended properties should be ignored.|
 |**/p:**|IgnorePermissions=(BOOLEAN 'True')|Specifies whether permissions should be ignored.|
 |**/p:**|IgnoreUserLoginMappings=(BOOLEAN)|Specifies whether relationships between users and logins are ignored.|
-|**/p:**|LongRunningCommandTimeout=(INT32)| Specifies the long running command timeout in seconds when executing queries against SQL Server. Use 0 to wait indefinitely.|
+|**/p:**|LongRunningCommandTimeout=(INT32 '0')| Specifies the long running command timeout in seconds when executing queries against SQL Server. Use 0 to wait indefinitely.|
 |**/p:**|Storage=({File|Memory})|Specifies the type of backing storage for the schema model used during extraction. 'Memory' is default for .NET Core version of SqlPackage. 'File' is only available and default for .NET Framework version of SqlPackage.|
 |**/p:**|TableData=(STRING[])|Indicates the table from which data will be extracted. Specify the table name with or without the brackets surrounding the name parts in the following format: schema_name.table_identifier. This option may be specified multiple times.|
 |**/p:**|TempDirectoryForTableData=(STRING)|Specifies the temporary directory used to buffer table data before being written to the package file.|
@@ -108,3 +118,4 @@ SqlPackage /Action:Extract /TargetFile:{filename}.dacpac /DiagnosticsFile:{logFi
 ## Next Steps
 
 - Learn more about [SqlPackage](sqlpackage.md)
+- [Troubleshooting with SqlPackage](./troubleshooting-issues-and-performance-with-sqlpackage.md)

docs/tools/sqlpackage/sqlpackage-import.md

@@ -37,6 +37,14 @@ SqlPackage /a:Import /tsn:"{yourserver}.database.windows.net,1433" /tdn:"Adventu
 # example import using Azure Active Directory Service Principal
 SqlPackage /Action:Import /SourceFile:"C:\AdventureWorksLT.bacpac" \
     /TargetConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;Authentication=Active Directory Service Principal;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
+
+# example import connecting using Azure Active Directory username and password
+SqlPackage /Action:Import /SourceFile:"C:\AdventureWorksLT.bacpac" \
+    /TargetConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;Authentication=Active Directory Password;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;User ID={yourusername};Password={yourpassword}"
+
+# example import connecting using Azure Active Directory universal authentication
+SqlPackage /Action:Import /SourceFile:"C:\AdventureWorksLT.bacpac" /UniversalAuthentication=True \
+    /TargetConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
 ```
 
 ## Parameters for the Import action
@@ -80,12 +88,12 @@ SqlPackage /Action:Import /SourceFile:"C:\AdventureWorksLT.bacpac" \
 |**/p:**|ImportContributorArguments=(STRING)|Specifies deployment contributor arguments for the deployment contributors. This property should be a semi-colon delimited list of values.|
 |**/p:**|ImportContributorPaths=(STRING)|Specifies paths to load additional deployment contributors. This property should be a semi-colon delimited list of values.|
 |**/p:**|ImportContributors=(STRING)|Specifies the deployment contributors, which should run when the bacpac is imported. This property should be a semi-colon delimited list of fully qualified build contributor names or IDs.|
-|**/p:**|LongRunningCommandTimeout=(INT32)| Specifies the long running command timeout in seconds when executing queries against SQL Server. Use 0 to wait indefinitely.|
+|**/p:**|LongRunningCommandTimeout=(INT32 '0')| Specifies the long running command timeout in seconds when executing queries against SQL Server. Use 0 to wait indefinitely.|
 |**/p:**|PreserveIdentityLastValues=(BOOLEAN)|Specifies whether last values for identity columns should be preserved during deployment.|
 |**/p:**|RebuildIndexesOfflineForDataPhase=(BOOLEAN FALSE)|When true, rebuilds indexes offline after importing data into SQL Server.|
 |**/p:**|Storage=({File|Memory})|Specifies how elements are stored when building the database model. For performance reasons the default is InMemory. For large databases, File backed storage is required.|
 
 ## Next Steps
 
 - Learn more about [SqlPackage](sqlpackage.md)
-- [Troubleshooting Import/Export with SqlPackage](./troubleshooting-import-export-sqlpackage.md)
+- [Troubleshooting with SqlPackage](./troubleshooting-issues-and-performance-with-sqlpackage.md)

docs/tools/sqlpackage/sqlpackage-publish.md

@@ -41,6 +41,14 @@ SqlPackage /a:Publish /tsn:"{yourserver}.database.windows.net,1433" /tdn:"Advent
 SqlPackage /Action:Publish /SourceFile:"C:\AdventureWorksLT.dacpac" \
     /TargetConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;Authentication=Active Directory Service Principal;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
 
+# example publish connecting using Azure Active Directory username and password
+SqlPackage /Action:Publish /SourceFile:"C:\AdventureWorksLT.dacpac" \
+    /TargetConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;Authentication=Active Directory Password;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;User ID={yourusername};Password={yourpassword}"
+
+# example publish connecting using Azure Active Directory universal authentication
+SqlPackage /Action:Publish /SourceFile:"C:\AdventureWorksLT.dacpac" /UniversalAuthentication=True \
+    /TargetConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
+
 # example publish with 2 SQLCMD variables
 # as seen in a post deployment script for user passwords
 # https://github.com/Azure-Samples/app-sql-devops-demo-project/blob/main/sql/wwi-dw-ssdt/PostDeploymentScripts/AddUsers.sql
@@ -189,7 +197,7 @@ SqlPackage /Action:Publish /SourceFile:"C:\AdventureWorksLT.dacpac" \
 |**/p:**|IncludeCompositeObjects=(BOOLEAN)|Include all composite elements with the same database as part of a single publish operation.|
 |**/p:**|IncludeTransactionalScripts=(BOOLEAN)|Specifies whether transactional statements should be used where possible when you publish to a database.|
 |**/p:**|IsAlwaysEncryptedParameterizationEnabled=(BOOLEAN 'False')|Enables variable parameterization on Always Encrypted columns in pre/post deployment scripts.|
-|**/p:**|LongRunningCommandTimeout=(INT32)|Specifies the long running command timeout in seconds when executing queries against SQL Server. Use 0 to wait indefinitely.|
+|**/p:**|LongRunningCommandTimeout=(INT32 '0')|Specifies the long running command timeout in seconds when executing queries against SQL Server. Use 0 to wait indefinitely.|
 |**/p:**|NoAlterStatementsToChangeClrTypes=(BOOLEAN)|Specifies that publish should always drop and re-create an assembly if there is a difference instead of issuing an ALTER ASSEMBLY statement.|
 |**/p:**|PopulateFilesOnFileGroups=(BOOLEAN 'True')|Specifies whether a new file is also created when a new FileGroup is created in the target database.|
 |**/p:**|PreserveIdentityLastValues=(BOOLEAN)|Specifies whether last values for identity columns should be preserved during deployment.|
@@ -221,4 +229,5 @@ The following table describes the format of the option that you can use to overr
 
 ## Next Steps
 
-- Learn more about [SqlPackage](sqlpackage.md)
+- Learn more about [SqlPackage](sqlpackage.md)
+- [Troubleshooting with SqlPackage](./troubleshooting-issues-and-performance-with-sqlpackage.md)