Skip to main content

Generate Aurora DSQL auth tokens with Atlas

Aurora DSQL authenticates connections with short-lived IAM tokens rather than static passwords. Atlas can generate those tokens in atlas.hcl with the aws_dsql_token data source and use them directly in your DSQL connection URL.

With this setup, Atlas generates the token at runtime from your environment configuration.

Before you start​

You need:

  1. An Aurora DSQL cluster endpoint, for example cluster-id.dsql.us-east-1.on.aws.
  2. AWS credentials available to Atlas, either through environment variables, a shared profile, or an assumed role.
  3. IAM permission to connect. Use dsql:DbConnectAdmin for the built-in admin role, or dsql:DbConnect for a custom database role.
  4. Atlas installed and logged in if you are using Aurora DSQL support.

Generate an admin token​

For the built-in admin role, set admin = true and embed the generated token in the dsql:// URL:

atlas.hcl
locals {
  endpoint = "cluster-id.dsql.us-east-1.on.aws"
}

data "aws_dsql_token" "db" {
  endpoint = local.endpoint
  region   = "us-east-1"
  admin    = true
}

env "dsql" {
  url = "dsql://admin:${urlescape(data.aws_dsql_token.db)}@${local.endpoint}:5432/postgres?sslmode=require"
  dev = "docker://dsql/16/dev"
}

The important parts are:

  • endpoint is the Aurora DSQL cluster endpoint.
  • region is optional if your AWS configuration already sets a default region.
  • admin = true tells Atlas to generate an admin auth token.
  • urlescape() is required because the token contains characters that must be URL-encoded in the connection string.

With that in place, Atlas can generate the token at runtime:

atlas schema inspect --env dsql --config "file://atlas.hcl"

You can use the same environment for other commands too:

atlas migrate apply --env dsql --config "file://atlas.hcl"

Use a custom database role​

If you do not want to connect as admin, create a database role with LOGIN, map your IAM identity to it, and let Atlas generate a regular DSQL token.

CREATE ROLE atlas_migrations WITH LOGIN;
AWS IAM GRANT atlas_migrations TO 'arn:aws:iam::123456789012:role/AtlasDSQLConnect';

Grant whatever database privileges that role needs, then configure Atlas to use it:

atlas.hcl
locals {
  endpoint = "cluster-id.dsql.us-east-1.on.aws"
  username = "atlas_migrations"
}

data "aws_dsql_token" "db" {
  endpoint = local.endpoint
  region   = "us-east-1"
}

env "dsql" {
  url = "dsql://${local.username}:${urlescape(data.aws_dsql_token.db)}@${local.endpoint}:5432/postgres?sslmode=require"
}

When admin is omitted, Atlas generates a regular user token.

Use a profile or assume a role​

aws_dsql_token can read credentials from a named AWS profile, and it can assume another IAM role before signing the token:

atlas.hcl
data "aws_dsql_token" "db" {
  endpoint = "cluster-id.dsql.us-east-1.on.aws"
  region   = "us-east-1"
  profile  = "prod"
  role_arn = "arn:aws:iam::123456789012:role/AtlasDSQLConnect"
  admin    = true
}

Use profile when Atlas should load credentials from ~/.aws/config and ~/.aws/credentials. Use role_arn when Atlas should assume a different IAM role before generating the token.