Creating a PostgreSQL user

Written by

Updated at July 24, 2026

If you have a PostgreSQL cluster in your project, you can create a user in it, i.e., a PostgreSQL role with login permissions. Use a PostgresqlRole resource to define the user. The user password is stored in a Kubernetes Secret: the operator can generate it automatically or you can provide a custom Secret with credentials.

CLI

Management console

Create the PostgresqlRole resource file, e.g., using the touch postgresqlrole.yaml command.

Open the file and paste the configuration below into it:

The naming requirements are as follows:

The PostgreSQL role name (spec.username) must start with a Latin letter or underscore and can only contain Latin letters, numbers, and underscores.
The PostgresqlRole resource name (metadata.name) must follow this pattern: `<cluster_name>-<username_with_hyphens_instead_of_underscores>.

Minimum configuration

Configuration with an explicit password

Full configuration

apiVersion: postgresql.stackland.yandex.cloud/v1alpha1
kind: PostgresqlRole
metadata:
  name: test-cluster-test-user # Name of the PostgresqlRole resource in this format: <cluster-name>-<username-with-dashes-instead-of-underscores>
spec:
  cluster: test-cluster # Name of PostgresqlCluster resource
  username: test_user # Name of role in PostgreSQL

The manifest defines only the required fields, such as the cluster name and the PostgreSQL role name. The password will be automatically generated and stored in a Kubernetes Secret with the same name as the PostgresqlRole resource.

apiVersion: v1
kind: Secret
metadata:
  name: test-cluster-user-secret
type: Opaque
stringData:
  username: test_user # username
  password: "<user_password>" # password
---
apiVersion: postgresql.stackland.yandex.cloud/v1alpha1
kind: PostgresqlRole
metadata:
  name: test-cluster-test-user # Name of the PostgresqlRole resource in this format: <cluster-name>-<username-with-dashes-instead-of-underscores>
spec:
  cluster: test-cluster # Name of PostgresqlCluster resource
  username: test_user # Name of role in PostgreSQL
  authentication:
    type: password
    secretName: test-cluster-user-secret # Name of the Secret with the credentials

The manifest defines a Secret with credentials and a PostgresqlRole resource that references this Secret via spec.authentication.secretName. The Secret must contain the username key with the username and the password key with the user password.

apiVersion: v1
kind: Secret
metadata:
  name: test-cluster-user-secret
type: Opaque
stringData:
  username: test_user # username
  password: "<user_password>" # password
---
apiVersion: postgresql.stackland.yandex.cloud/v1alpha1
kind: PostgresqlRole
metadata:
  name: test-cluster-test-user # Name of the PostgresqlRole resource in this format: <cluster-name>-<username-with-dashes-instead-of-underscores>
spec:
  cluster: test-cluster
  username: test_user
  authentication:
    type: password
    secretName: test-cluster-user-secret
  membership: # Parent roles to include the user in
    - test-parent-role
  options:
    superuser: false # Superuser privileges
    login: true # Allow login
    createdb: false # Permission to create databases
    createrole: false # Permission to create roles
    inherit: true # Permission inheritance from parent roles
    replication: false # Permission to use replication
    bypassRLS: false # Row-level security policy bypass
    connectionLimit: -1 # Limit on simultaneous connections: -1 for no limit
    validUntil: "2026-12-31T23:59:59Z" # Password expiration date in RFC3339 format

spec.options defines role permissions, such as superuser, login, createdb, createrole, inherit, replication, bypassRLS, connectionLimit, or validUntil. spec.membership lists parent roles to include the user in.

Apply the manifest: kubectl apply -f postgresqlrole.yaml -n <project_name>. Optionally, you can specify the project name in the metadata.namespace resource property and skip it in the command.

If you have not opened a project yet, select one.
In the left-hand menu, select PostgreSQL Clusters.
Select the cluster.
Go to the Users tab.
Click Create.
Fill out the fields as follows:
- Name: Role name in PostgreSQL. The name must start with a Latin letter or _ and can only contain Latin letters, numbers, and _. It may be up to 63 characters long.
- Password: User password. Its value is stored in a Kubernetes Secret and not available in plain text once saved.
- Superuser: Toggle for superuser privileges. Disabled by default.
Expand the Advanced parameters section and change the values as needed:
- Allow login: Allows the role to connect to PostgreSQL. This parameter is enabled by default.
- Parent roles: List of roles the user will be included in.
- Creating databases: Permission to create new databases. Disabled by default.
- Create roles: Permission to create, modify, and delete roles. Disabled by default.
- Inherit role privileges: Permission inheritance from parent roles. This parameter is enabled by default.
- Replication mode: Permission to use replication and WAL shipping operations. Disabled by default.
- Bypass RLS: Permission to bypass row-level security policies. Disabled by default.
- Connection limit: Maximum number of simultaneous connections. If set to -1, there is no limit. 0 disables new connections. The default value is -1.
- Password valid until: Password expiration date in RFC3339 format.
Click Create.

Done. The new user now appears in the cluster’s Users tab.

Creating a PostgreSQL user

Was the article helpful?