PostgreSQL を使う Web アプリを 1 ステップずつ構築する
ノートを PostgreSQL に保存する小さな Web アプリケーションを、4 つのステップで育てていきます。まずデータベースをお使いのマシン上で動かして始め、次に Redis キャッシュを加え、データベースを Amazon RDS に置いて AWS へ移行し、最後にバックアップを設定します。各ステップはそれ自体で完結したワークスペースで、ディレクトリ 1/ から 4/ にあり、どれもそのままの状態でビルドできます。
どの aggregate.yaml も、そのステップを示す 1 行のコメントで始まります。ステップが release.yaml や manifest.yaml を変更する場合は、それらのファイルも同様です。ファイルを前のステップのものと比較すると、そのステップで何が追加されたのかが正確にわかります:
diff 1/aggregate.yaml 2/aggregate.yamlアプリケーションは hub.aggrega.ai/tools/quickstart-web:1.1.0 で、Apache-2.0 ライセンスで提供されています。設定は環境変数のみから読み取ります。PostgreSQL には PGHOST、PGPORT、PGUSER、PGPASSWORD、PGDATABASE を、キャッシュには REDIS_HOST と REDIS_PORT を使い、キャッシュは REDIS_HOST が設定されている間だけ使用します。ポート 8080 で待ち受け、ノートに関する応答はすべて、そのノートをどこから読み取ったかを source フィールドで示すため、キャッシュの働きを外部から確認できます。
このページの出力ブロックは、これらのページの出力の読み方に従い、実際の実行からコピーしたものです。
必要なもの
aggregaCLI(すべてのステップで使用)。- Compose 付きの Docker(お使いのマシン上で動作する
1/と2/で使用)。 3/と4/には、それ以上何も必要ありません。これらは Terraform ファイルをビルドして停止します。それぞれの初回ビルドでは、RDS と ElastiCache のモジュールを各 git リポジトリから取得します。これらのファイルの計画と適用は別の作業であり、プレースホルダーを置き換えた後、ご自身の AWS アカウントと資格情報で行います。
1 つのコマンドで実行する
最初のステップは 1 つのコマンドで実行できます。または、AI アシスタントに作成とビルドを任せることもできます。
データベースのパスワードを決め、まずそれをエクスポートします。Linux または macOS の場合:
export QUICKSTART_DB_PASSWORD=choose-a-passwordcurl -fsSL https://aggrega.ai/quickstart-web.sh | shWindows では、PowerShell で次を実行します。
$env:QUICKSTART_DB_PASSWORD = 'choose-a-password'irm https://aggrega.ai/quickstart-web.ps1 | iexDocker Compose はシェルからパスワードを読み取るため、パスワードはエクスポートしておく必要があります。また、データベースは最初に起動されたときのパスワードを保持するため、2 番目のステップでも同じパスワードが必要です。パスワードがないと、スクリプトは起動を拒否します。
スクリプトは、これから行うことを示し、続行する前に確認を求めます。aggrega が見つかること、そして Docker が応答し Compose を備えていることを確認します。例を quickstart-web フォルダーに書き出すか、そのフォルダーがすでにある場合はそれを使います。その後、最初のステップをビルドし、Docker Compose で起動します。スクリプトは最後に、アプリのページ http://127.0.0.1:8080/ を出力して終了します。
別のステップを実行するには、2、3、4 のいずれかで指定します。ステップ 3 と 4 はビルドのみを行います。Linux または macOS では sh -s -- の後に指定し、確認なしで進めるにはそこに --yes を追加します:
curl -fsSL https://aggrega.ai/quickstart-web.sh | sh -s -- 2PowerShell では、先に QUICKSTART_STEP に設定します。設定はそのウィンドウで、以降のすべての実行に対して、Remove-Item Env:QUICKSTART_STEP で削除するまで保持されます:
$env:QUICKSTART_STEP=2; irm https://aggrega.ai/quickstart-web.ps1 | iexサンプルを生成する
ステップごとにビルドして実行したい場合は、サンプルの名前を付けた新しいフォルダーにサンプルを書き出します。
aggrega scaffold --example quickstart-webその後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。
cd quickstart-webビルド
以下のコマンドは、この例のディレクトリから最初のステップを開始します。パスワードは自由に選べます。Docker Compose はスタックの起動時にシェルからパスワードを読み取るため、パスワードを保持するファイルはありません。
cd 1aggrega build --release release.yaml --auto-pullexport QUICKSTART_DB_PASSWORD=choose-a-passworddocker compose -p quickstart-web -f dist/compose/docker-compose.yaml up -d --wait# then open http://127.0.0.1:8080/ in your browserビルドは dist/compose/docker-compose.yaml という 1 つのファイルを書き出し、docker compose がそれをプロジェクト名 quickstart-web で起動して、両方のサービスが起動した時点で戻ります。以下の各セクションでは、1 ステップずつ先へ進みます。
AI アシスタントを使う
Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。
Aggrega のツールだけを使い、自分ではフォルダーを作成しないでください。ワークスペースフォルダーにまだ `quickstart-web` フォルダーがない場合は、`example` を `quickstart-web` に設定し、`dir` を指定せずに `scaffold` ツールを 1 回呼び出してください。これにより、例が新しい `quickstart-web` フォルダーに書き込まれ、README とステップフォルダー `1` から `4` が含まれます。次に、`workspace_root` を `quickstart-web/1`、`release` を `release.yaml`、`auto_pull` を true、`write` を true に設定して `build` ツールを呼び出してください。ビルドが書き込んだファイルを教えてください。それらは `quickstart-web/1/dist/` の下にあります。Web アプリとその PostgreSQL — 1/
Aggregate は 2 つのコンポーネントを宣言します。web(型は core/compute/server)と db(型は core/datastore/postgres)です。アプリケーションは、自身が読み取る名前で、エッジを通じてデータベースを要求します:
uses: database: db: target: db inject: env: - in: PGHOST from: host - in: PGPORT from: port - in: PGUSER from: user - in: PGDATABASE from: databaseパスワードは、両端それぞれにある core/secret-value アタッチメントを通じて両端に届きます。そのオリジンは Compose の変数参照 ${QUICKSTART_DB_PASSWORD} です。Release は、マルチプラットフォームインデックスのダイジェストで固定したイメージ、待ち受けるポート port: 8080、そしてマシン上でそのために公開されるポートである published_port: 8080 を指定します。published_port がなければ、そこには何も公開されません。web サービス(dist/compose/docker-compose.yaml 内):
web: image: hub.aggrega.ai/tools/quickstart-web:1.1.0@sha256:72d42d6db51d34d1268108eca1989e1467ccb2c66d15ed3e50ca97e09003c8fb environment: PGDATABASE: appdb PGHOST: db PGPASSWORD: ${QUICKSTART_DB_PASSWORD} PGPORT: "5432" PGUSER: appuser ports: - 127.0.0.1:8080:8080 [… omitted: the aggrega.ai/ labels every service carries] networks: - compose depends_on: - db deploy: resources: limits: cpus: "0.1" memory: "134217728" reservations: cpus: "0.1" memory: "134217728"PGHOST は db、つまり Compose ネットワーク上でのデータベースのサービス名で、ポートはお使いのマシンのループバックアドレスにのみ公開されます。
同じマシンのブラウザーで http://127.0.0.1:8080/ を開くと、アプリのページが表示されます。ページには、アプリが接続しているデータベースとキャッシュが示され、ノートを追加して読み取ることができます。各読み取りには、「from PostgreSQL」または「from the cache」と、その取得元が表示されます。キャッシュがまだ接続されていない場合、ページには「No cache is wired to the app, so every read comes from PostgreSQL.」と表示されます。
ターミナルから、アプリケーションに何に接続しているかを尋ね、それからメモを保存して読み戻します:
curl -s http://localhost:8080/curl -s -X POST --data 'hello from the quickstart' http://localhost:8080/notescurl -s http://localhost:8080/notes/1{ "cache": "not wired", "database": "postgresql at db:5432/appdb", "service": "quickstart-web"}{ "id": 1, "text": "hello from the quickstart", "created_at": "2026-11-01T17:22:34.261989Z", "source": "postgresql"}{ "id": 1, "text": "hello from the quickstart", "created_at": "2026-11-01T17:22:34.261989Z", "source": "postgresql"}キャッシュを追加する — 2/
Aggregate は cache コンポーネント(型は core/datastore/redis)を追加し、アプリケーションにエッジをもう 1 つ追加します:
cache: cache: target: cache inject: env: - in: REDIS_HOST from: host - in: REDIS_PORT from: portManifest は新しい型を compose/redis に対応付け、Release は新しいコンポーネントを配置します。同じパスワードをエクスポートしたまま、同じプロジェクト名でビルドして起動します:
cd ../2aggrega build --release release.yaml --auto-pulldocker compose -p quickstart-web -f dist/compose/docker-compose.yaml up -d --waitDocker Compose はデータベースを稼働させたまま、2 つの新しい変数を持つアプリケーションを再作成し、キャッシュを起動します。データベースは 1/ でエクスポートしたパスワードで作成され、そのパスワードを保持し続けるため、このステップでも同じ値を使ってください。1/ で保存したノートはまだ残っています。2 回読み取ります:
curl -s http://localhost:8080/curl -s http://localhost:8080/notes/1curl -s http://localhost:8080/notes/1{ "cache": "cache:6379", "database": "postgresql at db:5432/appdb", "service": "quickstart-web"}{ "id": 1, "text": "hello from the quickstart", "created_at": "2026-11-01T17:22:34.261989Z", "source": "postgresql"}{ "id": 1, "text": "hello from the quickstart", "created_at": "2026-11-01T17:22:34.261989Z", "source": "cache"}1 回目の読み取りは PostgreSQL から行われてキャッシュを満たし、2 回目はキャッシュから行われます。キャッシュはノートを 5 分間保持します。ページ上でノートを 2 回読み取ると、「from PostgreSQL」、続いて「from the cache」と表示されます。
スタックを使い終えたら、データベースのデータも含めて削除します。
docker compose -p quickstart-web -f dist/compose/docker-compose.yaml down -v同じデータベースを AWS のマネージドサービスで — 3/
同じ 3 つのコンポーネントを、Terraform を通じて AWS 上で動かします。Manifest は、サーバーを Fargate 上の Amazon ECS サービスである terraform/server-ecs に、PostgreSQL を terraform-aws-modules プロジェクトが公開している RDS モジュールをベンダリングした terraform/postgres-rds-terraform-aws-modules に、Redis を同プロジェクトの ElastiCache モジュールをベンダリングした terraform/redis-elasticache に対応付けます。Aggregate 内のエッジは変わりません。
Aggregate から削除されるのは 2 つのパスワードアタッチメントです。RDS がデータベースのパスワードを自ら生成するため、パスワードを含むビルド入力はありません。AWS では、RDS はパスワードを AWS Secrets Manager に保管します。パスワードを PGPASSWORD からしか読み取らないクイックスタートアプリケーションは、パスワードを渡すまでサインインできません。
Release は infra.overrides の下で、アカウント内ですでに稼働しているものを指定します。ECS クラスター、タスクが接続するサブネットとセキュリティグループ、ECS がイメージの取得とログの書き込みに使う実行ロール、そして RDS と ElastiCache のサブネットグループです。また、キャッシュの engine_version を 7.1 に設定します。ElastiCache が実行する Redis OSS は 7.1 までであるためです。これらの値はすべてプレースホルダーです:123456789012 は AWS のドキュメントが例で使うアカウント番号であり、subnet-… と sg-… の ID、サブネットグループ、クラスター、ロールは、ご自身のアカウント内のリソースを表します。ビルドはこれらを照会しないため、そのまま受け付けます。計画の前に置き換えてください。
cd ../3aggrega build --release release.yaml --auto-pullルート構成 dist/terraform/aggrega.modules.tf:
# Root configuration for this boundary. Each component rendered here is one# module block below, and the directory that block points at holds that# component's own files. One configuration means one dependency graph, which is# what lets a reference or a depends_on reach from one component to another.
module "cache" { source = "./modules/cache"
create_security_group = false create_subnet_group = false engine = "redis" engine_version = "7.1" node_type = "cache.t3.small" port = 6379 replication_group_id = "cache" security_group_ids = ["sg-0123456789abcdef1"] subnet_group_name = "example-private-cache-subnets" transit_encryption_enabled = false}
module "db" { source = "./modules/db"
allocated_storage = 10 backup_retention_period = 7 create_db_subnet_group = false db_name = "appdb" db_subnet_group_name = "example-private-db-subnets" engine = "postgres" engine_version = "16" family = "postgres16" identifier = "db" instance_class = "db.t3.small" manage_master_user_password = true multi_az = false port = "5432" skip_final_snapshot = false storage_type = "gp3" username = "appuser" vpc_security_group_ids = ["sg-0123456789abcdef0"]}
module "web" { source = "./modules/web"
assign_public_ip = false cluster = "example-cluster" cpu = "256" desired_count = 1 environment = {"PGDATABASE":"appdb","PGHOST":"${module.db.db_instance_address}","PGPORT":"5432","PGUSER":"appuser","REDIS_HOST":"${module.cache.replication_group_primary_endpoint_address}","REDIS_PORT":"6379"} execution_role_arn = "arn:aws:iam::123456789012:role/example-ecs-task-execution" image = "hub.aggrega.ai/tools/quickstart-web:1.1.0@sha256:72d42d6db51d34d1268108eca1989e1467ccb2c66d15ed3e50ca97e09003c8fb" memory = "512" name = "web" port = 8080 security_groups = ["sg-0fedcba9876543210"] subnet_ids = ["subnet-0123456789abcdef0","subnet-0fedcba9876543210"]}アプリケーションは Compose の場合と同じ名前を受け取ります。PGHOST と REDIS_HOST は今度は RDS と ElastiCache の各モジュール自身の出力への参照となり、Terraform が構成を適用する際に解決します。インスタンスとキャッシュが作成されるまで、どちらのアドレスも存在しないためです。コンパイラはどちらも読み取らずにそのまま受け渡します。dist/terraform のコピー上で、tofu init -backend=false はルートとベンダリングされたモジュールを読み込み、プロバイダーのみを取得します。続いて tofu validate は次のように出力します:
Success! The configuration is valid.バックアップを追加する — 4/
特に指定がない場合、RDS はインスタンスの自動バックアップを、自ら選んだ時間帯に 7 日間保持します。上記の backup_retention_period = 7 がそれです。Release はデータベースに core/backup をアタッチします:
db: features: backup: type: core/backup infra: retention_days: 14 schedule: "30 2 * * *"そして Manifest は Feature を terraform/backup-native にバインドします。これは自身では何もレンダリングしません。バックアップはインスタンスの設定であるため、データベースの Recipe がアタッチメントを読み取り、インスタンスのモジュールブロックに書き込みます。RDS は 1 日に 1 回自動バックアップを取得するため、スケジュールはその時刻に UTC で 30 分の時間帯を開きます。Aggregate は変わりません。
cd ../4aggrega build --release release.yaml --auto-pullルート構成が 3/ のものと異なるのは db モジュールブロックだけで、これに対する tofu validate も Success! The configuration is valid. を出力します:
backup_retention_period = 7backup_retention_period = 14backup_window = "02:30-03:00"ビルドはデプロイではない
3/ と 4/ は dist/ の下にファイルを書き出して停止します。ビルドは Terraform も OpenTofu も実行せず、AWS に対して認証することもなく、Releases が指定する識別子を照会することもありません。計画と適用は、プレースホルダーを置き換えた後、ご自身の資格情報で出力に対して行う手順です。
すべてのステップを確認する
ドキュメントリポジトリのチェックアウト(aggrega scaffold --example が書き出したコピーにはない共有ビルドヘルパーを含みます)では、このディレクトリにある ./check.sh が 4 つのステップをビルドし、それぞれがこのページに示した内容を書き出すことを確認します。すなわち、サービスと変数を含む 2 つの Compose ファイルと、モジュールブロック、参照、バックアップ設定を含む 2 つの Terraform ルート構成です。ステップごとに 1 行を出力し、いずれかのステップが異なる場合はゼロ以外の終了コードで終了します。dist/、.aggrega/、*.lock ファイルは生成物であり、コミットされません。これらはコミットされているファイルから再生成されます。