Lakebase için Databricks CLI'yi kullanmaya başlama

Bu kılavuz, Lakebase projelerinizi, dallarınızı ve işlemlerinizi (uç noktalar) yönetmek için Databricks CLI ile çalışmaya başlamanıza yardımcı olur. Yalnızca birkaç komutla çalışan bir proje oluşturmayı öğreneceksiniz.

Tam komut başvurusu ve tüm kullanılabilir seçenekler için bkz. Databricks CLI postgres komutları.

Önkoşullar

• Databricks CLI: Databricks CLI'yi yükleyin. Bkz. Databricks CLI'yi yükleme.
• Çalışma alanı erişimi: Lakebase kaynağınızın bulunduğu Azure Databricks çalışma alanına erişiminiz olmalıdır.

Azure Databricks ile kimlik doğrulaması

CLI komutlarını çalıştırmadan önce Azure Databricks çalışma alanınızla kimlik doğrulaması yapın:

databricks auth login --host https://your-workspace.cloud.databricks.com

https://your-workspace.cloud.databricks.com ifadesini gerçek çalışma alanı URL'nizle değiştirin. Bu komut, OAuth kullanarak Azure Databricks hesabınızla kimlik doğrulaması yapmanız için bir tarayıcı penceresi açar.

Daha fazla kimlik doğrulama seçeneği için bkz. Databricks kimlik doğrulaması.

Komut yardımı al

CLI, tüm komutlar için yerleşik yardım sağlar. Kullanılabilir komutları ve seçenekleri görmek için kullanın --help .

Tüm Postgres komutlarına genel bakış elde edin:

databricks postgres --help

komutu kullanılabilir tüm komutları, genel bayrakları ve kaynak adlandırma kuralları hakkındaki bilgileri görüntüler.

Belirli bir komut için ayrıntılı yardım alın:

databricks postgres create-project --help

Bu, komutun amacını, gerekli ve isteğe bağlı parametrelerini, kullanım örneklerini ve kullanılabilir bayrakları gösterir.

Hızlı Başlangıç: İlk projenizi oluşturma

Dal ve işlem uç noktası ile proje oluşturmak için şu adımları izleyin:

1. Proje oluşturma

Lakebase projesi oluşturma:

databricks postgres create-project my-project \
  --json '{
    "spec": {
      "display_name": "My Lakebase Project"
    }
  }'

Bu komut bir proje oluşturur ve tamamlanmasını bekler. Proje kimliği (my-project), kaynak adının bir parçası olur: projects/my-project. Proje, otomatik olarak oluşturulan kimliklere sahip varsayılan bir üretim dalı ve okuma-yazma işlem uç noktasıyla oluşturulur.

İsteğe bağlı olarak, proje kimliğini sonraki komutlarda kullanmak üzere bir değişken olarak dışarı aktarın:

export PROJECT_ID="my-project"

2. Dal kimliğini alma

Varsayılan dal kimliğini bulmak için projenizdeki dalları listeleyin:

databricks postgres list-branches projects/$PROJECT_ID

Bu, projedeki tüm dallar hakkında bilgi döndürür. Durumunda "default": true olan dalı arayın. Alandaki dal kimliğini name not edin (örneğin, production varsayılan dal için).

İsteğe bağlı olarak, dal kimliğini sonraki komutlarda kullanmak üzere bir değişken olarak dışarı aktarın:

export BRANCH_ID="production"

Gerçek dal kimliğinizi liste çıktısından alarak production ile değiştirin.

3. Uç nokta kimliğini alma

Dalınızdaki uç noktaları listeleyin. Varsayılan dal otomatik olarak bir okuma-yazma uç noktası içerir:

databricks postgres list-endpoints projects/$PROJECT_ID/branches/$BRANCH_ID

Alanındaki uç nokta kimliğini name not edin (örneğin, primary varsayılan okuma-yazma uç noktası için). İsteğe bağlı olarak değişken olarak dışarı aktarın:

export ENDPOINT_ID="primary"

Liste çıktısında bulunan gerçek uç nokta kimliğinizle primary değerini değiştirin.

4. Veritabanı kimlik bilgileri oluşturma

Veritabanınıza bağlanmak için kimlik bilgileri oluşturun:

databricks postgres generate-database-credential \
  projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID

Komut, Databricks kimliğinizi kullanarak verilerinize erişmek gibi psql PostgreSQL istemcileri ile kullanabileceğiniz bir OAuth belirteci döndürür. psql ile bağlanma hakkında adım adım yönergeler için bkz. psql ile bağlanma. Belirteç süre sonu ve kimlik doğrulaması hakkında daha fazla bilgi için bkz. Kimlik doğrulaması.

Projeleri yönetme

Projeleri listeleme

Çalışma alanınızdaki tüm projeleri listeleyin:

databricks postgres list-projects

Komut her projenin adını, görünen adını, geçerli durumunu ve zaman damgalarını döndürür.

Proje ayrıntılarını alma

Proje hakkında ayrıntılı bilgi edinin:

databricks postgres get-project projects/$PROJECT_ID

Komut, projenin görünen adını, PostgreSQL sürümünü, sahibini, geçmiş saklama süresini, dal boyutu sınırlarını, depolama boyutunu ve zaman damgalarını döndürür.

Şubeleri Yönet

Dal ayrıntılarını alma

Dal hakkında ayrıntılı bilgi edinin:

databricks postgres get-branch projects/$PROJECT_ID/branches/$BRANCH_ID

Komut dalın geçerli durumunu, koruma durumunu, mantıksal boyutunu, kaynak dal ayrıntılarını (varsa) ve zaman damgalarını döndürür.

Özellik dalı oluşturma

Değişiklikleri test etmek için var olan bir dalı temel alan yeni bir dal oluşturun. belirttiğinizde source_branch, yeni dal oluşturma sırasında kaynak dal ile aynı şemaya ve verilere sahip olur. Proje ve dal kimliklerini gerçek değerlerinizle değiştirin:

databricks postgres create-branch \
  projects/my-project \
  feature \
  --json '{
    "spec": {
      "source_branch": "projects/my-project/branches/production",
      "no_expiry": true
    }
  }'

Lakebase, birincil okuma-yazma işlem uç noktasıyla özellik dalını otomatik olarak oluşturur. Özellik dalında geliştirme ve test işlemini tamamladıktan sonra silebilirsiniz:

databricks postgres delete-branch projects/$PROJECT_ID/branches/feature

Dal korumasını güncelleştirme

Güncelleştirme maskesi desenini kullanarak bir kaynağı güncelleştirin. Güncelleştirme maskesi hangi alanların güncelleştirilecek olduğunu belirtir:

databricks postgres update-branch \
  projects/$PROJECT_ID/branches/$BRANCH_ID \
  spec.is_protected \
  --json '{
    "spec": {
      "is_protected": true
    }
  }'

Bu örnek spec.is_protected öğesini true olarak ayarlar ve dalı korumalı hale getirir. Güncelleştirme maskesi (spec.is_protected), API'ye hangi alanın güncelleştirilecek olduğunu bildirir. komutu, yeni değeri ve güncelleştirilmiş bir zaman damgasını gösteren güncelleştirilmiş update_time kaynağı döndürür.

Hesaplama kaynaklarını yönetme

Hesaplama ayrıntılarını al

Uç nokta hakkında ayrıntılı bilgi edinin:

databricks postgres get-endpoint projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID

Komut uç nokta türünü, otomatik ölçeklendirme ayarlarını, geçerli durumu, bağlantı ana bilgisayarını, askıya alma zaman aşımını ve zaman damgalarını döndürür.

Okuma çoğaltmalarıyla okumaları ölçeklendirme

Artan okuma trafiğini işlemek için okuma replikaları ekleyin. Aşağıdaki örnek, varsayılan üretim dalı için bir okuma replikası ekler:

databricks postgres create-endpoint \
  projects/$PROJECT_ID/branches/$BRANCH_ID \
  read-replica-1 \
  --json '{
    "spec": {
      "endpoint_type": "ENDPOINT_TYPE_READ_ONLY",
      "autoscaling_limit_min_cu": 0.5,
      "autoscaling_limit_max_cu": 4.0
    }
  }'

Okuma iş yüklerini dağıtmak için farklı uç nokta kimlikleriyle (read-replica-1, read-replica-2 gibi) birden fazla okuma replikası oluşturabilirsiniz.

Otomatik ölçeklendirme sınırlarını güncelleştirme

Birden çok alanı güncelleştirmek için virgülle ayrılmış bir liste kullanın:

databricks postgres update-endpoint \
  projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID \
  "spec.autoscaling_limit_min_cu,spec.autoscaling_limit_max_cu" \
  --json '{
    "spec": {
      "autoscaling_limit_min_cu": 1.0,
      "autoscaling_limit_max_cu": 8.0
    }
  }'

Ölçeği sıfır olarak yapılandırma

Ölçeği sıfır olarak yapılandırmak için güncelleştirme maskesine ekleyin spec.suspension . Etkin olmama zaman aşımını tanımlamak için `suspend_timeout_duration` değerini (60s–604800s) olarak ayarlayın veya devre dışı bırakmak için `no_suspension: true` değerini ayarlayın. İkisini de ayarlamayın. Ayar no_suspension: false geçersiz ve hata döndürüyor. Varsayılan olarak, production dalında 24 saatlik zaman aşımı ile sıfıra ölçeklendirme etkindir.

# Disable scale to zero (compute stays active indefinitely)
databricks postgres update-endpoint \
  projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID \
  spec.suspension \
  --json '{
    "spec": {
      "no_suspension": true
    }
  }'

# Enable scale to zero with a 5-minute inactivity timeout (60s–604800s)
databricks postgres update-endpoint \
  projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID \
  spec.suspension \
  --json '{
    "spec": {
      "suspend_timeout_duration": "300s"
    }
  }'

Rolleri yönetme

Bir dal içinde veritabanı erişimi için Postgres rolleri oluşturmak ve yönetmek için CLI'yi kullanın. Rol türleri ve kimlik doğrulaması hakkında ayrıntılı yönergeler için bkz. Postgres rolleri oluşturma.

Rol oluşturma

Parola tabanlı rol oluşturma:

databricks postgres create-role projects/$PROJECT_ID/branches/$BRANCH_ID \
  --role-id my-app-role \
  --json '{"spec": {"postgres_role": "my-app-role"}}'

Azure Databricks kimliğine bağlı bir OAuth rolü oluşturun:

# For a user:
databricks postgres create-role projects/$PROJECT_ID/branches/$BRANCH_ID \
  --role-id my-user-role \
  --json '{"spec": {"identity_type": "USER", "postgres_role": "user@example.com"}}'

# For a service principal:
databricks postgres create-role projects/$PROJECT_ID/branches/$BRANCH_ID \
  --role-id my-sp-role \
  --json '{"spec": {"identity_type": "SERVICE_PRINCIPAL", "postgres_role": "<sp-client-id>"}}'

Rolleri listele ve al

Daldaki tüm rolleri listeleme:

databricks postgres list-roles projects/$PROJECT_ID/branches/$BRANCH_ID

Belirli bir rolle ilgili ayrıntıları alın:

databricks postgres get-role projects/$PROJECT_ID/branches/$BRANCH_ID/roles/$ROLE_ID

Yanıt, güncelleştirme ve silme çağrıları için gereken sistem tarafından oluşturulan rol kaynak adını (örneğin, rol-xxxx-xxxxxxxxxx) içerir.

Rolü güncelleştirme

Güncelleştirme maskesi desenini kullanarak bir rolü güncelleştirin. Güncelleştirme maskesini ikinci konumsal bağımsız değişken olarak geçirin.

güncelleştirirken spec.attributesüç öznitelik alanının tümünü sağlamanız gerekir; API, öznitelik nesnesinin tamamının yerini alır:

databricks postgres update-role \
  projects/$PROJECT_ID/branches/$BRANCH_ID/roles/$ROLE_ID \
  "spec.attributes" \
  --json '{"spec": {"attributes": {"createdb": true, "createrole": false, "bypassrls": false}}}'

Rol silme

databricks postgres delete-role projects/$PROJECT_ID/branches/$BRANCH_ID/roles/$ROLE_ID

Rol veritabanı nesnelerine sahipse, silmeden önce sahipliği aktarmak için kullanın --reassign-owned-to :

databricks postgres delete-role \
  projects/$PROJECT_ID/branches/$BRANCH_ID/roles/$ROLE_ID \
  --reassign-owned-to projects/$PROJECT_ID/branches/$BRANCH_ID/roles/$OTHER_ROLE_ID

Eşitlenmiş tabloları yönetme

Eşitlenen tablolar, düşük gecikmeli işlem okumaları için Unity Kataloğu verilerini Lakebase veritabanınıza çoğaltır. {catalog}.{schema}.{table} kimliğiyle create-synced-table kullanın:

databricks postgres create-synced-table my-catalog.sales.orders \
  --json '{
    "spec": {
      "source_table_full_name": "main.sales.orders",
      "branch": "projects/my-project/branches/production",
      "primary_key_columns": ["order_id"],
      "scheduling_policy": "SNAPSHOT",
      "postgres_database": "databricks_postgres",
      "create_database_objects_if_missing": true
    }
  }'

Eşitlenen tablo kimliği hem Unity Kataloğu varlık adı olur hem de Postgres tablosunu tanımlar. Durumu alın ve aynı kimlik biçimine sahip eşitlenmiş bir tabloyu silin:

# Check status
databricks postgres get-synced-table "synced_tables/my-catalog.sales.orders"

# Delete
databricks postgres delete-synced-table "synced_tables/my-catalog.sales.orders"

create-synced-table ve create-catalog uzun süre çalışan işlemlerdir. Varsayılan olarak, CLI tamamlanmasını bekler. Hemen geri dönmek için --no-wait veya özel bir bekleme süresi ayarlamak için --timeout kullanın. Bkz. Uzun süre çalışan işlemler.

Eşitleme modları, veri türü eşlemesi ve kapasite planlaması hakkında ayrıntılı yönergeler için bkz. Eşitlenmiş tablolarla lakehouse verilerini sunma.

Temel kavramları anlama

Uzun süreli işlemler

Oluşturma, güncelleştirme ve silme komutları uzun süre çalışan işlemlerdir. Varsayılan olarak, CLI işlemin tamamlanmasını bekler. Hemen dönmek ve durumu ayrı ayrı yoklamak için kullanın --no-wait :

databricks postgres create-project $PROJECT_ID \
  --json '{"spec": {"display_name": "My Project"}}' \
  --no-wait

İşlem durumunu yoklama:

databricks postgres get-operation projects/$PROJECT_ID/operations/operation-id

Kaynak adlandırma

Lakebase hiyerarşik kaynak adlarını kullanır:

• Projeler: projects/{project_id}. Proje oluştururken proje kimliğini belirtirsiniz.
• Şubeler: projects/{project_id}/branches/{branch_id}. Dal oluştururken dal kimliğini belirtirsiniz.
• Uç noktalar: projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}. Uç nokta oluştururken uç nokta kimliğini (veya gibi primaryread-replica-1) belirtirsiniz.

Kimlikler 1-63 karakter uzunluğunda olmalı, küçük harfle başlamalıdır ve yalnızca küçük harf, sayı ve kısa çizgi içermelidir.

Maskeleri güncelleştirme

Güncelleştirme komutları, değiştirileceği alanları belirten bir güncelleştirme maskesi gerektirir. Maske, birden çok alan için veya virgülle ayrılmış liste gibi spec.display_name bir alan yoludur.

Yük, --json bu alanların yeni değerlerini içerir. Yalnızca güncelleştirme maskesinde listelenen alanlar değiştirilir.

Ek kaynaklar

• Databricks CLI postgres komutları referansı
• Postgres rolleri oluşturma
• psql ile bağlanma
• Şubeleri Yönet
• Otomatik ölçeklendirmeyi yapılandırma
• Eşitlenmiş tablolarla göl evi verilerini sunma