Mulai menggunakan Databricks CLI untuk Lakebase

Penting

Lakebase Autoscaling adalah versi terbaru Lakebase, dengan komputasi penskalaan otomatis, skala-ke-nol, percabangan, dan pemulihan instan. Untuk wilayah yang didukung, lihat Ketersediaan wilayah. Jika Anda adalah pengguna Lakebase Provisioned, lihat Lakebase Provisioned.

Panduan ini membantu Anda memulai Databricks CLI untuk mengelola proyek, cabang, dan komputasi Lakebase Anda (titik akhir). Anda akan mempelajari cara membuat proyek kerja hanya dalam beberapa perintah.

Untuk referensi perintah lengkap dan semua opsi yang tersedia, lihat Perintah postgres CLI Databricks.

Prasyarat

  • Databricks CLI: Instal Databricks CLI. Lihat Menginstal Databricks CLI.
  • Akses ruang kerja: Anda harus memiliki akses ke ruang kerja Azure Databricks tempat sumber daya Lakebase Anda berada.

Mengautentikasi dengan Azure Databricks

Sebelum menjalankan perintah CLI apa pun, autentikasi dengan ruang kerja Azure Databricks Anda:

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

Ganti https://your-workspace.cloud.databricks.com dengan URL ruang kerja Anda yang sebenarnya. Perintah ini membuka jendela browser bagi Anda untuk mengautentikasi dengan akun Azure Databricks Anda menggunakan OAuth.

Nota

Jika Anda memiliki beberapa profil, gunakan --profile bendera untuk menentukan profil mana yang akan digunakan: databricks postgres <command> --profile my-profile. Untuk melihat profil yang dikonfigurasi, jalankan databricks auth profiles.

Untuk opsi autentikasi lainnya, lihat Autentikasi Databricks.

Minta bantuan perintah

CLI menyediakan bantuan bawaan untuk semua perintah. Gunakan --help untuk melihat perintah dan opsi yang tersedia.

Dapatkan gambaran umum semua perintah Postgres:

databricks postgres --help

Perintah menampilkan semua perintah yang tersedia, bendera global, dan informasi tentang konvensi penamaan sumber daya.

Dapatkan bantuan terperinci untuk perintah tertentu:

databricks postgres create-project --help

Ini menunjukkan tujuan perintah, parameter yang diperlukan dan opsional, contoh penggunaan, dan bendera yang tersedia.

Mulai cepat: Membuat proyek pertama Anda

Ikuti langkah-langkah ini untuk membuat proyek kerja lengkap dengan cabang dan titik akhir komputasi:

1. Buat proyek

Buat proyek Lakebase:

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

Perintah ini membuat proyek dan menunggunya selesai. ID proyek (my-project) menjadi bagian dari nama sumber daya: projects/my-project. Proyek ini dibuat dengan cabang produksi bawaan dan titik akhir komputasi baca-tulis, keduanya dengan ID yang dihasilkan secara otomatis.

Secara opsional, ekspor ID proyek sebagai variabel untuk digunakan dalam perintah berikutnya:

export PROJECT_ID="my-project"

2. Dapatkan ID cabang

Cantumkan cabang di proyek Anda untuk menemukan ID cabang default:

databricks postgres list-branches projects/$PROJECT_ID

Ini mengembalikan informasi tentang semua cabang dalam proyek. Cari cabang dengan "default": true pada statusnya. Perhatikan ID cabang dari name bidang (misalnya, production untuk cabang default).

Secara opsional ekspor ID cabang sebagai variabel untuk digunakan dalam perintah berikutnya:

export BRANCH_ID="production"

Ganti production dengan ID cabang aktual Anda dari output daftar.

3. Dapatkan ID titik akhir

Cantumkan titik akhir di cabang Anda. Cabang utama secara otomatis menyertakan titik akhir baca-tulis.

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

Perhatikan ID titik akhir dari name bidang (misalnya, primary untuk titik akhir baca-tulis default). Secara opsional mengekspornya sebagai variabel:

export ENDPOINT_ID="primary"

Ganti primary dengan ID titik akhir aktual Anda dari output daftar.

4. Hasilkan kredensial database

Buat kredensial untuk menyambungkan ke database Anda:

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

Perintah mengembalikan token OAuth yang dapat Anda gunakan dengan klien PostgreSQL seperti psql mengakses data Anda menggunakan identitas Databricks Anda. Untuk instruksi langkah demi langkah tentang menyambungkan dengan psql, lihat Menyambungkan dengan psql. Untuk informasi selengkapnya tentang kedaluwarsa dan autentikasi token, lihat Autentikasi.

Mengelola sumber daya Anda

Mencantumkan semua proyek

Cantumkan semua proyek di ruang kerja Anda:

databricks postgres list-projects

Perintah mengembalikan informasi tentang setiap proyek, termasuk nama, nama tampilan, dan status saat ini. Ini juga termasuk pembuatan dan pembaruan tanda waktu.

Mendapatkan detail sumber daya

Dapatkan informasi terperinci tentang proyek:

databricks postgres get-project projects/$PROJECT_ID

Perintah mengembalikan konfigurasi proyek terperinci, termasuk nama tampilan, versi PostgreSQL, pemilik, dan periode retensi riwayat. Ini juga mencakup batas ukuran cabang, pengaturan titik akhir default, ukuran penyimpanan, dan tanda waktu pembuatan dan pembaruan.

Dapatkan informasi terperinci tentang cabang:

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

Perintah mengembalikan informasi cabang terperinci, termasuk status saat ini, status cabang default, status perlindungan, dan ukuran logis. Ini juga mencakup detail cabang sumber (jika bercabang dari cabang lain) serta tanda waktu pembuatan dan pembaruan.

Dapatkan informasi terperinci tentang titik akhir:

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

Perintah mengembalikan konfigurasi titik akhir terperinci, termasuk jenis titik akhir (baca-tulis atau baca-saja), pengaturan penskalaan otomatis (unit komputasi minimum dan maksimum), dan status saat ini (ACTIVE, IDLE, dan sebagainya). Ini juga mencakup host koneksi, waktu habis tunda, dan tanda waktu pembuatan dan pembaruan.

Memperbarui sumber daya

Perbarui sumber daya menggunakan pola masker pembaruan. Masker pembaruan menentukan bidang mana yang akan diperbarui:

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

Contoh ini mengatur spec.is_protected ke true, menjadikan cabang terlindungi. Masker pembaruan (spec.is_protected) memberi tahu API bidang mana yang akan diperbarui. Perintah mengembalikan sumber daya yang diperbarui yang menunjukkan nilai baru dan tanda waktu yang diperbarui update_time .

Untuk memperbarui beberapa bidang, gunakan daftar yang dipisahkan koma:

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
    }
  }'

Alur kerja umum

Buat cabang fitur dari cabang produksi

Buat cabang baru berdasarkan cabang yang ada untuk menguji perubahan. Ketika Anda menentukan source_branch, cabang baru akan memiliki skema dan data yang sama dengan cabang sumber pada saat pembuatan. Ganti ID proyek dan cabang dengan nilai aktual Anda:

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

Nota

Saat membuat cabang, Anda harus menentukan kebijakan kedaluwarsa. Gunakan no_expiry: true untuk membuat cabang permanen.

Untuk menggunakan variabel shell di dalam spesifikasi JSON (seperti $PROJECT_ID atau $BRANCH_ID), Anda harus menggunakan tanda kutip ganda untuk --json nilai dan menghindari tanda kutip internal.

Lakebase secara otomatis membuat cabang fitur dengan titik akhir komputasi baca-tulis utama. Setelah menyelesaikan pengembangan dan pengujian di cabang fitur, Anda dapat menghapusnya:

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

Nota

Perintah penghapusan segera kembali, tetapi penghapusan aktual mungkin membutuhkan waktu untuk diselesaikan. Anda dapat memverifikasi penghapusan dengan menjalankan perintah dapatkan sumber daya yang sesuai, yang mengembalikan kesalahan setelah sumber daya dihapus sepenuhnya.

Meningkatkan pembacaan dengan replika pembacaan

Tambahkan replika baca untuk menangani peningkatan lalu lintas baca. Contoh berikut menambahkan replika baca ke cabang produksi default:

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
    }
  }'

Anda dapat membuat beberapa replika baca dengan ID titik akhir yang berbeda (read-replica-1, , read-replica-2dll.) untuk mendistribusikan beban kerja baca.

Mengelola peran

Gunakan CLI untuk membuat dan mengelola peran Postgres untuk akses database dalam cabang. Untuk panduan terperinci tentang jenis peran dan autentikasi, lihat Membuat peran Postgres.

Membuat peran

Buat peran berbasis kata sandi:

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

Buat peran OAuth yang terkait dengan identitas Azure Databricks:

# 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>"}}'

Mendaftar dan mengambil peran

Mencantumkan semua peran dalam cabang:

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

Dapatkan detail tentang peran tertentu:

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

Respons mencakup nama sumber daya peran yang dihasilkan sistem (misalnya, rol-xxxx-xxxxxxxxxx) yang diperlukan untuk memperbarui dan menghapus panggilan.

Memperbarui peran

Perbarui peran menggunakan pola perbarui masker. Teruskan update mask sebagai argumen posisi kedua.

Saat memperbarui spec.attributes, Anda harus menyediakan ketiga bidang atribut — API menggantikan seluruh objek atribut:

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

Menghapus peran

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

Jika peran memiliki objek database, gunakan --reassign-owned-to untuk mentransfer kepemilikan sebelum penghapusan:

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

Memahami konsep utama

Operasi jangka panjang

Perintah buat, perbarui, dan hapus adalah operasi yang memakan waktu lama. Secara default, CLI menunggu operasi selesai. Gunakan --no-wait untuk segera mengembalikan dan memeriksa status secara terpisah.

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

Periksa status operasi:

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

Penamaan sumber daya

Lakebase menggunakan nama sumber daya hierarkis:

  • Proyek: projects/{project_id}. Anda menentukan ID proyek saat membuat proyek.
  • Cabang: projects/{project_id}/branches/{branch_id}. Anda menentukan ID cabang saat membuat cabang.
  • Titik akhir: projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}. Anda menentukan ID titik akhir (seperti primary atau read-replica-1) saat membuat titik akhir.

ID harus panjangnya 1-63 karakter, dimulai dengan huruf kecil, dan hanya berisi huruf kecil, angka, dan tanda hubung.

Memperbarui masker

Perintah pembaruan memerlukan masker pembaruan yang menentukan bidang mana yang akan diubah. Masker adalah jalur bidang seperti spec.display_name atau daftar yang dipisahkan koma untuk beberapa bidang.

Payload --json berisi nilai baru untuk bidang tersebut. Hanya bidang yang tercantum dalam masker pembaruan yang dimodifikasi.

Langkah selanjutnya

  • Last updated on