PlanetScale CLI commands: role
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-Command | Description |
|---|---|
create | Create a new role for a Postgres database branch |
delete | Delete a role |
get | Retrieve information about a specific role |
list | List all roles for a Postgres database branch |
renew | Renew a role's expiration |
reset-default | Reset the credentials for the default postgres role |
update | Update a role's name |
Available flags
| Flag | Description |
|---|---|
-h, --help | View help for role command |
--org string | The organization for the current user |
Global flags
| Command | Description |
|---|---|
--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. |
--debug | Enable debug mode. |
-f, --format <FORMAT> | Show output in a specific format. Possible values: human (default), json, csv. |
--no-color | Disable 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 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-default sub-command
Reset the credentials for the default postgres role:
Warning
Warning: 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 your existing connections will stop working.
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
Related documentation
Need help?
Get help from the PlanetScale Support team, or join our GitHub discussion board to see how others are using PlanetScale.