Πιθανότατα κάνεις λάθος στις Μεταναστεύσεις EF...

Sunday, 23 November 2025

Τρέξιμο MigrateAsync() Υπάρχει ένας καλύτερος τρόπος - τα πακέτα μετανάστευσης EF σας επιτρέπουν να εκτελέσετε τις μεταναστεύσεις ως ένα ελεγχόμενο βήμα CI, κρατώντας την εφαρμογή παραγωγής σας ασφαλή. Αλλά εδώ είναι το θέμα: μερικές φορές ο "λάθος" τρόπος είναι πραγματικά μια χαρά. Ας εξερευνήσουμε πότε να χρησιμοποιήσουμε κάθε προσέγγιση.

Επίσημα έγγραφα: Επισκόπηση των μεταναστευτικών ροών | Εφαρμογή των Μεταναστών | ΜπάντλςCity name (optional, probably does not need a translation)

Ο "λάθος" τρόπος (που χρησιμοποιώ)

Αυτό το blog χρησιμοποιεί MigrateAsync() Κατά την εκκίνηση - η προσέγγιση που είμαι έτοιμος να σας πω να μην χρησιμοποιήσετε . Εδώ είναι γιατί αυτό είναι εντάξει για μένα , και γιατί πιθανώς δεν είναι για εσάς .

Στο Program.cs αρχείο Έχω τα ακόλουθα:

    using (var scope = app.Services.CreateScope())
    {
        var blogContext = scope.ServiceProvider.GetRequiredService<IMostlylucidDBContext>();
        await blogContext.Database.MigrateAsync();
    }

MigrateAsync() εφαρμόζει εν αναμονή της μετανάστευσης και δημιουργεί τη βάση δεδομένων, εάν χρειάζεται. Απλό - αλλά προβληματικό:

Εξάρτηση εκκίνησης Η εφαρμογή σου δεν ξεκινάει.
Παραβίαση της ασφάλειας - Η εφαρμογή σας χρειάζεται db_owner Μόλις έδωσες στην εφαρμογή σου τα κλειδιά για να πετάξεις τραπέζια.

Γιατί τη γλιτώνω: δημόσια δεδομένα, ενιαίο δίκτυο Ντόκερ, προσωπικό έργο. Μάλλον δεν μπορείς.

Όταν οι Μεταναστεύσεις σε Διαρκή Χρόνο Είναι Καλές

Local dev - Η γρήγορη φαγούρα κερδίζει την τελετή.
Προσωπικά έργα - Χαμηλή ακτίνα έκρηξης, χωρίς ευαίσθητα δεδομένα
Docker-σύνθετο περιβάλλον dev - Η ευκολία κερδίζει.
Πρωτότυπο - Ο Σίμα αλλάζει συνεχώς έτσι κι αλλιώς.

Όταν δεν είναι

Πολλαπλές περιπτώσεις εφαρμογής - Οι συνθήκες των αγώνων θολώνουν.
Ευαίσθητα δεδομένα - PII, οικονομικός, ρυθμιζόμενος = απαιτούμενος σωστός διαχωρισμός
Παραγωγή με πραγματικούς χρήστες - Αποτυχημένη μετανάστευση = έξοδος

Ο σωστός τρόπος: Bundles EF

Ένα πακέτο EF είναι ένα αυτόνομο εκτελέσιμο που περιέχει τις συγκεντρωμένες μεταναστεύσεις σας. dotnet ef database update συσκευάζεται σε ένα αυτόνομο .exe.

Γιατί τα πακέτα κερδίζουν:

Δεν υπάρχουν εξαρτήσεις χρόνου λειτουργίας - Ο στόχος δεν χρειάζεται SDK ή EF CLI
Ορθός διαχωρισμός - Το App δεν χρειάζεται ποτέ. db_owner; μόνο CI runner κάνει, μόνο κατά τη διάρκεια της ανάπτυξης
Ορατότητα CI - Οι αποτυχίες εμφανίζονται σε αρχεία καταγραφής αγωγών, όχι θαμμένες στην εκκίνηση της εφαρμογής
Ασφάλεια αναστροφής - Η μετανάστευση αποτυγχάνει; Η ανάπτυξη σταματά πριν αναπτυχθεί κακός κώδικας
Είσαι πανίσχυρος. - Εντοπίζει ό, τι εφαρμόζεται, τρέχει μόνο ό, τι χρειάζεται

Σημείωση: Για ασφάλεια ποιότητας παραγωγής, χρήση Διαχειριζόμενη Ταυτότητα Αλλά οι δέσμες εξακολουθούν να είναι ένα σημαντικό βήμα προς τα πάνω από τις μεταναστεύσεις runtime.

Παράδειγμα ενεργειών GitHub

      - name: Install EF Core tools
        run: dotnet tool install --global dotnet-ef

      - name: Add EF tools to PATH
        run: echo "$HOME/.dotnet/tools" >> $GITHUB_PATH

      - name: Generate EF migration bundle
        run: |
          dotnet ef migrations bundle \
            --project ${{ env.WEB_PROJECT }} \
            --output efbundle.exe \
            --configuration ${{ env.BUILD_CONFIGURATION }} \
            --runtime ${{ env.RUNTIME_IDENTIFIER }} \
            --context AdminDbContext \
        env:
          AdminSite__ConnectionString: ${{ secrets.PROD_SQL_CONNECTIONSTRING }}

      - name: Run EF migration bundle
        run: |
          ./efbundle.exe
        env:
          AdminSite__ConnectionString: ${{ secrets.PROD_SQL_CONNECTIONSTRING }}

Το πακέτο διαβάζει συμβολοσειρές σύνδεσης από τις περιβαλλοντικές μεταβλητές και εφαρμόζει εν αναμονή των μεταναστευτικών ροών.

Τοπικά BundlesName

Δεν υπάρχει πληροφοριοδότης; Θέλετε να δοκιμάσετε πριν σπρώξετε; Φτιάξτε δέσμες τοπικά.

Χρήση περιπτώσεων: Δοκιμή πριν από CI, DBA παράδοση (αυτοσυντηρούμενη exe, δεν χρειάζεται SDK), ανάπτυξη stage, αποσφαλμάτωση με --verbose.

Δημιουργία ενός Bundle

# Install EF CLI (once)
dotnet tool install --global dotnet-ef

# Basic bundle
dotnet ef migrations bundle \
    --project Mostlylucid.DbContext \
    --startup-project Mostlylucid \
    --output efbundle.exe

# Self-contained (includes runtime - portable to machines without .NET)
dotnet ef migrations bundle \
    --project Mostlylucid.DbContext \
    --startup-project Mostlylucid \
    --output efbundle.exe \
    --self-contained

# Cross-platform (e.g., build on Windows, deploy to Linux)
dotnet ef migrations bundle \
    --project Mostlylucid.DbContext \
    --startup-project Mostlylucid \
    --output efbundle \
    --runtime linux-x64

Τρέχω τη Γέννηση Σας

# Using default connection string from appsettings.json
./efbundle.exe

# Override with a specific connection string
./efbundle.exe --connection "Host=localhost;Database=mostlylucid;Username=postgres;Password=secret"

# Using an environment variable (matches your config key)
$env:ConnectionStrings__DefaultConnection="Host=localhost;..." # PowerShell
export ConnectionStrings__DefaultConnection="Host=localhost;..." # Bash
./efbundle.exe

Χρήσιμες επιλογές Bundle

# See what migrations would be applied without running them
./efbundle.exe --dry-run

# Verbose output for debugging
./efbundle.exe --verbose

# Apply migrations up to a specific migration (useful for testing)
./efbundle.exe --target-migration "20231115_AddUserTable"

# Combine options
./efbundle.exe --verbose --dry-run

Τοπική ροή εργασίας δοκιμής

# 1. Create migration
dotnet ef migrations add AddNewFeature \
    --project Mostlylucid.DbContext \
    --startup-project Mostlylucid

# 2. Build bundle
dotnet ef migrations bundle \
    --project Mostlylucid.DbContext \
    --startup-project Mostlylucid \
    --output efbundle.exe

# 3. Dry run first
./efbundle.exe --dry-run --verbose

# 4. Run for real
./efbundle.exe --verbose

# 5. Broken? Remove and retry
dotnet ef migrations remove \
    --project Mostlylucid.DbContext \
    --startup-project Mostlylucid

Σφάλματα σύνταξης αλιευμάτων, παραβιάσεις περιορισμών, θέματα FK - όλα πριν ΚΚΠ ή παραγωγή.

Επιδόσεις κατασκευής

Η γενιά Bundle είναι αργή - 30+ δευτερόλεπτα σε μεγάλα έργα.

Δημιουργήστε χειροκίνητα κατά τη δοκιμή τοπικά
Δημιουργία σε CI μόνο κατά τη διάρκεια της ανάπτυξης, όχι κάθε PR
Πακέτα cache αν οι μεταναστεύσεις δεν έχουν αλλάξει

Αν θέλετε πραγματικά αυτό-γενιά, προσθέστε ένα MSBuild στόχο:

<Target Name="BuildMigrationBundle">
  <Exec Command="dotnet ef migrations bundle --output $(OutputPath)efbundle.exe --force" />
</Target>

Τότε: dotnet build -t:BuildMigrationBundle

Υβριδική προσέγγιση

Οι καλύτεροι και από τους δύο κόσμους: ευκολία τοπικά, ασφάλεια στην παραγωγή.

if (builder.Environment.IsDevelopment())
{
    using var scope = app.Services.CreateScope();
    var context = scope.ServiceProvider.GetRequiredService<IMostlylucidDBContext>();
    await context.Database.MigrateAsync();
}
// Production: CI pipeline runs the bundle

Εναλλακτικές λύσεις για Bundles

SQL Scripts

Δημιουργήστε απλό SQL αντί για εκτελέσιμο. Μεγάλη για αναθεώρηση DBA και τις υπάρχουσες διαδικασίες διαχείρισης αλλαγών.

# All migrations
dotnet ef migrations script --output migrations.sql

# Idempotent (safe to run multiple times) - USE THIS
dotnet ef migrations script --idempotent --output migrations.sql

# Range of migrations
dotnet ef migrations script FromMigration ToMigration --output migrations.sql

Pros: Πλήρης ορατότητα, κάθε πελάτης SQL μπορεί να το τρέξει, φιλική έκδοση ελέγχου, DBA ροή εργασίας έγκριση.

Κατά: Δεν υπάρχει αυτόματη παρακολούθηση (χρήση) --idempotent), χειρωνακτική εκτέλεση, πιθανή μετατόπιση εάν τα σενάρια τροποποιούνται.

Βλέπεις; επίσημα έγγραφα σχετικά με τα σενάρια SQL.

SQL Scripts in CI

- name: Generate and apply migrations
  run: |
    dotnet ef migrations script --idempotent --output migrations.sql
    # SQL Server
    sqlcmd -S ${{ secrets.DB_SERVER }} -d ${{ secrets.DB_NAME }} -i migrations.sql
    # Or PostgreSQL
    PGPASSWORD=${{ secrets.DB_PASSWORD }} psql -h ${{ secrets.DB_HOST }} -f migrations.sql

DIACAC (μόνο Server SQL)

ΔΑΚΑΚ είναι κρατικής βάσης Όχι, όχι. με βάση τη μετανάστευση. Μπορείτε να καθορίσει το επιθυμητό σχήμα, και SqlPackage diffs αυτό στη βάση δεδομένων στόχου.

SqlPackage.exe /Action:Publish /SourceFile:MyDatabase.dacpac /TargetConnectionString:"..."

Pros: Schema ως κώδικας, παραγωγή auto-diff, χειρίζεται τα πάντα (τραπέζια, απόψεις, SPs, ευρετήρια), εργαλεία επιχειρήσεων.

Κατά: SQL Server μόνο, schema σε δύο θέσεις (EF μοντέλα + SQL έργο), diff κινητήρα κάνει αμφισβητήσιμες επιλογές, στήλη μετονομάσεις μοιάζουν με drop+add.

Βλέπεις; SqlPackage docs.

Πίνακας σύγκρισης

Η προσέγγιση είναι η καλύτερη για την χρήση .NET Αυτόματες tracks Εφαρμοσμένες DBA Friendly _ DBA Friendly Cross-platform DB |----------|----------|---------------|---------------------|--------------|-------------------| | MigrateAsync() Ναι, ναι, ναι, ναι, όχι, ναι, ναι, ναι, ναι, ναι, ναι, ναι, ναι. Ναι, ναι, ναι, ναι, ναι, ναι. SQL Scripts DBA-ελεγχόμενα περιβάλλοντα --idempotent Ναι, ναι, ναι, ναι, ναι, ναι, ναι. Ναι (βασισμένο στο κράτος) Ναι, ναι, ναι, όχι, όχι, όχι, όχι.

Συμβουλές

Ο Σχεδιαστής Αρχείο Πήρε

Οι μεταναστεύσεις δουλεύουν τοπικά αλλά όχι στον πληροφοριοδότη; Έλεγξες και τα δύο αρχεία:

20231115_AddUserTable.cs - Ο κώδικας μετανάστευσης
20231115_AddUserTable.Designer.cs - Το μοντέλο στιγμιότυπο

Λείπει το αρχείο Designer = σιωπηλή αποτυχία.

Πολλαπλά DbContexts

dotnet ef migrations bundle --context BlogDbContext --output blog-migrations.exe
dotnet ef migrations bundle --context IdentityDbContext --output identity-migrations.exe

Προτεραιότητα συμβολοσειράς σύνδεσης

--connection επιχείρημα
Μεταβλητή περιβάλλοντος
appsettings.json

Χρήση μεταβλητών περιβάλλοντος σε CI.

IDesignTimeDbContextFactory

Εάν το DbContext σας βρίσκεται σε ξεχωριστό έργο ή έχει περίπλοκη εκκίνηση, εφαρμόστε το IDesignTimeDbContextFactory<T>:

public class AdminDbContextFactory : IDesignTimeDbContextFactory<AdminDbContext>
{
    public AdminDbContext CreateDbContext(string[] args)
    {
        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("appsettings.json", optional: true)
            .AddEnvironmentVariables()
            .AddUserSecrets<AdminDbContextFactory>()
            .Build();

        var connectionString = config["AdminSite:ConnectionString"]
            ?? throw new InvalidOperationException("Missing connection string");

        var optionsBuilder = new DbContextOptionsBuilder<AdminDbContext>();
        optionsBuilder.UseSqlServer(connectionString, sql => sql.CommandTimeout(120));

        return new AdminDbContext(optionsBuilder.Options);
    }
}

Χρήση όταν: DbContext σε ξεχωριστό έργο, περίπλοκη εκκίνηση, χρειάζονται μυστικά χρηστών για το σχεδιασμό-χρόνο.

Τι θα γίνει με...;

Συνηθισμένες ερωτήσεις και αναπηδήσεις που έλαβα.

"Γιατί δεν τρέχεις απλά `dotnet ef database update` στην CI;"

Καλύπτεται παραπάνω, αλλά η σύντομη έκδοση: τα πακέτα είναι φορητά αντικείμενα. Το βήμα ανάπτυξής σας δεν χρειάζεται EF CLI, πηγαίο κώδικα, ή ανάλυση σχεδιασμού-χρόνου.

"Δεν είναι υπερβολή για μια μικρή εφαρμογή;"

Αν είσαι μόνος, τα δεδομένα είναι δημόσια και η ακτίνα έκρηξης είναι χαμηλή... MigrateAsync() Αλλά τη στιγμή που θα προσθέσετε ένα δεύτερο προγραμματιστή, ευαίσθητα δεδομένα, ή πολλαπλά περιβάλλοντα, πακέτα πληρώνουν για τον εαυτό τους.

"Τι γίνεται με τις αναποδογυρίσεις;"

Η EF δεν κάνει αυτόματα rollbacks.

Δημιουργία ενός Down() μετανάστευση και να το τρέξει (αλλά θα πρέπει να έχετε γράψει)
Επαναφορά από το backup
Γράψτε μια χειροκίνητη μετανάστευση για να αναιρέσετε τις αλλαγές

Για τα κρίσιμα συστήματα: δοκιμή μετανάστευσης κατά ενός κλώνου βάσης δεδομένων πρώτα.

"Μπορώ να τρέξω μεταναστεύσεις σε ένα δοχείο Kubernetes init;"

Ναι. Το δοχείο Bundle + init είναι ένα συμπαγές μοτίβο:

initContainers:
  - name: migrate
    image: myapp:latest
    command: ["./efbundle.exe"]
    env:
      - name: ConnectionStrings__Default
        valueFrom:
          secretKeyRef:
            name: db-secrets
            key: connection-string

Το δοχείο App περιμένει να ολοκληρωθεί το init.

"Τι γίνεται με το FluentMigrator / DbUp / άλλα εργαλεία;"

Τα πακέτα EF είναι η ιθαγενή λύση EF, αλλά FluentMigrator και DbUpName έχουν τους οπαδούς τους. Βασική διαφορά: αυτά είναι εργαλεία ειδικά για τη μετανάστευση, ενώ τα πακέτα EF προέρχονται από το υπάρχον μοντέλο EF σας.

"Ο DBA μου θέλει να επανεξετάσει όλα τα SQL πριν τρέξει"

Χρήση --idempotent σενάρια:

dotnet ef migrations script --idempotent --output migrations.sql

DBA κριτικές και εγκρίνει. Στη συνέχεια είτε:

Εκτελέστε το σενάριο χειροκίνητα, ή
Μόλις εγκριθεί, τρέξε το πακέτο (το οποίο κάνει το ίδιο πράγμα)

"Πώς χειρίζομαι τις μεταναστεύσεις με μηδενικό χρόνο;"

Αυτό είναι ζήτημα στρατηγικής ανάπτυξης, όχι ζήτημα μετανάστευσης.

Κάντε τη μετανάστευση προς τα πίσω συμβατή (προσθέστε στήλες που δεν μπορούν να ακυρωθούν, μην μετονομάσετε)
Αναπτύξτε νέο κώδικα που χειρίζεται τόσο παλιά όσο και νέα schema
Εκτέλεση της μετανάστευσης
Αναπτύξτε κώδικα που χρησιμοποιεί μόνο νέο σχήμα
Καθαρισμός (σταγόνα παλιές στήλες σε μεταγενέστερη μετανάστευση)

Οι bundles δεν το λύνουν αυτό - απλά κάνουν το 3ο βήμα πιο προβλέψιμο.