ローカルのファイルをリモートのDatabricksワークスペースとリアルタイムで同期する

[Sync local files with remote workspaces in real time \| Databricks on AWS](https://docs.databricks.com/dev-tools/dbx-sync.html) [2022/12/21時点]の翻訳です。

:::note warn
本書は抄訳であり内容の正確性を保証するものではありません。正確な内容に関しては原文を参照ください。
:::

:::note info
**注意**
[Databricks Labs](https://databricks.com/learn/labs)の[dbx](https://github.com/databrickslabs/dbx/blob/main/README.rst)はas-isで提供されており、カスタマーテクニカルサポートチャネルを通じて、Databricksによって正式にはサポートされていません。サポート、質問、機能リクエストに関しては、Github上の[databrickslabs/dbx](https://github.com/databrickslabs/dbx)リポジトリの[Issues](https://github.com/databrickslabs/dbx/issues)ページを通じてコミュニケーションすることができます。
:::

Databricks Labsの[dbx](https://dbx.readthedocs.io/en/latest)を活用することで、ご自身のローカル開発マシンにあるファイルの変更をDatabricksワークスペースで対応するファイルにリアルタイムで同期することができます。これらのワークスペースファイルは[DBFS](https://qiita.com/taka_yayoi/items/f15b50469b368907ec3b)あるいは[Databricks Repos](https://qiita.com/taka_yayoi/items/b89f199ff0d3a4c16140)に格納することができます。

dbxによるリアルタイムファイル同期(`dbx sync`)は、迅速なコード開発シナリオで有用です。例えば、シンタックスのハイライト、スマートなコードコンプリーション、コードリンティング、テスト、デバッグのような生産性を高める機能のためにローカルの統合開発環境(IDE)を活用することができます。そして、更新したコードをワークスペースですぐに実行することができます。

[自動化ジョブ](https://qiita.com/taka_yayoi/items/994c701552e58d260562)や[IDE](https://docs.databricks.com/dev-tools/ide-how-to.html)で`dbx sync`を活用することができます。

# `dbx sync`の開発ワークフロー

`dbx sync`の開発ワークフローには2つあり、DBFSを用いるものとDatabricks Reposを用いるものです。

`dbx sync`とDBFSによる典型的な開発ワークフローは:

1. DBFSに同期したいファイルを格納するローカルディレクトリを特定します。
1. ローカルディレクトリを同期するDBFSのパスを特定します。
1. ローカルディレクトリをDBFSパスに同期するために`dbx sync dbfs`を実行します。`dbx sync`がローカルディレクトリにおけるファイルの変更の監視をスタートします。
1. 必要に応じてローカルディレクトリのファイルを変更します。`dbx sync`がこれらの変更をリアルタイムでDBFSで対応するファイルに適用します。

`dbx sync`とDatabricks Reposによる典型的な開発ワークフローは:

1. 使用できるリポジトリが無い場合には、Databricks ReposをサポートするGitプロバイダーのリポジトリを作成します。
1. Databricksワークスペースにリポジトリをクローンします。
1. ローカル開発マシンにリポジトリをクローンします。
1. ローカルにクローンされたリポジトリとワークスペースにクローンされたリポジトリを関連づけるために`dbx sync repo`を実行します。`dbx sync`がローカルディレクトリにおけるファイルの変更の監視をスタートします。
1. 必要に応じてローカルにクローンしたリポジトリのファイルを変更します。`dbx sync`がこれらの変更をリアルタイムでDatabricks Reposで対応するファイルに適用します。
1. リポジトリがお使いのGitプロバイダーと同期されるように、ワークスペースにクローンしたリポジトリから定期的にGitプロバイダーにプッシュします。

:::note warn
**重要！**
`dbx sync`はローカル開発マシンからリモートワークスペースに対してファイルの変更を一方向かつリアルタイムの同期のみを実行します。このため、`dbx sync`で監視されているファイルをDatabricksワークスペースで開始することはお勧めしません。そのようなワークスペース起源の変更を行う必要がある場合には、以下のことをも実行しなくてはなりません:

- DBFSのファイルを変更した際には、ローカルファイルに対して同じ変更を手動で行ってください。
- Databricks Reposのファイルを変更した場合には、ワークスペースからGitプロバイダーにプッシュしてください。そして、ローカルの開発マシンでは、Gitプロバイダーからこれらの変更をプルしてください。
:::

# 要件

Databricks Reposで`dbx sync`を使う際には、Databricksワークスペースは以下の要件を満たしている必要があります:

- 必須ではありませんが、Gitプロバイダーから[クローン](https://docs.databricks.com/repos/git-operations-with-repos.html)したリポジトリを推奨します。設定されていない場合には、まずワークスペースで[ワークスペースファイルのサポートを設定](https://docs.databricks.com/files/workspace.html#enable-files-in-repos)する必要があります。

ローカルの開発マシンでは、以下をインストールする必要があります:

- バージョン3.8以降の[Python](https://www.python.org/downloads/)。Pythonがインストールされているかどうかをチェックするには、ターミナルあるいはPowerShellで`python --version`を実行します。

    ```bash:Bash
    python --version
    ```

    :::note
    **注意**
    ある環境では`python`ではなく`python3`を使用しなくてはならない場合があります。その場合、本書では`python`を`python3`で読み替えてください。
:::

- [pip](https://pip.pypa.io/en/stable/installation/)。`pip`がインストールされているかどうか、インストールされている`pip`のバージョンをチェックするには、`pip --version`あるいは`python -m pip --version`を実行します。

    ```bash:Bash
    pip --version

    # Or...

    python -m pip --version
    ```

    :::note
    **注意**
    ある環境では`python`ではなく`python3`を使用しなくてはならない場合があります。その場合、本書では`python`を`python3`で読み替えてください。
:::

- バージョン0.8.0以降の[dbx](https://pypi.org/project/dbx/)。`dbx`がインストールされているかどうか、インストールされている`dbx`のバージョンをチェックするには、`dbx --version`を実行します。Python Package Index (PyPI)から`dbx`をインストールするには、`pip install dbx`あるいは`python -m pip install dbx`を実行します。(`dbx`に[dbx sync](https://dbx.readthedocs.io/en/latest/reference/cli/#dbx-sync)が含まれています)

    ```bash:Bash
    # Check whether dbx is installed, and check its version.
    dbx --version

    # Install dbx.
    pip install dbx

    # Or...
    python -m pip install dbx
    ```

    :::note
    **注意**
    `dbx`の詳細は、[Databricks Labsのdbx](https://qiita.com/taka_yayoi/items/994c701552e58d260562)や[dbx documentation](https://dbx.readthedocs.io/en/latest)をご覧ください。
:::

- [Databricks CLI](https://docs.databricks.com/dev-tools/cli/index.html)、[認証](https://docs.databricks.com/dev-tools/cli/index.html#set-up-authentication)を設定します。`dbx`をインストールする際に自動でDatabricks CLIがインストールされます。以下の場所のいずれか、あるいは両方でローカル開発マシンの認証を設定することができます。
    - 環境変数`DATABRICKS_HOST`と`DATABRICKS_TOKEN`(Databricks CLIバージョン0.8.0以降)
    - `.databrickscfg`ファイル内の[設定プロファイル](https://docs.databricks.com/dev-tools/auth.html#config-profiles)

    `dbx`は、これら二つの場所の認証クレディンシャルを検索します。`dbx`は最初にマッチしたもののみを使用します。

    :::note
    **注意**
    `.databrickscfg`ファイルを使用している際、`dbx sync`はデフォルトでこのファイルの`DEFAULT`という設定プロファイルを参照します。別のプロファイルを使用するには、本書の後半で`dbx sync`コマンドを使用する際に`--profile`オプションを使用してください。  

    `dbx`は[\.netrc](https://docs.databricks.com/dev-tools/api/latest/authentication.html#netrc)を用いた認証をサポートしていません。
:::

- Databricks Reposと`dbx sync`を使いたい場合には、Gitプロバイダーのリポジトリのローカルクローンが必須ではありませんが推奨となります。ローカルのクローンを実行する際には、Gitプロバイダーのドキュメントを参照してください。

# `dbx sync`でDBFSを使う

1. ローカルの開発マシンのターミナル、PowerShellで、DatabricksワークスペースのDBFSと同期したいファイルを格納するディレクトリに移動します。
1. 以下のように、ワークスペースのDBFSに同期するローカルディレクトリで[dbx sync](https://dbx.readthedocs.io/en/latest/reference/cli/#dbx-sync)コマンドを実行します。(カレントディレクトリを表現するドット(`.`)を末尾に記述することを忘れないでください。)

    ```bash:Bash
    dbx sync dbfs --source .
    ```

    :::note
    **ティップス**
    別のソースディレクトリを指定するには、ドット(`.`)を別のパスに置き換えます。
   :::

    :::note
    **注意**
    `Error: No such command 'sync'`というエラーが表示される場合、お使いの`dbx`が古い可能性があります。これを修正するには、`pip install --upgrade dbx==<version>`あるいは`python -m pip install --upgrade dbx==version`を実行します。`<version>`は`dbx`の最新バージョンです。バージョン番号は[PyPI webpage for dbx](https://pypi.org/project/dbx/)で確認することができます。
    
    ```bash:Bash
    pip install --upgrade dbx==<version>    
    # Or...
    python -m pip install --upgrade dbx==version
    ```
   :::

1. `dbx sync`がカレントのローカルディレクトリのファイルと以下のワークスペース上のDBFSパスのファイルとの同期を開始します。`dbx sync`は以下のように`Target base path`の後にDBFSパスを表示することでこれを確認することができます。

    ```
    /tmp/users/<your-Databricks-username>/<local-directory-name>
    ```

    :::note
    **ティップス**
    別のユーザー名やDBFSパスを指定するには、`dbx sync`を実行する際に、`--user`や`--dest`オプションを使用します。
:::

1. 必要に応じてローカルファイルを変更します。

    :::note warn
    **重要！**
    `dbx sync`による同期が継続されるように、ターミナルやPowerShellは開いたままにしておく必要があります。ターミナルやPowerShellを閉じると、`dbx sync`による監視は停止し、同期も停止します。ファイル変更の同期を再開するには、最初から手順を繰り返してください。
:::

1. 必要に応じて、ワークスペースのDBFSのパスにおけるファイルの変更を検証します。

# `dbx sync`でDatabricks Reposを使う

1. ローカルの開発マシンのターミナル、PowerShellで、Gitプロバイダーのリポジトリのクローンを格納するルートディレクトリに移動します。
1. Databricksワークスペースでは、ローカルにクローンされたレポジトリと同期したいDatabricks Repoの名前を特定します。ワークスペースの**Data Science & Engineering**あるいは**Machine Learning**のサイドバーの**Repos**をクリックすることでリポジトリの名前を特定することができます。
1. 以下のように、ワークスペースのDatabricks Reposにローカルにクローンしたリポジトリを同期するために[dbx sync](https://dbx.readthedocs.io/en/latest/reference/cli/#dbx-sync)コマンドを実行します。`<your-repo-name>`をDatabricks Reposのリポジトリの名前で置き換えてください。(カレントディレクトリを表現するドット(`.`)を末尾に記述することを忘れないでください。)

    ```bash:Bash
    dbx sync repo -d <your-repo-name> --source .
    ```

    :::note
    **ティップス**
    別のソースディレクトリを指定するには、ドット(`.`)を別のパスに置き換えます。
   :::

    :::note
    **注意**
    `Error: No such command 'sync'`というエラーが表示される場合、お使いの`dbx`が古い可能性があります。これを修正するには、`pip install --upgrade dbx==<version>`あるいは`python -m pip install --upgrade dbx==version`を実行します。`<version>`は`dbx`の最新バージョンです。バージョン番号は[PyPI webpage for dbx](https://pypi.org/project/dbx/)で確認することができます。
    
    ```bash:Bash
    pip install --upgrade dbx==<version>    
    # Or...
    python -m pip install --upgrade dbx==version
    ```
   :::

1. `dbx sync`がカレントのローカルにクローンしたリポジトリのファイルと以下のワークスペース上のDatabricks Reposのファイルとの同期を開始します。`dbx sync`は以下のように`Target base path`の後にDatabricks Reposのパスを表示することでこれを確認することができます。

    ```
    /Repos/<your-Databricks-username>/<your-repo-name>
    ```

    :::note
    **ティップス**
    別のユーザー名やリポジトリ名を指定するには、`dbx sync`を実行する際に、`--user`や`--dest-repo`オプションを使用します。
:::

1. 必要に応じてローカルファイルを変更します。

    :::note warn
    **重要！**
    `dbx sync`による同期が継続されるように、ターミナルやPowerShellは開いたままにしておく必要があります。ターミナルやPowerShellを閉じると、`dbx sync`による監視は停止し、同期も停止します。ファイル変更の同期を再開するには、最初から手順を繰り返してください。
:::

1. 必要に応じて、ワークスペースのDatabricks Reposにおけるファイルの変更を検証します。

# その他のリソース

- [dbx documentation](https://dbx.readthedocs.io/en/latest)
- [dbx sync documentation](https://dbx.readthedocs.io/en/latest/reference/cli/#dbx-sync)
- GitHubの[databrickslabs/dbx](https://github.com/databrickslabs/dbx)リポジトリ
- [dbx limitations](https://dbx.readthedocs.io/en/latest/#limitations)

### Databricks 無料トライアル

[Databricks 無料トライアル](https://databricks.com/jp/try-databricks)