Bagikan melalui

Mulai menggunakan Databricks CLI untuk Lakebase

Penting

Lakebase Autoscaling berada di Beta di wilayah berikut: eastus2, , westeuropewestus.

Lakebase Autoscaling adalah versi terbaru Lakebase dengan komputasi penskalaan otomatis, skala-ke-nol, percabangan, dan pemulihan instan. Untuk perbandingan fitur dengan Lakebase Provisioned, lihat memilih antar versi.

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

Ini menampilkan semua perintah, bendera global, dan informasi yang tersedia 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 baru:

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, br-divine-sea-y2k942xa).

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

export BRANCH_ID="br-divine-sea-y2k942xa"

Ganti br-divine-sea-y2k942xa dengan ID cabang default 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

Catat ID endpoint pada bidang name Ini akan dalam format projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}. Ekstrak ID titik akhir (misalnya, ep-plain-sunset-y2vc0zan) dan secara opsional ekspor sebagai variabel:

export ENDPOINT_ID="ep-plain-sunset-y2vc0zan"

Ganti ep-plain-sunset-y2vc0zan 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

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

Mendapatkan detail sumber daya

Dapatkan informasi terperinci tentang proyek:

databricks postgres get-project projects/$PROJECT_ID

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

Dapatkan informasi terperinci tentang cabang:

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

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

Dapatkan informasi terperinci tentang titik akhir:

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

Ini mengembalikan konfigurasi titik akhir terperinci termasuk jenis titik akhir (baca-tulis atau baca-saja), pengaturan penskalaan otomatis (unit komputasi minimum dan maksimum), status saat ini (ACTIVE, IDLE, dll.), host koneksi, waktu tunggu penangguhan, dan cap waktu pembuatan/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/br-divine-sea-y2k942xa",
      "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.

Cabang fitur memerlukan titik akhir komputasi baca-tulis untuk memungkinkan operasi database:

databricks postgres create-endpoint \
  projects/$PROJECT_ID/branches/feature \
  primary \
  --json '{
    "spec": {
      "endpoint_type": "ENDPOINT_TYPE_READ_WRITE",
      "autoscaling_limit_min_cu": 0.5,
      "autoscaling_limit_max_cu": 2.0
    }
  }'

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 ini 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.

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