Submodule box.schema¶

The box.schema submodule has data-definition functions for spaces, users, roles, and function tuples.

box.schema.space.create(space-name[, {options}])¶

Create a space.

Parameters:	space-name (string) – name of space, which should not be a number and should not contain special characters options (table) – see “Options for box.schema.space.create” chart, below
Return:	space object
Rtype:	userdata

Options for box.schema.space.create

Name	Effect	Type	Default
temporary	space contents are temporary: changes are not stored in the write-ahead log and there is no replication.	boolean	false
id	unique identifier: users can refer to spaces with the id instead of the name	number	last space’s id, +1
field_count	fixed count of fields: for example if field_count=5, it is illegal to insert a tuple with fewer than or more than 5 fields	number	0 i.e. not fixed
if_not_exists	create space only if a space with the same name does not exist already, otherwise do nothing but do not cause an error	boolean	false
engine	storage engine: ‘memtx’	string	‘memtx’
user	name of the user who is considered to be the space’s owner for authorization purposes	string	current user’s name
format	field names and types: For an illustration with the format option, see the box.space._space example.	table	(blank)

There are three syntax variations for object references targeting space objects, for example box.schema.space.drop(space-id) will drop a space. However, the common approach is to use functions attached to the space objects, for example space_object:drop().

Example

tarantool> s = box.schema.space.create('space55')
---
...
tarantool> s = box.schema.space.create('space55', {
         >   id = 555,
         >   temporary = false
         > })
---
- error: Space 'space55' already exists
...
tarantool> s = box.schema.space.create('space55', {
         >   if_not_exists = true
         > })
---
...

After a space is created, usually the next step is to create an index for it, and then it is available for insert, select, and all the other box.space functions.

box.schema.user.create(user-name[, {options}])¶

Create a user. For explanation of how Tarantool maintains user data, see section Users and reference on _user space.

The possible options are:

• if_not_exists = true|false (default = false) - boolean; true means there should be no error if the user already exists,
• password (default = ‘’) - string; the password = password specification is good because in a URI (Uniform Resource Identifier) it is usually illegal to include a user-name without a password.

Note

The maximum number of users is 32.

Parameters:	user-name (string) – name of user, which should not be a number and should not contain special characters options (table) – if_not_exists, password
Return:	nil

Examples:

box.schema.user.create('Lena')
box.schema.user.create('Lena', {password = 'X'})
box.schema.user.create('Lena', {if_not_exists = false})

box.schema.user.drop(user-name[, {options}])¶

Drop a user. For explanation of how Tarantool maintains user data, see section Users and reference on _user space.

Parameters:	user-name (string) – the name of the user options (table) – if_exists = true|false (default = false) - boolean; true means there should be no error if the user does not exist.

Examples:

box.schema.user.drop('Lena')
box.schema.user.drop('Lena',{if_exists=false})

box.schema.user.exists(user-name)¶

Return true if a user exists; return false if a user does not exist. For explanation of how Tarantool maintains user data, see section Users and reference on _user space.

Parameters:	user-name (string) – the name of the user
Rtype:	bool

Example:

box.schema.user.exists('Lena')

box.schema.user.grant(user-name, priveleges, object-type, object-name)¶

box.schema.user.grant(user-name, priveleges, 'universe')

box.schema.user.grant(user-name, role-name)

Grant privileges to a user or to another role.

Parameters:	user-name (string) – the name of the user priveleges (string) – ‘read’ or ‘write’ or ‘execute’ or a combination, object-type (string) – ‘space’ or ‘function’. object-name (string) – name of object to grant permissions to role-name (string) – name of role to grant to user.

If 'function','object-name' is specified, then a _func tuple with that object-name must exist.

Variation: instead of object-type, object-name say ‘universe’ which means ‘all object-types and all objects’. In this case, object name is omitted.

Variation: instead of privilege, object-type, object-name say role-name (see section Roles).

Example:

box.schema.user.grant('Lena', 'read', 'space', 'tester')
box.schema.user.grant('Lena', 'execute', 'function', 'f')
box.schema.user.grant('Lena', 'read,write', 'universe')
box.schema.user.grant('Lena', 'Accountant')
box.schema.user.grant('Lena', 'read,write,execute', 'universe')

box.schema.user.revoke(user-name, privilege, object-type, object-name)¶

box.schema.user.revoke(user-name, privilege, 'role', role-name)

Revoke privileges from a user or from another role.

Parameters:	user-name (string) – the name of the user privilege (string) – ‘read’ or ‘write’ or ‘execute’ or a combination object-type (string) – ‘space’ or ‘function’ object-name (string) – the name of a function or space

The user must exist, and the object must exist, but it is not an error if the user does not have the privilege.

Variation: instead of object-type, object-name say ‘universe’ which means ‘all object-types and all objects’.

Variation: instead of privilege, object-type, object-name say role-name (see section Roles).

Example:

box.schema.user.revoke('Lena', 'read', 'space', 'tester')
box.schema.user.revoke('Lena', 'execute', 'function', 'f')
box.schema.user.revoke('Lena', 'read,write', 'universe')
box.schema.user.revoke('Lena', 'Accountant')

box.schema.user.password(password)¶

Return a hash of a user’s password. For explanation of how Tarantool maintains passwords, see section Passwords and reference on _user space.

Note

• If a non-‘guest’ user has no password, it’s impossible to connect to Tarantool using this user. The user is regarded as “internal” only, not usable from a remote connection. Such users can be useful if they have defined some procedures with the SETUID option, on which privileges are granted to externally-connectable users. This way, external users cannot create/drop objects, they can only invoke procedures.
• For the ‘guest’ user, it’s impossible to set a password: that would be misleading, since ‘guest’ is the default user on a newly-established connection over a binary port, and Tarantool does not require a password to establish a binary connection. It is, however, possible to change the current user to ‘guest’ by providing the AUTH packet with no password at all or an empty password. This feature is useful for connection pools, which want to reuse a connection for a different user without re-establishing it.

Parameters:	password (string) – password to be hashed
Rtype:	string

Example:

box.schema.user.password('ЛЕНА')

box.schema.user.passwd([user-name, ]password)¶

Associate a password with the user who is currently logged in, or with another user.

Users who wish to change their own passwords should use box.schema.user.passwd(password) syntax.

Administrators who wish to change passwords of other users should use box.schema.user.passwd(user-name, password) syntax.

Parameters:	user-name (string) – user-name password (string) – password

Example:

box.schema.user.passwd('ЛЕНА')
box.schema.user.passwd('Lena', 'ЛЕНА')

box.schema.user.info([user-name])¶

Return a description of a user’s privileges. For explanation of how Tarantool maintains user data, see section Users and reference on _user space.

Parameters:	user-name (string) – the name of the user. This is optional; if it is not supplied, then the information will be for the user who is currently logged in.

Example:

box.schema.user.info()
box.schema.user.info('Lena')

box.schema.role.create(role-name[, {options}])¶

Create a role. For explanation of how Tarantool maintains role data, see section Roles.

Parameters:	role-name (string) – name of role, which should not be a number and should not contain special characters options (table) – if_not_exists = true|false (default = false) - boolean; true means there should be no error if the role already exists
Return:	nil

Example:

box.schema.role.create('Accountant')
box.schema.role.create('Accountant', {if_not_exists = false})

box.schema.role.drop(role-name[, {options}])¶

Drop a role. For explanation of how Tarantool maintains role data, see section Roles.

Parameters:	role-name (string) – the name of the role options (table) – if_exists = true|false (default = false) - boolean; true means there should be no error if the role does not exist.

Example:

box.schema.role.drop('Accountant')

box.schema.role.exists(role-name)¶

Return true if a role exists; return false if a role does not exist.

Parameters:	role-name (string) – the name of the role
Rtype:	bool

Example:

box.schema.role.exists('Accountant')

box.schema.role.grant(user-name, privilege, object-type, object-name)¶

box.schema.role.grant(user-name, privilege, 'universe')

box.schema.role.grant(role-name, role-name)

Grant privileges to a role.

Parameters:	user-name (string) – the name of the role privilege (string) – ‘read’ or ‘write’ or ‘execute’ or a combination object-type (string) – ‘space’ or ‘function’ object-name (string) – the name of a function or space

The role must exist, and the object must exist.

Variation: instead of object-type, object-name say ‘universe’ which means ‘all object-types and all objects’.

Variation: instead of privilege, object-type, object-name say role-name – to grant a role to a role.

Example:

box.schema.role.grant('Accountant', 'read', 'space', 'tester')
box.schema.role.grant('Accountant', 'execute', 'function', 'f')
box.schema.role.grant('Accountant', 'read,write', 'universe')
box.schema.role.grant('public', 'Accountant')

box.schema.role.revoke(user-name, privilege, object-type, object-name)¶

Revoke privileges from a role.

Parameters:	user-name (string) – the name of the role privilege (string) – ‘read’ or ‘write’ or ‘execute’ or a combination object-type (string) – ‘space’ or ‘function’ object-name (string) – the name of a function or space

The role must exist, and the object must exist, but it is not an error if the role does not have the privilege.

Variation: instead of object-type, object-name say ‘universe’ which means ‘all object-types and all objects’.

Variation: instead of privilege, object-type, object-name say role-name.

Example:

box.schema.role.revoke('Accountant', 'read', 'space', 'tester')
box.schema.role.revoke('Accountant', 'execute', 'function', 'f')
box.schema.role.revoke('Accountant', 'read,write', 'universe')
box.schema.role.revoke('public', 'Accountant')

box.schema.role.info([role-name])¶

Return a description of a role’s privileges.

Parameters:	role-name (string) – the name of the role.

Example:

box.schema.role.info('Accountant')

box.schema.func.create(func-name[, {options}])¶

Create a function tuple. This does not create the function itself – that is done with Lua – but if it is necessary to grant privileges for a function, box.schema.func.create must be done first. For explanation of how Tarantool maintains function data, see reference on _func space.

The possible options are:

• if_not_exists = true|false (default = false) - boolean; true means there should be no error if the _func tuple already exists.
• setuid = true|false (default = false) - with true to make Tarantool treat the function’s caller as the function’s creator, with full privileges. Remember that SETUID works only over binary ports. SETUID doesn’t work if you invoke a function via an admin console or inside a Lua script.
• language = ‘LUA’|’C’ (default = ‘LUA’).

Parameters:	func-name (string) – name of function, which should not be a number and should not contain special characters options (table) – if_not_exists, setuid, language.
Return:	nil

Example:

box.schema.func.create('calculate')
box.schema.func.create('calculate', {if_not_exists = false})
box.schema.func.create('calculate', {setuid = false})
box.schema.func.create('calculate', {language = 'LUA'})

box.schema.func.drop(func-name[, {options}])¶

Drop a function tuple. For explanation of how Tarantool maintains function data, see reference on _func space.

Parameters:	func-name (string) – the name of the function options (table) – if_exists = true|false (default = false) - boolean; true means there should be no error if the _func tuple does not exist.

Example:

box.schema.func.drop('calculate')

box.schema.func.exists(func-name)¶

Return true if a function tuple exists; return false if a function tuple does not exist.

Parameters:	func-name (string) – the name of the function
Rtype:	bool

Example:

box.schema.func.exists('calculate')