box

package
v2.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 11, 2025 License: BSD-2-Clause Imports: 5 Imported by: 0

Documentation

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Box

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

Box is a helper that wraps box.* requests. It holds a connection to the Tarantool instance via the Doer interface.

func New

func New(conn tarantool.Doer) *Box

New returns a new instance of the box structure, which implements the Box interface.

func (*Box) Info

func (b *Box) Info() (Info, error)

Info retrieves the current information of the Tarantool instance. It calls the "box.info" function and parses the result into the Info structure.

Example
dialer := tarantool.NetDialer{
	Address:  "127.0.0.1:3013",
	User:     "test",
	Password: "test",
}
ctx, cancel := context.WithTimeout(context.Background(), 500*time.Millisecond)
client, err := tarantool.Connect(ctx, dialer, tarantool.Opts{})
cancel()
if err != nil {
	log.Fatalf("Failed to connect: %s", err)
}

// You can use Info Request type.

fut := client.Do(box.NewInfoRequest())

resp := &box.InfoResponse{}

err = fut.GetTyped(resp)
if err != nil {
	log.Fatalf("Failed get box info: %s", err)
}

// Or use simple Box implementation.

b := box.New(client)

info, err := b.Info()
if err != nil {
	log.Fatalf("Failed get box info: %s", err)
}

if info.UUID != resp.Info.UUID {
	log.Fatalf("Box info uuids are not equal")
}

fmt.Printf("Box info uuids are equal\n")
fmt.Printf("Current box ro: %+v", resp.Info.RO)
Output:

Box info uuids are equal
Current box ro: false

func (*Box) Schema added in v2.4.0

func (b *Box) Schema() *Schema

Schema returns a new Schema instance, providing access to schema-related operations. It uses the connection from the Box instance to communicate with Tarantool.

func (*Box) Session added in v2.4.0

func (b *Box) Session() *Session

Session method returns a new Session object associated with the Box instance.

type Downstream added in v2.3.0

type Downstream struct {
	// Status is replication status of the connection with the instance.
	Status string `msgpack:"status"`
	// Idle is the time (in seconds) since the last event was received.
	Idle float64 `msgpack:"idle"`
	// VClock contains the vector clock, which is a table of ‘id, lsn’ pairs.
	VClock map[int]uint64 `msgpack:"vclock"`
	// Lag is the time difference between the local time of instance n,
	// recorded when the event was received, and the local time at another master
	// recorded when the event was written to the write-ahead log on that master.
	Lag float64 `msgpack:"lag"`
	// Message contains an error message in case of a degraded state; otherwise, it is nil.
	Message string `msgpack:"message,omitempty"`
	// SystemMessage contains an error message in case of a degraded state; otherwise, it is nil.
	SystemMessage string `msgpack:"system_message,omitempty"`
}

Downstream information.

type Info

type Info struct {
	// The Version of the Tarantool instance.
	Version string `msgpack:"version"`
	// The node ID (nullable).
	ID *int `msgpack:"id"`
	// Read-only (RO) status of the instance.
	RO bool `msgpack:"ro"`
	// UUID - Unique identifier of the instance.
	UUID string `msgpack:"uuid"`
	// Process ID of the instance.
	PID int `msgpack:"pid"`
	// Status - Current status of the instance (e.g., running, unconfigured).
	Status string `msgpack:"status"`
	// LSN - Log sequence number of the instance.
	LSN uint64 `msgpack:"lsn"`
	// Replication - replication status.
	Replication map[int]Replication `msgpack:"replication,omitempty"`
}

Info represents detailed information about the Tarantool instance. It includes version, node ID, read-only status, process ID, cluster information, and more.

type InfoRequest

type InfoRequest struct {
	*tarantool.CallRequest // Underlying Tarantool call request.
}

InfoRequest represents a request to retrieve information about the Tarantool instance. It implements the tarantool.Request interface.

func NewInfoRequest

func NewInfoRequest() InfoRequest

NewInfoRequest returns a new empty info request.

type InfoResponse

type InfoResponse struct {
	Info Info
}

InfoResponse represents the response structure that holds the information of the Tarantool instance. It contains a single field: Info, which holds the instance details (version, UUID, PID, etc.).

func (*InfoResponse) DecodeMsgpack

func (ir *InfoResponse) DecodeMsgpack(d *msgpack.Decoder) error

type Permission added in v2.4.0

type Permission string

Permission is a struct based on permission tarantool object https://www.tarantool.io/en/doc/latest/admin/access_control/#permissions

const (
	// PermissionRead allows reading data of the specified object.
	// For example, this permission can be used to allow a user
	// to select data from the specified space.
	PermissionRead Permission = "read"
	// PermissionWrite allows updating data of the specified object.
	// For example, this permission can be used to allow
	// a user to modify data in the specified space.
	PermissionWrite Permission = "write"
	// PermissionCreate allows creating objects of the specified type.
	// For example, this permission can be used to allow a user to create new spaces.
	// Note that this permission requires read and write access to certain system spaces.
	PermissionCreate Permission = "create"
	// PermissionAlter allows altering objects of the specified type.
	// Note that this permission requires read and write access to certain system spaces.
	PermissionAlter Permission = "alter"
	// PermissionDrop allows dropping objects of the specified type.
	// Note that this permission requires read and write access to certain system spaces.
	PermissionDrop Permission = "drop"
	// PermissionExecute for role,
	// allows using the specified role. For other object types, allows calling a function.
	// Can be used only for role, universe, function, lua_eval, lua_call, sql.
	PermissionExecute Permission = "execute"
	// PermissionSession allows a user to connect to an instance over IPROTO.
	PermissionSession Permission = "session"
	// PermissionUsage allows a user to use their privileges on database objects
	// (for example, read, write, and alter spaces).
	PermissionUsage Permission = "usage"
)

type Privilege added in v2.4.0

type Privilege struct {
	// Permissions is a list of privileges that apply to the privileges object type.
	Permissions []Permission
	// Type - one of privilege object types (it might be space,function, etc.).
	Type PrivilegeType
	// Name - can be the name of a function or space,
	// and can also be empty in case of universe access
	Name string
}

Privilege is a structure that is used to create new rights, as well as obtain information for rights.

type PrivilegeType added in v2.4.0

type PrivilegeType string

PrivilegeType is a struct based on privilege object types list https://www.tarantool.io/en/doc/latest/admin/access_control/#all-object-types-and-permissions

const (
	// PrivilegeUniverse - privilege type based on universe.
	// A database (box.schema) that contains database objects, including spaces,
	// indexes, users, roles, sequences, and functions.
	// Granting privileges to universe gives a user access to any object in the database.
	PrivilegeUniverse PrivilegeType = "universe"
	// PrivilegeTypeUser - privilege type based on user.
	// A user identifies a person or program that interacts with a Tarantool instance.
	PrivilegeTypeUser PrivilegeType = "user"
	// PrivilegeRole - privilege type based on role.
	// A role is a container for privileges that can be granted to users.
	// Roles can also be assigned to other roles, creating a role hierarchy.
	PrivilegeRole PrivilegeType = "role"
	// PrivilegeSpace - privilege type based on space.
	// Tarantool stores tuples in containers called spaces.
	PrivilegeSpace PrivilegeType = "space"
	// PrivilegeFunction - privilege type based on functions.
	// This allows access control based on function access.
	PrivilegeFunction PrivilegeType = "function"
	// PrivilegeSequence - privilege type based on sequences.
	// A sequence is a generator of ordered integer values.
	PrivilegeSequence PrivilegeType = "sequence"
	// PrivilegeLuaEval - privilege type based on executing arbitrary Lua code.
	PrivilegeLuaEval PrivilegeType = "lua_eval"
	// PrivilegeLuaCall - privilege type based on
	// calling any global user-defined Lua function.
	PrivilegeLuaCall PrivilegeType = "lua_call"
	// PrivilegeSQL - privilege type based on
	// executing an arbitrary SQL expression.
	PrivilegeSQL PrivilegeType = "sql"
)

type Replication added in v2.3.0

type Replication struct {
	// ID is a short numeric identifier of instance n within the replica set.
	ID int `msgpack:"id"`
	// UUID - Unique identifier of the instance.
	UUID string `msgpack:"uuid"`
	// LSN - Log sequence number of the instance.
	LSN uint64 `msgpack:"lsn"`
	// Upstream - information about upstream.
	Upstream Upstream `msgpack:"upstream,omitempty"`
	// Downstream - information about downstream.
	Downstream Downstream `msgpack:"downstream,omitempty"`
}

Replication section of box.info() is a table with statistics for all instances in the replica set that the current instance belongs to.

type Schema added in v2.4.0

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

Schema represents the schema-related operations in Tarantool. It holds a connection to interact with the Tarantool instance.

func (*Schema) User added in v2.4.0

func (s *Schema) User() *SchemaUser

User returns a new SchemaUser instance, allowing schema-related user operations.

type SchemaUser added in v2.4.0

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

SchemaUser provides methods to interact with schema-related user operations in Tarantool.

func (*SchemaUser) Create added in v2.4.0

func (u *SchemaUser) Create(ctx context.Context, username string, options UserCreateOptions) error

Create creates a new user in Tarantool with the given username and options.

Example
// Connect to Tarantool.
dialer := tarantool.NetDialer{
	Address:  "127.0.0.1:3013",
	User:     "test",
	Password: "test",
}
ctx := context.Background()

client, err := tarantool.Connect(ctx, dialer, tarantool.Opts{})
if err != nil {
	log.Fatalf("Failed to connect: %s", err)
}

// Create SchemaUser.
schemaUser := box.New(client).Schema().User()

// Create a new user.
username := "new_user"
options := box.UserCreateOptions{
	IfNotExists: true,
	Password:    "secure_password",
}
err = schemaUser.Create(ctx, username, options)
if err != nil {
	log.Fatalf("Failed to create user: %s", err)
}

fmt.Printf("User '%s' created successfully\n", username)
Output:

User 'new_user' created successfully

func (*SchemaUser) Drop added in v2.4.0

func (u *SchemaUser) Drop(ctx context.Context, username string, options UserDropOptions) error

Drop drops the specified user from Tarantool, with optional conditions.

Example
// Connect to Tarantool.
dialer := tarantool.NetDialer{
	Address:  "127.0.0.1:3013",
	User:     "test",
	Password: "test",
}
ctx := context.Background()

client, err := tarantool.Connect(ctx, dialer, tarantool.Opts{})
if err != nil {
	log.Fatalf("Failed to connect: %s", err)
}

// Create SchemaUser.
schemaUser := box.New(client).Schema().User()

// Drop an existing user.
username := "new_user"
options := box.UserDropOptions{
	IfExists: true,
}
err = schemaUser.Drop(ctx, username, options)
if err != nil {
	log.Fatalf("Failed to drop user: %s", err)
}

exists, err := schemaUser.Exists(ctx, username)
if err != nil {
	log.Fatalf("Failed to get user exists: %s", err)
}

fmt.Printf("User '%s' dropped successfully\n", username)
fmt.Printf("User '%s' exists status: %v \n", username, exists)
Output:

User 'new_user' dropped successfully
User 'new_user' exists status: false

func (*SchemaUser) Exists added in v2.4.0

func (u *SchemaUser) Exists(ctx context.Context, username string) (bool, error)

Exists checks if the specified user exists in Tarantool.

Example
dialer := tarantool.NetDialer{
	Address:  "127.0.0.1:3013",
	User:     "test",
	Password: "test",
}
ctx := context.Background()

client, err := tarantool.Connect(ctx, dialer, tarantool.Opts{})

if err != nil {
	log.Fatalf("Failed to connect: %s", err)
}

// You can use UserExistsRequest type and call it directly.
fut := client.Do(box.NewUserExistsRequest("user"))

resp := &box.UserExistsResponse{}

err = fut.GetTyped(resp)
if err != nil {
	log.Fatalf("Failed get box schema user exists with error: %s", err)
}

// Or use simple User implementation.
b := box.New(client)
exists, err := b.Schema().User().Exists(ctx, "user")
if err != nil {
	log.Fatalf("Failed get box schema user exists with error: %s", err)
}

if exists != resp.Exists {
	log.Fatalf("Box schema users exists are not equal")
}

fmt.Printf("Box schema users exists are equal\n")
fmt.Printf("Current exists state: %+v", exists)
Output:

Box schema users exists are equal
Current exists state: false

func (*SchemaUser) Grant added in v2.4.0

func (u *SchemaUser) Grant(ctx context.Context, username string, privilege Privilege,
	opts UserGrantOptions) error

Grant executes the user grant operation in Tarantool, returning an error if it fails.

func (*SchemaUser) Info added in v2.4.0

func (u *SchemaUser) Info(ctx context.Context, username string) ([]Privilege, error)

Info returns a list of user privileges according to the box.schema.user.info method call.

Example
// Connect to Tarantool.
dialer := tarantool.NetDialer{
	Address:  "127.0.0.1:3013",
	User:     "test",
	Password: "test",
}
ctx := context.Background()

client, err := tarantool.Connect(ctx, dialer, tarantool.Opts{})
if err != nil {
	log.Fatalf("Failed to connect: %s", err)
}

// Create SchemaUser.
schemaUser := box.New(client).Schema().User()

info, err := schemaUser.Info(ctx, "test")
if err != nil {
	log.Fatalf("Failed to get password hash: %s", err)
}

hasSuper := false
for _, i := range info {
	if i.Name == "super" && i.Type == box.PrivilegeRole {
		hasSuper = true
	}
}

if hasSuper {
	fmt.Printf("User have super privileges")
}
Output:

User have super privileges

func (*SchemaUser) Passwd added in v2.4.0

func (u *SchemaUser) Passwd(ctx context.Context, args ...string) error

Passwd sends a request to set a password for a currently logged in or a specified user. A currently logged-in user can change their password using box.schema.user.passwd(password). An administrator can change the password of another user with box.schema.user.passwd(username, password).

func (*SchemaUser) Password added in v2.4.0

func (u *SchemaUser) Password(ctx context.Context, password string) (string, error)

Password sends a request to retrieve the user's password from Tarantool. It returns the password hash as a string or an error if the request fails. It works just like hash function.

Example
// Connect to Tarantool.
dialer := tarantool.NetDialer{
	Address:  "127.0.0.1:3013",
	User:     "test",
	Password: "test",
}
ctx := context.Background()

client, err := tarantool.Connect(ctx, dialer, tarantool.Opts{})
if err != nil {
	log.Fatalf("Failed to connect: %s", err)
}

// Create SchemaUser.
schemaUser := box.New(client).Schema().User()

// Get the password hash.
password := "my-password"
passwordHash, err := schemaUser.Password(ctx, password)
if err != nil {
	log.Fatalf("Failed to get password hash: %s", err)
}

fmt.Printf("Password '%s' hash: %s", password, passwordHash)
Output:

Password 'my-password' hash: 3PHNAQGFWFo0KRfToxNgDXHj2i8=

func (*SchemaUser) Revoke added in v2.4.0

func (u *SchemaUser) Revoke(ctx context.Context, username string, privilege Privilege,
	opts UserRevokeOptions) error

Revoke executes the user revoke operation in Tarantool, returning an error if it fails.

type Session added in v2.4.0

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

Session struct represents a connection session to Tarantool.

func (*Session) Su added in v2.4.0

func (s *Session) Su(ctx context.Context, username string) error

Su method is used to switch the session to the specified username. It sends the request to Tarantool and returns an error.

type SessionSuRequest added in v2.4.0

type SessionSuRequest struct {
	*tarantool.CallRequest // Underlying Tarantool call request.
}

SessionSuRequest struct wraps a Tarantool call request specifically for session switching.

func NewSessionSuRequest added in v2.4.0

func NewSessionSuRequest(username string) (SessionSuRequest, error)

NewSessionSuRequest creates a new SessionSuRequest for switching session to a specified username. It returns an error if any execute functions are provided, as they are not supported now.

type Upstream added in v2.3.0

type Upstream struct {
	// Status is replication status of the connection with the instance.
	Status string `msgpack:"status"`
	// Idle is the time (in seconds) since the last event was received.
	Idle float64 `msgpack:"idle"`
	// Peer contains instance n’s URI.
	Peer string `msgpack:"peer"`
	// Lag is the time difference between the local time of instance n,
	// recorded when the event was received, and the local time at another master
	// recorded when the event was written to the write-ahead log on that master.
	Lag float64 `msgpack:"lag"`
	// Message contains an error message in case of a degraded state; otherwise, it is nil.
	Message string `msgpack:"message,omitempty"`
	// SystemMessage contains an error message in case of a degraded state; otherwise, it is nil.
	SystemMessage string `msgpack:"system_message,omitempty"`
}

Upstream information.

type UserCreateOptions added in v2.4.0

type UserCreateOptions struct {
	// IfNotExists - if true, prevents an error if the user already exists.
	IfNotExists bool `msgpack:"if_not_exists"`
	// Password for the new user.
	Password string `msgpack:"password"`
}

UserCreateOptions represents options for creating a user in Tarantool.

type UserCreateRequest added in v2.4.0

type UserCreateRequest struct {
	*tarantool.CallRequest // Underlying Tarantool call request.
}

UserCreateRequest represents a request to create a new user in Tarantool.

func NewUserCreateRequest added in v2.4.0

func NewUserCreateRequest(username string, options UserCreateOptions) UserCreateRequest

NewUserCreateRequest creates a new request to create a user with specified options.

type UserCreateResponse added in v2.4.0

type UserCreateResponse struct{}

UserCreateResponse represents the response to a user creation request.

func (*UserCreateResponse) DecodeMsgpack added in v2.4.0

func (uer *UserCreateResponse) DecodeMsgpack(_ *msgpack.Decoder) error

DecodeMsgpack decodes the response for a user creation request. In this case, the response does not contain any data.

type UserDropOptions added in v2.4.0

type UserDropOptions struct {
	IfExists bool `msgpack:"if_exists"` // If true, prevents an error if the user does not exist.
}

UserDropOptions represents options for dropping a user in Tarantool.

type UserDropRequest added in v2.4.0

type UserDropRequest struct {
	*tarantool.CallRequest // Underlying Tarantool call request.
}

UserDropRequest represents a request to drop a user from Tarantool.

func NewUserDropRequest added in v2.4.0

func NewUserDropRequest(username string, options UserDropOptions) UserDropRequest

NewUserDropRequest creates a new request to drop a user with specified options.

type UserDropResponse added in v2.4.0

type UserDropResponse struct{}

UserDropResponse represents the response to a user drop request.

type UserExistsRequest added in v2.4.0

type UserExistsRequest struct {
	*tarantool.CallRequest // Underlying Tarantool call request.
}

UserExistsRequest represents a request to check if a user exists in Tarantool.

func NewUserExistsRequest added in v2.4.0

func NewUserExistsRequest(username string) UserExistsRequest

NewUserExistsRequest creates a new request to check if a user exists.

type UserExistsResponse added in v2.4.0

type UserExistsResponse struct {
	Exists bool // True if the user exists, false otherwise.
}

UserExistsResponse represents the response to a user existence check.

func (*UserExistsResponse) DecodeMsgpack added in v2.4.0

func (uer *UserExistsResponse) DecodeMsgpack(d *msgpack.Decoder) error

DecodeMsgpack decodes the response from a Msgpack-encoded byte slice.

type UserGrantOptions added in v2.4.0

type UserGrantOptions struct {
	Grantor     string `msgpack:"grantor,omitempty"` // Optional grantor name.
	IfNotExists bool   `msgpack:"if_not_exists"`     // Option to skip if the grant already exists.
}

UserGrantOptions holds options for granting permissions to a user.

type UserGrantRequest added in v2.4.0

type UserGrantRequest struct {
	*tarantool.CallRequest // Underlying Tarantool call request.
}

UserGrantRequest wraps a Tarantool call request for granting user permissions.

func NewUserGrantRequest added in v2.4.0

func NewUserGrantRequest(username string, privilege Privilege,
	opts UserGrantOptions) UserGrantRequest

NewUserGrantRequest creates a new UserGrantRequest based on provided parameters.

type UserGrantResponse added in v2.4.0

type UserGrantResponse struct{}

UserGrantResponse represents the response from a user grant request.

type UserInfoRequest added in v2.4.0

type UserInfoRequest struct {
	*tarantool.CallRequest // Underlying Tarantool call request.
}

UserInfoRequest represents a request to get a user's info in Tarantool.

func NewUserInfoRequest added in v2.4.0

func NewUserInfoRequest(username string) UserInfoRequest

NewUserInfoRequest creates a new request to get user privileges.

type UserInfoResponse added in v2.4.0

type UserInfoResponse struct {
	Privileges []Privilege
}

UserInfoResponse represents the response to a user info request.

func (*UserInfoResponse) DecodeMsgpack added in v2.4.0

func (uer *UserInfoResponse) DecodeMsgpack(d *msgpack.Decoder) error

DecodeMsgpack decodes the response from Tarantool in Msgpack format.

type UserPasswdRequest added in v2.4.0

type UserPasswdRequest struct {
	*tarantool.CallRequest // Underlying Tarantool call request.
}

UserPasswdRequest represents a request to change a user's password in Tarantool.

func NewUserPasswdRequest added in v2.4.0

func NewUserPasswdRequest(args ...string) (UserPasswdRequest, error)

NewUserPasswdRequest creates a new request to change a user's password in Tarantool.

type UserPasswdResponse added in v2.4.0

type UserPasswdResponse struct{}

UserPasswdResponse represents the response to a user passwd request.

type UserPasswordRequest added in v2.4.0

type UserPasswordRequest struct {
	*tarantool.CallRequest // Underlying Tarantool call request.
}

UserPasswordRequest represents a request to retrieve a user's password from Tarantool.

func NewUserPasswordRequest added in v2.4.0

func NewUserPasswordRequest(username string) UserPasswordRequest

NewUserPasswordRequest creates a new request to fetch the user's password. It takes the username and constructs the request to Tarantool.

type UserPasswordResponse added in v2.4.0

type UserPasswordResponse struct {
	Hash string // The password hash of the user.
}

UserPasswordResponse represents the response to the user password request. It contains the password hash.

func (*UserPasswordResponse) DecodeMsgpack added in v2.4.0

func (upr *UserPasswordResponse) DecodeMsgpack(d *msgpack.Decoder) error

DecodeMsgpack decodes the response from Tarantool in Msgpack format. It expects the response to be an array of length 1, containing the password hash string.

type UserRevokeOptions added in v2.4.0

type UserRevokeOptions struct {
	IfExists bool `msgpack:"if_exists"` // Option to skip if the revoke does not exist.
}

UserRevokeOptions holds options for revoking permissions from a user.

type UserRevokeRequest added in v2.4.0

type UserRevokeRequest struct {
	*tarantool.CallRequest // Underlying Tarantool call request.
}

UserRevokeRequest wraps a Tarantool call request for revoking user permissions.

func NewUserRevokeRequest added in v2.4.0

func NewUserRevokeRequest(username string, privilege Privilege,
	opts UserRevokeOptions) UserRevokeRequest

NewUserRevokeRequest creates a new UserRevokeRequest based on provided parameters.

type UserRevokeResponse added in v2.4.0

type UserRevokeResponse struct{}

UserRevokeResponse represents the response from a user revoke request.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL