ARNscopeDocs

RDS and Aurora PostgreSQL

Last updated 15 October 2026

ARNscope lists the PostgreSQL databases in your account and connects to them with IAM database authentication: it asks AWS for a short-lived token and uses it as the password. There are no database passwords to type, store or rotate. Once connected you get a SQL console, a browsable object tree, query history and a query plan view.

A narrated tour of under two minutes, with captions: connecting through a tunnel, the object tree, completion, results, plans, transactions, favourites, Top SQL and metrics. Sample data.

Which databases appear

Open RDS and choose a profile and region. ARNscope lists:

MySQL, MariaDB and Aurora MySQL are listed too; see MySQL, StarRocks and ClickHouse. SQL Server, Oracle and Db2 are not listed.

Set up the database for IAM authentication

You do this once per database, outside ARNscope.

  1. Enable IAM database authentication on the DB instance or cluster.

  2. Create a database user and grant it the rds_iam role. Connect as the master user or another user who can create users and grant privileges:

    CREATE USER ops_readonly;
    GRANT rds_iam TO ops_readonly;
    GRANT CONNECT ON DATABASE commerce TO ops_readonly;
    GRANT USAGE ON SCHEMA public TO ops_readonly;
    GRANT SELECT ON ALL TABLES IN SCHEMA public TO ops_readonly;
    

    The first two lines are what IAM authentication needs. The rest are ordinary PostgreSQL grants for what the user may read. What the IAM role can reach through the user is limited to what the database user can reach. The name must match the case of the name in the IAM policy.

  3. Allow your IAM role to connect as that user with rds-db:connect (next section).

A PostgreSQL user that has the rds_iam role must log in with IAM: password login stops working for it, including for the master user. See Creating a database account using IAM authentication.

The IAM permission

The role you sign in with needs rds-db:connect on the database user:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "rds-db:connect",
    "Resource": "arn:aws:rds-db:us-east-1:123456789012:dbuser:db-ABCDEFGHIJKL01234/ops_readonly"
  }]
}

The resource format is arn:aws:rds-db:<region>:<account-id>:dbuser:<DbiResourceId>/<database-user>. For an instance, DbiResourceId is its Resource ID (it starts with db- and does not change). For Aurora, use the cluster’s DbClusterResourceId. rds-db:connect is not an rds: action and does not appear in the console’s usual RDS permissions. See Creating and using an IAM policy for IAM database access.

Connect

  1. Open RDS, choose the database, and stay on the Connect tab.
  2. Choose the Mode: Read only or Write.
  3. If the database has a reader endpoint, choose what the tunnel forwards to: Writer endpoint or Reader endpoint.
  4. Choose how you reach the database (below).
  5. Enter the Database user and the Database, and click Connect.

ARNscope remembers each connection (user, database, mode and tunnel) under Previous connections on this Mac, so next time one click on Connect is enough. You can forget one with the trash button.

Through an ARNscope tunnel

If you have an SSM tunnel that forwards to this endpoint, a Tunnel picker appears with ARNscope tunnel and My own tunnel. Pick the tunnel and, if it is stopped, click Start tunnel (this opens an SSM session). ARNscope then connects inside the app and nothing listens on a local port. The tunnel must forward to the endpoint you chose, writer or reader. If you have an RDS tunnel that goes to a different endpoint, ARNscope tells you which one it reaches.

Choose the endpoint and ARNscope tunnel, start the tunnel and connect: the console header shows Read only and Connected.

Through your own tunnel

Start your own tunnel (SSM, SSH or anything else) that forwards a local port to the endpoint and port shown on the page, then enter that Local tunnel port. ARNscope connects to 127.0.0.1 on that port and checks that something is listening. The TLS certificate is still checked against the RDS endpoint name, so use the real endpoint in the tunnel, not a custom DNS name.

What happens when you connect

The SQL console

After connecting, the Query tab has:

Feature Details
Editor SQL editor with highlighting and completion from the database’s objects: keywords (upper case), tables, views, functions and procedures, and the columns of the tables in the statement, each captioned with its table. A column that more than one of those tables has is inserted with the table’s alias, for example o.customer_id. Ctrl+Cmd+L formats the statement at the cursor, or the selection. Your text is saved per database on this Mac and survives restarts.
Run Run executes the statement at the cursor, or the selection. Run all executes everything. Shortcut: Cmd+Enter. A single SELECT without LIMIT, FETCH or INTO gets LIMIT 500 added; write LIMIT ALL to get every row.
Results A grid with sorting, copy and export. At most 1,000 rows and 1 MiB are kept per result; the header says when a result was cut. Several statements show several results.
Time limit ARNscope sets none: a query runs until it finishes, the database’s own statement_timeout stops it, or you press Cancel. The toolbar shows how long the query has been running.
Transactions Statements commit on their own (Auto-commit). Begin, Commit and Roll back group them, and the header shows Transaction open while one is open.
Explain Explain plan shows the estimated plan as a diagram without running the statement; the most expensive step is marked in red. Explain analyze runs the statement and adds real timings and row counts, and where the planner’s estimate was off. It is refused, before anything runs, for anything but a plain SELECT (a SELECT with an INSERT, UPDATE, DELETE or MERGE in a WITH is refused too).
Database tree Database objects on the right lists schemas, tables, views, functions, indexes and more, filterable. Open a table to browse 200 rows per page with a WHERE filter and sorting. View source shows an object’s definition. The tree is saved and refreshed on demand.
History Query history keeps the last 500 statements per database on this Mac, as they ran (with an added LIMIT 500 or the EXPLAIN wrapper), with duration, row count and result. Click one to add it to the console.
Favourites The star saves the statement at the cursor, with an optional label, under Favourites in the target list. A favourite remembers its profile, region, target and database: opening it switches there and adds the SQL to the console. It never runs on its own.
Switching The database menu in the header switches to another database on the same server.
Completion offers keywords, tables and views, and columns captioned with their table; a column two joined tables share comes in as o.customer_id.
Ctrl+Cmd+L formats the statement at the cursor, keywords in upper case.
Cmd+Enter runs the statement under the cursor. The grid sorts, copies as JSON, exports to CSV, and shows JSON values in the value viewer.
Explain plan draws the estimated plan; the costliest step is red. Click a step for its details.
Explain analyze shows real timings and misestimates, and refuses a write before anything runs.
The database tree: expand a table, filter, open a cron job's source, and browse a table's rows.
Begin opens a transaction; the chip shows Transaction open until you commit or roll back.
Star a statement and give it a label; it appears under Favourites.

The Metrics and Top SQL tabs read CloudWatch and Performance Insights (or pg_stat_statements when connected). Metrics also opens as a panel beside the console, from the strip on the right. Top SQL can hand a statement to the console, which adds it for you to review and never runs it.

Top SQL ranks statements by load (Performance Insights) or time (pg_stat_statements); Open in console adds one for review.
The Metrics panel sits beside the console; the Metrics tab shows the full set.

Why IAM authentication

IAM authentication is the best way to sign in to a database from a tool like ARNscope:

Be aware of the trade-offs, which AWS documents:

Sources: IAM database authentication, Aurora IAM database authentication, and the AWS Database Blog post Use IAM authentication to connect with SQL Workbench/J for the connection-rate guidance.

Requirements

Permissions

What IAM actions
List databases rds:DescribeDBInstances, rds:DescribeDBClusters
Connect rds-db:connect on the database user (see above)
Metrics tab rds:DescribeDBInstances, rds:DescribeDBClusters, cloudwatch:GetMetricData
Top SQL with Performance Insights pi:GetResourceMetrics, pi:DescribeDimensionKeys, pi:GetDimensionKeyDetails
Start an ARNscope tunnel See SSM tunnels

The IAM permission check also lists secretsmanager:GetSecretValue next to connecting. ARNscope does not read a secret to connect; you can ignore that line.

Limitations

Need another mode? Write to [email protected] and tell us what you use.