DuckDBからParquetデータを取り込み、PostgreSQLへ高速にロードする検証用リポジトリです。フェーズ1では最新ツールを用いた開発環境とコンテナ基盤を整備します。

• Docker と Docker Compose v2

1. DuckDBサービスを起動する（初回はイメージビルドが走ります）。

   docker compose --profile duckdb up -d duckdb

2. 依存パッケージの同期（本番 + 開発グループ）。

   docker compose exec duckdb uv sync --all-groups

   /workspace/duckdb/.venv/ に仮想環境が作成され、duckdb/pyproject.toml と duckdb/uv.lock の内容が反映されます。

3. コマンド例

   docker compose exec duckdb uv run python -V
   docker compose exec duckdb uv run ruff check
   docker compose exec duckdb uv run ty check
   docker compose exec duckdb uv run python -m copy_duck_pg.scripts.verify_connections --skip-duckdb

   すべてのPythonコマンドはDuckDBコンテナ上で実行されます。

1. 環境変数ファイルの作成

   cp .env.example .env
   # 必要に応じて POSTGRES_ および DUCKDB_ の値を編集

2. PostgreSQL コンテナの起動

   docker compose up -d postgres
   docker compose ps

   State が healthy になれば接続可能です（ヘルスチェックは pg_isready を利用）。

3. DuckDB コンテナの起動（必要時）

   docker compose --profile duckdb up -d duckdb
   docker compose --profile duckdb ps

   DuckDBコンテナは SELECT 1 を定期実行するヘルスチェック付きで起動します。リポジトリ全体が /workspace にマウントされるため、data/ 配下のファイルを直接操作できます。

4. 疎通確認

   docker compose exec duckdb uv run python -m copy_duck_pg.scripts.verify_connections

   Psycopgによる接続とDuckDB CLI経由の確認を、コンテナ内でまとめて実行します。

• .env.example: 接続情報テンプレート
• compose.yml: PostgreSQL・DuckDBのコンテナ定義
• duckdb/: DuckDB用コンテナとPythonツール群（Dockerfile / pyproject.toml / uv.lock / src/ / tests/）
• postgres/: PostgreSQL用コンテナ（Dockerfile / init/）
• data/: DuckDB側の作業ディレクトリ（.gitkeepで空ディレクトリを維持）
• AGENTS.md: 全体計画とフェーズ整理

• DuckDB CLIおよびPythonスクリプトからParquet読み込みとPostgreSQL書き込みを実装する。
• ベースラインとなるPostgreSQLテーブルスキーマとサンプルデータをpostgres/init/に追加する。
• uv run 経由でのベンチマークスクリプト、ロギング、メトリクス収集の仕組みを検討する。