Create, list, filter, renew, and delete branch passwords for database connections. The pscale password command group is for Vitess databases; use pscale role for Postgres and Neki branch credentials.
Common Commands
# Create password
pscale password create <database> <branch> <password-name>
# Create a reader password scoped to one separate Vitess read-only region
pscale keyspace read-only-regions <database> <branch> <keyspace> --format json
pscale password create <database> <branch> <password-name> \
--read-only-region <region> \
--format json
# List the default page (up to 100 passwords); omit branch to audit all branches
pscale password list <database> [branch]
pscale password list --status renewable --format json
Filter and paginate passwordspscale password list
--name production
--status active
--page 1
--per-page 100
--format json
pscale password renew
Show password metadata by ID or exact namepscale password show --format json pscale password show --name production-app --format json
Update password metadata or CIDR restrictions without rotating the secretpscale password update --new-name production-app-v2 --format json pscale password update --name production-app --cidrs 10.0.0.0/8,192.168.1.1/32 --format json
Delete passwordpscale password delete
`--name` performs a substring match. Password status values are `active`, `renewable`, and `expired`. List output is limited to one page by default; request subsequent pages with `--page` when needed.
When `--read-only-region` is present, the default role is `reader`, the created password is labeled as a read-only-region credential, and `--replica` is rejected. Use the region slug, display name, or ID returned by `pscale keyspace read-only-regions`. The plaintext secret is shown only at creation time: capture it directly into an approved secret manager and never print it in logs or commit it.
### Show or update Vitess password metadata
`pscale password show` returns metadata only. The secret cannot be retrieved after create or renew. `show`, `update`, and `delete` can identify a password by ID or by `--name`; use IDs when names are ambiguous.
```bash
# Inspect metadata before changing it
pscale password show <database> <branch> <password-id> --org <org> --format json
pscale password show <database> <branch> --org <org> --name <password-name> --format json
# Change the display name without rotating the password
pscale password update <database> <branch> <password-id> --org <org> \
--new-name <new-name> \
--format json
# Replace CIDR restrictions; pass an empty value to clear all restrictions
pscale password update <database> <branch> --org <org> \
--name <password-name> \
--cidrs 10.0.0.0/8,192.168.1.1/32 \
--format json
pscale password update <database> <branch> --org <org> \
--name <password-name> \
--cidrs "" \
--format json
# Verify the metadata after the write
pscale password show <database> <branch> <password-id> --org <org> --format json
Updating a name or CIDR allowlist does not rotate the secret. Treat updates as credential-access writes: show the target password metadata, exact new name/CIDRs, and clearing behavior before asking for approval, then verify with show or list. Use create/delete or renew only when the user needs a new secret.
Workflows
Application Connection
# Create password for production app
pscale password create my-database main production-app
# Returns connection string:
# mysql://username:password@host/database
# Use in application environment variables
export DATABASE_URL="mysql://..."
Local Development
# Create temporary password for local dev
pscale password create my-db main local-dev
# Delete when done
pscale password delete my-db main <password-id>
Region-scoped read access
# Discover configured regions and confirm the intended target is ready
pscale keyspace read-only-regions <database> <branch> <keyspace> \
--org <org> --format json
# Create a temporary, reader-only credential for that region
pscale password create <database> <branch> reporting-reader \
--org <org> \
--read-only-region <region> \
--role reader \
--ttl 24h \
--format json
Use --read-only-region when reads must stay in one separate region. Use --replica instead when reads may route to the primary region's replicas and all read-only regions. The two routing modes are mutually exclusive.
Postgres and Neki role creation, lookup, and filtering
Postgres and Neki databases use roles instead of Vitess branch passwords. pscale role default is a read-only lookup for the default postgres role and does not rotate credentials. Use pscale role reset-default only when the user explicitly asks to reset default-role credentials and approves the connection impact. Role list/get/default output includes status and expires_at; listing supports pagination and name filtering plus status filters for active, renewable, disabled, and expired.
This workflow intentionally lives here because no dedicated pscale-role skill exists, and both command groups manage branch credentials.
pscale role list <database> <branch> \
--name production \
--status active \
--page 1 \
--per-page 100 \
--format json
pscale role default <database> <branch> --format json
# Create Neki roles only after confirming the intended privilege pairing
pscale role create <database> <branch> viewer --org <org> --format json \
--inherited-roles neki_viewer,pg_read_all_data
pscale role create <database> <branch> operator --org <org> --format json \
--inherited-roles neki_operator,postgres
# Postgres alternate connection targets
pscale role get <database> <branch> <role-id> --org <org> --format json --replica
pscale role get <database> <branch> <role-id> --org <org> --format json --read-only-replica <replica-name>
pscale role get <database> <branch> <role-id> --org <org> --format json --bouncer <bouncer-name>
# Neki target selectors can be combined
pscale role get <database> <branch> <role-id> --org <org> --format json \
--shard <shard-name> --router <router-name> --replica
Neki --inherited-roles supports neki_viewer only with pg_read_all_data, and neki_operator only with postgres; the API rejects an incomplete pairing. Role creation returns a credential, so obtain approval for the exact role name and privilege set, then capture the secret directly into an approved secret manager.
--replica, --read-only-replica, and --bouncer are mutually exclusive. Named --read-only-replica and --bouncer targets are Postgres-only and cannot combine with Neki --router or --shard. --read-only-replica takes the replica name returned by branch infrastructure or pscale read-only-replica list, not a read-only-region slug. A targeted response can change username, access_host_url, and database_url; PgBouncer URLs use port 6432.
On Neki, --replica, --router, and --shard can be combined: router selection rewrites the username, while replica and shard selection produce libpq options and an options-bearing database_url. Use the shard name from pscale branch shard list, not its API ID; pscale inspect --shard is different and takes the ID.
A target-specific NOT_FOUND can mean the role or any requested target was not found, so verify every identifier before retrying. Treat returned passwords, connection URLs, and libpq options as secrets: capture them directly into an approved secret manager and never print them in logs or commit them.
Troubleshooting
Password not working
Solution: Inspect status and metadata first. For ordinary name or CIDR allowlist changes, use password update; delete/recreate or renew only when the secret itself has expired or must rotate.
pscale password list <database> <branch> --format json
pscale password show <database> <branch> <password-id> --format json
# After explicit approval; --cidrs replaces the entire allowlist
pscale password update <database> <branch> <password-id> --cidrs <cidr-allowlist> --format json
Related Skills
- pscale-service-token - For CI/CD authentication (preferred over passwords)
- pscale-database - Database management
References
See references/commands.md for complete command reference.