You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/tools/sqlpackage/troubleshooting-issues-and-performance-with-sqlpackage.md
+17-17Lines changed: 17 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -22,10 +22,10 @@ As general guideline, better performance can be obtained via the [.NET Core vers
22
22
1. Unzip archive as directed on the download page.
23
23
1. Open a command prompt and change directory (`cd`) to the SqlPackage folder.
24
24
25
-
It is important to use the latest available version of SqlPackage as performance improvements and bug fixes are released regularly.
25
+
It's important to use the latest available version of SqlPackage as performance improvements and bug fixes are released regularly.
26
26
27
27
### Substitute SqlPackage for the Import/Export Service
28
-
If you have attempted to use the Import/Export Service to import or export your database, you may be interested in using SqlPackage to perform the same operation with more control on optional parameters and properties.
28
+
If you have attempted to use the Import/Export Service to import or export your database, you can use SqlPackage to perform the same operation with more control on optional parameters and properties.
29
29
30
30
For Import, an example command is:
31
31
@@ -39,7 +39,7 @@ For Export, an example command is:
Alternative to username and password, [multi-factor authentication](/azure/azure-sql/database/authentication-mfa-ssms-overview) can be used to authenticate via Microsoft Entra authentication (formerly Azure Active Directory) with multi-factor authentication. Substitute the username and password parameters for `/ua:true` and `/tid:"yourdomain.onmicrosoft.com"`.
42
+
Alternative to username and password, [multifactor authentication](/azure/azure-sql/database/authentication-mfa-ssms-overview) can be used to authenticate via Microsoft Entra authentication (formerly Azure Active Directory) with multifactor authentication. Substitute the username and password parameters for `/ua:true` and `/tid:"yourdomain.onmicrosoft.com"`.
43
43
44
44
## Common issues
45
45
@@ -53,18 +53,18 @@ For issues related to timeouts, the following properties can be used to tune the
53
53
54
54
### Client resource consumption
55
55
56
-
For the export and extract commands, table data is passed to a temporary directory to buffer before being written to the bacpac/dacpac file. This storage requirement may be large and is relative to the full size of the data to be exported. Specify an alternative temporary directory with the property `/p:TempDirectoryForTableData=<path>`.
56
+
For the export and extract commands, table data is passed to a temporary directory to buffer before being written to the bacpac/dacpac file. This storage requirement can be large and is relative to the full size of the data to be exported. Specify an alternative temporary directory with the property `/p:TempDirectoryForTableData=<path>`.
57
57
58
-
The schema model is compiled in memory, so for large database schemas the memory requirement on the client machine running SqlPackage may be significant.
58
+
The schema model is compiled in memory, so for large database schemas the memory requirement on the client machine running SqlPackage can be significant.
59
59
60
60
61
61
### Low server resource consumption
62
62
63
-
By default, SqlPackage sets the maximum server parallelism to 8. If you note low server resource consumption, increasing the value of the `MaxParallelism` parameter may improve performance.
63
+
By default, SqlPackage sets the maximum server parallelism to 8. If you note low server resource consumption, increasing the value of the `MaxParallelism` parameter can improve performance.
64
64
65
65
### Access token
66
66
67
-
Using the `/AccessToken:` or `/at:` parameter enables token-based authentication for SqlPackage, however passing the token to the command can be tricky. If you are parsing an access token object in PowerShell either explicitly pass the string value or wrap the reference to the token property in $(). For example:
67
+
Using the `/AccessToken:` or `/at:` parameter enables token-based authentication for SqlPackage, however passing the token to the command can be tricky. If you're parsing an access token object in PowerShell either explicitly pass the string value or wrap the reference to the token property in $(). For example:
If SqlPackage is failing to connect, the server may not have encryption enabled or the configured certificate may not be issued from a trusted certificate authority (such as a self-signed certificate). You can change the SqlPackage command to either connect without encryption or to trust the server certificate. The [best practice](../../relational-databases/security/securing-sql-server.md) is to ensure that a trusted encrypted connection to the server can be established.
81
+
If SqlPackage is failing to connect, the server might not have encryption enabled or the configured certificate might not be issued from a trusted certificate authority (such as a self-signed certificate). You can change the SqlPackage command to either connect without encryption or to trust the server certificate. The [best practice](../../relational-databases/security/securing-sql-server.md) is to ensure that a trusted encrypted connection to the server can be established.
82
82
83
83
- Connect without encryption: /SourceEncryptConnection=False or /TargetEncryptConnection=False
84
84
- Trust server certificate: /SourceTrustServerCertificate=True or /TargetTrustServerCertificate=True
85
85
86
-
You may see any of the following warning messages when connecting to a SQL instance, indicating that command line parameters may require changes to connect to the server:
86
+
You could see any of the following warning messages when connecting to a SQL instance, indicating that command line parameters could require changes to connect to the server:
87
87
88
88
```output
89
89
The settings for connection encryption or server certificate trust may lead to connection failure if the server is not properly configured.
@@ -105,23 +105,23 @@ ALTER TABLE [HumanResources].[Department]
105
105
ADD CONSTRAINT [DF_Department_ModifiedDate_] DEFAULT ('') FOR [ModifiedDate];
106
106
```
107
107
108
-
These are the causes and solutions to work around this error:
108
+
Here are the causes and solutions to work around this error:
109
109
110
-
1. Verify that the destination you are importing into is an empty database.
111
-
1. If your database has constraints that are using the DEFAULT attribute (where SQL Server assigns a random name to the constraint) as well as an explicitly named constraint, you may have an issue where a constraint with the same name is attempted to be created twice. It is recommended to use all explicitly named constraints (not using DEFAULT), or all system-defined names (using DEFAULT).
110
+
1. Verify that the destination you're importing into is an empty database.
111
+
1. If your database has constraints that are using the DEFAULT attribute (where SQL Server assigns a random name to the constraint) and an explicitly named constraint, a constraint with the same name might be created twice. You should use all explicitly named constraints (not using DEFAULT), or all system-defined names (using DEFAULT).
112
112
1. Manually edit the model.xml and rename the constraint with the name experiencing the error to a unique name. This option should be undertaken only if directed by Microsoft support and poses a risk of .bacpac corruption.
113
113
114
114
## Diagnostics
115
115
Logs are essential to troubleshooting. Capture the diagnostic logs to a file with the `/DiagnosticsFile:<filename>` parameter.
116
116
117
-
Additional performance-related trace data can be logged by setting the environment variable `DACFX_PERF_TRACE=true` before running SqlPackage. To set this environment variable in PowerShell, use the following command:
117
+
More performance-related trace data can be logged by setting the environment variable `DACFX_PERF_TRACE=true` before running SqlPackage. To set this environment variable in PowerShell, use the following command:
118
118
119
119
```powershell
120
120
Set-Item -Path Env:DACFX_PERF_TRACE -Value true
121
121
```
122
122
123
123
## Import action tips
124
-
For imports that contain large tables or tables with many indexes, the use of `/p:RebuildIndexesOfflineForDataPhase=True` or `/p:DisableIndexesForDataPhase=False`may improve performance. These properties modify the index rebuild operation to occur offline or not occur, respectively. Those and other properties are available to tune the [SqlPackage Import](sqlpackage-import.md) operation.
124
+
For imports that contain large tables or tables with many indexes, the use of `/p:RebuildIndexesOfflineForDataPhase=True` or `/p:DisableIndexesForDataPhase=False`can improve performance. These properties modify the index rebuild operation to occur offline or not occur, respectively. Those and other properties are available to tune the [SqlPackage Import](sqlpackage-import.md) operation.
125
125
126
126
## Export action tips
127
127
A common cause of performance degradation during export is unresolved object references, which causes SqlPackage to attempt to resolve the object multiple times. For example, a view is defined that references a table and the table no longer exists in the database. If unresolved references appear in the export log, consider correcting the schema of the database to improve the export performance.
@@ -130,21 +130,21 @@ In scenarios where the OS disk space is limited and runs out during the export,
130
130
131
131
During an export process, the table data is compressed in the bacpac file. The use of `/p:CompressionOption` set to `Fast`, `SuperFast`, or `NotCompressed` may improve the export process speed while compressing the output bacpac file less.
132
132
133
-
To obtain the database schema and data while skipping the schema validation, perform an [Export](sqlpackage-export.md) with the property `/p:VerifyExtraction=True`.
133
+
To obtain the database schema and data while skipping the schema validation, perform an [Export](sqlpackage-export.md) with the property `/p:VerifyExtraction=False`.
134
134
135
135
## Azure SQL Database
136
136
137
137
The following tips are specific to running import or export against Azure SQL Database from an Azure virtual machine (VM):
138
138
139
139
- Use Business Critical or Premium tier database for best performance.
140
-
- Use SSD storage on the VM and ensure there is enough room to unzip the bacpac.
140
+
- Use SSD storage on the VM and ensure there's enough room to unzip the bacpac.
141
141
- Execute SqlPackage from a VM in the same region as the database.
142
142
- Enable accelerated networking in the VM.
143
143
144
144
For more information on utilizing a PowerShell script to collect more information about an import operation, see [Lesson Learned #211: Monitoring SQLPackage Import Process](https://techcommunity.microsoft.com/t5/azure-database-support-blog/lesson-learned-211-monitoring-sqlpackage-import-process/ba-p/3556382).
145
145
146
146
147
-
## Next steps
147
+
## Related content
148
148
149
149
-[SqlPackage overview](sqlpackage.md)
150
150
- Learn more about [SqlPackage Import](sqlpackage-import.md)
0 commit comments