Migrasi CLI Databricks

Artikel ini menjelaskan cara bermigrasi dari Databricks CLI versi 0.18 atau di bawahnya ke Databricks CLI versi 0.205 atau lebih tinggi. Databricks CLI versi 0.205 ke atas berada di Pratinjau Umum.

Untuk singkatnya, artikel ini mengacu pada Databricks CLI versi 0.18 ke bawah sebagai CLI "lama", dan Databricks CLI versi 0.205 ke atas sebagai CLI "baru".

Untuk informasi lebih lanjut tentang CLI lama dan baru, lihat:

Legacy Databricks CLI untuk versi CLI terdahulu.
Databricks CLI untuk CLI baru.

Copot pemasangan CLI versi lama

Jika Anda telah menginstal CLI warisan dan ingin menghapus instalannya, gunakan pip (atau pip3, tergantung pada versi Python Anda) untuk menjalankan perintah uninstall, sebagai berikut:

pip uninstall databricks-cli

Menginstal CLI baru

Untuk mempelajari cara menginstal CLI baru, lihat Menginstal atau memperbarui Databricks CLI.

Memverifikasi penginstalan CLI Anda

Jika Anda tidak yakin apakah Anda menggunakan CLI baru, ikuti instruksi di bagian ini untuk memverifikasi dan menyesuaikan sesuai kebutuhan. Sebelum Anda mengikuti instruksi ini, pastikan untuk keluar dari lingkungan virtual Python, lingkungan conda, atau lingkungan serupa.

Untuk memeriksa versi penginstalan default CLI Anda, jalankan perintah berikut:

databricks -v

Jika nomor versi bukan yang Anda harapkan, lakukan salah satu hal berikut:

Jika Anda hanya ingin menggunakan satu versi CLI: hapus instalan semua versi CLI sebelumnya yang tidak ingin Anda gunakan lagi. Anda mungkin perlu memperbarui sistem PATH operasi Anda sehingga jalur ke versi CLI yang tersisa yang ingin Anda gunakan tercantum.
Jika Anda ingin terus menggunakan beberapa versi CLI: prepend jalur lengkap ke versi CLI yang ingin Anda gunakan untuk masing-masing dan setiap panggilan ke CLI.
Jika Anda ingin terus menggunakan beberapa versi CLI, tetapi Anda tidak ingin terus menambahkan jalur lengkap ke versi CLI yang paling sering Anda gunakan: pastikan bahwa jalur lengkap ke versi tersebut tercantum terlebih dahulu di sistem PATHoperasi Anda. Perhatikan bahwa Anda masih harus menambahkan jalur lengkap ke versi CLI yang tidak tercantum terlebih dahulu di sistem operasi PATH Anda.

Untuk memperbarui sistem PATHoperasi Anda, lakukan hal berikut:

MacOS atau Linux

Cantumkan jalur tempat databricks diinstal dengan menjalankan salah satu perintah berikut:
```
which -a databricks

# Or:
where databricks
```
Dapatkan jalur menuju instalasi yang ingin Anda gunakan tanpa menambahkan seluruh jalur ke setiap panggilan ke CLI. Jika Anda tidak yakin jalur mana ini, jalankan jalur lengkap ke setiap lokasi, diikuti oleh -v, misalnya:
```
/usr/local/bin/databricks -v
```
Untuk menempatkan jalur ke penginstalan yang ingin Anda gunakan terlebih dahulu di PATH, jalankan perintah berikut, dan ganti /usr/local/bin dengan jalur yang ingin Anda gunakan. Jangan tambahkan databricks ke akhir jalur ini. Contohnya:
```
export PATH="/usr/local/bin:$PATH"
```
Untuk memverifikasi bahwa PATH telah diatur dengan benar untuk sesi terminal saat ini, jalankan databricks diikuti dan -v periksa nomor versi:
```
databricks -v
```
Untuk menyetel PATH dengan cara ini setiap kali Anda menghidupkan ulang terminal, tambahkan perintah dari langkah 3 ke berkas inisialisasi shell Anda. Misalnya, untuk Zshell, file ini biasanya terletak di ~/.zshrc. Untuk Bash, file ini biasanya terletak di ~/.bashrc. Untuk shell lain, lihat dokumentasi penyedia shell Anda.
Setelah memperbarui file inisialisasi shell, Anda harus memulai ulang terminal untuk menerapkan nilai yang diperbarui PATH .

Windows

Klik kanan pada penginstalan databricks yang ingin Anda gunakan tanpa menambahkan jalur lengkap ke setiap panggilan ke CLI.
Klik Buka lokasi file.
Perhatikan jalur ke databricks, misalnya C:\Windows.
Pada menu Mulai , cari variabel Lingkungan.
Klik Edit variabel lingkungan untuk akun Anda.
Pilih variabel Jalur di bagian Variabel pengguna untuk <username>.
Klik Sunting.
Klik Baru.
Masukkan jalur yang ingin Anda tambahkan, tanpa databricks.exe (seperti C:\Windows).
Gunakan tombol Pindah ke Atas untuk memindahkan jalur yang baru saja Anda tambahkan ke awal daftar.
Klik OK.
Untuk memverifikasi bahwa PATH telah diatur dengan benar, buka Prompt Perintah baru, jalankan databricks diikuti oleh -v, dan periksa nomor versi:
```
databricks -v
```

Gunakan jenis autentikasi tambahan

CLI warisan dan CLI baru kedua-duanya mendukung autentikasi token akses pribadi di Azure Databricks. Namun, Databricks merekomendasikan agar Anda menggunakan jenis autentikasi Azure Databricks lainnya jika memungkinkan, yang hanya didukung CLI baru.

Jika Anda harus menggunakan autentikasi token akses pribadi Azure Databricks, Databricks menyarankan agar Anda menggunakan yang terkait dengan perwakilan layanan, bukan akun Azure Databricks atau pengguna ruang kerja. Lihat Service principals.

CLI baru mendukung token Microsoft Entra ID selain token akses pribadi Azure Databricks. Token tambahan ini lebih aman karena biasanya kedaluwarsa dalam satu jam, sedangkan Azure Databricks token akses pribadi dapat berlaku dari satu hari hingga tanpa batas waktu. Ini sangat penting jika token secara tidak sengaja diperiksa ke dalam sistem kontrol versi yang dapat diakses oleh orang lain. Selain itu, CLI baru dapat secara otomatis me-refresh token tambahan ini saat kedaluwarsa, sedangkan me-refresh token akses pribadi Azure Databricks adalah proses manual atau sulit untuk diotomatisasi.

Untuk informasi selengkapnya, lihat Autentikasi untuk Databricks CLI.

Grup perintah dan perbandingan perintah

Tabel berikut mencantumkan grup perintah CLI warisan dan grup perintah CLI baru yang setara. Jika ada perbedaan signifikan antara CLI, tabel tambahan mencantumkan perintah atau opsi CLI warisan dan perintah atau opsi CLI baru yang setara.

Grup perintah

Grup perintah purnabakti	Grup perintah baru
`cluster-policies`	`cluster-policies`. Semua nama perintah sama.
`clusters`	`clusters`. Semua nama perintah sama.
`configure`	`configure`. Lihat `configure` opsi.
`fs`	`fs`. Lihat `fs` perintah.
`groups`	`groups`. Lihat `groups` perintah.
`instance-pools`	`instance-pools`. Semua nama perintah sama.
`jobs`	`jobs`. Semua nama perintah sama.
`libraries`	`libraries`. Semua nama perintah sama kecuali untuk `list`. Perintah `list` tidak lagi tersedia; gunakan perintah `all-cluster-statuses` atau `cluster-status` sebagai gantinya.
`pipelines`	`pipelines`. Lihat `pipelines` perintah.
`repos`	`repos`. Semua nama perintah sama.
`runs`	`jobs`. Lihat `runs` perintah.
`secrets`	`secrets`. Lihat `secrets` perintah.
`stack`	Tidak tersedia di CLI baru. Databricks merekomendasikan agar Anda menggunakan penyedia Databricks Terraform sebagai gantinya.
`tokens`	`tokens`. Lihat `tokens` perintah.
`unity-catalog`	Bermacam-macam. Lihat `unity-catalog` grup perintah.
`workspace`	`workspace`. Lihat `workspace` perintah.

Opsi `configure`

Opsi lama	Opsi baru
`-o`	CLI warisan menggunakan `-o` untuk autentikasi OAuth. CLI baru menggunakan `-o` kembali untuk menentukan apakah output CLI dalam format teks atau JSON. Tidak berlaku untuk Azure Databricks.
`--oauth`	Tidak berlaku untuk Azure Databricks.
`-s` atau `--scope`	Tidak berlaku untuk Azure Databricks.
`-t` atau `--token`	`-t` atau `--token` (sama)
`-f` atau `--token-file`	Tidak tersedia di CLI baru.
`--host`	`--host` (sama)
`--aad-token`	Gunakan `--host` dan tentukan token Microsoft Entra ID saat diminta alih-alih token akses pribadi Azure Databricks.
`--insecure`	Tidak tersedia di CLI baru.
`--jobs-api-version`	Tidak tersedia di CLI baru. CLI baru hanya menggunakan Jobs API 2.1. Untuk memanggil Jobs API 2.0 warisan, gunakan CLI warisan dan lihat Jobs CLI (warisan).
`--debug`	Untuk penelusuran kesalahan dan pencatatan log pada CLI baru, lihat Mode debug.
`--profile`	`--profile` (sama) atau `-p`
`-h` atau `--help`	`-h` atau `--help` (sama)

`fs` Perintah

Semua fs perintah dalam CLI warisan sama di CLI baru, kecuali fs mv yang tidak tersedia di CLI baru.

Perintah lama	Perintah baru
`fs cat`	`fs cat` (sama)
`fs cp`	`fs cp` (sama)
`fs ls`	`fs ls` (sama)
`fs mkdirs`	`fs mkdir`
`fs mv`	Tidak tersedia di CLI baru.
`fs rm`	`fs rm` (sama)

`groups` Perintah

Perintah lama	Perintah baru
`groups add-member`	`groups patch`
`groups create`	`groups create` (sama)
`groups delete`	`groups delete` (sama)
`groups list`	`groups list` (sama)
`groups list-members`	`groups list`
`groups list-parents`	`groups list`
`groups remove-member`	`groups patch`

`pipelines` Perintah

Perintah lama	Perintah baru
`pipelines create`	`pipelines create` (sama)
`pipelines delete`	`pipelines delete` (sama)
`pipelines deploy`	`pipelines create`
`pipelines edit`	`pipelines update`
`pipelines get`	`pipelines get` (sama)
`pipelines list`	`pipelines list-pipeline-events` atau `pipelines list-pipelines` atau `pipelines list-updates`
`pipelines reset`	`pipelines reset` (sama)
`pipelines start`	`pipelines start update`
`pipelines stop`	`pipelines stop` (sama)
`pipelines update`	`pipelines update` (sama)

`runs` Perintah

Perintah lama	Perintah baru
`runs cancel`	`jobs cancel-run`
`runs get`	`jobs get-run`
`runs get-output`	`jobs get-run-output`
`runs list`	`jobs list-runs`
`runs submit`	`jobs submit`

`secrets` Perintah

Perintah lama	Perintah baru
`secrets create-scope`	`secrets create-scope` (sama)
`secrets delete`	`secrets delete-secret`
`secrets delete-acl`	`secrets delete-acl` (sama)
`secrets delete-scope`	`secrets delete-scope` (sama)
`secrets get-acl`	`secrets get-acl` (sama)
`secrets list`	`secrets list-secrets`
`secrets list-acls`	`secrets list-acls` (sama)
`secrets list-scopes`	`secrets list-scopes` (sama)
`secrets put`	`secrets put-secret`
`secrets put-acl`	`secrets put-acl` (sama)
`secrets write`	`secrets put-secret`
`secrets write-acl`	`secrets put-acl`

`tokens` Perintah

Perintah lama	Perintah baru
`tokens create`	`tokens create` (sama)
`tokens list`	`tokens list` (sama)
`tokens revoke`	`tokens delete`

`unity-catalog` grup perintah

unity-catalog <command> di CLI lama menjadi hanya <command> di CLI baru.

Grup perintah purnabakti	Grup perintah baru
`unity-catalog catalogs`	`catalogs` (sama tapi hilangkan `unity-catalog`)
`unity-catalog external-locations`	`external-locations` (sama tapi hilangkan `unity-catalog`)
`unity-catalog lineage`	Tidak tersedia di CLI baru. Lihat Menampilkan silsilah data menggunakan Katalog Unity.
`unity-catalog metastores`	`metastores` (sama tapi hilangkan `unity-catalog`)
`unity-catalog permissions`	`grants`
`unity-catalog providers`	`providers` (sama tapi hilangkan `unity-catalog`)
`unity-catalog recipients`	`recipients` (sama tapi hilangkan `unity-catalog`)
`unity-catalog schemas`	`schemas` (sama tapi hilangkan `unity-catalog`)
`unity-catalog shares`	`shares` (sama tapi hilangkan `unity-catalog`)
`unity-catalog storage-credentials`	`storage-credentials` (sama tapi hilangkan `unity-catalog`)
`unity-catalog tables`	`tables` (sama tapi hilangkan `unity-catalog`)

`workspace` Perintah

Perintah lama	Perintah baru
`workspace delete`	`workspace delete` (sama)
`workspace export`	`workspace export` (sama)
`workspace export-dir`	`workspace export`
`workspace import`	`workspace import` (sama)
`workspace import-dir`	`workspace import`
`workspace list`	`workspace list` (sama)
`workspace ls`	`workspace list`
`workspace mkdirs`	`workspace mkdirs` (sama)
`workspace rm`	`workspace delete`

Argumen bawaan dan posisional

Sebagian besar perintah CLI baru memiliki setidaknya satu argumen default yang tidak memiliki opsi yang menyertainya. Beberapa perintah CLI baru memiliki dua argumen posisi atau lebih yang harus ditentukan dalam urutan tertentu dan yang tidak memiliki opsi yang menyertainya. Ini berbeda dari CLI lama, di mana sebagian besar perintah memerlukan agar opsi ditentukan untuk semua argumen. Misalnya, perintah CLI clusters get baru mengambil ID kluster sebagai argumen default. Namun, perintah warisan CLI clusters get mengharuskan Anda untuk menentukan opsi --cluster-id dengan ID kluster. Contohnya:

Untuk CLI versi lama:

# This works with the legacy CLI.
databricks clusters get --cluster-id 1234-567890-a1b23c4d

# This does **not** work with the legacy CLI - "Error:
#   Missing None. One of ['cluster-id', 'cluster-name'] must be provided."
databricks clusters get 1234-567890-a1b23c4d

Untuk CLI yang baru:

# This works with the new CLI.
databricks clusters get 1234-567890-a1b23c4d

# This does **not** work with the new CLI - "Error: unknown flag: --cluster-id"
databricks clusters get --cluster-id 1234-567890-a1b23c4d

Sebagai contoh lain, perintah baru CLI grants get mengambil dua argumen default: tipe yang dapat diamankan diikuti dengan nama lengkap yang dapat diamankan. Namun, perintah warisan CLI unity-catalog permissions get mengharuskan Anda menentukan opsi --<securable-type> bersama dengan nama lengkap objek. Contohnya:

Untuk CLI versi lama:

databricks unity-catalog permissions get --schema main.default

Untuk CLI yang baru:

# This works with the new CLI.
databricks grants get schema main.default

# This does **not** work with the new CLI - "Error: unknown flag: --schema"
databricks grants get --schema main.default

Mode debug

CLI warisan menyediakan --debug opsi untuk menampilkan jejak kesalahan lengkap ketika terjadi kesalahan. Untuk CLI baru, --debug opsi tidak dikenali. Sebagai gantinya, gunakan opsi berikut:

Gunakan --log-file <path> untuk menulis informasi log ke file yang ditentukan dalam <path>. Jika opsi ini tidak disediakan, informasi log akan dioutput ke stderr. Menentukan --log-file tanpa juga menentukan --log-level hasil tidak ada informasi log yang ditulis ke file.
Gunakan --log-format <type> untuk menentukan format informasi yang dicatat. <type> bisa text (sebagai default jika tidak ditentukan) atau json.
Gunakan --log-level <format> untuk menentukan tingkat informasi yang dicatat. Nilai yang diizinkan adalah disabled (default, jika tidak ditentukan), trace, , debug, infowarn, dan error.

Untuk CLI warisan, contoh berikut menunjukkan jejak lengkap dari tumpukan saat terjadi kesalahan.

databricks fs ls / --debug

# Output:
#
# HTTP debugging enabled
# NoneType: None
# Error: The path / must start with "dbfs:/"

Untuk CLI baru, contoh berikut mencatat jejak tumpukan penuh ke file bernama new-cli-errors.log di direktori kerja saat ini. Jejak tumpukan ditulis ke file dalam format JSON:

databricks fs ls / --log-file new-cli-errors.log --log-format json --log-level trace

# Output:
#
# Error: expected dbfs path (with the dbfs:/ prefix): /
#
# (The full stack trace is also written to the new-cli-errors.log file.)

Pertanyaan umum

Bagian ini mencantumkan pertanyaan umum tentang migrasi dari warisan ke CLI baru.

Apa yang terjadi dengan CLI lama?

CLI warisan masih tersedia tetapi tidak menerima pembaruan yang tidak penting. Dokumentasi CLI lama ini mencerminkan hal tersebut. Databricks merekomendasikan agar pengguna bermigrasi ke CLI baru sesegera mungkin.

CLI versi lama selalu dalam keadaan Eksperimental dengan penafian bahwa Databricks tidak merencanakan fitur baru untuk CLI versi lama, dan CLI versi lama tidak didukung melalui saluran dukungan Databricks.

Kapan CLI versi lama akan dihentikan?

Databricks belum menetapkan tanggal atau jadwal untuk menghentikan CLI lama. Namun, Databricks merekomendasikan agar pengguna bermigrasi ke CLI baru sesegera mungkin.

Kapan CLI baru akan dirilis sebagai tersedia secara umum (GA)?

Tanggal rilis atau garis waktu untuk merilis CLI baru sebagai Ketersediaan Umum belum ditetapkan. Ini akan bergantung pada umpan balik yang diterima Databricks dari pengguna selama Pratinjau Umum.

Apa perbedaan utama antara CLI warisan dan baru?

CLI yang merupakan warisan dirilis sebagai paket Python. CLI baru dirilis sebagai executable mandiri dan tidak memerlukan pemasangan dependensi runtime apa pun.
CLI baru memiliki cakupan lengkap API REST Databricks. Tidak ada di CLI warisan.
CLI baru tersedia sebagai Pratinjau Publik. CLI warisan tetap bersifat eksperimental.

Apakah CLI baru memiliki paritas fitur lengkap dengan CLI warisan?

CLI baru memiliki cakupan untuk hampir semua perintah dari CLI lama. Namun, yang terutama tidak ada dalam CLI baru adalah grup perintah stacks dari CLI warisan. Selain itu, beberapa grup perintah CLI warisan seperti unity-catalog dan runs telah direfaktorkan ke dalam grup perintah baru di CLI baru. Untuk panduan migrasi, lihat informasi yang disediakan sebelumnya di artikel ini.

Bagaimana cara bermigrasi dari warisan ke CLI baru?

Untuk panduan migrasi, lihat informasi yang disediakan sebelumnya di artikel ini. Perhatikan bahwa CLI baru bukanlah pengganti yang langsung bisa digunakan untuk CLI lama dan memerlukan beberapa penyiapan untuk berpindah dari CLI lama ke CLI baru.

Dapatkah penginstalan warisan dan CLI baru ada di komputer yang sama?

Ya. Penginstalan warisan dan CLI baru dapat ada di komputer yang sama, tetapi harus terletak di direktori yang berbeda. Karena executable keduanya bernama databricks, Anda harus mengontrol executable mana yang dijalankan secara default dengan mengonfigurasi mesin PATHAnda. Jika Anda ingin menjalankan CLI baru tetapi entah bagaimana secara tidak sengaja menjalankan CLI warisan sebagai gantinya, secara default CLI warisan akan menjalankan CLI baru dengan argumen yang sama dan menampilkan pesan peringatan berikut:

Databricks CLI <new-version-number> found at <new-path>
Your current PATH prefers running CLI <old-version-number> at <old-path>

Because both are installed and available in PATH,
I assume you are trying to run the newer version.

If you want to disable this behavior you can set DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION=1.

Executing CLI <new-version-number>...
-------------------------------------
Databricks CLI <new-version-number>

Seperti yang ditunjukkan dalam pesan peringatan sebelumnya, Anda dapat mengatur variabel lingkungan DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION ke 1 untuk menonaktifkan perilaku ini dan menjalankan CLI lama sebagai gantinya.

Dapatkan bantuan

Untuk mendapatkan bantuan terkait migrasi dari CLI warisan ke CLI baru, lihat sumber daya berikut:

Pusat Bantuan Databricks

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-04-11