Importing databases from STACKIT S3 buckets

You can perform on-demand imports of an SQLServer backup into your SQLServer Flex instance (Single and HA) from a STACKIT S3 bucket at any time.

Prerequisites

In order to follow the steps described on this page, the following conditions need to be met:

• Your organization has a customer account.
  (See: Create a customer account)

• You have a User Account with the necessary permissions.
  (See: Create a user account)

• You have a Project in your customer account.
  (See: Create a Project)

• You have created a Service Account.
  (See: Create a Service account)

• You have assigned the required project permissions to this service account.
  (See: Assign permissions to a service account)

• You have created an Access Token for this service account.
  (See: Assign authentication token to a service account)

• You have created a SQLServer Flex Instance.
  (See: Create a SQLServer Flex Instance)

• You are connected to the SQLServer Flex Instance.
  (See: Connect to a SQLServer Flex Instances)

• You have previously created a database..
  (See: Create databases in SQLServer Flex instances)

• You previously created a user and assigned the right server role to it.
  (See: Create user)
  (See: Server and project roles and permissions)

• You have a STACKIT S3 bucket.

• You have uploaded the database to be imported as .bak file(s) to the STACKIT S3 bucket
  Note: Only unencrypted backups.

• The database to be imported does not exist on the SQLServer Flex instance (Single and HA) to be imported.

Import a Database from a STACKIT S3 Bucket

API

Further requirements:

• Access token with permission sqlserver-flex.restore.trigger (or equivalent for v3alpha1).
• S3 Access Key and Secret with read access to the bucket.

Import

Submit a database restore request from an external S3 source with a POST call.
Replace the placeholders with your actual project and instance details.

Curl example

curl https://mssql-flex-service.api.eu01.stackit.cloud/v3alpha1/projects/$PROJECT_ID/regions/$REGION/instances/$INSTANCE_ID/restores \
-D- \
-X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"database_name": "'$NEW_DB_NAME'",
"source": {
    "database_owner": "'$DBUSER'",
    "logging_guid": "1",
    "s3_details": {
        "s3_access_key": "'$S3_ACCESS_KEY'",
        "s3_access_secret": "'$S3_SECRET_KEY'",
        "s3_bucket": "s3://object.storage.eu01.onstackit.cloud/$BUCKET_PATH/",
        "s3_files": [
                {
                    "file_number": 1,
                    "file_path": "s3://object.storage.eu01.onstackit.cloud/$BUCKET_PATH/file.bak"
                }
            ]
        },
    "type": "EXTERNAL_S3"
}
}'

More information about the endpoint can be found in the API documentation

Parameter values

Expand

Parameter	Description
TOKEN	Valid access token with restore permissions
PROJECT_ID	Project ID where the instance is located
REGION	Region where the instance was created (e.g., eu01)
INSTANCE_ID	SQLServer Flex instance ID
NEW_DB_NAME	The name the database will have after import
S3_ACCESS_KEY	Access key for the STACKIT S3 bucket
S3_SECRET_KEY	Secret key for the STACKIT S3 bucket
s3_files.file_path	Full S3 URI to the .bak file (e.g., s3://host/path/file.bak)

Response For a successfully initiated database import, the API responds with a 202 Accepted HTTP status code. The actual restoration process happens asynchronously in the background.

API response example

HTTP/2 202
date: Fri, 16 Jan 2026 14:30:00 GMT
traceparent: 00-5c32d68f7g64e96318fgcf12d568f9d3-fefc7e32157b6a1f-01
server: stackit
content-length: 0

Transact SQL (T-SQL)

The stored procedure can be used on the STACKIT Flex SQLServer instances (Single and HA).
You can use any SQL Server query run tool that can run T-SQL against an SQL Server, e. g. SQL Server Management Studio, Azure Data Studio, or PowerShell.

• Databases can be impored with the stored procedure [msdb].[stackit].[import_database].
• Parameter description The procedure accepts various parameters
  Expand

  Parameter	SQL data type	Mandatory	Default value	Description
  @database_name	NVARCHAR(80)	YES	-	Name of the database (observes naming conventions).
  @owner_name	NVARCHAR(128)	No	Current user	The database owner.
  @s3_url	NVARCHAR(MAX)	YES	N/A	Comma separated list of files including path that contain the backup. Must start with s3://.
  @s3_access_key_id	NVARCHAR(MAX)	YES	N/A	Access key for the STACKIT S3 bucket.
  @s3_secret_key_id	NVARCHAR(MAX)	YES	N/A	Secret key for the STACKIT S3 bucket.

• Example:

  1. Simple import:

     EXEC [msdb].[stackit].[import_database]
       @database_name = 'demo_db_1'
     , @owner_name = 'Administrator'
     , @s3_url='s3://object.storage.eu01.onstackit.cloud/[FOLDER_NAME]/[DATABASE_FILENAME].bak'
     , @s3_access_key_id = 'abc123'
     , @s3_secret_key_id = 'xyz321'

  2. If the database to be imported consists of several files, this can be done comma-separated using the @s3_url parameter.

     EXEC [msdb].[stackit].[import_database]
         @database_name = 'demo_db_1'
     , @owner_name = 'Administrator'
     , @s3_url=' s3://object.storage.eu01.onstackit.cloud/[FOLDER_NAME]/[DATABASE_FILENAME_1].bak,
                 s3://object.storage.eu01.onstackit.cloud/[FOLDER_NAME]/[DATABASE_FILENAME_2].bak,
                 s3://object.storage.eu01.onstackit.cloud/[FOLDER_NAME]/[DATABASE_FILENAME_3].bak,
                 s3://object.storage.eu01.onstackit.cloud/[FOLDER_NAME]/[DATABASE_FILENAME_4].bak,
                 s3://object.storage.eu01.onstackit.cloud/[FOLDER_NAME]/[DATABASE_FILENAME_5].bak,
                 s3://object.storage.eu01.onstackit.cloud/[FOLDER_NAME]/[DATABASE_FILENAME_6].bak,
                 s3://object.storage.eu01.onstackit.cloud/[FOLDER_NAME]/[DATABASE_FILENAME_7].bak,
                 s3://object.storage.eu01.onstackit.cloud/[FOLDER_NAME]/[DATABASE_FILENAME_8].bak
                 '
     , @s3_access_key_id = 'abc123'
     , @s3_secret_key_id = 'xyz321'