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
Following are some quick ways to troubleshoot errors when backing up to or restoring from the S3-compatible object storage. To avoid errors due to unsupported options or limitations, see [SQL Backup and Restore with S3-compatible object storage](sql-server-backup-to-url-s3-compatible-object-storage.md#limitations).
26
26
27
-
###Ensure a correctly formed URL
27
+
## Ensure a correctly formed URL
28
28
29
29
Here's an example of a virtual host URL formed correctly when issuing a T-SQL backup query such as follows:
30
30
31
31
```sql
32
32
BACKUP DATABASE AdventureWorks2022
33
-
TO URL ='s3://<bucketName>.<virtualHost>/<pathToBackup>/<backupFileName>'
33
+
TO URL ='s3://<bucketName>.<virtualHost>/<pathToBackup>/<backupFileName>'
34
34
```
35
35
36
36
Or for URL path style:
@@ -43,43 +43,70 @@ TO URL = 's3://<domainName>/<bucketName>/<pathToBackup>/<backupFileName>';
43
43
Review in the URL:
44
44
45
45
1. The URL starts with `s3://` scheme.
46
-
1. The S3 storage virtual host `<virtualHost>` or server domain `<domainName>` exists and is running using HTTPS. The endpoint will be validated by a CA installed on the SQL Server OS Host.
47
-
1.`<bucketName>` is the name of this bucket where the backup is written. This must be created before running the backup T-SQL. The backup T-SQL doesn't create the bucket for the customer. For example, if the user doesn't create the bucket 'nonExistingBucket' beforehand and runs a T-SQL statement as follows:
48
-
49
-
```sql
50
-
BACKUP DATABASE AdventureWorks2022
51
-
TO URL ='s3://<your-endpoint>/nonExistingBucket/AdventureWorks2022.bak';
52
-
```
53
-
54
-
A URL that is not correctly formed may return the following:
55
-
56
-
```
57
-
Msg 3201, Level 16, State 1, Line50
58
-
Cannot open backup device 's3://<your-endpoint>/nonExistingBucket/AdventureWorks2022.bak'. Operating system error 50(The request is not supported.).
59
-
Msg 3013, Level 16, State 1, Line50
60
-
BACKUP DATABASE is terminating abnormally.
61
-
```
62
-
63
-
1. The `<pathToBackup>` need not exist before running the backup T-SQL. It is created in the storage server automatically. For example, if the user creates the bucket 'existingBucket' beforehand and not the path`'existingBucket/sqlbackups'`, the following will still run successfully:
46
+
1. The S3 storage virtual host `<virtualHost>` or server domain `<domainName>` exists and is running using HTTPS. A CA installed on the SQL Server OS host validates the endpoint.
47
+
1.`<bucketName>` is the name of the bucket where the backup is written. The bucket must be created before you run the backup T-SQL statement. The backup T-SQL doesn't create the bucket. For example, if you don't create the bucket 'nonExistingBucket' beforehand and run a T-SQL statement as follows:
48
+
49
+
```sql
50
+
BACKUP DATABASE AdventureWorks2022
51
+
TO URL ='s3://<your-endpoint>/nonExistingBucket/AdventureWorks2022.bak';
52
+
```
53
+
54
+
A URL that isn't correctly formed might return the following error:
55
+
56
+
```
57
+
Msg 3201, Level 16, State 1, Line 50
58
+
Cannot open backup device 's3://<your-endpoint>/nonExistingBucket/AdventureWorks2022.bak'. Operating system error 50(The request is not supported.).
59
+
Msg 3013, Level 16, State 1, Line 50
60
+
BACKUP DATABASE is terminating abnormally.
61
+
```
62
+
63
+
1. The `<pathToBackup>`doesn't need to exist before you run the backup T-SQL. The storage server creates the path automatically. For example, if you create the bucket 'existingBucket' beforehand but not the path `'existingBucket/sqlbackups'`, the following command still runs successfully:
64
64
65
65
```sql
66
66
BACKUP DATABASE AdventureWorks2022
67
67
TO URL ='s3://<your-endpoint>/existingBucket/sqlbackups/AdventureWorks2022.bak';
68
68
```
69
69
70
-
### Create a server-level credential prior to running backup/restore
70
+
## Create a server-level credential before running backup/restore
71
+
72
+
Before running BACKUP or RESTORE Transact-SQL commands against S3-compatible object storage, you must create a server-level credential containing the Access Key ID and Secret Key ID that your S3 storage provider requires. There are two ways to name the credential:
73
+
74
+
-**[Set a credential name](#set-a-credential-name)**: Choose any name you want, but you must explicitly specify the `CREDENTIAL` parameter in each BACKUP/RESTORE statement.
75
+
-**[Use the S3 URL path as the credential name](#use-the-s3-url-path-as-the-credential-name)**: Name the credential with the S3 URL path, and SQL Server automatically matches the credential to the backup URL without requiring the `CREDENTIAL` parameter.
76
+
77
+
### Set a credential name
78
+
79
+
Choose any credential name, as long as the Access Key ID and Secret Key ID grant access to the S3 backup URL. When you use a credential with an arbitrary name, you must explicitly reference it in the BACKUP/RESTORE statement by adding the `CREDENTIAL` parameter.
80
+
81
+
The following example creates a credential with an arbitrary name:
82
+
83
+
```sql
84
+
CREATE CREDENTIAL [myOwnCredential]
85
+
WITH IDENTITY ='S3 Access Key',
86
+
SECRET ='<AccessKeyID>:<SecretKeyID>';
87
+
```
88
+
89
+
The following example backs up a database using the credential:
90
+
91
+
```sql
92
+
BACKUP DATABASE [Test]
93
+
TO URL ='s3://<your-endpoint>/myS3Bucket/sqlbackups/AdventureWorks2022.bak'
94
+
WITH COMPRESSION, NOFORMAT, NAME = N'FULL bkp', MAXTRANSFERSIZE =20971520, CREDENTIAL = N'myOwnCredential'
95
+
```
96
+
97
+
### Use the S3 URL path as the credential name
71
98
72
-
Before running backup/restore Transact-SQL queries to S3-compatible storage, you must create a server level credential. This credential needs to contain the Access key and Secret Key set up by customers on their S3-compatible object storage server prior to issuing backup/restore queries.
99
+
Name the credential using the S3 URL path. With this approach, SQL Server automatically performs credential lookup, and you don't need to specify the `CREDENTIAL` parameter in the BACKUP/RESTORE statement. SQL Server attempts to find the most specific matching credential based on the URL.
73
100
74
-
An example of a credential that needs to be created for URL:`s3://<your-endpoint>/myS3Bucket/sqlbackups/AdventureWorks2022.bak` would be the following:
101
+
The following example creates a credential for the URL `s3://<your-endpoint>/myS3Bucket/sqlbackups/AdventureWorks2022.bak`:
In this statement `<AccessKeyID>`is not allowed to contain a `:` character. If the credential is not created prior to running the backup/restore query, the user will see the following error message:
109
+
In this statement,`<AccessKeyID>`can't contain a `:` character. If the credential isn't created before you run the backup/restore query, SQL Server returns the following error message:
83
110
84
111
```
85
112
Msg 3201, Level 16, State 1, Line 50
@@ -88,19 +115,19 @@ Msg 3013, Level 16, State 1, Line 50
88
115
BACKUP DATABASE is terminating abnormally.
89
116
```
90
117
91
-
The name of the credential is not required to match the exact URL path. Here is an example how credential lookup will work. If we need to query path `s3://10.193.16.183:9000/myS3Bucket/sqlbackups/AdventureWorks2022.bak`, the following credential names are tried:
118
+
The credential name doesn't need to match the exact URL path. The following example shows how credential lookup works. If you need to query path `s3://10.193.16.183:9000/myS3Bucket/sqlbackups/AdventureWorks2022.bak`, SQL Server tries the following credential names:
If there are multiple credentials matching search, such as more specific `s3://10.193.16.183:8787/myS3Bucket/sqlbackups` and more generic `s3://10.193.16.183:8787/myS3Bucket`, choose the most specific one. This allows you to set up more granular access control at directory level for what folders may be accessed from SQL Server.
124
+
If multiple credentials match the search, such as the more specific `s3://10.193.16.183:8787/myS3Bucket/sqlbackups` and the more generic `s3://10.193.16.183:8787/myS3Bucket`, SQL Server chooses the most specific one. This behavior lets you set up granular access control at the directory level for which folders can be accessed from SQL Server.
98
125
99
-
### Unsupported option FILE_SNAPSHOT
126
+
## Unsupported option FILE_SNAPSHOT
100
127
101
-
Currently, the BACKUP TSQL option FILE_SNAPSHOT is not supported for S3-compatible object storage. This is an Azure Blob Storage-specific option.
128
+
Currently, the BACKUP Transact-SQL option FILE_SNAPSHOT isn't supported for S3-compatible object storage. FILE_SNAPSHOT is an Azure Blob Storage-specific option.
102
129
103
-
If the user runs the following Transact-SQL for example:
130
+
If you run the following Transact-SQL example:
104
131
105
132
```sql
106
133
BACKUP DATABASE AdventureWorks2022
@@ -117,9 +144,9 @@ Msg 3013, Level 16, State 1, Line 62
117
144
BACKUP DATABASE is terminating abnormally.
118
145
```
119
146
120
-
###Backup stripe exceeding 100 GB
147
+
## Backup stripe exceeding 100 GB
121
148
122
-
Currently, the size of a single backup file created by customers in S3-compatible object storage during a backup cannot exceed 100 GB per file, using default `MAXTRANSFERSIZE`. If the backup stripe goes beyond 100 GB, the backup T-SQL syntax statement throws the following error message:
149
+
Currently, the size of a single backup file created by customers in S3-compatible object storage during a backup can't exceed 100 GB per file, using default `MAXTRANSFERSIZE`. If the backup stripe goes beyond 100 GB, the backup T-SQL syntax statement throws the following error message:
123
150
124
151
```
125
152
Msg 3202, Level 16, State 1, Line 161
@@ -144,17 +171,17 @@ TO URL = 's3://<your-endpoint>/myS3Bucket/sqlbackups/AdventureWorks2022.bak'
144
171
WITH COMPRESSION;
145
172
```
146
173
147
-
###Maximum length of URL
174
+
## Maximum length of URL
148
175
149
-
The total URL length is limited to 259 bytes by the Backup and Restore engine. This means that `s3://hostname/objectkey` shouldn't exceed 259 characters. Leaving aside `s3://` the user can input the path length (hostname + object key) to be 259 – 5 = 254 characters. Refer to [SQL Server Backup to URL - SQL Server](sql-server-backup-to-url.md). The backup T-SQL syntax statement throws the following error message:
176
+
The total URL length is limited to 259 bytes by the Backup and Restore engine. This limit means that `s3://hostname/objectkey` shouldn't exceed 259 characters. Leaving aside `s3://` the user can input the path length (hostname + object key) to be 259 - 5 = 254 characters. Refer to [SQL Server backup to URL for Azure Blob Storage](sql-server-backup-to-url.md). The backup T-SQL syntax statement throws the following error message:
150
177
151
178
```
152
179
SQL Server has a maximum limit of 259 characters for a backup device name. The BACKUP TO URL consumes 36 characters for the required elements used to specify the URL - 'https://.blob.core.windows.net//.bak', leaving 223 characters for account, container, and blob names put together'
153
180
```
154
181
155
-
###Clock-skew correction
182
+
## Clock-skew correction
156
183
157
-
The S3 storage might reject connection, giving a "InvalidSignatureException" error back to SQL Server whenever the time difference between SQL Host and S3 server is bigger than 15 minutes. On SQL Server it shows as:
184
+
The S3 storage might reject connection, giving a "InvalidSignatureException" error back to SQL Server whenever the time difference between SQL Host and S3 server is bigger than 15 minutes. On SQL Server, the error appears as:
158
185
159
186
```
160
187
Msg 3201, Level 16, State 1, Line 28
@@ -163,9 +190,9 @@ Msg 3013, Level 16, State 1, Line 28
163
190
BACKUP DATABASE is terminating abnormally.
164
191
```
165
192
166
-
###SQL Server on Linux support
193
+
## SQL Server on Linux support
167
194
168
-
SQL Server uses `WinHttp` to implement client of HTTP REST APIs it uses. It relies on OS certificate store for validations of the TLS certificates presented by the HTTP(s) endpoint. However, SQL Server on Linux delegates the certificate validation to SQLPAL, which validates the endpoints' HTTPS certificates with the certificate shipped with PAL. Thus, customer-provided self-signed certificates cannot be used on Linux for HTTPS validation.
195
+
SQL Server uses `WinHttp` to implement the client of HTTP REST APIs it uses. SQL Server relies on the OS certificate store for validation of the TLS certificates presented by the HTTPS endpoint. However, SQL Server on Linux delegates the certificate validation to SQLPAL, which validates the endpoints' HTTPS certificates with the certificate shipped with PAL. As a result, customer-provided self-signed certificates can't be used on Linux for HTTPS validation.
169
196
170
197
During backup/restore the customer gets the following error message on Linux:
171
198
@@ -178,16 +205,16 @@ BACKUP DATABASE is terminating abnormally.
178
205
179
206
To get past this problem, the following predefined location must be created: `/var/opt/mssql/security/ca-certificates`. Place self-signed certificates, or certificates not shipped with PAL in this location. SQL Server reads the certificates from the folder during startup and adds them to the PAL trust store.
180
207
181
-
Up to 50 files can be stored in this location, if the folder is not created, when SQL Server is started, the SQL Server error log will show:
208
+
Up to 50 files can be stored in this location. If the folder doesn't exist when SQL Server starts, the SQL Server error log shows:
182
209
183
210
```
184
211
2022-02-05 00:32:10.86 Server Installing Client TLS certificates to the store.
185
212
2022-02-05 00:32:10.88 Server Error searching first file in /var/opt/mssql/security/ca-certificates: 3(The system cannot find the path specified.)
186
213
```
187
214
188
-
###Object Lock - delete retention is not supported
215
+
## Object Lock - delete retention isn't supported
189
216
190
-
The SQL Server backup to S3-compatible object storage feature does not support Object Lock, also called the Delete Retention feature. Object Lock prevents files from being deleted or overwritten for the duration of its retention period.
217
+
The SQL Server backup to S3-compatible object storage feature doesn't support Object Lock, also called the Delete Retention feature. Object Lock prevents files from being deleted or overwritten during the retention period.
191
218
192
219
The bucket and folder location targeted by your backup operation must not have Object Lock enabled. If this feature is enabled and configured in your S3-compatible object storage, the backup operation fails with the following message:
193
220
@@ -200,7 +227,7 @@ BACKUP DATABASE is terminating abnormally.
200
227
201
228
## Related content
202
229
203
-
-[SQL Server backup and restore with S3-compatible object storage](sql-server-backup-and-restore-with-s3-compatible-object-storage.md)
204
-
-[SQL Server backup to URL for S3-compatible object storage](sql-server-backup-to-url-s3-compatible-object-storage.md)
![learn-build-service-prod[bot]](https://avatars.githubusercontent.com/in/237442?v=4&size=40){kind=avatar}
0 commit comments