SQLAlchemy Migracija su Alembic: Schemos Versijavimo Paaiškinimas

Duomenų bazės schemos valdymas yra kritiškai svarbus programinės įrangos kūrimo aspektas, ypač projektuose, kurie vystosi laikui bėgant. Jūsų programai augant ir keičiantis jos duomenų reikalavimams, jums reikės patikimo būdo modifikuoti savo duomenų bazės schemą neprarandant duomenų ar nesugadinant esamo funkcionalumo. Čia atsiranda duomenų bazės migracijos.

SQLAlchemy, populiarus Python SQL įrankių rinkinys ir Object-Relational Mapper (ORM), suteikia galingą ir lankstų būdą sąveikauti su duomenų bazėmis. Tačiau SQLAlchemy pats tiesiogiai neapima schemos migracijų. Čia įsijungia Alembic. Alembic yra lengvas ir paprastas naudoti migracijos įrankis, specialiai sukurtas sklandžiai veikti su SQLAlchemy.

Šis išsamus vadovas padės jums atlikti Alembic naudojimo SQLAlchemy migracijoms procesą, apimdamas viską nuo pradinio nustatymo iki pažangių technikų. Nesvarbu, ar esate patyręs kūrėjas, ar tik pradedate dirbti su SQLAlchemy, šis vadovas suteiks jums žinių ir įgūdžių efektyviai valdyti savo duomenų bazės schemą.

Kodėl Naudoti Duomenų Bazės Migracijas?

Prieš gilinantis į technines detales, supraskime, kodėl duomenų bazės migracijos yra tokios svarbios:

• Versijų Valdymas Jūsų Duomenų Bazei: Migracijos leidžia sekti duomenų bazės schemos pakeitimus versijų valdymo būdu, kaip ir jūsų programos kode. Tai reiškia, kad prireikus galite lengvai grįžti prie ankstesnės schemos arba taikyti pakeitimus palaipsniui.
• Automatizuoti Schemos Atnaujinimai: Vietoj rankinio SQL skriptų vykdymo, migracijos suteikia automatizuotą būdą atnaujinti duomenų bazės schemą. Tai sumažina klaidų riziką ir užtikrina nuoseklumą skirtingose aplinkose.
• Bendradarbiavimas: Migracijos palengvina komandų bendradarbiavimą atliekant duomenų bazės pakeitimus. Kiekvienas kūrėjas gali kurti ir taikyti migracijas nepriklausomai, nesikertant su vienas kito darbu.
• Diegimas: Migracijos supaprastina diegimo procesą, pateikdamos patikimą būdą atnaujinti duomenų bazės schemą kaip dalį jūsų programos diegimo srauto. Tai užtikrina, kad jūsų duomenų bazė visada būtų sinchronizuota su jūsų programos kodu.
• Duomenų Išsaugojimas: Gerai suprojektuotos migracijos gali padėti išsaugoti jūsų duomenis schemos pakeitimų metu. Pavyzdžiui, galite sukurti migraciją, kuri prideda naują stulpelį ir užpildo jį duomenimis iš esamo stulpelio.

Alembic Nustatymas su SQLAlchemy

Pradėkime nustatydami Alembic jūsų SQLAlchemy projekte. Tarkime, kad jau turite Python projektą su įdiegta SQLAlchemy.

1. Įdiekite Alembic

Pirmiausia įdiekite Alembic naudodami pip:

            pip install alembic
            

              
                Copy
              
            
          

2. Inicializuokite Alembic

Pereikite į savo projekto šakninį katalogą ir paleiskite šią komandą, kad inicializuotumėte Alembic:

            alembic init alembic
            

              
                Copy
              
            
          

Tai sukurs naują katalogą, pavadintą `alembic` jūsų projekte. Šiame kataloge bus Alembic konfigūracijos failas (`alembic.ini`) ir `versions` katalogas, kuriame bus saugomi jūsų migracijos scenarijai.

3. Konfigūruokite Alembic

Atidarykite `alembic.ini` failą ir sukonfigūruokite `sqlalchemy.url` nustatymą, kad jis nurodytų jūsų duomenų bazės prisijungimo eilutę. Pavyzdžiui:

            sqlalchemy.url = postgresql://user:password@host:port/database
            

              
                Copy
              
            
          

Pakeiskite `user`, `password`, `host`, `port` ir `database` savo tikrais duomenų bazės kredencialais. Apsvarstykite galimybę naudoti aplinkos kintamuosius, kad saugotumėte jautrius kredencialus, o ne įrašytumėte juos tiesiai į failą. Tai ypač svarbu bendradarbiaujant projektuose arba diegiant skirtingose aplinkose.

Toliau atidarykite `alembic/env.py` failą ir sukonfigūruokite Alembic prisijungti prie jūsų SQLAlchemy variklio. `env.py` failas yra Alembic integracijos su SQLAlchemy širdis. Jis atsakingas už duomenų bazės ryšio nustatymą, esamos schemos atspindėjimą (jei tokia yra) ir konteksto suteikimą migracijos scenarijų generavimui.

Suraskite `run_migrations_online` funkciją ir pakeiskite ją, kad naudotumėte savo SQLAlchemy variklį. Štai pavyzdys:

            def run_migrations_online():
    """Run migrations in a 'live' settings.

    This hook is provided to run migrations using a direct
    database connection.

    Instead of an Engine, the connectable within the
    configuration context is already a Connection.
    """
    connectable = engine_from_config(
        config.get_section(config.config_ini_section),
        prefix="sqlalchemy.",
        poolclass=pool.NullPool,
    )

    with connectable.connect() as connection:
        context.configure(
            connection=connection,
            target_metadata=target_metadata
        )

        with context.begin_transaction():
            context.run_migrations()

            

              
                Copy
              
            
          

Įsitikinkite, kad `target_metadata` yra nustatytas į jūsų SQLAlchemy metaduomenų objektą. Tai pasako Alembic, kurias lenteles ir schemas valdyti. Pavyzdys:

            from myapp.models import Base
target_metadata = Base.metadata

            

              
                Copy
              
            
          

Šiame pavyzdyje daroma prielaida, kad `myapp.models` yra modulis, kuriame apibrėžti jūsų SQLAlchemy modeliai, o `Base` yra deklaratyvi pagrindinė klasė jūsų modeliams.

4. Sukurkite Savo Pirmąją Migraciją

Dabar, kai Alembic yra nustatytas, galite sukurti savo pirmąją migraciją. Alembic gali automatiškai aptikti jūsų modelių pakeitimus ir generuoti migracijas, arba galite jas sukurti rankiniu būdu sudėtingesniems scenarijams.

Automatinis Migracijos Generavimas

Norėdami automatiškai sugeneruoti migraciją pagal dabartinius SQLAlchemy modelius, paleiskite šią komandą:

            alembic revision --autogenerate -m "Create initial tables"
            

              
                Copy
              
            
          

Tai sukurs naują migracijos scenarijų `alembic/versions` kataloge. Scenarijuje bus SQL kodas, reikalingas lentelėms, apibrėžtoms jūsų SQLAlchemy modeliuose, sukurti.

`-m` vėliava nurodo pranešimą, apibūdinantį migraciją. Šis pranešimas bus saugomas migracijos istorijoje ir gali būti naudingas suprasti kiekvienos migracijos paskirtį.

Rankinis Migracijos Kūrimas

Sudėtingesnėms migracijoms gali prireikti sukurti scenarijų rankiniu būdu. Norėdami sukurti tuščią migracijos scenarijų, paleiskite šią komandą:

            alembic revision -m "Add a new column"
            

              
                Copy
              
            
          

Tai sukurs naują migracijos scenarijų su tuščiomis `upgrade` ir `downgrade` funkcijomis. Jums reikės užpildyti šias funkcijas atitinkamu SQL kodu, kad atliktumėte migraciją.

Migracijos Scenarijų Supratimas

Štai paprasto migracijos scenarijaus, kuris prideda naują stulpelį į lentelę, pavyzdys:

            """
Add a new column to the users table

Revision ID: 1234567890ab
Revises: None
Create Date: 2023-10-27 10:00:00.000000

"""
from alembic import op
import sqlalchemy as sa


revision = '1234567890ab'
revises = None
down_revision = None


def upgrade():
    op.add_column('users', sa.Column('email', sa.String(255), nullable=True))


def downgrade():
    op.drop_column('users', 'email')

            

              
                Copy
              
            
          

Šiame pavyzdyje `upgrade` funkcija naudoja `op.add_column` funkciją, kad pridėtų naują stulpelį, pavadintą `email`, į `users` lentelę. `downgrade` funkcija naudoja `op.drop_column` funkciją stulpeliui pašalinti.

Alembic teikia įvairias operacijas duomenų bazės schemų modifikavimui, įskaitant:

• `op.create_table`: Sukuria naują lentelę.
• `op.drop_table`: Ištrina esamą lentelę.
• `op.add_column`: Prideda naują stulpelį į lentelę.
• `op.drop_column`: Ištrina stulpelį iš lentelės.
• `op.create_index`: Sukuria naują indeksą.
• `op.drop_index`: Ištrina esamą indeksą.
• `op.alter_column`: Pakeičia esamą stulpelį.
• `op.execute`: Vykdo žalias SQL ataskaitas.

Rašant migracijos scenarijus, svarbu atsižvelgti į šiuos dalykus:

• Idempotencija: Migracijos scenarijai turėtų būti idempotentiniai, o tai reiškia, kad juos galima vykdyti kelis kartus nekeliant klaidų ar nenumatytų šalutinių poveikių. Tai ypač svarbu automatizuotiems diegimams.
• Duomenų Išsaugojimas: Modifikuodami esamas lenteles, turėtumėte stengtis kuo labiau išsaugoti duomenis. Pavyzdžiui, pervardydami stulpelį, galite sukurti laikiną stulpelį, nukopijuoti duomenis į naują stulpelį ir tada ištrinti seną stulpelį.
• Operacijos: Migracijos scenarijai turėtų būti vykdomi operacijos metu. Tai užtikrina, kad visi pakeitimai bus taikomi atomiškai ir kad duomenų bazė gali būti grąžinta į ankstesnę būseną, jei įvyks klaida.

Migracijų Taikymas

Sukūrę migracijos scenarijus, galite juos pritaikyti savo duomenų bazei naudodami `alembic upgrade` komandą.

            alembic upgrade head
            

              
                Copy
              
            
          

Ši komanda pritaikys visas laukiančias migracijas duomenų bazei, pakeldama ją į naujausią versiją. `head` argumentas nurodo, kad Alembic turėtų pritaikyti visas migracijas iki galvos versijos. Taip pat galite nurodyti konkrečią versiją, į kurią norite atnaujinti.

Norėdami grįžti prie ankstesnės versijos, galite naudoti `alembic downgrade` komandą.

            alembic downgrade -1
            

              
                Copy
              
            
          

Ši komanda sumažins duomenų bazės versiją viena versija. Taip pat galite nurodyti konkrečią versiją, į kurią norite sumažinti.

Alembic seka, kurios migracijos buvo pritaikytos duomenų bazei, lentelėje, pavadintoje `alembic_version`. Šioje lentelėje yra viena eilutė, kurioje saugoma dabartinė duomenų bazės versija.

Pažangios Alembic Technikos

Šakos

Šakos leidžia jums sukurti kelias lygiagrečias migracijų sekas. Tai gali būti naudinga kuriant skirtingas savo programos funkcijas ar versijas lygiagrečiai.

Norėdami sukurti naują šaką, naudokite `alembic branch` komandą.

            alembic branch feature_x
            

              
                Copy
              
            
          

Tai sukurs naują šaką, pavadintą `feature_x`. Tada galite sukurti naujas migracijas šioje šakoje naudodami `alembic revision` komandą.

            alembic revision -m "Add feature X" --branch feature_x
            

              
                Copy
              
            
          

Norėdami sujungti šaką atgal į pagrindinį magistralę, galite naudoti `alembic merge` komandą.

            alembic merge feature_x -m "Merge feature X"
            

              
                Copy
              
            
          

Aplinkos

Aplinkos leidžia jums skirtingai sukonfigūruoti Alembic skirtingoms aplinkoms, pvz., kūrimo, testavimo ir gamybos. Tai gali būti naudinga naudojant skirtingus duomenų bazės ryšius arba taikant skirtingas migracijas kiekvienoje aplinkoje.

Norėdami sukurti naują aplinką, galite sukurti atskirą Alembic konfigūracijos failą kiekvienai aplinkai. Pavyzdžiui, galite sukurti `alembic.dev.ini` failą kūrimo aplinkai ir `alembic.prod.ini` failą gamybos aplinkai.

Tada galite nurodyti, kurį konfigūracijos failą naudoti vykdant Alembic komandas, naudodami `-c` vėliavą.

            alembic upgrade head -c alembic.dev.ini
            

              
                Copy
              
            
          

Individualios Operacijos

Norėdami sukurti individualią operaciją, turite apibrėžti naują klasę, kuri paveldi iš `alembic.operations.Operation` klasės. Ši klasė turėtų apibrėžti `upgrade` ir `downgrade` metodus, kurie bus iškviesti, kai operacija bus pritaikyta arba atšaukta.

Tada turite užregistruoti individualią operaciją su Alembic naudodami `alembic.operations.Operations.register_operation` metodą.

Geriausia Duomenų Bazės Migracijų Praktika

• Išbandykite Savo Migracijas: Visada išbandykite savo migracijas ne gamybos aplinkoje prieš pritaikydami jas savo gamybos duomenų bazei. Tai gali padėti jums pagauti klaidas ir išvengti duomenų praradimo.
• Naudokite Aprašomus Migracijos Pranešimus: Kurdami migracijas, naudokite aiškius ir aprašomus pranešimus. Tai palengvins suprasti kiekvienos migracijos paskirtį ateityje.
• Laikykite Migracijas Mažas ir Sutelktas: Laikykite savo migracijas mažas ir sutelktas į vieną pakeitimą. Tai palengvins atskirų migracijų atšaukimą, jei prireiks.
• Naudokite Operacijas: Visada vykdykite savo migracijas operacijos metu. Tai užtikrins, kad visi pakeitimai bus taikomi atomiškai ir kad duomenų bazė gali būti grąžinta į ankstesnę būseną, jei įvyks klaida.
• Dokumentuokite Savo Migracijas: Dokumentuokite savo migracijas su komentarais ir paaiškinimais. Tai palengvins kitiems kūrėjams suprasti ir prižiūrėti jūsų duomenų bazės schemą.
• Automatizuokite Savo Migracijas: Automatizuokite savo migracijas kaip dalį savo programos diegimo srauto. Tai užtikrins, kad jūsų duomenų bazė visada būtų sinchronizuota su jūsų programos kodu.
• Apsvarstykite Duomenų Išsaugojimą: Modifikuodami esamas lenteles, visada apsvarstykite, kaip kuo labiau išsaugoti duomenis. Tai gali padėti išvengti duomenų praradimo ir sumažinti trikdžius jūsų vartotojams.
• Atsarginė Savo Duomenų Bazės Kopija: Visada sukurkite atsarginę savo duomenų bazės kopiją prieš pritaikydami bet kokias migracijas savo gamybos aplinkoje. Tai leis jums atkurti savo duomenų bazę į ankstesnę būseną, jei kas nors nutiktų ne taip.

Išvada

Duomenų bazės migracijos yra esminė šiuolaikinio programinės įrangos kūrimo dalis. Naudodami Alembic su SQLAlchemy, galite efektyviai valdyti savo duomenų bazės schemą, sekti pakeitimus ir automatizuoti atnaujinimus. Šis vadovas suteikė jums išsamų Alembic ir jo funkcijų apžvalgą. Laikydamiesi čia aprašytų geriausių praktikų, galite užtikrinti, kad jūsų duomenų bazės migracijos būtų patikimos, prižiūrimos ir saugios.

Nepamirškite reguliariai praktikuotis ir ištirti pažangias Alembic funkcijas, kad taptumėte įgudusiu efektyviai valdyti savo duomenų bazės schemą. Jūsų projektams vystantis, jūsų duomenų bazės migracijų supratimas taps neįkainojamu turtu.

Šis vadovas skirtas būti atspirties tašku. Norėdami gauti išsamesnės informacijos, žr. oficialią SQLAlchemy ir Alembic dokumentaciją. Laimingo migravimo!