Data Connect şemalarını ve bağlayıcılarını dağıtma ve yönetme

Firebase Data Connect hizmeti üç ana bileşenden oluşur:

  • Kendi SQL şemasına sahip temel bir PostgreSQL veritabanı
  • Data Connect uygulama şeması (.gql dosyalarınızda beyan edilir)
  • çeşitli bağlantılayıcılar (.gql dosyalarınızda tanımlanır, connector.yaml dosyalarında yapılandırılır).

SQL şeması, verilerinizin doğru kaynağıdır. Data Connect şeması, bağlayıcılarınızın bu verileri nasıl görebileceğini belirtir. Bağlayıcılar ise istemcilerinizin bu verilere erişmek için kullanabileceği API'leri tanımlar.

Data Connect hizmetinizi CLI ile dağıtırken SQL şemanızı taşır, ardından Data Connect şemanızı ve bağlayıcılarınızın her birini güncellersiniz.

Önemli dağıtım kavramları

Dağıtım sürecini tam olarak anlamak için şema ve bağlayıcılarla ilgili temel kavramları incelemek önemlidir.

Şema dağıtımları

Data Connect şemasının dağıtımı, Cloud SQL veritabanınızın SQL şemasını etkiler. Data Connect, yeni bir veritabanıyla çalışıyor veya mevcut bir veritabanını veri kaybı olmadan uyarlamanız gerekiyorsa dağıtım sırasında şemalarınızı taşımanıza yardımcı olur.

Data Connect şema taşıma işlemlerinde iki farklı şema doğrulama modu vardır: katı ve uyumlu.

  • Katı mod doğrulaması, uygulama şemasının güncellenebilmesi için veritabanı şemasının uygulama şemasıyla tam olarak eşleşmesini gerektirir. Data Connect şemanızda kullanılmayan tüm tablolar veya sütunlar veritabanından silinir.

  • Uyumlu mod doğrulaması, uygulama şemasının güncellenebilmesi için veritabanı şemasının uygulama şemasıyla uyumlu olmasını gerektirir. Şemaları, tabloları veya sütunları kaldıran ek değişiklikler isteğe bağlıdır.

    Uyumlu, şema taşıma işlemlerinin yalnızca uygulama şemanızda referans verilen tabloları ve sütunları etkilediği anlamına gelir. Veritabanınıza uygulama şemanız tarafından kullanılmayan öğeler değiştirilmeden bırakılır. Bu nedenle, dağıtım sonrasında veritabanınızda kullanılmayan öğeler bulunabilir:

    • Şemalar
    • Tablolar
    • Sütunlar

Bağlayıcı dağıtımları

Data Connect sorguları ve mutasyonları istemci kodu tarafından gönderilmez ve sunucuda yürütülmez. Bunun yerine, dağıtıldığında bu Data Connect işlemleri Cloud Functions gibi sunucuda depolanır. Bu, dağıtımın mevcut kullanıcıları etkileyebileceği anlamına gelir.

Data Connect, bağlayıcı güncellemelerinizdeki önemli değişikliklerin analizini Firebase CLI'ye entegre eder.

CLI, her bağlayıcıdaki değişiklikleri şemanıza göre analiz eder ve bağlayıcı değişiklikleriyle ilgili bir dizi değerlendirme mesajı yayınlar. Bu mesajlar, istemci davranışını değiştirebilecek (uyarı düzeyinde mesajlar) veya istemci kodunun önceki sürümlerini bozabilecek ya da bozacak (önemli düzeyde mesajlar) değişiklikleri içerir.

Örneğin:

  • İstemci davranışını değiştirebilecek bağlayıcı değişiklikleri arasında, @retired şeması ek açıklaması olmadan bir sorgudaki boş bırakılabilir alanın kaldırılması yer alır.
  • İstemcileri bozabilecek veya bozacak bağlayıcı değişiklikleri arasında, boş değer kabul eden bir işlem değişkeninin varsayılan değer olmadan boş olmayan değere değiştirilmesi veya bir alanın veri türünü uyumlu olmayan bir değere (ör. String yerine Int) değiştirilmesi yer alır.

Uyarı düzeyindeki ve önemli düzeydeki senaryoların daha kapsamlı bir listesi CLI referans kılavuzunda verilmiştir.

Dağıtım iş akışını takip edin

Data Connect projelerinde hem yerel proje dizininde hem de Firebase konsolunda çalışabilirsiniz.

Önerilen dağıtım akışı şunları içerir:

  1. firebase dataconnect:services:list ile şu anda dağıtılmış şema ve bağlayıcıları listeleme.
  2. Şema güncellemelerini yönetme
    1. firebase dataconnect:sql:diff ile Cloud SQL veritabanınız ile yerel Data Connect şeması arasındaki SQL şeması farklılıklarını kontrol edin.
    2. Gerekirse dataconnect:sql:migrate ile SQL şeması taşıma işlemini gerçekleştirin.
  3. Yalnızca şemanız, yalnızca bağlayıcılarınız veya kaynak kombinasyonlarınız için firebase deploy'yi çalıştırarak şema ve bağlantı dağıtımları gerçekleştirme.

Data Connect kaynaklarını dağıtma ve yönetme

Dağıtımlar yapmadan önce üretim kaynaklarını doğrulamak iyi bir fikirdir.

firebase dataconnect:services:list

Yerel bir proje dizininde çalışırken şemanızı ve bağlayıcılarınızı etkileşimli geri bildirimlerle üretime dağıtmak için genellikle firebase deploy komutunu kullanırsınız.

deploy komutu ile --only dataconnect işareti, Data Connect dağıtımlarını projenizdeki diğer ürünlerden ayırmanızı sağlar.

Normal dağıtım

firebase deploy --only dataconnect

Bu normal dağıtımda Firebase CLI, şemanızı ve bağlayıcılarınızı dağıtmaya çalışır.

Yeni şemanın mevcut bağlayıcıları bozmadığını doğrular. Önemli değişiklikler yaparken en iyi uygulamalardan yararlanın.

Ayrıca, Data Connect şemasını güncellemeden önce SQL şemasının zaten taşındığını doğrular. Aksi takdirde, şema taşıma için gerekli tüm adımlarda size otomatik olarak yol gösterilir.

--force işaret dağıtımı

firebase deploy --only dataconnect --force

Bağlantılayıcı veya SQL şeması doğrulamaları sorun oluşturmuyorsa bunları yoksaymak için komutu --force ile yeniden çalıştırabilirsiniz.

--force dağıtımı, SQL şemasının Data Connect şemasıyla eşleşip eşleşmediğini kontrol etmeye, uyumsuzluk konusunda uyarıda bulunmaya ve istem göstermeye devam eder.

Seçilen kaynakları dağıtma

Daha ayrıntılı denetimle dağıtmak için --only işaretini serviceId bağımsız değişkeniyle kullanın. Yalnızca belirli bir hizmete ait şema değişikliklerini dağıtmak için:

firebase deploy --only dataconnect:serviceId:schema

Belirli bir bağlayıcı ve hizmet için tüm kaynakları da dağıtabilirsiniz.

firebase deploy --only dataconnect:serviceId:connectorId

Son olarak, şemayı ve tüm bağlayıcıları tek bir hizmet için dağıtabilirsiniz.

firebase deploy --only dataconnect:serviceId

Dağıtımı geri alma

Manuel geri alma işlemi yapmak için kodunuzun önceki bir sürümünü inceleyin ve dağıtın. Orijinal dağıtım, yıkıcı kesinti değişiklikleri içeriyorsa silinen verileri tamamen kurtaramayabilirsiniz.

Veritabanı şemalarını taşıma

Hızlı bir şekilde prototip oluşturuyor, şemalarla deneysel çalışmalar yapıyor ve şema değişikliklerinizin yıkıcı olduğunu biliyorsanız değişiklikleri doğrulamak ve güncellemelerin nasıl yapıldığını denetlemek için Data Connect araçlarını kullanmayı planlayabilirsiniz.

SQL şeması değişikliklerini karşılaştırma

Değişiklikleri doğrulayabilirsiniz:

firebase dataconnect:sql:diff

Virgülle ayrılmış bir hizmet listesi iletebilirsiniz.

Komut, bir hizmetin yerel şemasını ilgili Cloud SQL veritabanının mevcut şemasıyla karşılaştırır. Fark varsa bu farkı düzeltmek için çalıştırılacak SQL komutlarını yazdırır.

Değişiklikleri uygula

Değişikliklerden memnun kaldığınızda ve şemayı Cloud SQL örneğine dağıtmaya hazır olduğunuzda firebase dataconnect:sql:migrate komutunu verin. Değişiklikleri onaylamanız istenir.

firebase dataconnect:sql:migrate [serviceId]

Etkileşimli ortamlarda SQL taşıma ifadeleri ve işlem istemleri gösterilir.

Yüksek düzey veya uyumlu modda taşıma

Yepyeni bir projede varsayılan şema doğrulama modu geçerlidir. migrate komutunun davranışı, uygulama şemanız tarafından gerekli olan tüm veritabanı şeması değişikliklerini uygulamak ve ardından veritabanı şemanızı uygulama şemanızla tam olarak eşleştirmeye zorlamak için şemaları, tabloları veya sütunları bırakan isteğe bağlı işlemleri onaylamanızı istemektir.

Bu davranışı dataconnect.yaml dosyanızı değiştirerek ayarlayabilirsiniz. Taşıma işlemlerinde yalnızca gerekli değişikliklerin uygulanması için schemaValidation anahtarının yorumunu kaldırın ve COMPATIBLE'ı tanımlayın.

schemaValidation: "COMPATIBLE"

Alternatif olarak, tüm şema değişikliklerinin uygulanması ve veritabanı şemanızın uygulama şemanızla eşleşmesi için davranışı STRICT olarak ayarlayabilirsiniz.

schemaValidation: "STRICT"

Daha fazla bilgi için Data Connect KSA referansına bakın.

Bağlayıcı güncelleme

firebase deploy komutunu çalıştırdığınızda CLI, geçerli bağlayıcıların güncellenmesini başlatır ve geçerli uyarı düzeyinde (istemci davranışını etkileyebilir) ve kesinti düzeyinde (muhtemelen veya kesinlikle kesinti) değerlendirme mesajları yayınlar.

CLI ile bağlayıcı güncellemelerini yönetme

CLI'nin etkileşimli mod ve etkileşimli olmayan moddaki davranışı biraz farklıdır.

Beklediğiniz gibi, etkileşimli modda KSA tüm iletileri kabul etmenizi ister. --force işaretini kullanarak konnektör dağıtımını geçersiz kılabilir ve zorlayabilirsiniz.

# Prompts for acceptance for any warning-level or breaking-level changes prior
# to deploying connectors.
firebase deploy --only dataconnect
# Will deploy connectors without prompting.
firebase deploy --only dataconnect --force

Etkileşimli olmayan modda, CLI, önemli düzeyde değerlendirme olmadığı sürece bağlayıcınızı dağıtır. Aksi takdirde komut dosyanız, bozucu değişikliklerin günlüğünü göstererek çıkar. --force işaretini ayarlayarak geçersiz kılabilir ve dağıtabilirsiniz.

# Will deploy connectors with warning-level changes. If any breaking changes
# are present, the deploy will fail and output any breaking changes
firebase deploy --only dataconnect --non-interactive
# Will deploy the connectors from the previous step, if the same issues are present.
firebase deploy --only dataconnect --non-interactive --force

Daha fazla bilgi için CLI referans kılavuzuna bakın.

Şemaları ve bağlayıcıları yönetmeyle ilgili en iyi uygulamalar

Firebase, Data Connectprojelerinizde uygulayabileceğiniz bazı uygulamaları önerir.

Kullanıcı deneyimini bozan değişiklikleri en aza indirme

  • Firebase, Data Connect şeması ve bağlayıcı dosyalarınızı kaynak denetiminde tutmanızı önerir.
  • Mümkünse akış bozucu değişikliklerden kaçının. Kullanıcı deneyimini bozan değişikliklere örnek olarak şunlar verilebilir:
    • Bir alanı şemanızdan kaldırma
    • Şemanızdaki boş bırakılabilir bir alanı boş bırakılamaz hale getirme (ör. Int -> Int!)
    • Şemanızdaki bir alanı yeniden adlandırma
  • Şemanızdan bir alanı kaldırmanız gerekiyorsa etkiyi en aza indirmek için alanı birkaç dağıtıma ayırabilirsiniz:
    • Öncelikle bağlayıcılarınızdaki alana yapılan tüm referansları kaldırın ve değişikliği dağıtın.
    • Ardından, uygulamalarınızı yeni oluşturulan SDK'ları kullanacak şekilde güncelleyin.
    • Son olarak, şema .gql dosyanızdaki alanı kaldırın, SQL şemanızı taşıyın ve bir kez daha dağıtın.

Yeni veritabanlarıyla çalışırken katı modu kullanma

Data Connect'ü yeni bir veritabanıyla kullanıyorsanız ve uygulama şemanızı etkin bir şekilde geliştiriyorsanız ve veritabanı şemanızın uygulama şemanızı tam olarak karşıladığından emin olmak istiyorsanız dataconnect.yaml dosyanızda schemaValidation: "STRICT"'ü belirtebilirsiniz.

Bu sayede, isteğe bağlı değişikliklerin de uygulanması sağlanır.

Veritabanında üretim verileri varsa uyumlu modu kullanma

Üretim verilerini içeren bir veritabanında değişiklik yapıyorsanız mevcut verilerin silinmediğinden emin olmak için şema taşıma işlemlerinizi uyumlu modda gerçekleştirmenizi öneririz. dataconnect.yaml tarayıcınızda schemaValidation: "COMPATIBLE" belirtebilirsiniz.

Uyumlu modda, veritabanınıza yalnızca gerekli şema taşıma değişiklikleri uygulanır.

  • DROP SCHEMA, DROP TABLE ve DROP COLUMN isteğe bağlı ifadeler olarak kabul edilir ve veritabanı şemanız uygulama şemanızda tanımlanmayan şemalar, tablolar veya sütunlar içerse bile planınız için oluşturulmaz.
  • Veritabanı tablonuz, uygulama şemanıza dahil edilmeyen boş olmayan bir sütun içeriyorsa NOT NULL kısıtlaması kaldırılır. Böylece, tanımlanmış bağlayıcılarınızla tabloya veri eklemeye devam edebilirsiniz.

Sırada ne var?