- はじめに:Snowflake CLIでできること
- Snowflake CLIとは?
- SnowSQLとの違い
- Snowflake CLIを使う場面
- インストール方法
- バージョン確認とヘルプ表示
- 最初にやる接続設定
- config.tomlの基本
- パスワード認証・SSO・キーペア認証・WIFの違い
- 接続をテストする
- 基本コマンド早見表
- snow sqlでSQLを実行する
- SQLファイルを実行する
- ステージ操作に使う
- オブジェクト一覧を確認する
- snowflake.ymlによるプロジェクト管理
- Snowpark / Streamlit / Native Appでの使いどころ
- CI/CDでSnowflake CLIを使う
- よくあるエラーと確認ポイント
- 運用時のベストプラクティス
- まとめ
- 参考リンク
- 関連記事
はじめに:Snowflake CLIでできること
Snowflake CLIは、ターミナルからSnowflakeを操作するための公式コマンドラインツールです。SQLの実行だけでなく、SQLファイルの一括実行、接続環境の切り替え、SnowparkやStreamlit、Native Appのデプロイ、CI/CD連携にも使えます。従来はSnowSQLを使うケースも多くありましたが、これから新しくCLIを覚えるならSnowflake CLIを優先するのがおすすめです。
本記事では、インストール・接続設定・snow sql・snowflake.yml・CI/CDまでを初心者向けに整理します。コマンドのオプションやファイル名は将来変わる可能性があるため、最新の状態はSnowflake公式ドキュメントで確認してください。
Snowflake CLIとは?
Snowflake CLIは、snow コマンドで起動する公式CLIです。以下のような幅広い操作をターミナルから実行できます。
- SQL実行 (1文 / ファイル単位)
- 接続情報の登録・切り替え (dev / stg / prod)
- ステージへのファイルアップロード・ダウンロード
- Snowflakeオブジェクト(テーブル・ビュー・タスクなど)の一覧確認
- Snowpark / Streamlit in Snowflake / Native App のデプロイ
snowflake.ymlによるプロジェクト定義
SnowSQLとの違い
| 比較項目 | Snowflake CLI | SnowSQL |
|---|---|---|
| コマンド | snow | snowsql |
| 位置づけ | 現在の開発者向けCLI | レガシー寄りのSQL実行CLI |
| 主な用途 | SQL実行、Snowpark、Streamlit、Native App、CI/CD | SQL実行 |
| プロジェクト管理 | snowflake.yml に対応 | 基本的になし |
| 今後の学習優先度 | 高い | 既存環境の保守で理解しておく |
SnowSQLがすぐ使えなくなる、という意味ではありません。ただし、Snowflake CLIはSQL以外の開発者向け機能にも対応しているため、これから新しく学ぶ場合はSnowflake CLIから始めるのがおすすめです。SnowSQLの基本はSnowSQLのインストールと基本的な使い方もご覧ください。
Snowflake CLIを使う場面
- ローカルでSQLをまとめて実行したいとき
- dev / stg / prod の接続を切り替えて作業したいとき
- Snowpark / Streamlit / Native Appをデプロイしたいとき
- GitHub ActionsなどのCI/CDから自動デプロイしたいとき
- SnowflakeオブジェクトをGitで管理したいとき
インストール方法
macOS:Homebrewでインストール
brew tap snowflakedb/snowflake-cli
brew update
brew install snowflake-cliuvでインストール
uv tool install snowflake-clipipでインストールする場合
pip install snowflake-cli- 公式ではパッケージマネージャやバイナリインストールが推奨される場合があります。
- 会社PCではインストール方法が制限されることがあります。
- Windowsでは公式インストーラや環境に合った方法を確認してください。
- うまくいかない場合は、Snowflake公式ドキュメントのインストール手順を確認してください。
バージョン確認とヘルプ表示
snow --version
snow --help
snow sql --help
snow connection --helpSnowflake CLIはバージョンによって使えるコマンドやオプションが変わる可能性があります。本記事のコマンドが動かない場合は、まず snow --version と snow <command> --help を確認してください。
最初にやる接続設定
対話形式で接続を追加するには、次のコマンドを実行します。
snow connection add登録済みの接続一覧を確認するには:
snow connection list名前を指定して接続テストするには:
snow connection test -c dev-c dev のように接続名を指定すると、dev / stg / prod など環境ごとに接続を切り替えられます。
config.tomlの基本
Snowflake CLIの接続情報は、通常 config.toml に保存されます。snow connection add を使うと対話形式で接続情報を登録でき、内部的には設定ファイルに接続定義が追加されます。
default_connection_name = "dev"
[connections.dev]
account = "xy12345.ap-northeast-1.aws"
user = "TARO"
role = "SYSADMIN"
warehouse = "COMPUTE_WH"
database = "DEMO_DB"
schema = "PUBLIC"- パスワードを設定ファイルに平文で保存しないようにします。
- macOS / Linuxでは設定ファイルの権限を制限します。
- 開発用と本番用の接続を分けます。
connections.tomlを併用している場合、どちらが優先されるかを確認します。
権限設定例(macOS / Linux):
chmod 0600 ~/.snowflake/config.tomlパスワード認証・SSO・キーペア認証・WIFの違い
| 認証方式 | 主な用途 | 注意点 |
|---|---|---|
| パスワード認証 | 個人検証・学習 | MFA必須化の影響を受けやすい |
| SSO | 人間ユーザーのログイン | IdP側の設定が必要 |
| キーペア認証 | ローカルCLI、ETL、CI/CD | 秘密鍵管理が必要 |
| OAuth | BIツール、外部アプリ連携 | IdPや認可サーバーとの連携が必要 |
| Workload Identity Federation | GitHub Actions、クラウド上のCI/CD | 長期シークレットを持たない設計に向く |
個人学習ではパスワードやSSOでも始められますが、本番運用やCI/CDではパスワード直書きではなく、キーペア認証やWorkload Identity Federationを検討してください。MFA・SSOの基本はSnowflakeのMFA・SSO設定入門もご覧ください。
キーペア認証の接続設定例
[connections.dev_keypair]
account = "xy12345.ap-northeast-1.aws"
user = "svc_deploy"
authenticator = "SNOWFLAKE_JWT"
private_key_file = "/path/to/rsa_key.p8"
role = "SYSADMIN"
warehouse = "COMPUTE_WH"
database = "DEMO_DB"
schema = "PUBLIC"- Snowflake側には公開鍵を登録します。
- CLI側では秘密鍵ファイルを安全に管理します。
- 秘密鍵はGitにコミットしないでください。
- CI/CDではGitHub Secretsなどで安全に扱います。
- 鍵ローテーションも考慮します。
MFA利用時の注意点
- MFAが必須のアカウントでは、CLI実行時にも承認が必要になることがあります。
- MFAキャッシュを使うと、一定時間は再承認を減らせる場合があります。
- 自動実行・CI/CDにはMFA付きの人間ユーザーは向きません。
- CI/CDではサービスユーザー + キーペア認証、OAuth、WIFを検討します。
接続をテストする
snow connection test -c dev接続テストが通らない場合は、account、user、role、warehouse、authenticator を順に見直すと原因にたどり着きやすいです。
基本コマンド早見表
# バージョン確認
snow --version
# ヘルプ表示
snow --help
# 接続一覧
snow connection list
# 接続テスト
snow connection test -c dev
# SQLを直接実行
snow sql -q "SELECT CURRENT_VERSION();"
# SQLファイルを実行
snow sql -f ./scripts/init.sql -c dev
# ステージにファイルをアップロード
snow stage copy ./data.csv @my_stage -c dev
# テーブル一覧を確認
snow object list table --database DEMO_DB --schema PUBLIC -c devコマンドの細かいオプションはCLIのバージョンで変わる可能性があります。実行前に snow <command> --help で確認してください。
snow sqlでSQLを実行する
もっとも基本的な使い方は snow sql -q による直接実行と、snow sql -f によるSQLファイル実行です。
snow sql -q "SELECT CURRENT_USER(), CURRENT_ROLE(), CURRENT_WAREHOUSE();" -c devsnow sql -f ./sql/create_tables.sql -c dev複数ステートメントを含むSQLファイル例
CREATE DATABASE IF NOT EXISTS DEMO_DB;
CREATE SCHEMA IF NOT EXISTS DEMO_DB.PUBLIC;
CREATE OR REPLACE TABLE DEMO_DB.PUBLIC.HELLO_CLI (
ID NUMBER,
MESSAGE STRING
);
INSERT INTO DEMO_DB.PUBLIC.HELLO_CLI VALUES
(1, 'Hello Snowflake CLI');
SELECT * FROM DEMO_DB.PUBLIC.HELLO_CLI;非同期SQL実行について
Snowflake CLIでは、長いSQLを非同期で実行できる場合があります。重い処理やバッチ処理では便利ですが、初心者の方はまず通常の snow sql -q / snow sql -f から覚えれば十分です。
snow sql -q "SELECT 'This is async query';>"SQLファイルを実行する
SQLはGitで管理し、CLIから一気に実行するのが基本パターンです。実行前に CURRENT_ROLE() や CURRENT_WAREHOUSE() を確認するクエリを差し込んでおくと、想定外のロール・WHでの実行を防げます。
snow sql -f ./sql/deploy_v1.sql -c devステージ操作に使う
内部ステージへのアップロード・ダウンロードもCLIから可能です。
snow stage copy ./data.csv @my_stage -c dev
snow stage list-files @my_stage -c devステージ操作にはUSAGE / READ / WRITE 権限が必要です。エラーが出る場合は、ロールに対する権限付与状況を確認してください。
オブジェクト一覧を確認する
snow object list table --database DEMO_DB --schema PUBLIC -c dev
snow object list view --database DEMO_DB --schema PUBLIC -c dev
snow object list task --database DEMO_DB --schema PUBLIC -c devテーブル・ビュー・タスク・ストリームなどを snow object list でまとめて確認できます。タスクやストリームの基礎はSnowflakeタスク入門、Snowflakeストリーム入門もあわせてご覧ください。
snowflake.ymlによるプロジェクト管理
snowflake.yml は、Snowflake CLIで管理するプロジェクト定義ファイルです。Snowpark、Streamlit in Snowflake、Native App、SQLスクリプトなど、開発対象のSnowflakeオブジェクトをプロジェクトとして管理できます。
definition_version: 2
entities:
hello_function:
type: function
stage: dev_stage
artifacts:
- src: app/
dest: my_app/
handler: functions.hello
signature:
- name: name
type: string
returns: stringdefinition_version: 2を基本にします。- 古い記事ではversion 1の書き方も見かけます。
- 既存のversion 1プロジェクトは移行コマンドを確認します。
- Snowpark、Streamlit、Native Appで定義内容が異なります。
snowflake.ymlで管理するメリット
- 手作業で作成したオブジェクトをコード管理できる
- dev / stg / prod で同じ定義を使いやすい
- Git管理しやすい
- CI/CDで自動デプロイしやすい
- レビュー・差分確認がしやすい
- 手順書依存を減らせる
Snowpark / Streamlit / Native Appでの使いどころ
- Snowpark:Python関数やUDFをSnowflakeにデプロイするときにCLIで一括管理できます。
- Streamlit in Snowflake:アプリのソースをまとめてデプロイ・更新できます。
- Native App:Snowflake Native Appのパッケージ作成・デプロイにCLIを使います。
各機能の詳しい使い方はSnowpark Python入門、Streamlit in Snowflake入門、Snowflake Native App入門もあわせてご覧ください。
CI/CDでSnowflake CLIを使う
Snowflake CLIはGitHub ActionsなどのCI/CDから実行できます。SQLファイルを適用したり、SnowparkやStreamlitアプリをデプロイしたり、本番反映を自動化できます。
name: Deploy Snowflake Objects
on:
push:
branches:
- main
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Install Snowflake CLI
uses: snowflakedb/snowflake-cli-action@v1
- name: Test connection
run: snow connection test -c prod
- name: Run SQL files
run: snow sql -f ./sql/deploy.sql -c prod- 上記は概念例として扱ってください。
- 実際には接続情報や認証情報をGitHub Secretsなどで管理します。
- パスワードをYAMLに直接書かないでください。
- 本番環境ではサービスユーザー + キーペア認証、またはWIFを検討してください。
- まずはdev環境で検証してください。
- mainブランチへのマージだけで本番反映される設計は慎重に行ってください。
CI/CDでの認証ベストプラクティス
- 人間ユーザーではなくサービスユーザーを使う
TYPE = SERVICEのユーザーを検討する- パスワードではなくキーペア認証やWIFを使う
- 秘密鍵やトークンをGitにコミットしない
- GitHub SecretsやOIDCを使う
- 本番反映ロールは最小権限にする
- dev / stg / prodで接続とロールを分ける
- デプロイ前に
snow connection testを実行する
RBACの考え方はSnowflake RBAC入門、ロール設計はSnowflakeカスタムロール設計もあわせてご確認ください。
よくあるエラーと確認ポイント
| 症状 | 確認ポイント |
|---|---|
snow: command not found | PATH、インストール方法、ターミナル再起動を確認 |
| 接続テストに失敗する | account、user、role、warehouse、authenticatorを確認 |
| MFA承認を毎回求められる | MFAキャッシュ、認証方式、CI/CDでの利用可否を確認 |
config.toml の権限エラー | chmod 0600 を確認 |
| SQLファイルが実行できない | ファイルパス、セミコロン、ロール権限を確認 |
| ステージ操作で失敗する | USAGE権限、READ/WRITE権限、ステージ名を確認 |
snowflake.yml で失敗する | definition_version、インデント、entity type、stageを確認 |
| CI/CDで失敗する | Secrets、接続名、認証方式、ロール、ネットワーク制限を確認 |
Snowflake全体のエラー対応はSnowflake Error Handbookもあわせてご活用ください。
運用時のベストプラクティス
- 開発・検証・本番で接続名を分ける(
dev/stg/prodなど) - 本番用接続は明確に
prodと分かる名前にする - パスワードや秘密鍵をGitに入れない
config.tomlの権限を制限する- SQLファイルはGit管理する
- 本番反映前にdev環境で
snow sql -fを試す - CI/CDではサービスユーザーを使う
- ロールは最小権限にする
- コマンド実行前に
CURRENT_ROLE()やCURRENT_WAREHOUSE()を確認する - CLIバージョンを定期的に確認する
まとめ
Snowflake CLIは、SQL実行だけでなく、Snowpark、Streamlit、Native App、CI/CD連携まで扱える開発者向けの公式CLIです。最初は snow connection add、snow connection test、snow sql -q、snow sql -f を覚えれば十分です。慣れてきたら config.toml で接続を整理し、snowflake.yml でプロジェクトを管理し、GitHub Actionsなどから安全にデプロイできる構成を目指しましょう。本番運用では、パスワード直書きを避け、キーペア認証やWIF、最小権限ロール、環境分離を意識することが重要です。
参考リンク
- Snowflake公式:Snowflake CLI
- Snowflake公式:Install Snowflake CLI
- Snowflake公式:Configure connections (config.toml)
- Snowflake公式:Project definition (snowflake.yml)
- Snowflake公式:Key-pair authentication
- Snowflake公式:Workload Identity Federation
※リンク先のパスはSnowflake側の構成変更で変わる可能性があります。最新URLは公式ドキュメントのトップから検索してください。
