Skip to main content

​
Getting Started

Make sure to first set up your PlanetScale developer environment. Once you’ve installed the pscale CLI, you can interact with PlanetScale and manage your databases straight from the command line.

​
The role command

Manage database roles for a Postgres database branch. This command is only supported for Postgres databases. Usage: 
pscale role [command]

​
Available sub-commands

Sub-CommandProductDescription
createPostgresCreate a new role for a Postgres database branch
deletePostgresDelete a role
getPostgresRetrieve information about a specific role
listPostgresList all roles for a Postgres database branch
reassignPostgresReassign objects owned by a role to another role
renewPostgresRenew a role’s expiration
resetPostgresReset a role’s password
reset-defaultPostgresReset the credentials for the default postgres role
updatePostgresUpdate a role’s name

​
Available flags

FlagDescription
-h, --helpView help for role command
--org stringThe organization for the current user

​
Global flags

CommandDescription
--api-token <TOKEN>The API token to use for authenticating against the PlanetScale API.
--api-url <URL>The base URL for the PlanetScale API. Default is https://api.planetscale.com/.
--config <CONFIG_FILE>Config file. Default is $HOME/.config/planetscale/pscale.yml.
--debugEnable debug mode.
-f, --format <FORMAT>Show output in a specific format. Possible values: human (default), json, csv.
--no-colorDisable color output.
--service-token <TOKEN>The service token for authenticating.
--service-token-id <TOKEN_ID>The service token ID for authenticating.

​
Examples

​
The create sub-command

Create a new role for a Postgres database branch: Usage: 
pscale role create <database> <branch> <name> [flags]
Available flags:
  • --inherited-roles string - Comma-separated list of role names to inherit privileges from. Common values are ‘pg_read_all_data’ for read access, ‘pg_write_all_data’ for write access, and ‘postgres’ for admin access.
  • --ttl duration - TTL defines the time to live for the role. Durations such as “30m”, “24h”, or bare integers such as “3600” (seconds) are accepted. The default TTL is 0s, which means the role will never expire.
Example: 
pscale role create my-database main api-user --inherited-roles pg_read_all_data --ttl 24h

​
The delete sub-command

Delete a role: Usage: 
pscale role delete <database> <branch> <role-id> [flags]
Available flags:
  • --force - Delete a role without confirmation
  • --successor string - Role to transfer ownership to before deletion. Usually ‘postgres’.
Aliases: delete, rm Example: 
pscale role delete my-database main role-123 --successor postgres

​
The get sub-command

Retrieve information about a specific role: Usage: 
pscale role get <database> <branch> <role-id> [flags]
Example: 
pscale role get my-database main role-123

​
The list sub-command

List all roles for a Postgres database branch: Usage: 
pscale role list <database> <branch> [flags]
Available flags:
  • -w, --web - List roles in your web browser.
Aliases: list, ls Example: 
pscale role list my-database main

​
The reassign sub-command

Reassign objects owned by one role to any other role:
Be careful with this command. Reassigning objects like databases, tables, or schemas will change who is able to write to them, alter them, or delete them.
Usage: 
pscale role reassign <database> <branch> <role-id> --successor <role-id>
Available flags:
  • --force - Force reset without confirmation
Example: 
pscale role reassign my-database main role-123 --successor postgres

​
The renew sub-command

Renew a role’s expiration: Usage: 
pscale role renew <database> <branch> <role-id> [flags]
Example: 
pscale role renew my-database main role-123

​
The reset sub-command

Reset the credentials for any API-created role:
Be careful with this command. If you are currently using the affected role’s credentials for connecting to your database, running this command will reset the password, and new connections using the old password will not work.
Usage: 
pscale role reset <database> <branch> <role-id> [flags]
Available flags:
  • --force - Force reset without confirmation
Example: 
pscale role reset my-database main role-123

​
The reset-default sub-command

Reset the credentials for the default postgres role:
Be careful with this command. If you are currently using the default postgres role credentials for connecting to your database, running this command will reset the password, and new connections using the old password will not work.
Usage: 
pscale role reset-default <database> <branch> [flags]
Available flags:
  • --force - Force reset without confirmation
Example: 
pscale role reset-default my-database main

​
The update sub-command

Update a role’s name: Usage: 
pscale role update <database> <branch> <role-id> [flags]
Available flags:
  • --name string - New name for the role
Example: 
pscale role update my-database main role-123 --name new-role-name

Managing Postgres roles

Postgres roles API documentation

​
Need help?

Get help from the PlanetScale Support team, or join our Discord community to see how others are using PlanetScale.