PSSLの佐々木です Claude Code・Copilot・Codex といった AI コーディングエージェントは、コマンドを実行できる権限を持ったまま手元のリポジトリの中で動きます。便利ですが、 secret (API token、DB 接続文字列、本番 AWS キー) との同居していることでシークレットが漏洩しないか心配になったので対応策を調査してみました。 この記事では、 ルールで縛っても AI Agent に .env を読まれてしまう情報漏洩リスク その緩和策として Infisical を選んだ理由 Infisical の仕組み (= なぜ AI に「見えない」のか) 個人 AWS アカウントを使った検証での導入手順 についてまとめました。 1. ルールで縛っても AI Agent は secret を読みうる危険がある Claude Code / Copilot 等の主要な AI コーディングエージェントには、運用ルールを書ける場所が用意されています。Claude Code なら CLAUDE.md みたいなやつです。 検証用に立てたプロジェクトの CLAUDE.md にも、こんなルールを書いてみました: - `.env`, `.env.prod`, `.env.*`, `*.pem`, `client_secret.json` などの secret 実体を読まないでください - secret ファイルに対して `cat`, `grep`, `sed`, `awk`, `head`, `tail`, `less`, `python` などで 内容を表示・抽出しないでください - secret 値、DATABASE_URL、SECRET_KEY、SMTP password、RDS password、private key を チャット、docs、issue、PR、ログへ書かないでください しかしここにルールを記載しても何度も裏切られた経験もあり、意図せずAgnetがルールを無視してシークレット情報を見に行く可能性も否定しきれないなと開発をしながら思っていました。 例えば以下のような場合にAgentがルールを無視してシークレットを読みに行く可能性があります 「node dev server が立ち上がらない」→ デバッグのため DATABASE_URL の構造を確認する必要が出る 「ECR push が失敗している」→ AWS profile / credential の状態を見る必要が出る 「 make で env が読まれていないっぽい」→ シェルから env | grep XXX する つまり、 CLAUDE.md だけに頼った secret 管理は 「事故が起きないことを祈る運用」 だと感じていて商用製品の開発をする際にかなりのリスクになりえると思っています。 2. Infisical とは Infisical は OSS の secret 管理プラットフォームです。AWS Secrets Manager や HashiCorp Vault と同じ「secret を集中管理する」カテゴリに属しますが、開発者体験が抜群に良いと思いました Web UI で見て編集できる (json でなく key-value のテーブル) CLI が direnv / dotenv-cli の上位互換 として使える 環境別 ( dev / staging / prod ) + パス別 で分離可能 メンバー単位の RBAC 、誰がいつ何を見たかの audit log Cloud (SaaS) も Self-host (Docker compose) も選べる 無料枠 が個人開発で十分使える 公式に GitHub Star 約 2 万 あって、HashiCorp Vault よりは小規模、AWS Secrets Manager よりは開発者寄りという立ち位置です。 3. 仕組み ― なぜ AI Agent から「見えない」のか Infisical CLI の中核機能は infisical run です: infisical run --env=dev --path=/aws/sandbox -- aws sts get-caller-identity このコマンドの裏では、こういう流れが起きます: infisical CLI (親) │ ├─ 1. ローカルに保存された JWT で Infisical API へ認証 ├─ 2. /aws/sandbox パスの secret 一覧を HTTPS で取得 (in-memory) ├─ 3. fork して子プロセスを作る │ └─ 子プロセスの environ に AWS_ACCESS_KEY_ID 等を export └─ 4. 子プロセス (= `aws sts get-caller-identity`) 実行 └─ 子プロセス終了で memory も解放、secret はどこにも残らない Infisicalを使っていてうれしいポイント ディスクに .env ファイルを一切作らない — AI が cat .env しても “そんなファイルない” 親 shell の env に export しない — AI が env や printenv を打っても見えない (= デフォルトの shell には載っていない) shell history に値が残らない — infisical run -- foo という呼び出し履歴は残るが、secret 値は履歴に出ない 子プロセスが終わったら secret 痕跡ゼロ — RAM 上から消える つまり、AI エージェントが「環境変数経由で secret を盗む」最もカジュアルな経路 (= cat .env と env ) を 両方とも構造的に塞いでいます 。 4. 導入手順 (個人 AWS アカウントで検証) ここからは、自分の個人 AWS アカウント上に検証用の IAM user を作り、その credential を Infisical に登録して AI エージェントから AWS リソースを操作させる、という流れで手を動かしてみた手順です。あわせて、検証用に立てた Django プロダクトの .env 相当の値 (DB 接続文字列、SECRET_KEY、SMTP password など) も Infisical に寄せて、ローカルの .env を消し去るところまでやりました。 4.1 アカウント作成 infisical.com/cloud でサインアップ。Org → Project を作成。 4.2 CLI のインストール # macOS brew install infisical/get-cli/infisical # Linux curl -1sLf '<https://dl.cloudsmith.io/public/infisical/infisical-cli/setup.deb.sh>' | sudo -E bash sudo apt update && sudo apt install -y infisical 4.3 ログインとリポジトリの紐付け infisical login # ブラウザが開いて OAuth cd path/to/repo infisical init # この repo を Infisical project に紐付け (.infisical.json 生成) .infisical.json は project ID と環境名の対応だけ が入っていて secret 値は無いので、git に commit しても問題なし。 4.4 secret を登録 Web UI から登録するのが楽です。複数環境 ( dev / staging / prod ) と任意のパス ( /aws/sandbox /django/app 等) で分けられます。 検証では、個人 AWS アカウントに作った IAM user の credential と、検証用 Django プロダクトの env をこんな感じで分けました: Infisical path env vars 用途 dev / /aws/sandbox AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY (個人検証用 IAM user) AI エージェントから S3 / EC2 / SSM などを叩く検証 dev / /django/app DATABASE_URL / SECRET_KEY / SMTP_PASSWORD 等 検証用 Django アプリの実行時 env これで手元の .env は完全に削除。値は全部 Infisical 側にだけ存在する状態にしました。 4.5 実行 # AWS 操作 infisical run --env=dev --path=/aws/sandbox -- aws sts get-caller-identity # → arn:aws:iam::xxxxxxxx:user/sandbox-user # Django 起動 infisical run --env=dev --path=/django/app -- python manage.py runserver これで OK。 .env ファイルもシェルへの export も一切無し。 5. 検証してわかった恩恵 5.1 AI エージェントが構造的に secret に触れなくなった 検証では Claude Code に「個人 AWS アカウントの S3 バケットを一覧して、不要なものを削除して」みたいなタスクを投げてみました。 infisical run 経由で AWS 操作を委任しても、Claude は そもそも secret 値を「知る」術がない 。例えば: infisical run --env=dev --path=/aws/sandbox --silent -- \\ aws s3 ls これを Claude に実行させても、Claude が見られるのは: コマンドの引数 (= 公開情報) コマンドの出力 (= 私が許可した情報) だけ。 AWS キー本体は Claude のプロセス空間にも会話履歴にも入りません。 検証用 Django アプリ側でも同様で、 .env を消した状態で Claude に「dev server を立ち上げて動作確認して」と頼むと、 infisical run 経由でしか起動できない。エージェントが好奇心で cat .env しても ファイルが存在しない ので空振りに終わります。実際にやらせてみても、 DATABASE_URL や SECRET_KEY の値が会話履歴に出てくることは一度もありませんでした。 5.2 検証用 IAM user を分けやすい 個人 AWS アカウントで遊んでいると「これは AI に渡していい権限」「これは自分が手でしかやらない権限」を分けたくなります。Infisical のパスで切るとそこが綺麗: # AI に渡していい権限 (read 中心、限定リソース) infisical run --env=dev --path=/aws/sandbox -- <command> # 自分しか使わない権限 (IAM 編集、billing 系) infisical run --env=dev --path=/aws/admin -- <command> IAM user 自体は別々に作って、Infisical 側でパス権限を分けるだけ。エージェントには /aws/sandbox だけアクセスできるトークンを渡す、みたいな運用が現実的にできます。 5.3 検証が終わったら剥奪が一瞬 個人検証あるあるで「検証終わったけど IAM key 消し忘れて放置」が起こりがちですが、Infisical に集約しておけば Web UI で値を消すだけ。 .env が複数のリポジトリに散らばってる状態より圧倒的に管理が楽でした。 6. まとめ AI Agent と一緒に開発する時代、 .env をローカルに転がしておく運用は 「ルールで縛っても、いつかは事故る」 可能性があります。 文章ルール ( CLAUDE.md ) は「お願い」レベル AI Agent はタスク遂行のために env を覗くことがある (悪意なしでも) 一度履歴に入った secret は AI ベンダー側に永続化される Infisical の infisical run -- <command> 方式に切り替えると、 .env ファイルがそもそも存在しない → cat で出ない shell env にも default で乗らない → env / printenv で出ない 子プロセスのライフサイクル内だけで secret が生きる それでいて direnv 同等の手軽さで開発が回る 完全防御ではないが、 カジュアルな漏洩経路を構造的に塞いだ上で、AI エージェントとの共存を成立させる ための最小コストの一手として、強くおすすめできます。 個人 AWS アカウントでの検証レベルでも、 .env を消して Infisical に寄せたことで「エージェントに何を喋らせても secret が混入しない」という安心感は段違いでした。本番投入前のサンドボックスとして手を動かしてみる価値は十分あると思います。 参考リンク Infisical 公式 Infisical CLI ドキュメント Anthropic Claude Code 公式 GitHub: Infisical/infisical ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post AI エージェントに.envを読まれたくなかったからInfisicalを導入てみた first appeared on SIOS Tech Lab .

本記事は 2026 年 5 月 11 日 に公開された「 Amazon Aurora DSQL connections: Drivers, strings, and best practices 」を翻訳したものです。 Amazon Aurora DSQL への初めての接続を設定しようとしていますか? PostgreSQL を使ったことがあれば流れは似ていますが、いくつか重要な違いがあります。長期間有効なパスワードの代わりに、 短命の IAM 認証トークン を使用します。静的なエンドポイントの代わりに、複数のアベイラビリティゾーンにまたがる分散クラスターエンドポイントを使用します。接続タイムアウトのトラブルシューティング、トークンの有効期限管理、ドライバーの初回設定など、接続パターンを理解しておくと一般的な問題を回避できます。 本記事では、接続文字列の設定方法、Python・Java・Node.js でのドライバー設定、認証・接続プーリング・ライフサイクル管理のベストプラクティスについて説明します。 接続アーキテクチャ Amazon Aurora DSQL は、従来の PostgreSQL デプロイとは根本的に異なる分散接続アーキテクチャを採用しています。アプリケーションは単一のデータベースインスタンスに接続するのではなく、複数のアベイラビリティゾーンにトラフィックを分散するルーティングレイヤーを介して接続します。ドライバーや接続文字列を設定する前に、エンドポイントの構造とワイヤプロトコルの動作を理解しておく必要があります。以下のセクションでは、接続前に知っておくべきエンドポイント形式とワイヤプロトコルの互換性について説明します。 エンドポイント形式 Amazon Aurora DSQL クラスターのエンドポイントは次のパターンに従います。 <cluster-id>.dsql.<region>.on.aws 例: weaxxxxxxxxxxxxxxxxqdqqm.dsql.us-east-1.on.aws デュアルスタック形式で、IPv4 と IPv6 の両方をサポートしています。エンドポイントは Aurora DSQL の分散ルーティングレイヤーに接続し、複数のアベイラビリティゾーンへの接続分散を自動的に処理します。 主要な接続パラメータ: Host: クラスターエンドポイント (上記の形式)。 Port: 5432 (PostgreSQL 標準ポート)。 Database: postgres (デフォルトのデータベース名)。 SSL Mode: すべての接続で必須。 ワイヤプロトコルの互換性 Amazon Aurora DSQL は標準の PostgreSQL v3 ワイヤプロトコルを使用しており、psql、pgjdbc、psycopg、psycopg2 などの一般的な PostgreSQL ドライバーとの互換性があります。既存のツールやライブラリは、最小限の設定変更で利用できます。 認証とセキュリティ Aurora DSQL では、従来の PostgreSQL データベースとは異なる認証方式とネットワークセキュリティを採用しています。以下のセクションでは、IAM ベースのトークン生成、ネットワーク接続オプション、認証情報管理のベストプラクティスについて説明します。 IAM ベースの認証 Amazon Aurora DSQL は短命の IAM 認証トークンのみを使用します。IAM 認証には以下のセキュリティ上の利点があります。 セキュリティの強化: パスワードの保存やローテーションに伴うリスクを軽減します。 アクセス制御の一元化: AWS Identity and Access Management (AWS IAM) による統一的な権限管理が可能です。 監査証跡: 接続試行が AWS CloudTrail に記録されます。 自動期限切れ: トークンはデフォルトで 15 分後に期限切れになります (最大 1 週間まで設定可能)。デフォルトを超える有効期間の延長は推奨しません。漏洩した長命トークンは重大なセキュリティリスクです。延長が必要な場合は、トークンのスコープを最小限の権限に絞り、CloudTrail で長命トークンを監視してください。 アクセス制御パターンとセキュリティのベストプラクティスの詳細については、 Amazon Aurora DSQL のセキュリティ対策：アクセス制御のベストプラクティス を参照してください。 AWS Command Line Interface (AWS CLI) でのトークン生成: 以下のコマンドで、AWS CLI を使用して Aurora DSQL クラスターの認証トークンを生成します。 aws dsql generate-db-connect-admin-auth-token \ --region us-east-1 \ --hostname <your-cluster-id>.dsql.us-east-1.on.aws 必要な IAM 権限: { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "dsql:DbConnect", "dsql:DbConnectAdmin" ], "Resource": "arn:aws:dsql:region:account-id:cluster/cluster-id", "Condition": { "IpAddress": { "aws:SourceIp": ["10.0.0.0/8"] } } } ] } dsql:DbConnect: 通常のデータベースユーザーとしての接続権限を付与します。 dsql:DbConnectAdmin: 管理者権限を付与します。 最小権限の原則 ユースケースごとに必要最小限の権限のみを付与します。 標準のアプリケーションアクセスには dsql:DbConnect を使用します。 dsql:DbConnectAdmin は管理タスク専用に限定します。 既知のネットワーク範囲のみにアクセスを制限するため、IP ベースの 条件 を追加します。 ネットワークセキュリティ Amazon Aurora DSQL はパブリックアクセスとプライベートアクセスの両方をサポートしています。 パブリックエンドポイントアクセス は以下によりセキュリティを確保します。 IAM ベースの認証 – パスワードベースの脆弱性を軽減します。 IP ベースのアクセス制御 – IAM ポリシー条件により接続を制限します。 SSL/TLS 暗号化の必須化 – 暗号化されたトランスポートが必須です。 プライベートエンドポイントアクセス (AWS PrivateLink) はトラフィックを AWS 内に保持します。 VPC インターフェイスエンドポイント – インターネットに公開されないプライベート接続。 VPC エンドポイントポリシー – ネットワークレベルの追加のアクセス制御。 セキュリティグループ – 特定のサブネットとポートへのトラフィックを制限。 VPC エンドポイントポリシーをアタッチして、エンドポイント経由で接続できるプリンシパルを制限します。設定しない場合、VPC 内のすべてのプリンシパルがエンドポイントを使用してクラスターに接続できます。 { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::account-id:role/your-app-role" }, "Action": [ "dsql:DbConnect" ], "Resource": "arn:aws:dsql:region:account-id:cluster/cluster-id" } ] } ネットワークエグレス制御 インバウンドアクセスの制御だけでは不十分です。エグレス制限がなければ、侵害されたアプリケーションが外部にデータを送出する可能性があります。アプリケーションホストからのアウトバウンドトラフィックを制限してください。 セキュリティグループのアウトバウンドルール – 必要な宛先 (Aurora DSQL のポート 5432、AWS サービスエンドポイントなど) へのトラフィックのみを許可します。 VPC Network ACLs – セカンダリレイヤーとしてサブネットレベルのエグレス制限を追加します。 VPC Flow Logs – 予期しないアウトバウンドトラフィックパターンを監視します。 AWS Network Firewall – セキュリティグループを超えた、きめ細かいエグレスフィルタリングに使用します。 認証情報の管理 Aurora DSQL に接続する際の認証情報管理のベストプラクティスを以下に示します。 認証情報をハードコードしない – アプリケーションコードに埋め込まないでください。 環境変数を使用する – ホスト名やリージョンなどの設定値には環境変数を使用します。 トークンを動的に生成する – 接続時に AWS SDK 呼び出しでトークンを生成します。 AWS Secrets Manager を使用する – 接続設定の保存に利用します。 IAM 認証情報を定期的にローテーションする – AWS のセキュリティベストプラクティス に従います。 認証試行を監視する – CloudTrail による異常検知 を活用します。 認証トークンをログに記録・永続化しない – トークンはデータベースパスワードとして渡されるため、接続文字列ログ、アプリケーションログ、エラーメッセージに漏洩する可能性があります。ロギングフレームワークでパスワードフィールドを確実にマスクし、URL や診断出力にトークンを含めないでください。 接続の監視 CloudTrail はすべての Aurora DSQL 認証イベントを記録します。異常な接続アクティビティを検知するアラートを設定してください。 認証失敗 – DbConnect または DbConnectAdmin の繰り返し失敗に対して Amazon CloudWatch アラームを作成し、認証情報の悪用や設定ミスを検知します。 予期しない送信元 IP やリージョン – CloudTrail イベントを sourceIPAddress と awsRegion でフィルタリングし、想定外のネットワーク範囲からの接続をフラグ付けします。 異常な接続パターン – CloudWatch 異常検知を使用して、接続量の急増や通常の運用時間外の接続を監視します。 長命トークンの使用 – 要求された有効期間がデフォルトの 15 分を超える GenerateDbConnectAdminAuthToken 呼び出しを追跡します。 自動対応として、CloudTrail イベントの Amazon EventBridge ルールを使用して、 Amazon Simple Notification Service (Amazon SNS) 通知や AWS Lambda による修復ワークフローをトリガーできます。 SSL/TLS の設定 Amazon Aurora DSQL は接続に暗号化トランスポートを必須としています。 sslmode=require – 暗号化の最小要件。 sslmode=verify-full – 完全な証明書検証とホスト名検証によるセキュリティ強化。 本番環境の推奨事項: verify-full モードを使用してください。証明書チェーンとホスト名の両方を検証し、中間者攻撃への対策となります。 Amazon Aurora DSQL コネクター AWS は Amazon Aurora DSQL コネクターを提供しています。コネクターは透過的な認証レイヤーとして機能し、IAM トークンの生成とリフレッシュを自動的に処理します。認証コードではなく、接続コードだけを記述すれば済みます。 利用可能なコネクター JDBC Connector – 標準の Java データベース接続レイヤーに IAM 認証を統合し、既存の Java データアクセスフレームワークとシームレスに連携します。 Python Connector – psycopg、psycopg2、asyncpg (非同期ワークロード) をサポートします。認証プラグインとして動作し、既存の接続ワークフローを変更せずにトークン生成を処理します。 Node.js Connectors – node-postgres (pg) と Postgres.js の両方に対応しています。 Go Connector – pgx をラップし、IAM 認証の自動処理、SSL 設定、接続管理を行います。 Ruby Connector – Ruby アプリケーション向けの IAM ベース認証を提供します。 .NET Connector – Npgsql をラップし、IAM 認証の自動処理、SSL 設定、接続管理を行います。 Rust Connector – SQLx をラップし、IAM 認証の自動処理、SSL 設定、接続管理を行います。 実装の詳細については、 Amazon Aurora DSQL Connectors GitHub を参照してください。 コネクター使用の利点 トークン管理の自動化 – クラスターホスト名からのリージョン自動検出を含む、IAM トークン生成とリフレッシュのライフサイクル全体を管理します。 シームレスな統合 – 接続プーリングライブラリ (HikariCP、psycopg ConnectionPool、psycopg2 ThreadedConnectionPool、asyncpg ネイティブプール) と透過的に連携します。 フレームワークサポート – Spring Boot、Django など、標準的なデータベースドライバーインターフェイスに依存するフレームワークと互換性があります。 ボイラープレートの削減 – 手動のトークン生成コードの記述やメンテナンスが不要です。 クイックスタート例 (JDBC コネクター) 以下の例は、Java で JDBC コネクターを使用して Aurora DSQL クラスターに接続する方法を示しています。コードを実行する前に、プロジェクトの依存関係に Aurora DSQL JDBC ドライバーを追加し、IAM 認証情報を設定済みであることを確認してください (環境変数、インスタンスプロファイル、または AWS 認証情報ファイルのいずれか)。JDBC URL に jdbc:aws-dsql:// プレフィックスを設定し、 DriverManager.getConnection を呼び出します。コネクターが IAM トークン生成を自動的に処理するため、手動のトークンコードは不要です。コネクターは、トークンを長期間キャッシュするのではなく、新しい接続または接続プールの初期化ごとに新しいトークンを生成します。 // Change the JDBC URL prefix to jdbc:aws-dsql:// String url = "jdbc:aws-dsql://" + clusterEndpoint + ":5432/postgres"; Connection conn = DriverManager.getConnection(url, "admin", ""); // No password needed — the connector handles token generation automatically 手動接続パターン コネクターを使用しない場合 (学習目的、デバッグ、カスタム認証フローなど) は、AWS SDK で IAM トークンを手動で生成し、データベースパスワードとして渡せます。 接続には最低限 sslmode=require が必要です。トークンは、呼び出し元の IAM アイデンティティから派生し、特定のクラスターホスト名にスコープされた、有効期限付きの認証情報です。 SDK トークン生成メソッド Python (boto3) generate_db_connect_admin_auth_token Java DsqlClient.generateDbConnectAdminAuthToken Node.js GenerateDbConnectAdminAuthTokenCommand Go dsql.GenerateDbConnectAdminAuthToken Ruby Aws::DSQL::Client#generate_db_connect_admin_auth_token .NET AmazonDSQLClient.GenerateDBConnectAdminAuthToken Rust dsql::Client::generate_db_connect_admin_auth_token 生成したトークンを、接続確立時にデータベースパスワードとして渡します。 完全なコード例については、 Amazon Aurora DSQL ユーザーガイド と Amazon Aurora DSQL Code Samples を参照してください。 接続プーリング 適切に設定された接続プーリングは、レイテンシーを低減し、Aurora DSQL の接続レート制限への到達を回避します。本セクションでは、プールの設定、サイジング、考慮すべき主要な制約について説明します。 クライアント側プーリングが必須 Aurora DSQL にはサービスレイヤーでの組み込み接続プーリングがありますが、新しい接続ごとに TLS ハンドシェイクとサービスによる認証が必要です。接続をプールすれば、そのコストをリクエストごとではなく一度だけ支払えばよくなります。 PgBouncer や pgpool-II などのサーバー側コネクションプーラーは使用しないでください。 これらのツールは従来の PostgreSQL アーキテクチャ向けに設計されており、Amazon Aurora DSQL の分散接続処理で可用性の問題を引き起こす可能性があります。 プール設定 最も重要なパラメータは 最大接続寿命 です。Amazon Aurora DSQL は接続期間に 60 分のハードリミットを適用します。プールの最大ライフタイムを 45〜55 分に設定し、Aurora DSQL が接続を切断する前にプロアクティブにリサイクルしてください。 Java で HikariCP を使用する場合は、 maximumPoolSize 、 maxLifetime (60 分未満) を設定し、手動のトークン管理を避けるために JDBC Connector を使用します。HikariCP の完全な設定については、公式ガイド「 Using Amazon Aurora DSQL with JDBC, Hibernate, and HikariCP 」を参照してください。 Python の場合は、手動で生成した IAM トークンを使用して psycopg2 で接続するか ( Amazon Aurora DSQL ユーザーガイド – Psycopg2 の使用 を参照)、 Amazon Aurora DSQL Python Connector (GitHub) を使用してトークンのボイラープレートを完全に排除できます。 接続制限とクォータ 接続プールのサイジングを決定する前に、Amazon Aurora DSQL の接続制限を理解しておく必要があります。Amazon Aurora DSQL は接続作成レートの制御に トークンバケットアルゴリズム を使用しています。新しい接続ごとにトークンを 1 つ消費し、バケットは一定レートで補充されます。バケット容量を上限としてバーストも可能です。 クラスターあたりのデフォルト制限は以下のとおりです。 クォータ デフォルト値 備考 最大確立接続数 10,000 クラスターごとの制限。Service Quotas で調整可能 新規接続レート (定常状態) 100 接続/秒 トークンバケットの補充レート バースト容量 1,000 接続 補充前の t=0 時点で利用可能なトークン数 最大接続期間 60 分 ハードリミット。1 時間後に接続切断 最大トランザクション期間 5 分 トランザクションごと (BEGIN から COMMIT まで) トークンバケットの実際の動作: アプリケーション起動時に 1,000 接続を開いた場合、すべて成功します (バーストトークン 1,000 個)。ただし、バケットは空になります。1,001 番目の接続は、バケットが 100 トークン/秒で補充されるのを待つ必要があります。クライアント側プーリングが重要な理由はここにあります。接続を再利用すれば、作成バジェットの消費を避けられます。 接続ライフサイクル Aurora DSQL の接続には最大ライフタイムが固定されており、有効期限付きトークンを使用するため、アプリケーションは接続のリサイクルとトークンリフレッシュを適切に処理する必要があります。 1 時間の接続制限 Amazon Aurora DSQL のすべての接続の最大ライフタイムは 60 分です。1 時間後、接続がアイドル状態でもアクティブ状態でも、サービスが接続を切断します。これは設計上の仕様です。Aurora DSQL の分散アーキテクチャでは内部コンポーネントがバックグラウンドで障害復旧や交換されるため、1 時間の制限によりアプリケーションが定期的に新しい接続を確立し、正常なインフラに自然に接続されるようになっています。Aurora DSQL は切断にジッターを適用するため、接続が同時に切断されることはなく、トランザクション中の接続は切断されません。 トークンの有効期限管理 トークンはデフォルトで 15 分後に期限切れになります (最大 1 週間まで設定可能)。重要なポイント: 有効なトークンで接続が確立された後は、トークンが期限切れになっても接続は有効なままです。新しいトークンが必要なのは新しい接続を確立するときだけであり、60 分の接続制限がバインディング制約となります。トークンの有効期限は制約になりません。 トークンはリージョンスコープでもあります。 region=us-east-1 で生成されたトークンは us-east-1 エンドポイントへの接続にのみ有効で、同じマルチリージョンクラスターの us-east-2 エンドポイントには使用できません。マルチリージョンデプロイでは、アプリケーションが接続する各リージョンエンドポイントに対して個別のトークンを生成してください。 推奨アプローチ: Amazon Aurora DSQL コネクター を使用してください。新しい接続ごとに自動的にトークンを生成するため、トークン管理コードが不要です。 接続リトライロジック 分散システムでは一時的な接続障害は例外ではなく通常の動作です。内部コンポーネントに障害が発生した場合、Aurora DSQL が自動的に処理しますが、アプリケーション側ではその接続に対するエラーが発生します。 SerializationFailure (OCC コンフリクト) と OperationalError (一時的な障害) の両方に対して、エクスポネンシャルバックオフとジッターを伴うリトライロジックを実装してください。推奨パターンについては、Amazon Aurora DSQL の同時実行制御ドキュメントと AWS Builders’ Library – タイムアウト、リトライ、ジッター付きバックオフ を参照してください。 マルチリージョン接続パターン 地理的リージョンをまたいだ高可用性が必要なアプリケーション向けに、Amazon Aurora DSQL マルチリージョンクラスターはリージョンエンドポイントで読み書き両方をサポートするアクティブ-アクティブアーキテクチャを提供します。 アクティブ-アクティブ マルチリージョンアーキテクチャ Amazon Aurora DSQL マルチリージョンクラスターは、アクティブ-アクティブアクセスのためのリージョンエンドポイントを提供します。アプリケーションはどちらのエンドポイントにも接続して読み書きが可能で、地理的な分散とリージョンフェイルオーバーを実現します。 エンドポイント選択戦略 レイテンシーのために最寄りのリージョンエンドポイントに接続し、プライマリリージョンに問題がある場合はセカンダリエンドポイントへのヘルスベースのフェイルオーバーを実装します。 フェイルオーバーロジックは事前にテストしておいてください。 一般的な接続問題のトラブルシューティング 本セクションでは、Aurora DSQL に接続する際に発生しやすいエラーや接続障害と、その原因および推奨される対処方法について説明します。認証失敗、タイムアウトエラー、ドライバーの互換性の問題のいずれの場合も、以下のガイダンスで問題を迅速に診断・解決できます。 問題 1: “Connection Attempt Failed” 症状: Amazon Aurora DSQL エンドポイントへの接続を確立できない 一般的な原因: IAM 権限の不備、認証トークンの期限切れ、ネットワーク接続の問題、エンドポイント形式の誤り 解決方法: 接続失敗を解決するには、以下の手順を順に実行してください。まず、IAM ユーザーまたはロールのポリシーに適切な dsql:DbConnect または dsql:DbConnectAdmin 権限がアタッチされていることを確認します。次に、認証トークンが期限切れでないことを確認します。トークンは短命であり、新しい接続試行のたびに再生成が必要です。クラスターエンドポイントの形式が正しいこと、ポート 5432 へのアウトバウンドトラフィックをブロックするネットワークレベルの制限 (セキュリティグループ、VPC ルーティングルール、ファイアウォールポリシーなど) がないことを確認してください。以下の例は、新しいトークンを生成して明示的なエラーハンドリングで接続を試みることで、根本原因を特定しやすくする方法を示しています。 # Verify IAM permissions aws iam get-user # Test token generation aws dsql generate-db-connect-admin-auth-token \ --region us-east-1 \ --hostname <cluster-id>.dsql.us-east-1.on.aws # Test network connectivity nc -zv <cluster-id>.dsql.us-east-1.on.aws 5432 問題 2: “Access Denied” エラー 症状: 接続は確立されるが認証に失敗する 解決方法: IAM ポリシーに dsql:DbConnect または dsql:DbConnectAdmin が含まれていることを確認します。 IAM ポリシーのアクセス制限条件 (aws:SourceIp、aws:RequestedRegion、aws:PrincipalTag など) を確認します。基本権限が付与されていても、条件によって接続がサイレントに拒否される場合があります。 トークンが正しいリージョンで生成されていることを確認します。 AWS 認証情報が期限切れでないことを確認します。 問題 3: PrivateLink 接続の問題 VPC の外部から PrivateLink 経由で接続する場合、クライアントはクラスターエンドポイントを VPC エンドポイント IP に解決する必要があります。2 つのアプローチがあります。 オプション 1: PGHOSTADDR で IP アドレスをオーバーライド export PGHOSTADDR=<vpce-ip-address> export HOSTNAME=<cluster-id>.dsql.<region>.on.aws psql -h $HOSTNAME -U admin -d postgres SNI に正しいホスト名を使用しながら VPC エンドポイント IP に接続します。 オプション 2: amzn-cluster-id 接続オプションを使用 (DNS 不要) export CLUSTERID=<cluster-id> export PGOPTIONS="-c amzn-cluster-id=$CLUSTERID" psql -h <vpce-endpoint> -U admin -d postgres クラスター識別子を接続オプションとして直接渡し、DNS 解決を不要にします。VPC エンドポイントのプライベート DNS が設定されていない場合に便利です。 詳細については、 PrivateLink 接続エンドポイントを使用した Amazon Aurora DSQL への接続 を参照してください。 問題 4: 接続プールのヘルスチェックストーム 症状: 負荷スパイク時の大量の接続切断と再確立、カスケード的なヘルスチェック失敗、接続レート制限エラー 原因: 短いヘルスチェック間隔 (HikariCP のデフォルト 5 秒タイムアウトなど) により、数千のプール接続に対して同時にヘルスチェックがトリガーされる場合があります。多数のチェックが同時に失敗すると、プールがすべての接続の再確立を試み、100 接続/秒のレート制限を使い果たして障害がカスケードします。 解決方法: すべての接続に固定間隔を使用するのではなく、接続間でヘルスチェック間隔をずらします。 不要な接続リサイクルを避けるため、アイドルタイムアウトを増やします。 HikariCP の場合、 connectionTimeout と validationTimeout をデフォルトより長く設定します。 maxLifetime に十分なジッターを設定します (HikariCP は自動的に ±2.5% を適用)。同期した接続期限切れを回避できます。 まとめ 本記事では、JDBC や PostgreSQL 互換クライアント、AWS CLI など、さまざまなドライバーやツールを使用して Amazon Aurora DSQL に接続する方法を紹介しました。接続アーキテクチャ、IAM ベースの認証トークンの生成と使用方法、認証情報管理と接続プーリングのベストプラクティスについて解説しました。クイックスタート例と、一般的な接続問題の診断・解決に役立つトラブルシューティングガイドも提供しました。 実際に試してみたいですか? プレイグラウンド でセットアップなしに Aurora DSQL を体験できます 。接続の操作、クエリの実行、本記事で紹介した機能の確認を実際に行えます。 著者について Alex Pawvathil Alex は、AWS のシニアテクニカルアカウントマネージャーで、データベースアーキテクチャとエンタープライズ規模の実装を専門としています。クラウドアーキテクチャ、データベース戦略、エンタープライズアドバイザリーで 14 年以上の実務経験があり、Amazon RDS for SQL Server の実装とエンタープライズ規模のデプロイメントの専門家です。 Sandhya Khanderia Sandhya は、AWS のシニアテクニカルアカウントマネージャー兼データアナリティクススペシャリストです。AWS のお客様と密接に連携し、継続的なサポートと技術ガイダンスを提供しています。ベストプラクティスを活用したソリューションの計画・構築を支援しながら、AWS 環境の運用状態をプロアクティブに健全に保つことに取り組んでいます。 Rob Petersen Rob は、AWS のシニアテクニカルアカウントマネージャーで、IT 業界での 20 年の経験を活かし、お客様のクラウド導入ジャーニーを支援しています。大規模なクラウドマイグレーションのリードとハイブリッドインフラストラクチャの運用管理の両方の経験があり、クラウド導入時に組織が直面する課題と機会について独自の視点を持っています。 この記事は Kiro が翻訳を担当し、Solutions Architect の Arisa Izuno がレビューしました。

はじめに こんにちは、カケハシで Pocket Musubi というサービスの開発をしている宮里です。 Pocket Musubi は多数のリポジトリで構成されており、開発環境の構築は毎回それなりの時間がかかる作業でした。今回、その中でも主要な3リポジトリの環境構築を、Claude Code の「スキル」機能を使って自動化してみました。 本記事では、スキルの設計や工夫、使ってみた感想を紹介します。 環境構築がつらい Pocket Musubi の主要コンポーネントは、バックエンドAPI（Django / Docker Compose）、薬局管理画面（Next.js）、患者向けLIFFアプリ（N…