Imported from ymd65536/OceanBaseDemo (
AGENTS.md). Install upstream withnpx skills add ymd65536/OceanBaseDemo. Copyright stays with the author.
手順
uvによる環境構築
環境が存在しない場合は初回だけ、uvをインストールする必要があります。 uvは、Pythonの仮想環境を簡単に作成・管理するためのツールです。以下の手順で環境を構築します。
# uvのインストール
pip install uv
環境を作成するには、以下のコマンドを実行します。
# 新しい仮想環境の作成
uv venv .venv
uvによる環境の有効化
環境を有効化するには、以下のコマンドを実行します。
# 環境の有効化
. .venv/bin/activate
SeekDBのインストール
SeekDBをインストールするには、以下のコマンドを実行します。
# SeekDBのインストール
uv run pip install -U pyseekdb
最初のスクリプト
最初のスクリプトをseekdbディレクトリに作成します。以下の内容をseekdb/first_script.pyとして保存してください。
スクリプトを実行
最初のスクリプトを実行するには、以下のコマンドを実行します。
uv run seekdb/first_script.py
OceanBase CE on GitHub Codespaces
このリポジトリでは、GitHub Codespaces 上で OceanBase CE を短時間で起動し、開発・検証を開始できる Disposable Playground を提供します。
目的は本番相当の OceanBase クラスタを構築することではなく、Developer Experience と Time to First Query を重視した再現可能な検証環境を提供することです。
基本方針
Codespaces では OceanBase CE Docker Image を MODE=SLIM で起動します。
mkdir -p /tmp/oceanbase-volume
docker run \
--name oceanbase-ce \
--ulimit nofile=65535:65535 \
-p 2881:2881 \
-e MODE=SLIM \
-v /tmp/oceanbase-volume:/mnt/oceanbase \
-d oceanbase/oceanbase-ce
/mnt/oceanbase は dataset、dump、benchmark data、生成ファイルなどを配置する scratch space として使用します。
この環境は Disposable Playground です。
永続運用、性能評価、HA評価、本番相当の耐久性評価を目的とした環境ではありません。
Known Issues / Troubleshooting
1. MODE=MINI で OceanBase が起動しない
症状
MODE=MINI で起動すると OBD precheck で以下のようなエラーが発生する場合があります。
open files ... ERROR
not enough memory
disk ... Avail: 4G, Need: 14G
OceanBase の設定を以下のように縮小しても、
OB_MEMORY_LIMIT=4G
OB_DATAFILE_SIZE=1G
OB_LOG_DISK_SIZE=1G
ディスク容量不足が発生する場合があります。
Avail: 4G, Need: 6G
原因
Codespaces のホストに十分なディスク容量が存在していても、Docker の root filesystem は別の overlay filesystem を使用します。
検証時には概ね以下の状態でした。
Docker Root Dir: /var/lib/docker
overlay:
32GB total
約4GB available
一方、Codespaces ホストの /tmp には約100GB以上の空き容量が存在しました。
MODE=MINI は通常の OBD deployment を実行し、OceanBase の datafile や log disk を確保するため、Codespaces の Docker overlay の空き容量では不足する場合があります。
対処
Codespaces Playground では MODE=MINI ではなく MODE=SLIM を使用します。
-e MODE=SLIM
SLIM は prebuilt store を利用する fastboot path を使用します。
Time to First Query を重視する Disposable Playground では SLIM を使用してください。
2. Codespaces ホストの /tmp の空き容量が OceanBase コンテナから見えない
症状
Codespaces ホストでは、
df -h /tmp
で100GB以上の空き容量が存在するにもかかわらず、OceanBase コンテナ内の /tmp では数GB程度しか利用できない場合があります。
原因
OceanBase コンテナの /tmp は Codespaces ホストの /tmp ではありません。
通常は Docker の overlay filesystem 上に存在するため、Codespaces ホスト側の大容量 /tmp を自動的に利用できません。
対処
大容量の一時領域が必要な場合は Codespaces ホストの /tmp を bind mount します。
mkdir -p /tmp/oceanbase-volume
docker run \
--name oceanbase-ce \
--ulimit nofile=65535:65535 \
-p 2881:2881 \
-e MODE=SLIM \
-v /tmp/oceanbase-volume:/mnt/oceanbase \
-d oceanbase/oceanbase-ce
確認:
docker exec oceanbase-ce df -h /mnt/oceanbase
/tmp/oceanbase-volume は永続ストレージとして扱わないでください。
このリポジトリでは scratch space として使用します。
3. /root/ob/observer/store を直接 bind mount すると OBD deploy が失敗する
症状
OceanBase の内部 store directory を bind mount すると、以下のようなエラーが発生する場合があります。
OBD-1002: Fail to init
home path: /root/ob/observer is not empty
原因
OceanBase の内部 store directory を事前に bind mount すると、Docker によって対象ディレクトリが作成されます。
その結果、OBD が deployment directory を初期化するときに、既にディレクトリが使用されていると判定する場合があります。
対処
以下のような OceanBase 内部ディレクトリへ直接 mount しないでください。
/root/ob/observer/store
scratch space が必要な場合は OceanBase の管理対象外となるパスを使用します。
/mnt/oceanbase
例:
-v /tmp/oceanbase-volume:/mnt/oceanbase
4. open files の precheck に失敗する
症状
OBD precheck で open files に関する ERROR または WARN が発生します。
The recommended number of open files ...
原因
Codespaces ホスト側の ulimit -n が十分大きくても、Docker container 内の limit は別に設定されます。
ホスト側の値だけでは OceanBase コンテナへ反映されません。
対処
Docker 起動時に nofile を明示します。
--ulimit nofile=65535:65535
SLIM 環境では OceanBase の推奨値より低いという WARN が残る場合があります。
ただし Disposable Playground では observer が ACTIVE になり SQL 接続できることを確認できれば、開発用途の環境として利用できます。
5. Dev Container の docker-in-docker Feature がインストールできない
症状
Dev Container の構築中に以下のエラーが発生する場合があります。
The 'moby' option is not supported on ubuntu 'resolute'
because 'moby-cli' and related system packages are not available
続いて以下のエラーになります。
ERROR: Feature "Docker (Docker-in-Docker)" failed to install
原因
mcr.microsoft.com/devcontainers/base:ubuntu が使用する Ubuntu version と、docker-in-docker Feature がデフォルトで使用する Moby package の組み合わせに互換性問題があります。
対処
Dev Container Feature で Moby を無効化します。
{
"features": {
"ghcr.io/devcontainers/features/docker-in-docker:2": {
"moby": false
}
}
}
再現性を高める場合は、floating OS tag への依存を避け、検証済みの base image version を固定することも検討してください。
6. postCreateCommand から setup script が見つからない
症状
Dev Container の作成自体は成功しても postCreateCommand で以下のエラーが発生する場合があります。
bash: scripts/setup-oceanbase.sh: No such file or directory
または、
postCreateCommand from devcontainer.json failed with exit code 127
原因
postCreateCommand に指定した相対パスと、実際の repository layout が一致していません。
Dev Container configuration の移動や統合によって script directory が変更された場合、古いパスが devcontainer.json に残っている可能性があります。
対処
推測でパスを変更せず、現在の repository layout を確認してください。
pwd
find . -maxdepth 4 -type f | sort
その結果に基づいて、Workspace root から解決できる正しいパスを postCreateCommand に指定します。
例:
{
"postCreateCommand": "bash scripts/setup-oceanbase.sh"
}
Dev Container configuration や scripts の配置を変更した場合は、必ず postCreateCommand も同時に確認してください。
7. obd cluster start obcluster が失敗する
症状
SLIM モードで起動した OceanBase コンテナ内で、
obd cluster start obcluster
を実行すると以下のエラーになります。
[ERROR] No such deploy: obcluster.
原因
MODE=MINI と MODE=SLIM では OceanBase Docker Image の boot path が異なります。
概念的には以下の違いがあります。
MODE=MINI
↓
normal boot
↓
OBD deploy
↓
obcluster
一方、SLIM は以下のように動作します。
MODE=SLIM
↓
fastboot
↓
prebuilt store / configuration
↓
observer
↓
OBD deployment: demo
そのため SLIM 環境には obcluster という deployment が存在しません。
対処
まず deployment を確認します。
obd cluster list
SLIM 環境では demo を操作してください。
状態確認:
obd cluster display demo
停止:
obd cluster stop demo
起動:
obd cluster start demo
実際に demo の stop/start 後、observer が ACTIVE になり SQL 接続できることを確認済みです。
8. SLIM 起動時に OS パラメータやメモリの WARN が出る
症状
obd cluster start demo で以下のような WARN が発生する場合があります。
The recommended value of fs.aio-max-nr is 1048576
The recommended number of open files is 655350
The recommended number of stack size is unlimited
The value of the "vm.max_map_count" ...
not enough memory
原因
Codespaces は本番用 OceanBase host としてチューニングされた環境ではありません。
OceanBase / OBD が推奨する kernel parameters、resource limits、memory conditions と Codespaces の実行環境には差があります。
対処
Disposable Playground では WARN と ERROR を区別してください。
以下まで正常に進んでいることを確認します。
Start observer ok
observer program health check ok
Connect to observer 127.0.0.1:2881 ok
status ACTIVE
demo running
さらに SQL 接続を確認します。
obclient \
-h127.0.0.1 \
-P2881 \
-uroot@sys \
-Doceanbase \
-A
WARN が存在していても SQL 接続まで成功していれば、Codespaces Playground の開発用途では利用できます。
ただし、性能評価、HA評価、本番相当評価ではこれらの WARN を無視しないでください。
OceanBase Health Check
Docker container の確認
docker ps --filter name=oceanbase-ce
OBD deployment の確認
docker exec oceanbase-ce obd cluster display demo
SQL 接続確認
docker exec oceanbase-ce \
obclient \
-h127.0.0.1 \
-P2881 \
-uroot@sys \
-Doceanbase \
-A \
-e "SELECT VERSION(); SELECT 1;"
対話接続
docker exec -it oceanbase-ce \
obclient \
-h127.0.0.1 \
-P2881 \
-uroot@sys \
-Doceanbase \
-A
検証時には以下のバージョンで動作確認しています。
OceanBase_CE 4.4.2.1
5.7.25-OceanBase_CE-v4.4.2.1
OceanBase Codespaces Agent Rules
AI Agent が OceanBase Codespaces 環境を変更・調査するときは以下のルールを守ってください。
- Codespaces の Disposable Playground では原則として
MODE=SLIMを使用する MODE=MINIとMODE=SLIMの boot path の違いを考慮するobclusterとdemoを混同しない- SLIM の OBD deployment name は
demo - deployment name が不明な場合は推測せず
obd cluster listで確認する - OceanBase 内部の
/root/ob/observer/storeを直接 bind mount しない - 大容量 scratch data は
/mnt/oceanbaseを使用する - Codespaces ホストの filesystem と Docker overlay filesystem を混同しない
- Dev Container configuration を変更した場合は
postCreateCommandのパスも確認する - ファイルパスが不明な場合は推測せず
pwdとfindで確認する - setup 成功の判定は Docker container の起動だけで行わない
- observer の
ACTIVEを確認する - 最終的に SQL
SELECT 1が成功するところまで確認する - OBD の WARN と ERROR を区別する
- Codespaces Playground で発生する resource WARN を本番環境の設計判断へそのまま適用しない
- この環境の結果を本番性能、HA、durability の評価として扱わない
- Time to First Query と Developer Experience を優先する
