phoenix-sqlean

phoenix-sqlean

nalgeon/sqlean.py のベンダーフォークです。

バンドルされたバージョンの更新

ピンは packages/phoenix-sqlean/Makefile にあります。それぞれ、連動して更新する必要がある項目があります。

ピン	連動して更新する項目
SQLITE_VERSION	SQLITE_RELEASE_YEAR（URLには両方が含まれるため、不一致だと404になります）と SQLITE_SHA256
SQLEAN_COMMIT	Makefile と setup.py の SQLEAN_VERSION — 取得対象を決めるのはコミットで、文字列はその説明にすぎません
SQLEAN_VERSION	setup.py 側の値。コンパイル時に組み込まれ、sqlean_version() の戻り値になります。SQLEAN_COMMIT が指定したタグより先にある場合に限り、サフィックス +<short sha> を付けます
XXHASH_TAG	XXHASH_COMMIT と XXHASH_SHA256、および sqlean 自身の Makefile が取得するタグ

download-sqlean の前提条件である check-sqlean-pin は、1回の ls-remote で SQLEAN_* の行を検証します。サフィックスがコミットの接頭辞であること、ベースが実在するタグであること、先行している場合にのみサフィックスが存在すること、setup.py の値が一致することを確認します。ベースが誤ったリリースを指しているかどうかは判定できません。単一コミットの取得では、祖先関係を確認できないためです。SQLITE_* と XXHASH_* には同等の相互チェックがなく、取得時にハッシュのみを検証します。

sqlean はコミットを指定して git 経由で取得します。GitHub のソースアーカイブはオンデマンドで生成され、バイト単位で安定していないためチェックサムで固定できませんが、git は受け取ったすべてのオブジェクトをハッシュ化します。そのため、download-sqlean には PATH 上の git が必要で、チェックサムは不要です。他の2つは通常の HTTP 経由で取得されますが、curl は何も検証しません。XXHASH_COMMIT で正しいバイト列を指定し、XXHASH_SHA256 でそれが正しいバイト列であることを証明します。src/test_windirent.h はどちらも必要ありません。このリポジトリにコミットされています。

スクリプトを使う場合

scripts/check-upstream.sh は、ハッシュも含めてすべてのピンを解決し、書き換えます。

cd packages/phoenix-sqlean
./scripts/check-upstream.sh sqlite            # detection only, no downloads
./scripts/check-upstream.sh sqlite --apply    # rewrite pins, print a Markdown summary
./scripts/check-upstream.sh sqlean [--apply]  # also moves XXHASH_* if sqlean moved its own

手動で行う場合

git ls-remote <repo> 'refs/tags/<version>*' でタグをコミットに解決します。注釈付きタグの場合は、^{} の行を選びます。sqlean にはバージョン形式ではないタグ（incubator）もあるため、最新のものを選ぶ前に形式で絞り込んでください。

SQLITE_SHA256 については、SHA-256 を記録する前に、ダウンロードしたファイルを https://sqlite.org/download.html の PRODUCT 行に記載された SHA3-256 と照合してください（shasum は SHA3 に対応していません）。これを省略すると、初回使用時に信頼することになります。

検証

cd packages/phoenix-sqlean
make prepare-src download-sqlite download-sqlean   # always the full chain: download-sqlean
                                                   # APPENDS init.c, so alone it double-appends
python setup.py build_ext -i
python -m tests

最新の状態を保つ

Dependabot はこれらのピンを検出できません。カスタム正規表現マネージャーがなく、ここには Renovate もありません。phoenix-sqlean-upstream.yml がこの不足を補います。週次でコンポーネントごとにドラフト PR を1件作成し、check-upstream.sh --apply を実行します。モデルは関与しません。

ビルドもテストも行いません。 CI が PR 上でそれをカバーします。更新ジョブ内で検証すると、その一部を再実行することになりますが、最も起こりやすい失敗である MSVC パッチへの patch(1) の適用を再現できないプラットフォームで行うことになります。

スクリプト自体の失敗は別です。上流の形式が変わった場合、スクリプトは書き込み前に終了するため、ジョブは PR を作成せずに失敗します。レビュー対象となる更新内容を計算できないためです。

XXHASH_* は意図的に監視対象外です。sqlean 側で管理されており、sqlean 自身のピンが変わると download-sqlean がすでに失敗するためです。

注意点

• src/test_windirent.h は 3.50.4 に固定されています。再同期しないでください。 SQLite では 3.51.0 で削除されており、それ以降のタグにもありません。意図的に同梱しており、ダウンロードしたものではありません。
• sqlean 0.28 以降では crypto/xxhash.impl.h が必要ですが、sqlean には含まれていません。 新たなサードパーティソースを追加する場合は、THIRD_PARTY_LICENSES のセクションと、license= に指定する SPDX 識別子の両方が必要です。
• src/sqlean-time-msvc.patch への patch(1) の失敗は、意図した検知機構であり、破損ではありません。 新しい sqlean ソースに対して再生成してください。
• もう一つの注意点は、「sqlean fetches xxHash X, but XXHASH_TAG is Y」です。 3 つすべての XXHASH_* 固定値と、THIRD_PARTY_LICENSES に記載されたバージョンを更新してください。
• sqlean_version() のテスト単独では同語反復にすぎません。 コンパイル済みマクロと setup.py 自身の定数を比較しているだけで、バイナリが古くないことしか確認できません。その定数を SQLEAN_COMMIT に結び付けるのが check-sqlean-pin です。
• SQLEAN_VERSION だけを変更しても再コンパイルは行われません。 変更されるのは -D フラグだけであり、build_ext はソースの更新日時を基準にします。編集後に touch src/sqlean.c を実行してください。そうしないと、古いビルドのままバージョンテストが失敗します。
• パッケージのバージョンは標準の SemVer のままにしてください。 release-please のバージョン正規表現にはアンカーがないため、1.2.3.1 と 1.2.3.post1 は 1.2.3 に切り詰められ、既存のタグと衝突しても警告されません。同じ理由から、setup.py では VERSION を SQLEAN_VERSION より上に置く必要があります。パッケージのバージョンは、同梱する SQLite のバージョンとは意図的に独立しています。

Wheels と公開

• 設定は cibuildwheel.toml にあり、ランナーとステップは phoenix-sqlean-build.yml にあります。これは workflow_call ワークフローで、publish.yaml の build-sqlean と CI の wheels ジョブがどちらもオーバーライドなしで呼び出します。PR ではリリースとまったく同じビルドが実行されます。CI 側の設定だけを狭めず、この状態を維持してください。
• wheel マトリックスは、python_requires が認めるすべての CPython × TOML の build プラットフォーム × ビルドワークフローのランナーから、TOML の skip を除いたものに、C ソースの sdist を加えたものです。改めて列挙せず、設定を参照してください。
• すべての wheel は cibuildwheel によってテストされます。そのため、Linux／Windows の各アーキテクチャにつきランナーが 1 つ必要です。 これらのアーキテクチャは native です。cibuildwheel はクロスコンパイルされた win_arm64 のテストをスキップし、Windows AMD64 で auto を指定すると 32 ビットの x86 が追加されます。macOS は 1 つの arm64 ランナーで両方のアーキテクチャをビルドし、Rosetta で x86_64 をテストします。フリースレッドビルドは TOML の skip で除外されています。除外しなければ、cibuildwheel はデフォルトでこれらもビルドします。
• ビルドワークフローの check ジョブで scripts/check-wheelhouse.py がマージ済みのセットを検証するため、CI と公開の両方で実行されます。 PLATFORMS のそれぞれについて、python_requires が認める各 CPython 用の wheel がちょうど 1 つ、さらに sdist が 1 つ必要です。プラットフォームを追加または削除する場合は、ランナーと archs に加えて PLATFORMS も編集してください。
• サポート対象の Python バージョン範囲を定めるのは setup.py の python_requires だけです。 cibuildwheel はこれを読み取って CPython のバージョンを選び、wheelhouse の検証では、そのバージョンがすべて含まれていることを確認します。これは if __name__ == "__main__" 配下の setuptools.setup(...) 呼び出しにある、文字列リテラルのキーワード引数でなければなりません。cibuildwheel はこれを静的に解析するため、見つからない場合は、把握しているすべての CPython を警告なしでビルドします（その場合、wheelhouse の検証は失敗します）。
• 新しい CPython を対象に加えると、どちらも明確に失敗する可能性があります。 cibuildwheel がまだそのバージョンをプレリリースとして扱い、wheel が作成されず wheelhouse の検証が失敗する場合は、cibuildwheel を更新してください。または、ドライバーが使用する非公開 C API が削除されていて、そのバージョンの wheel ビルドが失敗する場合があります。
• ソースの準備はビルドワークフローの最初のジョブです。 Windows ランナーには make／curl／unzip がないため、Ubuntu で実行します。ビルド対象は ref 入力で選択します。CI では空欄（PR のコミット）にし、公開時にはリリースタグを渡します。呼び出し元は、それ以外のものを渡しません。
• test-sources は package-dir ではなく、cibuildwheel の作業ディレクトリを基準に解決されます。 そのため、ビルドの各ジョブではワークスペースのルートにソースを展開します。
• 公開は、タグ arize-phoenix-sqlean-v<manifest version> が付くまで実行されません。release-please がタグを作成するまでは、sqlean-release はスキップされ、何もビルドされません。
• sqlean は、特定のバージョンだけでなく、すべての配布物が PyPI に揃うまで公開を続けます。 list-python-packages にある汎用の「PyPI にバージョンが存在するか」のゲートでは sqlean をスキップします。sqlean-release はリリースのたびに実行され、PyPI のそのバージョンのファイル一覧に対して check-wheelhouse.py --missing-only を実行します。アップロードが途中で中断された場合は、publish を再実行してタグから再ビルドし、skip-existing を指定してアップロードを完了します。
• check-wheelhouse.py は常にワークフローを実行しているコミットのものが使われ、python_requires はビルド対象のソースから取得されます。 PLATFORMS はランナーと一致させる必要があります。ランナーも同じコミットのものが使われます。また、古いリリースタグにはこのスクリプトが含まれていません。
• PyPI は GitHub environment を使わずに信頼された公開を使用します。これに合わせるため、公開者の Environment フィールドは空欄のままにしてください。