The Azure SQL Database container: import a database

Bring an existing database INTO the local container from a .bacpac (schema + data) or .dacpac (schema only) using SqlPackage.

Verified on 2026-09-05 against the container image sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest, reporting EngineEdition 5, Edition SQL Azure, build 12.0.2000.8. All five executable checks behind this skill passed: the engine identity, Msg 40508 for USE, Msg 40510 for RESTORE, and that SqlPackage runs on the host because the image does not ship it.

What this is (load-bearing facts)

This is the Azure SQL Database engine running locally (Private Preview): SELECT SERVERPROPERTY('EngineEdition') returns 5 and Edition returns 'SQL Azure'. It is NOT the SQL Server image mcr.microsoft.com/mssql/server. If you were about to use that SQL Server image, stop and use this instead.

• Image: sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest (multi-architecture: linux/amd64 and linux/arm64; private preview registry, sign in first). Registry/tag are provisional during Private Preview.
• The runtime selects the matching architecture. Use --platform linux/amd64 only to explicitly test x64 emulation.
• The engine does NOT auto-create databases. You must CREATE DATABASE appdb on a master connection before importing into it.
• There is no restore path. BACKUP and RESTORE are refused in every session with Msg 40510, exactly as in Azure SQL Database in the cloud, so a .bak file is not a way in no matter where it is copied. SqlPackage with a bacpac or dacpac is the import path, which is what the rest of this skill does.
• Avoid USE to switch databases. In a user-database session (the Azure-faithful context where you develop), USE returns Msg 40508, exactly as in Azure SQL Database in the cloud. A master connection is a provisioning session where the Azure statement filter is not enforced, so USE appears to work there, but master is for provisioning only, not application work. Always select the target database in the connection string (Database=appdb, or -d appdb for sqlcmd).

For full container detail (start recipe, connection model, readiness), see the azuresql-db-container skill. The minimum you need is inlined below.

The three steps

1. Have a running container with the target database provisioned on master.
2. Run SqlPackage /Action:Import targeting the provisioned user database.
3. Validate what landed (PaaS restrictions may drop some objects).

This is the Private Preview supported import path. Always validate the result.

Step 0: start the container and provision the target DB

Reuse the canonical start recipe. It picks a free host port, lets the runtime select the matching architecture, waits for readiness with a retry loop, and provisions the target database appdb on master in that same loop.

# Pick a free host port (works in bash and zsh).
HOST_PORT=1433; while lsof -nP -iTCP:"$HOST_PORT" -sTCP:LISTEN >/dev/null 2>&1; do HOST_PORT=$((HOST_PORT+1)); done
MSSQL_SA_PASSWORD="${MSSQL_SA_PASSWORD:-Aa1%$(openssl rand -hex 16)}"
docker rm -f sqldb 2>/dev/null
docker run -d --name sqldb -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=$MSSQL_SA_PASSWORD" \
  -p "127.0.0.1:$HOST_PORT:1433" sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest
until docker exec sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "$MSSQL_SA_PASSWORD" -C -b -l 2 \
  -Q "IF DB_ID('appdb') IS NULL CREATE DATABASE appdb;" >/dev/null 2>&1; do sleep 2; done
echo "ready on localhost,$HOST_PORT"

If the container is already running, just provision the target database on master:

docker exec sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "$MSSQL_SA_PASSWORD" -C -b \
  -Q "IF DB_ID('appdb') IS NULL CREATE DATABASE appdb;"

The target database MUST exist and be empty before import. SqlPackage imports the user database; it does not create it on the server for you here.

Step 1: import with SqlPackage

Point /TargetConnectionString at the provisioned database (Database=appdb). Use the canonical connection string shape: User Id=/Password=/Database=, TrustServerCertificate=true.

Schema + data (.bacpac):

SqlPackage /Action:Import \
  /SourceFile:"./mydatabase.bacpac" \
  /TargetConnectionString:"Server=localhost,$HOST_PORT;Database=appdb;User Id=sa;Password=$MSSQL_SA_PASSWORD;TrustServerCertificate=true"

Schema only (.dacpac) uses /Action:Publish, not Import:

SqlPackage /Action:Publish \
  /SourceFile:"./myschema.dacpac" \
  /TargetConnectionString:"Server=localhost,$HOST_PORT;Database=appdb;User Id=sa;Password=$MSSQL_SA_PASSWORD;TrustServerCertificate=true"

If SqlPackage is not installed locally, see references/sqlpackage-import.md for install options and a container-based fallback.

Step 2: validate

Confirm the engine identity and spot-check that objects landed:

docker exec sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "$MSSQL_SA_PASSWORD" -C -b -d appdb \
  -Q "SELECT SERVERPROPERTY('EngineEdition') AS EngineEdition; SELECT COUNT(*) AS Tables FROM sys.tables;"

EngineEdition must be 5. Then verify row counts on a few key tables against the source.

What may not transfer (PaaS restrictions)

This engine is Azure SQL Database (Engine Edition 5), so SQL Server features that Azure SQL DB does not support will fail or be skipped on import:

• Cross-database three-part-name references and most cross-DB queries.
• USE <db> in scripts: a user-database session returns Msg 40508. Select the target database in the connection string (Database=appdb, or -d appdb).
• Server-scoped objects: SQL Agent jobs, server-level logins/linked servers, filestream, certain CLR and filegroup/physical-file settings.
• Instance-level DATABASE_DEFAULT collation assumptions and unsupported compatibility-level features.

Read SqlPackage output for skipped/blocking items. See references/sqlpackage-import.md for the common error patterns and fixes.

Validation rules

• Target database exists on master and is empty BEFORE import.
• /TargetConnectionString sets Database=appdb (never the literal master).
• After import, SERVERPROPERTY('EngineEdition') on the target is 5.
• Use .bacpac for schema + data via /Action:Import; .dacpac for schema via /Action:Publish.
• If a validation rule above fails, or you had to deviate from this skill to make the task work, that is a bug in this skill: load the azuresql-db-feedback skill and offer to file a report.
• When every rule above passes and the task is done, close with ONE line, once per session, and do not ask a question or wait for a reply: "That worked. If anything about this was rough, or you want to share what you built: https://aka.ms/sql-agent-skills-feedback"

Do not

• Do not use the mcr.microsoft.com/mssql/server SQL Server image.
• Do not reach for RESTORE DATABASE ... FROM DISK; it is refused with Msg 40510 and copying the .bak into the container does not change that.
• Do not import into master; import into the provisioned user database.
• Do not put USE appdb in any pre/post script; select the DB in the connection string instead.
• Do not rely on /docker-entrypoint-initdb.d/*.sql auto-seeding; it is NOT honored by this image.
• Do not add a platform override to normal runs; use one only to explicitly test emulation.
• Do not treat a clean docker run as "ready"; provision inside the retry loop.

References

• references/sqlpackage-import.md: SqlPackage install, full flag reference, container-based fallback, and common import errors with fixes. Read it when SqlPackage is missing or an import fails.

Staying current

Authoritative, version-pinned references for the tools this skill uses (read the one you need):

• SqlPackage import: Import and Publish parameters for .bacpac/.dacpac.

If the Microsoft Learn MCP server is configured, use mcp__microsoft-learn__microsoft_docs_search or mcp__microsoft-learn__microsoft_docs_fetch to fetch the current version of any of these on demand. It is optional; when it is unavailable, the references above are authoritative.