Module Database Migrations - Skills Guide¶

Skill Type: Database Migration & DevOps
Technology Stack: .NET, Entity Framework Core, Docker, SQL Server
Complexity Level: Intermediate
Last Updated: 2025

📋 Overview¶

This guide covers setting up database migration infrastructure for ABP modules, including Docker-based migration scripts for CI/CD pipelines.

What You'll Configure¶

✅ Dockerized migration scripts
✅ EF Core migration SQL generation
✅ Multi-database migration (AuthServer + ApiHost)
✅ Automated database creation and schema setup

🚀 Phase 1: Database Migration Setup¶

Step 1: Create Migration Folder¶

Create GridLab.Gmss.ModuleName.Database folder under host directory.

Step 2: Add Migration Dockerfile¶

Replace <ModuleName> with your module name. Dockerfile.Migrations is used in CI/CD pipelines:

# Replace <ModuleName>

FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build

# Add variables for nuget.config
ARG GITLAB_NUGET_USERNAME
ARG GITLAB_NUGET_PASSWORD

# Copy sln folder as build context
COPY ../../. .

# Restore dotnet-ef core
RUN dotnet tool restore
ENV PATH="${PATH}:/root/.dotnet/tools"

# Create migration sql scripts
WORKDIR /host/GridLab.Gmss.<ModuleName>.AuthServer
RUN dotnet ef migrations script -i -o migrations-AuthServer.sql

WORKDIR /host/GridLab.Gmss.<ModuleName>.HttpApi.Host
RUN dotnet ef migrations script -i -o migrations-ApiHost.sql

FROM mcr.microsoft.com/mssql-tools AS final
# UID of the non-root user 'app'
ENV APP_UID=1654

# Create a non-root user and group
RUN groupadd \
        --gid=$APP_UID \
        app \
    && useradd -l \
        --uid=$APP_UID \
        --gid=$APP_UID \
        --create-home \
        app

WORKDIR /src
COPY --from=build /host/GridLab.Gmss.<ModuleName>.AuthServer/migrations-AuthServer.sql migrations-AuthServer.sql
COPY --from=build /host/GridLab.Gmss.<ModuleName>.HttpApi.Host/migrations-ApiHost.sql migrations-ApiHost.sql
COPY --from=build /host/GridLab.Gmss.<ModuleName>.Database/entrypoint.sh .
RUN /bin/bash -c "sed -i $'s/\r$//' entrypoint.sh"
RUN chmod +x ./entrypoint.sh

USER $APP_UID
ENTRYPOINT ["./entrypoint.sh"]

Step 3: Update Entry Point Script¶

Update entrypoint.sh bash script. Replace <ModuleName> with your module name:

#!/bin/bash

until /opt/mssql-tools/bin/sqlcmd -S <modulename>-sql-server -U SA -P $SA_PASSWORD -Q 'SELECT name FROM master.sys.databases'; do
>&2 echo "SQL Server is starting up"
sleep 1
done

/opt/mssql-tools/bin/sqlcmd -S <modulename>-sql-server -U SA -P $SA_PASSWORD -Q "CREATE DATABASE [$AuthServer_DB]"
/opt/mssql-tools/bin/sqlcmd -S <modulename>-sql-server -U SA -P $SA_PASSWORD -Q "CREATE DATABASE [$ApiHost_DB]"

/opt/mssql-tools/bin/sqlcmd -S <modulename>-sql-server -U SA -P $SA_PASSWORD -Q "ALTER DATABASE [$AuthServer_DB] SET READ_COMMITTED_SNAPSHOT ON"
/opt/mssql-tools/bin/sqlcmd -S <modulename>-sql-server -U SA -P $SA_PASSWORD -Q "ALTER DATABASE [$ApiHost_DB] SET READ_COMMITTED_SNAPSHOT ON"

/opt/mssql-tools/bin/sqlcmd -d $AuthServer_DB -S <modulename>-sql-server -U sa -P $SA_PASSWORD -i migrations-AuthServer.sql -I
/opt/mssql-tools/bin/sqlcmd -d $ApiHost_DB -S <modulename>-sql-server -U sa -P $SA_PASSWORD -i migrations-ApiHost.sql -I