SQLAlchemy: ORM ile veritabanı

SQLAlchemy 2.0 üslubuyla veritabanları: Engine ve işlemler, Core ve ORM, bildirimsel modeller, Session ile ekleme, değiştirme ve silme, `select()` ile sorgular, ilişkiler ve N+1 sorunu, Alembic ile geçişler; SQLite örnekleriyle.

  • İleri
  • 22 dk
  • 12 soru
  • Ders 41 / 66

Bu derste öğreneceklerin

  • Bir Engine oluşturmak, bir işlem içinde parametreli SQL çalıştırmak ve Core ile ORM arasındaki farkı açıklamak
  • Mapped ve mapped_column ile modeller yazmak ve Session ile CRUD işlemleri yapmak
  • select(), where, join, group_by ile sorgular kurmak ve SQL’lerini okumak
  • İlişkileri kurmak, N+1 sorunundan kaçınmak ve geçişlerin neden gerektiğini açıklamak

Bir okul uygulaması öğrencileri, kursları ve notları bir veritabanında saklar. Standart sqlite3 modülüyle SQL’i metin olarak kendin yazar, sütun adlarını elle kopyalar ve satırları nesnelere kendin dönüştürürsün; proje SQLite’tan PostgreSQL’e geçtiğinde de SQL’in bir kısmını değiştirmek gerekir. SQLAlchemy, Python için popüler bir veritabanı araç takımıdır: tabloları Python sınıfları olarak tanımlar, nesnelerle çalışırsın; o da seçilen veritabanı için doğru SQL üretir. Ders modern SQLAlchemy 2.0 üslubuyla yazılmıştır.

ORM (nesne-ilişkisel eşleme)Tanım

Sınıf ↔ tablo, nesne ↔ satır, öznitelik ↔ sütun eşlemesi. Bir Student(first_name='Aysel') nesnesini oturuma eklemek bir INSERT’e, özniteliklerinden birini değiştirmek bir UPDATE’e dönüşür.

Senin kodun: Student ve Course nesneleriORM: Session ve select()Core: SQL ifadeleri, ConnectionEngine: bağlantı havuzu + diyalektVeritabanı: SQLite, PostgreSQL…
ORM, Core’un üzerine kuruludur; diyalekt aynı ifadeyi belirli bir veritabanının SQL lehçesine çevirir.

Engine, bağlantılar ve Core

create_engine bir URL alır: sqlite:///school.db bir dosya, sqlite:// bellekte bir veritabanı, postgresql+psycopg://user:password@host/db bir PostgreSQL sunucusudur. Engine tembeldir: ilk sorguda bağlanır ve bağlantıları bir havuzda tutar. engine.begin() bir işlem (transaction) açar: blok başarıyla biterse COMMIT, hata olursa ROLLBACK. text() ham SQL’dir, :name ise bir parametredir.

Python
from sqlalchemy import create_engine, text

engine = create_engine('sqlite://')
with engine.begin() as conn:
    conn.execute(text('CREATE TABLE students (first_name TEXT, age INTEGER)'))
    conn.execute(text('INSERT INTO students VALUES (:name, :age)'),
                 [{'name': 'Aysel', 'age': 15}, {'name': 'Murad', 'age': 16},
                  {'name': 'Leyla', 'age': 14}])

with engine.connect() as conn:
    result = conn.execute(text('SELECT first_name, age FROM students WHERE age >= :min_age'),
                          {'min_age': 15})
    for row in result:
        print(row.first_name, row.age)
print(engine.dialect.name, engine.url)

Beklenen çıktı

Aysel 15
Murad 16
sqlite sqlite://
SQLAlchemy tarayıcıda çalışmaz; bu dersin Python kodunu pip install sqlalchemy sonrasında kendi bilgisayarında çalıştır. Parametre listesi verildiğinde INSERT her satır için tekrarlanır; sonuç satırlarının alanlarına adla erişilir: row.first_name.

Okumaya devam etmek için ücretsiz kaydol

Dersin geri kalan bölümleri, test ve notlar Educora hesabıyla açılır. Kayıt bir dakika sürer; ilerlemen tüm cihazlarında saklanır.

Bildirimsel modeller

Model, DeclarativeBase’den türeyen bir sınıftır. __tablename__ tablonun adını verir, Mapped[...] notasyonu sütunun türünü ve NULL’a izin verilip verilmediğini, mapped_column(...) ise ek seçenekleri belirler: birincil anahtar, uzunluk, benzersizlik. Modelleri ayrı bir models.py dosyasında tutmak pratiktir:

Python
from sqlalchemy import ForeignKey, String
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship


class Base(DeclarativeBase):
    pass


class Student(Base):
    __tablename__ = 'students'
    id: Mapped[int] = mapped_column(primary_key=True)
    first_name: Mapped[str] = mapped_column(String(50))
    city: Mapped[str]
    email: Mapped[str | None]
    enrollments: Mapped[list['Enrollment']] = relationship(back_populates='student')

    def __repr__(self):
        return f'Student({self.first_name!r}, {self.city!r})'
models.py, 1. bölüm. relationship satırını ilişkiler bölümünde açıklayacağız.
Python’daSQL sütunu
Mapped[int]INTEGER NOT NULL
Mapped[str]VARCHAR NOT NULL
Mapped[str | None]VARCHAR (NULL olabilir)
mapped_column(String(50))VARCHAR(50)
mapped_column(primary_key=True)PRIMARY KEY
mapped_column(ForeignKey('students.id'))REFERENCES students (id)
Python
from sqlalchemy import create_engine
from sqlalchemy.schema import CreateTable
from models import Base, Student

engine = create_engine('sqlite:///school.db')
print(str(CreateTable(Student.__table__).compile(engine)).strip())
Base.metadata.create_all(engine)
print(sorted(Base.metadata.tables))

Beklenen çıktı

CREATE TABLE students (
	id INTEGER NOT NULL, 
	first_name VARCHAR(50) NOT NULL, 
	city VARCHAR NOT NULL, 
	email VARCHAR, 
	PRIMARY KEY (id)
)
['courses', 'enrollments', 'students']
CreateTable, modelin üreteceği SQL’i gösterir. create_all bütün modellerin tablolarını oluşturur, zaten var olan tablolara ise dokunmaz.

Session: eklemek, değiştirmek, silmek

Session (iş birimi)Tanım

Nesnelerdeki değişiklikleri toplayan ve commit() sırasında bunları tek bir işlemde veritabanına yazan nesne. Bir oturum içinde bir satıra tek bir nesne karşılık gelir: session.get(Student, 2) iki kez çağrılsa da aynı nesne döner.

  1. Transient (geçici)

    Student(...) oluşturuldu ama oturumda değil; id henüz None.

  2. Pending (bekleyen)

    session.add(obj): nesne kuyruğa girer, INSERT henüz gönderilmedi.

  3. Persistent (kalıcı)

    commit() (ya da flush()) INSERT’i gönderir ve nesne id alır; değişen öznitelikler bir sonraki commit()’te UPDATE olur.

  4. Detached (ayrılmış)

    Oturum kapandıktan sonra nesne kalır ama veritabanından yeni veri yükleyemez.

Python
from sqlalchemy import create_engine
from sqlalchemy.orm import Session
from models import Base, Student

engine = create_engine('sqlite://')
Base.metadata.create_all(engine)

with Session(engine) as session:
    aysel = Student(first_name='Aysel', city='Bakı', email='aysel@example.com')
    session.add(aysel)
    session.add_all([Student(first_name='Murad', city='Gəncə'),
                     Student(first_name='Leyla', city='Bakı')])
    print(aysel.id)
    session.commit()
    print(aysel.id)

    murad = session.get(Student, 2)
    murad.city = 'Sumqayıt'
    session.delete(session.get(Student, 3))
    session.commit()
    print(session.get(Student, 2), session.get(Student, 3))

Beklenen çıktı

None
1
Student('Murad', 'Sumqayıt') None
commit()’ten önce aysel.id None, sonra 1’dir. murad.city değişikliği ve session.delete(...) ikinci commit()’te UPDATE ve DELETE olur; silinen öğrenci için get None döndürür.

select() ile sorgular

select(Student) henüz bir sorgu değil, onun tanımıdır: print(stmt) üretilecek SQL’i gösterir. session.scalars(stmt) nesneler, session.execute(stmt) ise satırlar (demetler) döndürür; ardından .all(), .first() ya da .one() çağrılır. Koşullar sıradan Python operatörleriyle yazılır: Student.city == 'Bakı' True/False değil, bir SQL ifadesidir.

Python
from sqlalchemy import create_engine, func, select
from sqlalchemy.orm import Session
from models import Base, Student

engine = create_engine('sqlite://')
Base.metadata.create_all(engine)
with Session(engine) as session:
    data = [('Aysel', 'Bakı'), ('Murad', 'Gəncə'), ('Leyla', 'Bakı'),
            ('Elvin', 'Sumqayıt'), ('Rəşad', 'Bakı')]
    session.add_all([Student(first_name=n, city=c) for n, c in data])
    session.commit()

    stmt = select(Student).where(Student.city == 'Bakı').order_by(Student.first_name)
    print(stmt)
    print(session.scalars(stmt).all())
    first = session.scalars(select(Student.first_name).where(Student.first_name.like('E%'))).all()
    print(first)
    count = func.count(Student.id)
    stmt = select(Student.city, count).group_by(Student.city).order_by(count.desc(), Student.city)
    print(session.execute(stmt).all())

Beklenen çıktı

SELECT students.id, students.first_name, students.city, students.email 
FROM students 
WHERE students.city = :city_1 ORDER BY students.first_name
[Student('Aysel', 'Bakı'), Student('Leyla', 'Bakı'), Student('Rəşad', 'Bakı')]
['Elvin']
[('Bakı', 3), ('Gəncə', 1), ('Sumqayıt', 1)]
:city_1 bağlı bir parametredir; değer SQL metnine yapıştırılmaz. func.count, SQL’deki COUNT fonksiyonudur; sayısı eşit olan şehirler alfabetik sıralanır.
SQLSQLAlchemy
WHERE city = 'Bakı'.where(Student.city == 'Bakı')
WHERE first_name LIKE 'E%'.where(Student.first_name.like('E%'))
WHERE city IN ('Bakı', 'Quba').where(Student.city.in_(['Bakı', 'Quba']))
WHERE email IS NULL.where(Student.email.is_(None))
ORDER BY first_name DESC LIMIT 3.order_by(Student.first_name.desc()).limit(3)
SELECT city, COUNT(id) … GROUP BY cityselect(Student.city, func.count(Student.id)).group_by(Student.city)

Aynı sorgu düz SQL olarak sitenin örnek veritabanında burada çalışır (orada 12 öğrenci var, bu yüzden satırlar daha fazla):

SQL
SELECT first_name, city
FROM students
WHERE city = 'Bakı'
ORDER BY first_name;
Beklenen çıktı
first_name | city
Aysel | Bakı
Kamran | Bakı
Leyla | Bakı
Rəşad | Bakı

Örnek: Python’dan SQL’e

Problem

print(stmt) ne gösterir? 1) select(Student.first_name).where(Student.city == 'Gəncə'); 2) select(func.count()).select_from(Student); 3) select(Student).where(Student.email.is_(None)).

Çözümü gösterÇözümü gizle

Çözüm

1) SELECT students.first_name FROM students WHERE students.city = :city_1; değer parametre olarak gider.
2) SELECT count(*) AS count_1 FROM students; select_from tabloyu belirtir.
3) SELECT students.id, students.first_name, students.city, students.email FROM students WHERE students.email IS NULL; == None değil, .is_(None) kullan.

İlişkiler ve geçişler

Bir öğrenci birkaç kursa yazılır, bir kursta da birkaç öğrenci okur: bu bir “çoktan çoğa” ilişkidir. Puanı da saklamamız gerektiğinden ara bir Enrollment modeli ekliyoruz: her kaydın bir öğrencisi ve bir kursu vardır. ForeignKey veritabanındaki bağlantıdır, relationship ise Python tarafı: aysel.enrollments listesi, enrollment.course nesnesi. back_populates iki tarafı uyumlu tutar.

Python
class Course(Base):
    __tablename__ = 'courses'
    id: Mapped[int] = mapped_column(primary_key=True)
    title: Mapped[str] = mapped_column(unique=True)
    enrollments: Mapped[list['Enrollment']] = relationship(back_populates='course')


class Enrollment(Base):
    __tablename__ = 'enrollments'
    id: Mapped[int] = mapped_column(primary_key=True)
    student_id: Mapped[int] = mapped_column(ForeignKey('students.id'))
    course_id: Mapped[int] = mapped_column(ForeignKey('courses.id'))
    score: Mapped[int]
    student: Mapped[Student] = relationship(back_populates='enrollments')
    course: Mapped[Course] = relationship(back_populates='enrollments')
models.py, 2. bölüm (1. bölümün devamı).
Python
from sqlalchemy import create_engine, func, select
from sqlalchemy.orm import Session, selectinload
from models import Base, Course, Enrollment, Student

engine = create_engine('sqlite://')
Base.metadata.create_all(engine)
with Session(engine) as session:
    algebra, python = Course(title='Algebra'), Course(title='Python Basics')
    aysel = Student(first_name='Aysel', city='Bakı')
    murad = Student(first_name='Murad', city='Gəncə')
    session.add_all([Enrollment(student=aysel, course=algebra, score=92),
                     Enrollment(student=aysel, course=python, score=88),
                     Enrollment(student=murad, course=algebra, score=75)])
    session.commit()

    for e in aysel.enrollments:
        print(e.course.title, e.score)
    stmt = (select(Course.title, func.avg(Enrollment.score))
            .join(Course.enrollments).group_by(Course.id).order_by(Course.title))
    print(session.execute(stmt).all())
    stmt = select(Student).options(selectinload(Student.enrollments))
    print([(s.first_name, len(s.enrollments)) for s in session.scalars(stmt)])

Beklenen çıktı

Algebra 92
Python Basics 88
[('Algebra', 83.5), ('Python Basics', 88.0)]
[('Aysel', 2), ('Murad', 1)]
Bir Enrollment eklendiğinde ona bağlı öğrenci ve kurs da kendiliğinden oturuma girer. join(Course.enrollments), JOIN koşulunu ForeignKey’den kendisi bulur; Algebra ortalaması (92 + 75) / 2 = 83,5’tir.

create_all yalnızca eksik tabloları oluşturur: bir modele yeni sütun eklersen mevcut tablo değişmez. Gerçek bir projede şema geçişlerle (migration) değiştirilir: SQLAlchemy’nin yazarının geliştirdiği Alembic, modelleri veritabanıyla karşılaştırır ve sürümlü ALTER TABLE betikleri üretir (env.py içinde target_metadata = Base.metadata belirtilmelidir):

Terminal
pip install alembic
alembic init migrations
alembic revision --autogenerate -m "add birth_date to students"
alembic upgrade head
alembic downgrade -1

Alıştırma

Bu ORM sorgusunu SQL’e çevir ve örnek veritabanında çalıştır: select(Course.title, func.count(Enrollment.id), func.max(Enrollment.score)).join(Course.enrollments).group_by(Course.id).order_by(Course.title). Sütunları title, students ve best olarak adlandır.

Alıştırma · SQL
SELECT courses.title AS title
FROM courses
ORDER BY courses.title;
Beklenen çıktı
title | students | best
Algebra | 4 | 97
English B1 | 2 | 90
Geometry | 3 | 95
Mechanics | 4 | 94
Organic Chemistry | 2 | 72
Python Basics | 3 | 99
World History | 2 | 93

Alıştırma

Bir ORM’in içinde olanı tekrarla: insert_sql(table, row) fonksiyonu bir sözlükten kurulmuş parametreli bir INSERT ifadesi ve değerlerden oluşan bir demet döndürmeli. Kod son SQL’i ve tablonun içeriğini yazdırır; kesme işaretli O'Neil adı sorunsuz kaydedilmeli.

Alıştırma · Python
import sqlite3

def insert_sql(table, row):
    # build 'INSERT INTO table (col1, col2) VALUES (?, ?)' and the tuple of values
    return '', ()

conn = sqlite3.connect(':memory:')
conn.execute('CREATE TABLE students (id INTEGER PRIMARY KEY, first_name TEXT, city TEXT)')
for row in [{'first_name': 'Aysel', 'city': 'Bakı'}, {'first_name': "O'Neil", 'city': 'London'}]:
    sql, params = insert_sql('students', row)
    conn.execute(sql, params)
print(sql)
print(conn.execute('SELECT * FROM students').fetchall())
Beklenen çıktı
INSERT INTO students (first_name, city) VALUES (?, ?)
[(1, 'Aysel', 'Bakı'), (2, "O'Neil", 'London')]

Unutma

  • create_engine(url) veritabanına giriş noktasıdır; engine.begin() bir işlemdir, text() sorgularında değerler :name parametreleriyle verilir.
  • Model, __tablename__, Mapped[...] ve mapped_column(...) içeren bir DeclarativeBase alt sınıfıdır; | None NULL’a izin verir; tabloları Base.metadata.create_all oluşturur.
  • Session bir iş birimidir: add, delete ve öznitelik değişiklikleri commit()’te INSERT, DELETE, UPDATE olur; get bir nesneyi birincil anahtarla bulur.
  • select(...) bir sorguyu tanımlar; scalars nesneler, execute satırlar döndürür; print(stmt) ve echo=True SQL’i gösterir.
  • ForeignKey + relationship(back_populates=...) ilişkileri kurar; selectinload N+1’i önler; şema değişiklikleri Alembic geçişleriyle yapılır.
Bu derste bir hata ya da yanlışlık mı gördün?

Kendini test et

12 soru. Her doğru cevap XP kazandırır.

Soru 1 / 12

Soru 1 / 12. engine = create_engine('sqlite:///school.db') satırı ne yapar?