Atlas Veritabanı Sürüm Yönetimi

1. Atlas'a Giriş

atlas

Atlas, modern DevOps prensiplerini kullanarak veritabanı şemalarını yönetmek ve göç etmek için özel olarak tasarlanmış, dil bağımsız bir araçtır. İki iş akışı seçeneği sunar:

Deklaratif: Terraform'a benzer şekilde, Atlas, mevcut veritabanının durumunu HCL, SQL veya ORM şeması kullanarak tanımlanan istenen durumla karşılaştırır. Bu karşılaştırmaya dayanarak, veritabanını istenen durumuna geçiş yapacak bir göç planı oluşturur ve uygular.
Sürümlü: Diğer araçların aksine, Atlas otomatik olarak şema göçlerini planlar. Kullanıcılar istedikleri veritabanı şemasını HCL, SQL veya seçtikleri ORM kullanarak tanımlayabilir ve Atlas ile gerekli göçleri planlayabilir, gözden geçirebilir ve uygulayabilirler.

Atlas'ın önemli bir avantajı, veritabanı yönetiminin karmaşıklığını basitleştirmesidir ve bu durum sürüm kontrolü, iş birliği ve uygulamayı kolaylaştırır.

2. Atlas'ın Kurulumu

Veritabanı sürümlerini yönetmek için Atlas'ı kullanmadan önce, onu kurmamız gerekmektedir. Farklı platformlar için kurulum adımları aşağıda belirtilmiştir.

2.1 macOS + Linux Kurulumu

MacOS veya Linux sistemlerinde, aşağıdaki komut satırını kullanarak Atlas'ın en son sürümünü indirip kurabilirsiniz:

curl -sSf https://atlasgo.sh | sh

Bu komut, otomatik olarak işletim sistemi sürümünü algılar, uygun derleme sürümünü indirir ve Atlas ikili dosyasını yürütülebilir yola yerleştirir.

2.2 Homebrew Üzerinden Kurulum

Eğer macOS kullanıyorsanız ve zaten Homebrew paket yöneticisini kurduysanız, Atlas'ı kurmak oldukça basittir. Aşağıdaki komutu çalıştırmak yeterlidir:

brew install ariga/tap/atlas

Bu komut, Homebrew deposundan Atlas'ın en son sürümünü alıp kuracaktır.

2.3 Docker Kurulumu

Docker üzerinden Atlas'ı kurup çalıştırmak, özellikle geçici testler veya ana sistemlerine ek yazılım kurmak istemeyen kullanıcılar için hızlı ve pratik bir yöntemdir.

İlk olarak, Atlas Docker imajını çekin:

docker pull arigaio/atlas

Daha sonra, başarılı bir kurulumu doğrulamak için yardım komutunu çalıştırabilirsiniz:

docker run --rm arigaio/atlas --help

Eğer konteynerin ana ağa veya yerel dizinlere erişmesi gerekiyorsa, --net=host bayrağını kullanın ve gereken dizinleri bağlayın:

docker run --rm --net=host \
  -v $(pwd)/migrations:/migrations \
  arigaio/atlas migrate apply \
  --url "mysql://root:pass@:3306/test"

2.4 Windows Kurulumu

İkili dosyayı https://release.ariga.io/atlas/atlas-windows-amd64-latest.exe adresinden indirin ve kurulum dizinini sistem PATH ortam değişkenine ekleyin.

3. Mevcut Veritabanı Tablo Yapısının Atlas Kullanılarak Dışa Aktarılması

Atlas, mevcut bir veritabanının yapısını dışa aktarmak için atlas schema inspect komutunu sağlar. Bu komut, veritabanı tanımlarını veritabanı URL'sinden okuma ve bunları varsayılan Atlas HCL formatı, SQL formatı ve JSON formatı olmak üzere üç farklı formatta çıktı olarak verme özelliğini destekler. Bu rehberde, Atlas HCL ve SQL formatlarını nasıl kullanacağımızı göstereceğiz; çünkü JSON formatı genellikle çıktının jq ile işlenmesi için kullanılır.

Yerel bir MySQL örneğini incelemek ve çıktıyı schema.hcl adlı bir dosyaya yazmak için aşağıdaki komutu kullanın:

atlas schema inspect -u "mysql://root:pass@localhost:3306/example" > schema.hcl

schema.hcl dosyasını açın ve veritabanını açıklayan Atlas tablo yapı tanımını görüntüleyin (HCL, Atlas tarafından tanımlanan bağımsız bir tablo yapılandırma formatıdır). Örneğin, bu dosya aşağıdaki içeriği içerecektir:

table "users" {
  schema = schema.example
  column "id" {
    null = false
    type = int
  }
  column "name" {
    null = true
    type = varchar(100)
  }
  primary_key {
    columns = [column.id]
  }
}

Bu kod bloğu, id ve name sütunlarına sahip bir tablo yapısını temsil eder. schema alanı, başka bir yerde tanımlanan example model tanımına referans verir. Ayrıca primary_key alt bloğu, tablo için id sütununu birincil anahtar olarak belirtir. Atlas, işlem yapılan veritabanının sözdizimini taklit etmeye çalışır. Bu örnekte, id sütunu int türüne sahipken, name sütunu varchar(100) türüne sahiptir.

Benzer şekilde, veritabanının SQL model tanımını dışa aktarmak için aşağıdaki komutu kullanabilirsiniz:

atlas schema inspect -u "mysql://root:pass@localhost:3306/example" --format '{{ sql . }}' > schema.sql

schema.sql dosyasını açarak genellikle bazı CREATE TABLE ifadeleri içeren veritabanının SQL açıklamasını görüntüleyebilirsiniz.

Bu yaklaşım, mevcut veritabanı tablo yapısının detaylarını anlamak için uygun olup, ardışık sürümlü göç işlemleri için doğru bir referans sağlar.

4.1 Bildirimsel İş Akışı

Atlas'ın Bildirimsel İş Akışı, kullanıcıların veritabanının istenen nihai durumunu bildirimsel olarak tanımlamalarına izin verir. Kullanıcılar, yalnızca veritabanı şema'nın nihai durumunun ne olmasını istediklerini tanımlamaları gerekir ve Atlas aracı, mevcut durumdan bu beklenen duruma güvenli bir şekilde geçiş yapmak için göç planları otomatik olarak oluşturacak ve yürütecektir.

Aşağıda, Bildirimsel İş Akışı'nı kullanarak istenen veritabanı durumunu tanımlama ve gerçekleştirme adımları bulunmaktadır:

4.1.1 Hedef Tablo Yapısını Tanımlama

İlk olarak, beklenen veritabanı yapısını tanımlayan bir dosya oluşturmanız gerekmektedir; bu dosya HCL, SQL veya ORM (Nesne-İlişkisel Eşleme) formatında olabilir.

HCL formatını örnek olarak alarak, yeni bir blog_posts tablosunu tanımlayın:

table "blog_posts" {
  schema = schema.example
  column "id" {
    null = false
    type = int
  }
  column "title" {
    null = true
    type = varchar(100)
  }
  column "body" {
    null = true
    type = text
  }
  column "author_id" {
    null = true
    type = int
  }
  primary_key {
    columns = [column.id]
  }
  foreign_key "author_fk" {
    columns     = [column.author_id]
    ref_columns = [table.users.column.id]
  }
}

İpucu: HCL'nin sözdizim formatı daha sonraki bir bölümde ele alınacaktır.

4.1.2 Atlas Aracını Kullanarak Göç İşlemi Yapma

Veritabanı tablo yapısı tanımı tamamlandıktan sonra, Atlas aracının schema apply komutunu kullanarak göç işlemini gerçekleştirebilirsiniz.

atlas schema apply \
  -u "mysql://root:pass@localhost:3306/example" \
  --to file://schema.hcl

Yukarıdaki komutu çalıştırdıktan sonra, Atlas, mevcut veritabanı şemasını dosyada tanımlanan şema ile karşılaştıracak, bir göç planı oluşturacak ve kullanıcıdan yürütmek için onay isteyecektir. Kullanıcı yürütme planını onayladıktan sonra, Atlas, veritabanı üzerinde göç işlemini gerçekleştirerek onu istenen duruma güncelleyecektir.

4.2 Sürümlü İş Akışı

Sürümlü iş akışı, bazen "değişiklik temelli göç" olarak da adlandırılan Atlas tarafından desteklenen başka bir kullanım modudur. Bu mod, veritabanı şema değişikliklerinin sürüm kontrollü olması ve kod inceleme sürecinde incelenmesi gereken senaryolarda uygundur.

Sürümlü iş akışının adımları şunları içerir:

4.2.1 Farklılıkları Hesapla

Göç işlemine başlamadan önce mevcut veritabanı yapısını istenen durumla karşılaştırarak aralarındaki farkları belirlemek gerekir. Bunun için atlas migrate diff komutunu çalıştırabilirsiniz.

atlas migrate diff create_blog_posts \
  --dir "file://migrations" \
  --to "file://schema.hcl" \
  --dev-url "docker://mysql/8/example"

--dir, varsayılan olarak file://migrations olan göç klasörünün URL'sini belirtir. --to, istenen durumun URL'sini belirtir (örneğin, geliştirme ortamı veritabanınız), ve --dev-url farklılıkları hesaplamak için kullanılan bir geliştirme veritabanı için bir URL sağlar (not: bu --dev-url Atlas'ın farkları hesaplamak için kullandığı boş bir veritabanını belirtmelidir).

İpucu: SQL dosyaları oluşturmak istiyorsanız, --format parametresini kullanarak formatı ayarlama bölümüne bakın.

4.2.2 Göç Değişikliklerini Uygula

Farklılık hesaplama işlemi tamamlandıktan sonra, Atlas migrations klasörüne kaydedilmiş iki göç dosyası oluşturacaktır. Örneğin, seçilen format SQL ise, diff komutu tarafından oluşturulan aşağıdaki SQL dosyası gibi dosyalar, yeni bir tablo oluşturmak için göç komutlarını içerir:

-- "blog_posts" tablosunu oluştur
CREATE TABLE `blog_posts` (
  `id` int NOT NULL,
  `title` varchar(100) DEFAULT NULL,
  `body` text DEFAULT NULL,
  `author_id` int NULL REFERENCES `users`(id),
  PRIMARY KEY (`id`)
);

Göç dosyaları oluşturulduktan sonra, bu değişiklikleri yönetmek için sürüm kontrol araçları (örneğin, Git) kullanabilirsiniz. Bu yaklaşım, geliştirme ortamında birçok veritabanı tablo yapısı değişikliği yapmanıza izin verir ve yayın için geliştirme ortamını ve UAT ortamını Atlas komutlarını kullanarak karşılaştırarak veritabanı tablo yapısı göç dosyalarını oluşturabilirsiniz. Bu göç dosyaları daha sonra UAT ve üretim ortamlarına uygulanarak veritabanını güncellemenize olanak tanır.

Bu Dekleratif ve Sürümlü iki iş akışı, veritabanı şema değişikliklerini yönetmek için projenizin ihtiyaçlarına en uygun olan yöntemi seçmenize olanak tanır.

5. HCL Formatı Açıklaması

5.1 Giriş

HCL, veritabanı tablo yapısı tanımlamak için kullanılan deklaratif bir dildir. Atlas, farklı veritabanı yönlerini tanımlamak için HCL formatını kullanır ve değişken enjeksiyonu ve ek notasyonlar gibi özellikleri destekleme, okunabilirlik, bakım kolaylığı gibi avantajlara sahiptir.

İpucu: Projelerinizin birden çok veritabanına uyum sağlaması gerekiyorsa, HCL kullanarak veritabanı yapılarını veritabanı bağımsız bir şekilde açıklamak çok uygun olabilir.

5.2 `schema` nesnesi

schema nesnesi, bir veritabanı şemasını tanımlamak için kullanılır. MySQL ve SQLite'da DATABASE'i temsil ederken, PostgreSQL'de SCHEMA'yı temsil eder. Bir HCL dosyası birden fazla schema nesnesi içerebilir.

schema "public" {
  comment = "Bir şema yorumu"
}

schema "private" {}

5.3 `table` nesnesi

table nesnesi, bir SQL veritabanında bir tabloyu, sütunları, indeksleri, kısıtlamaları ve farklı veritabanı sürücüleri tarafından desteklenen çeşitli ek özellikleri tanımlamak için kullanılır.

table "users" {
  schema = schema.public
  column "id" {
    type = int
  }
  column "name" {
    type = varchar(255)
  }
  column "manager_id" {
    type = int
  }
  primary_key {
    columns = [
      column.id
    ]
  }
  index "idx_name" {
    columns = [
      column.name
    ]
    unique = true
  }
  foreign_key "manager_fk" {
    columns     = [column.manager_id]
    ref_columns = [table.users.column.id]
    on_delete   = CASCADE
    on_update   = NO_ACTION
  }
}

5.4 `column` nesnesi

column, tablodaki sütunları tanımlamak için table'ın bir alt kaynağıdır.

column "name" {
  type = text
  null = false
}

column "age" {
  type = integer
  default = 42
}

column "active" {
  type = tinyint(1)
  default = true
}

5.5 `primary_key` nesnesi

primary_key, tablonun birincil anahtarını tanımlayan table alt kaynağıdır.

primary_key {
  columns = [kolon.id]
}

5.6 `foreign_key` nesnesi

foreign_key, diğer tabloların sütunlarına referans olan sütunları tanımlayan table alt kaynağıdır.

table "siparişler" {
  schema = schema.market
  // ...
  column "sahip_id" {
    type = integer
  }
  foreign_key "sahip_id" {
    columns     = [column.sahip_id]
    ref_columns = [table.users.column.id]
    on_update   = NO_ACTION
    on_delete   = NO_ACTION
  }
}

5.7 `index` nesnesi

index nesnesi, tablodaki bir indeksi temsil eder.

index "idx_isim" {
  columns = [
    column.isim
  ]
  unique = true
}