username

Documentation

Index

• Constants
• Variables
• func GetDefaultRoleNameToID(username SQLUsername) catid.RoleID
• type Purpose
• type SQLUsername
  • func AdminRoleName() SQLUsername
  • func EmptyRoleName() SQLUsername
  • func MakeSQLUsernameFromPreNormalizedString(u string) SQLUsername
  • func MakeSQLUsernameFromPreNormalizedStringChecked(u string) (SQLUsername, error)
  • func MakeSQLUsernameFromUserInput(u string, purpose Purpose) (res SQLUsername, err error)
  • func NodeUserName() SQLUsername
  • func PublicRoleName() SQLUsername
  • func RootUserName() SQLUsername
  • func TestUserName() SQLUsername
  • func (s SQLUsername) EncodeProto() SQLUsernameProto
  • func (s SQLUsername) Format(fs fmt.State, verb rune)
  • func (s SQLUsername) IsAdminRole() bool
  • func (s SQLUsername) IsEmptyRole() bool
  • func (s SQLUsername) IsNodeUser() bool
  • func (s SQLUsername) IsNoneRole() bool
  • func (s SQLUsername) IsPublicRole() bool
  • func (s SQLUsername) IsReserved() bool
  • func (s SQLUsername) IsRootUser() bool
  • func (s SQLUsername) LessThan(u SQLUsername) bool
  • func (s SQLUsername) Normalized() string
  • func (s SQLUsername) SQLIdentifier() string
  • func (s SQLUsername) Undefined() bool
  • func (s SQLUsername) ValidateForCreation() error
• type SQLUsernameProto
  • func (s SQLUsernameProto) Decode() SQLUsername

Constants

const AdminRole = "admin"

AdminRole is the default (and non-droppable) role with superuser privileges.

const AdminRoleID = 2

AdminRoleID is the ID for admin.

const EmptyRole = ""

EmptyRole is a pseudo-role that's used in system tables.

const EmptyRoleID = 0

EmptyRoleID is the ID for EmptyRole.

const NodeUser = "node"

NodeUser is used by nodes for intra-cluster traffic.

const NodeUserID = 3

NodeUserID is the ID for NodeUser.

const NoneRole = "none"

NoneRole is a special role. It is primarily used in SET ROLE, where "none" symbolizes a reset.

const PublicRole = "public"

PublicRole is the special "public" pseudo-role. All users are implicit members of "public". The role cannot be created, dropped, assigned to another role, and is generally not listed. It can be granted privileges, implicitly granting them to all users (current and future).

const PublicRoleID = 4

PublicRoleID is the ID for public role.

const RootUser = "root"

RootUser is the default cluster administrator.

const RootUserID = 1

RootUserID is the ID for RootUser.

const TestUser = "testuser"

TestUser is used in tests.

Variables

var ErrUsernameEmpty = errors.WithHint(errors.New("username is empty"), usernameHelp)

ErrUsernameEmpty indicates that an empty string was used as username. It is returned by ValidateForCreation() or MakeSQLUserFromUserInput() with purpose PurposeCreation.

var ErrUsernameInvalid = errors.WithHint(errors.New("username is invalid"), usernameHelp)

ErrUsernameInvalid indicates that a username string contained invalid characters. It is returned by ValidateForCreation() or MakeSQLUserFromUserInput() with purpose PurposeCreation.

var ErrUsernameNotNormalized = errors.WithHint(errors.New("username is not normalized"),
	"The username should be converted to lowercase and unicode characters normalized to NFC.")

ErrUsernameNotNormalized indicates that a username was not pre-normalized during a conversion.

var ErrUsernameTooLong = errors.WithHint(errors.New("username is too long"), usernameHelp)

ErrUsernameTooLong indicates that a username string was too long. It is returned by ValidateForCreation() or MakeSQLUserFromUserInput() with purpose PurposeCreation.

Functions

func GetDefaultRoleNameToID

func GetDefaultRoleNameToID(username SQLUsername) catid.RoleID

GetDefaultRoleNameToID returns a role id for default roles.

Types

type Purpose

type Purpose bool

Purpose indicates the purpose of the resulting SQLUsername in MakeSQLUsernameFromUserInput.

const (
	// PurposeCreation indicates that the SQLUsername is being
	// input for the purpose of creating a user account.
	// This causes MakeSQLUsernameFromUserInput to also enforce
	// structural restrictions on the username: which characters
	// are allowed and a maximum length.
	PurposeCreation Purpose = false

	// PurposeValidation indicates that the SQLUsername is
	// being input for the purpose of looking up an existing
	// user, or to compare with an existing username.
	// This skips the structural restrictions imposed
	// for the purpose PurposeCreation.
	PurposeValidation Purpose = true
)

type SQLUsername

type SQLUsername struct {
	// contains filtered or unexported fields
}

SQLUsername represents a username valid inside SQL.

Note that SQL usernames are not just ASCII names: they can start with digits or contain only digits; they can contain certain punctuation, and they can contain non-ASCII unicode letters. For example, "123.-456" is a valid username. Therefore, care must be taken when assembling a string from a username for use in other contexts, e.g. to generate filenames: some escaping and/or quoting is likely necessary.

Additionally, beware that usernames as manipulated client-side (in client drivers, in CLI commands) may not be the same as server-side; this is because usernames can be substituted during authentication. Additional care must be taken when deriving server-side strings in client code. It is always better to add an API server-side to assemble the string safely on the client's behalf.

This datatype is more complex to a simple string so as to force usages to clarify when it is converted to/from strings. This complexity is necessary because in CockroachDB SQL, unlike in PostgreSQL, SQL usernames are case-folded and NFC-normalized when a user logs in, or when used as input to certain CLI commands or SQL statements. Then, "inside" CockroachDB, username strings are considered pre-normalized and can be used directly for comparisons, lookup etc.

• The constructor MakeSQLUsernameFromUserInput() creates a username from "external input".

• The constructor MakeSQLUsernameFromPreNormalizedString() creates a username when the caller can guarantee that the input is already pre-normalized.

For convenience, the SQLIdentifier() method also represents a username in the form suitable for input back by the SQL parser.

func AdminRoleName

func AdminRoleName() SQLUsername

AdminRoleName is the SQLUsername for AdminRole.

func EmptyRoleName

func EmptyRoleName() SQLUsername

EmptyRoleName is the SQLUsername for EmptyRole.

func MakeSQLUsernameFromPreNormalizedString

func MakeSQLUsernameFromPreNormalizedString(u string) SQLUsername

MakeSQLUsernameFromPreNormalizedString takes a string containing a canonical username and converts it to a SQLUsername. The caller of this promises that the argument is pre-normalized. This conversion is cheap. Note: avoid using this function when processing strings in requests from external APIs. See also: MakeSQLUsernameFromPreNormalizedStringChecked().

func MakeSQLUsernameFromPreNormalizedStringChecked

func MakeSQLUsernameFromPreNormalizedStringChecked(u string) (SQLUsername, error)

MakeSQLUsernameFromPreNormalizedStringChecked takes a string, validates it is a prenormalized username, then converts it to a SQLUsername. See also: MakeSQLUsernameFromPreNormalizedString().

func MakeSQLUsernameFromUserInput

func MakeSQLUsernameFromUserInput(u string, purpose Purpose) (res SQLUsername, err error)

MakeSQLUsernameFromUserInput normalizes a username string as entered in an ambiguous context into a SQL username (performs case folding and unicode normalization form C - NFC). If the purpose if PurposeCreation, the structure of the username is also checked. An error is returned if the validation fails. If the purpose is PurposeValidation, no error is returned.

func NodeUserName

func NodeUserName() SQLUsername

NodeUserName is the SQLUsername for NodeUser.

func PublicRoleName

func PublicRoleName() SQLUsername

PublicRoleName is the SQLUsername for PublicRole.

func RootUserName

func RootUserName() SQLUsername

RootUserName is the SQLUsername for RootUser.

func TestUserName

func TestUserName() SQLUsername

TestUserName is the SQLUsername for testuser.

func (SQLUsername) EncodeProto

func (s SQLUsername) EncodeProto() SQLUsernameProto

EncodeProto turns a username into its proto representation.

func (SQLUsername) Format

func (s SQLUsername) Format(fs fmt.State, verb rune)

Format implements the fmt.Formatter interface. It renders the username in normalized form.

func (SQLUsername) IsAdminRole

func (s SQLUsername) IsAdminRole() bool

IsAdminRole is true iff the username designates the admin role.

func (SQLUsername) IsEmptyRole

func (s SQLUsername) IsEmptyRole() bool

IsEmptyRole is true iff the username designates the empty user.

func (SQLUsername) IsNodeUser

func (s SQLUsername) IsNodeUser() bool

IsNodeUser is true iff the username designates the node user.

func (SQLUsername) IsNoneRole

func (s SQLUsername) IsNoneRole() bool

IsNoneRole is true iff the username designates the none role.

func (SQLUsername) IsPublicRole

func (s SQLUsername) IsPublicRole() bool

IsPublicRole is true iff the username designates the public role.

func (SQLUsername) IsReserved

func (s SQLUsername) IsReserved() bool

IsReserved is true if the given username is reserved. Matches Postgres and also includes crdb_internal_.

func (SQLUsername) IsRootUser

func (s SQLUsername) IsRootUser() bool

IsRootUser is true iff the username designates the root user.

func (SQLUsername) LessThan

func (s SQLUsername) LessThan(u SQLUsername) bool

LessThan is true iff the receiver sorts strictly before the given argument. This can be used e.g. in sort.Sort().

func (SQLUsername) Normalized

func (s SQLUsername) Normalized() string

Normalized returns the normalized username, suitable for equality comparison and lookups. The username is unquoted.

func (SQLUsername) SQLIdentifier

func (s SQLUsername) SQLIdentifier() string

SQLIdentifier returns the normalized username in a form suitable for parsing as a SQL identifier. The identifier is quoted if it contains special characters or it is a reserved keyword.

func (SQLUsername) Undefined

func (s SQLUsername) Undefined() bool

Undefined is true iff the username is an empty string.

func (SQLUsername) ValidateForCreation

func (s SQLUsername) ValidateForCreation() error

ValidateForCreation checks that a username matches the structural restrictions for creation of a user account with that name.

type SQLUsernameProto

type SQLUsernameProto string

SQLUsernameProto is the wire representation of a SQLUsername.

func (SQLUsernameProto) Decode

func (s SQLUsernameProto) Decode() SQLUsername

Decode turns the proto representation of a username back into its legitimate form.