コンテンツにスキップ
AggregaAggrega
言語の選択: 日本語
このページは機械翻訳されています。英語の原文を読む。

PostgreSQL を使う Web アプリを 1 ステップずつ構築する

ノートを PostgreSQL に保存する小さな Web アプリケーションを、4 つのステップで育てていきます。まずデータベースをお使いのマシン上で動かして始め、次に Redis キャッシュを加え、データベースを Amazon RDS に置いて AWS へ移行し、最後にバックアップを設定します。各ステップはそれ自体で完結したワークスペースで、ディレクトリ 1/ から 4/ にあり、どれもそのままの状態でビルドできます。

どの aggregate.yaml も、そのステップを示す 1 行のコメントで始まります。ステップが release.yaml や manifest.yaml を変更する場合は、それらのファイルも同様です。ファイルを前のステップのものと比較すると、そのステップで何が追加されたのかが正確にわかります:

Terminal window
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 フィールドで示すため、キャッシュの働きを外部から確認できます。

このページの出力ブロックは、これらのページの出力の読み方に従い、実際の実行からコピーしたものです。

必要なもの

  • aggrega CLI(すべてのステップで使用)。
  • Compose 付きの Docker(お使いのマシン上で動作する 1/ と 2/ で使用)。
  • 3/ と 4/ には、それ以上何も必要ありません。これらは Terraform ファイルをビルドして停止します。それぞれの初回ビルドでは、RDS と ElastiCache のモジュールを各 git リポジトリから取得します。これらのファイルの計画と適用は別の作業であり、プレースホルダーを置き換えた後、ご自身の AWS アカウントと資格情報で行います。

1 つのコマンドで実行する

最初のステップは 1 つのコマンドで実行できます。または、AI アシスタントに作成とビルドを任せることもできます。

データベースのパスワードを決め、まずそれをエクスポートします。Linux または macOS の場合:

Terminal window
export QUICKSTART_DB_PASSWORD=choose-a-password
curl -fsSL https://aggrega.ai/quickstart-web.sh | sh

Windows では、PowerShell で次を実行します。

Terminal window
$env:QUICKSTART_DB_PASSWORD = 'choose-a-password'
irm https://aggrega.ai/quickstart-web.ps1 | iex

Docker 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 を追加します:

Terminal window
curl -fsSL https://aggrega.ai/quickstart-web.sh | sh -s -- 2

PowerShell では、先に QUICKSTART_STEP に設定します。設定はそのウィンドウで、以降のすべての実行に対して、Remove-Item Env:QUICKSTART_STEP で削除するまで保持されます:

Terminal window
$env:QUICKSTART_STEP=2; irm https://aggrega.ai/quickstart-web.ps1 | iex

サンプルを生成する

ステップごとにビルドして実行したい場合は、サンプルの名前を付けた新しいフォルダーにサンプルを書き出します。

Terminal window
aggrega scaffold --example quickstart-web

その後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。

Terminal window
cd quickstart-web

ビルド

以下のコマンドは、この例のディレクトリから最初のステップを開始します。パスワードは自由に選べます。Docker Compose はスタックの起動時にシェルからパスワードを読み取るため、パスワードを保持するファイルはありません。

Terminal window
cd 1
aggrega build --release release.yaml --auto-pull
export QUICKSTART_DB_PASSWORD=choose-a-password
docker 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.」と表示されます。

ターミナルから、アプリケーションに何に接続しているかを尋ね、それからメモを保存して読み戻します:

Terminal window
curl -s http://localhost:8080/
curl -s -X POST --data 'hello from the quickstart' http://localhost:8080/notes
curl -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: port

Manifest は新しい型を compose/redis に対応付け、Release は新しいコンポーネントを配置します。同じパスワードをエクスポートしたまま、同じプロジェクト名でビルドして起動します:

Terminal window
cd ../2
aggrega build --release release.yaml --auto-pull
docker compose -p quickstart-web -f dist/compose/docker-compose.yaml up -d --wait

Docker Compose はデータベースを稼働させたまま、2 つの新しい変数を持つアプリケーションを再作成し、キャッシュを起動します。データベースは 1/ でエクスポートしたパスワードで作成され、そのパスワードを保持し続けるため、このステップでも同じ値を使ってください。1/ で保存したノートはまだ残っています。2 回読み取ります:

Terminal window
curl -s http://localhost:8080/
curl -s http://localhost:8080/notes/1
curl -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」と表示されます。

スタックを使い終えたら、データベースのデータも含めて削除します。

Terminal window
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、サブネットグループ、クラスター、ロールは、ご自身のアカウント内のリソースを表します。ビルドはこれらを照会しないため、そのまま受け付けます。計画の前に置き換えてください。

Terminal window
cd ../3
aggrega 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 は変わりません。

Terminal window
cd ../4
aggrega build --release release.yaml --auto-pull

ルート構成が 3/ のものと異なるのは db モジュールブロックだけで、これに対する tofu validate も Success! The configuration is valid. を出力します:

backup_retention_period = 7
backup_retention_period = 14
backup_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 ファイルは生成物であり、コミットされません。これらはコミットされているファイルから再生成されます。