Readyset Docs

Setting up a fleet

Import targets from CSV, discover RDS and Aurora instances from AWS, and manage fleet credentials.

Before you can run rdst fleet audit, you need a fleet. RDST gives you three ways to build one:

PathWhen to useCommand
AWS discoveryYour databases are AWS RDS / Aurorardst fleet discover --regions us-east-1
CSV importYou've a list of databases in a spreadsheetrdst fleet import --from fleet.csv
Interactive wizardYou want guided setuprdst fleet configure

Option A: AWS discovery

rdst fleet discover calls the AWS RDS API and registers every RDS instance and Aurora cluster it finds. Use it to import connection metadata from AWS.

Set up AWS credentials if you've not already:

aws configure sso
aws sts get-caller-identity   # verify
export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_DEFAULT_REGION=us-east-1
aws sts get-caller-identity   # verify

Run discovery:

rdst fleet discover --regions us-east-1,us-west-2

Use --name-pattern to scope to specific instance names, and --engine-filter postgresql or mysql to filter by engine.

Set credentials when prompted:

  • [1] Shared password: one password for all discovered instances
  • [2] Individual: set user/password per instance
  • [3] Skip: register targets without credentials (configure later)

Export the password env vars RDST prints. Discovery outputs a set of export FOO_PASS=... lines you need to run in your shell. Passwords saved in a working OS keychain persist across sessions. Otherwise, set the environment variables in each session.

What Aurora clusters look like after discovery

For every Aurora cluster, discovery creates:

TargetEndpointTags
<cluster>-writerCluster writer endpointaurora, writer
<cluster>-reader-<n>Each reader instanceaurora, reader

All instances from one cluster share the same group, so you can audit just that cluster with rdst fleet audit --group <cluster-name>.

Flags

FlagPurpose
--regions <list>Comma-separated AWS regions
--engine-filter {postgresql,mysql,all}Filter by engine
--name-pattern <glob>Only discover instance names matching a glob
--password-env <var>Env var for all discovered targets' passwords
--user <username>Override default DB user
--group <name>Assign all discovered targets to one group
--dry-runPreview without saving

Option B: CSV import

rdst fleet import --from ./fleet.csv --password-env FLEET_PASS

CSV format

Each row must include name, host, and engine.

You can also set the connection's port, database, and user. Use group and tags to organize targets. Set password_env or password_secret_arn to tell RDST where to read the password.

fleet.csv
name,host,engine,port,database,user,group,tags,password_env
prod-orders,db1.example.com,postgresql,5432,orders,rdst_ro,orders-prod,pii,PROD_ORDERS_PASS
prod-inventory,db2.example.com,postgresql,5432,inventory,rdst_ro,inventory-prod,,PROD_INV_PASS
staging-orders,staging.example.com,postgresql,5432,orders,rdst_ro,staging,,STAGING_PASS
legacy-mysql,legacy.example.com,mysql,3306,appdb,rdst_ro,legacy,mysql,LEGACY_PASS

tags is a semicolon-separated list (aurora;writer;pii). password_env can be set per-row or left blank to fall back to the global --password-env value.

Flags

FlagPurpose
--from <csv>Path to the CSV file
--password-env <var>Default env var for any row with blank password_env
--group <name>Assign all imported rows to one group (overrides CSV)
--tag <tag>Add a tag to all imported rows (repeatable)
--dry-runPreview what would be imported

Option C: Interactive wizard

rdst fleet configure

Choose AWS discovery or CSV import from the menu and enter the requested fields.

Listing and filtering the fleet

Once your fleet is populated:

# List every target
rdst fleet list

# Filter by group
rdst fleet list --group orders-prod

# Filter by tag
rdst fleet list --tag aurora --tag writer

# JSON output
rdst fleet list --json

Changing a target's group or tags

Groups and tags are per-target attributes, so you change them through rdst configure edit:

# Move a target into a different group
rdst configure edit prod-orders-reader-2 --group orders-prod-readers

# Replace the tags on a target
rdst configure edit prod-orders-writer --tags aurora,writer,pii

# Clear a target's group (back to ungrouped)
rdst configure edit legacy-mysql --group ""

The change is local and takes effect immediately, every subsequent rdst fleet list --group ... or rdst fleet audit --group ... will reflect it. There's no bulk "move group" command; if you need to re-group several targets at once, loop over them in your shell:

for name in prod-orders-reader-1 prod-orders-reader-2 prod-orders-reader-3; do
  rdst configure edit "$name" --group orders-prod-readers
done

Checking connectivity

rdst fleet status
rdst fleet status --group orders-prod

status opens a connection to every target (or every filtered target) and prints latency plus any errors. It's the first thing to run after import or discovery to confirm passwords are exported and network paths are clear.

Name                  Host                   Engine      Status     Latency
────────────────────  ─────────────────────  ──────────  ─────────  ────────
prod-orders           db1.example.com        postgresql  ✓ OK        12 ms
prod-inventory        db2.example.com        postgresql  ✓ OK        15 ms
staging-orders        staging.example.com    postgresql  ✓ OK        28 ms
legacy-mysql          legacy.example.com     mysql       ✗ FAILED     -
                      authentication failed (LEGACY_PASS not set)

Using AWS Secrets Manager

If your passwords live in AWS Secrets Manager, set password_secret_arn on a target (either in the CSV or during discovery). RDST will fetch the secret value at the start of each session and cache it for the duration of the run.

name,host,engine,password_env,password_secret_arn
prod-orders,db1.example.com,postgresql,,arn:aws:secretsmanager:us-east-1:123...:secret:prod-orders

Precedence: password_env wins if both are set, so you can override with a local env var when needed.

See also