Python で Supabase から効率的にファイルをインポート
Python で Supabase からファイルをインポートするには、公式のオープンソース SDK でバイト列をダウンロードし、ローカルに保存します。以下のスクリプトは、単一のオブジェクト、またはフォルダー配下の参照可能な全オブジェクトを処理します。一覧の後続ページやネストされたフォルダーも対象です。ローカルファイルの上書きを拒否し、インポートが中断すると失敗を示す終了ステータスを返します。
Supabase と Python のセットアップ
Supabase プロジェクト、非公開バケット、メールアドレスとパスワードで認証でき、そのバケットのオブジェクトを読み取れるユーザーが必要です。この手順では POSIX シェルと、ハードリンクをサポートするローカルファイルシステムを使います。Linux 上で Python 3.12.13、supabase 2.13.0、storage3 0.11.3 を使用してテストしました。メンテナンスされている Python 3.12 のパッチリリースを使用してください。上記の正確なパッチバージョンは、テストで使用したものです。
1. 必要な Python ライブラリのインストール
python3.12 とその venv モジュールがインストールされた環境で、管理下のディレクトリに次を貼り付けて実行します。
(
command -v python3.12 >/dev/null || exit 1
if [ -e .venv ] || [ -L .venv ]; then
printf 'Choose a directory without an existing .venv.\n' >&2
exit 1
fi
python3.12 -m venv .venv &&
.venv/bin/python -m pip install 'supabase==2.13.0'
)
サブシェルを使うため、現在のディレクトリとシェルオプションは変更されません。インストールに失敗すると、不完全な .venv が残る場合があります。診断用に残しておき、新しいディレクトリで再試行してください。以下のコマンドでは、この仮想環境を有効化せずに明示的に使用します。
2. Supabase での認証情報とアクセス権限の設定
プロセスの環境またはシークレットマネージャーを通じて、次の環境変数を指定します。
| 変数 | 値 |
|---|---|
SUPABASE_URL | プロジェクトの URL |
SUPABASE_PROJECT_KEY | プロジェクトのレガシー anon JWT キー |
SUPABASE_USER_EMAIL | 確認済みユーザーのメールアドレス |
SUPABASE_USER_PASSWORD | そのユーザーのパスワード |
SUPABASE_SOURCE_PREFIX | そのユーザーの UUID に /images を続けた値 |
この処理設定は、バージョンを固定したクライアントのレガシー JWT キーインターフェースを対象とします。バージョン 2.13.0 はプロジェクトキーを JWT として検証するため、sb_publishable_… キーには、より新しいクライアントが必要です。ここでは anon キーを使い、一般ユーザーとして認証してください。インポーターにサービスロールキーを渡さないでください。Supabase は2026 年末にレガシーキーを非推奨にする予定です。この処理設定は、引き続きレガシーキーを利用できるプロジェクトに適用されます。
小規模な例として、プロジェクト所有者に非公開の my-bucket バケットを作成し、image.jpg と nested/photo.jpg を
<user-uuid>/images 配下にアップロードしてもらいます。ユーザーの UUID は Auth のユーザー ID であり、メールアドレスではありません。プロジェクト所有者は、SQL エディターで次のポリシーを設定すると、各ユーザーの UUID フォルダーへの読み取り権限を付与できます。必要に応じて my-bucket を置き換えてください。
create policy "Read own UUID folder"
on storage.objects for select to authenticated
using (
bucket_id = 'my-bucket'
and (storage.foldername(name))[1] = (select auth.uid())::text
);
一覧取得とダウンロードには、どちらも
SELECT 権限が storage.objects に必要です。インポーターには、バケット作成権限もアップロード権限も必要ありません。既存のポリシーも確認してください。許可型ポリシーによって、この例のフォルダー制限を超えるアクセスが許可される場合があります。Storage のアクセス制御ガイドを参照してください。
3. Supabase バケットへの接続
以下のプログラム全体を import_supabase.py として保存します。バケットハンドルを作成する前にサインインします。保存先の親ディレクトリは管理下に置き、別のプロセスがそれらを変更しない状態で、インポートを順番に実行してください。このスクリプトは、親ディレクトリのシンボリックリンクや、安全でないリモートパスの構成要素を拒否します。
import argparse
import os
import sys
import tempfile
from pathlib import Path
from urllib.parse import quote
from supabase import create_client
VALID_NAME_CHARACTERS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-!.*'() &$=@;+,?"
def validate_path(value: str, allow_empty: bool = False) -> None:
if allow_empty and value == '':
return
for name in value.split('/'):
if (not name or name in {'.', '..'}
or any(char not in VALID_NAME_CHARACTERS for char in name)):
raise ValueError('Unsafe remote path component')
def download_file(bucket, key: str, target: Path) -> None:
validate_path(key)
print(f'Downloading {key}', flush=True)
for parent in [target.parent, *target.parent.parents]:
if parent.is_symlink():
raise ValueError('Symlink destination parent')
target.parent.mkdir(parents=True, exist_ok=True)
data = bucket.download(quote(key, safe='/'))
with tempfile.TemporaryDirectory(dir=target.parent) as staging:
temporary = Path(staging) / 'download'
temporary.write_bytes(data)
# Linking publishes a complete file and refuses an existing destination.
os.link(temporary, target)
print(f'Downloaded {key}')
def import_directory(bucket, prefix: str, root: Path) -> int:
prefix = prefix.rstrip('/')
validate_path(prefix, allow_empty=True)
pending = [(prefix, root)]
count = 0
while pending:
remote, local = pending.pop()
offset = 0
while True:
rows = bucket.list(path=remote, options={
'limit': 100, 'offset': offset,
'sortBy': {'column': 'name', 'order': 'asc'},
})
for row in rows:
name = row['name']
validate_path(name)
if '/' in name:
raise ValueError('Expected an immediate child name')
key = f'{remote}/{name}' if remote else name
target = local / name
if row.get('id') is None:
pending.append((key, target))
continue
download_file(bucket, key, target)
count += 1
if len(rows) < 100:
break
offset += 100
return count
def main() -> None:
parser = argparse.ArgumentParser(description='Download Supabase objects without overwriting')
parser.add_argument('mode', choices=['file', 'directory'])
parser.add_argument('bucket')
parser.add_argument('source')
parser.add_argument('destination')
args = parser.parse_args()
client = create_client(os.environ['SUPABASE_URL'], os.environ['SUPABASE_PROJECT_KEY'])
client.auth.sign_in_with_password({
'email': os.environ['SUPABASE_USER_EMAIL'],
'password': os.environ['SUPABASE_USER_PASSWORD'],
})
bucket = client.storage.from_(args.bucket)
destination = Path(args.destination).absolute()
if args.mode == 'file':
download_file(bucket, args.source, destination)
count = 1
else:
count = import_directory(bucket, args.source, destination)
print(f'Imported {count} file(s)')
if __name__ == '__main__':
try:
main()
except Exception as error:
print(f'Import stopped ({type(error).__name__}). Check credentials, '
'Storage SELECT policies, and destination paths.', file=sys.stderr)
sys.exit(1)
download() は、オブジェクト全体をバイト列として返します。まず一時ファイルを書き込み、次に os.link() が保存先を作成します。そのパスに既存のファイル、ディレクトリ、シンボリックリンクがあっても置き換えません。ブロックを抜けると、一時保存データを削除します。保存先のファイルシステムにはハードリンクのサポートが必要です。ストリーミングダウンロードは使用しません。
Python で Supabase からファイルをインポートする方法
単一ファイルのインポート
上記の環境変数を設定してから、次を実行します。
.venv/bin/python import_supabase.py file my-bucket "$SUPABASE_SOURCE_PREFIX/image.jpg" local/image.jpg
オブジェクトのバイト列は local/image.jpg に保存されます。実行に成功すると、ダウンロードしたキーと、インポート件数が一件であることを報告します。保存先がすでに存在する場合は FileExistsError が発生し、終了ステータスは 1 になります。必要なファイルを削除するのではなく、新しい保存先を選んでください。
ディレクトリ内の複数ファイルのインポート
同じプログラムを使い、参照可能なフォルダーツリー全体をコピーします。
.venv/bin/python import_supabase.py directory my-bucket "$SUPABASE_SOURCE_PREFIX" downloads
上記のオブジェクトが二つある構成では、downloads/image.jpg と
downloads/nested/photo.jpg が保存され、インポート件数は二件になります。一覧でオブジェクト ID が null の行はフォルダーを表します。スクリプトはその行をダウンロードせず、子要素の一覧を取得します。フォルダーごとに独立してページ分割し、オフセットにはファイルだけでなくフォルダーの行も含めます。
この例では、スペースや疑問符を含む
Storage で許可される ASCII 名を受け付けます。ダウンロード用に名前をエンコードしますが、ローカルの名前は変更しません。空のファイルも有効です。パスの検証ではさらに、空の構成要素、. と
..、バックスラッシュ、コロン、パーセント記号、ハッシュ記号、非 ASCII 文字を拒否します。既存の保存先ファイルは保持します。名前が衝突した場合は、ファイルをスキップして成功を報告するのではなく、インポートを停止します。
Storage の制限と考慮事項
ダウンロードごとに、オブジェクト一つの全体をメモリに保持します。また、一覧取得ごとに、直下の子要素を最大 100 件保持します。利用可能なメモリに収まるファイルを選んでください。大きなフォルダーツリーでは、処理待ちのフォルダーパスも蓄積されます。この例では、インポート全体のメモリ使用量や実行時間に制限を設けていません。
インポート中は、リモートのツリーを変更しないでください。オフセットによるページ分割はスナップショットではありません。同時にアップロード、名前変更、削除を行うと、項目の欠落や重複が発生する場合があります。失敗すると終了ステータス 1 でインポートを停止し、保存済みのファイルは保持します。ディレクトリのインポートはトランザクションではありません。原因を修正した後は、保存済みファイルが再実行を妨げないよう、新しい保存先を使ってください。
停止したインポートや結果が空のインポートの診断
認証エラーの場合は、プロジェクト URL、レガシー anon キー、確認済みユーザーの認証情報を確認してください。Storage エラーの場合は、バケット、正確なオブジェクトパス、そのユーザーの
SELECT ポリシーを確認してください。OSError(FileExistsError を含む)の場合は、ローカルの権限、既存の保存先、ディスクの空き容量、ハードリンクのサポートを確認してください。進捗出力には最後に試行したキーが表示されるため、失敗したオブジェクトを特定できます。スクリプトはプロバイダーのレスポンスや認証情報を出力しません。
インポート件数がゼロの場合、一覧取得でオブジェクトが見えなかったことを意味します。バケットが空である証明にはなりません。RLS により、そのユーザーにはオブジェクトが見えない場合があります。ローカルコピーを完全なものと見なす前に、想定されるオブジェクトの一覧をプロジェクト所有者に確認してください。バケットの MIME 制限とアップロードサイズの上限はアップロードに適用されます。ダウンロードしたファイルの内容を検証するものではありません。
インポートしたファイルの活用
保存したファイルは、アプリケーションで普段使っている Python ライブラリで読み込みます。ダウンロード後に別のメディア処理ワークフローが必要な場合は、Transloadit の Python SDK を参考にしてください。上記のダウンローダーは、処理のためにファイルを送信するものではありません。
