box.prepare()

box.prepare(sql-statement)

Prepare the SQL statement contained in the sql-statement parameter. The syntax and requirements for box.prepare are the same as for /reference/reference_lua/box_sql/execute.

Parameters:

• sql-statement (string) — statement, which should conform to the rules for SQL grammar

Returns

prepared_table, with id and methods and metadata

Return type

table

box.prepare compiles an SQL statement into byte code and saves the byte code in a cache. Since compiling takes a significant amount of time, preparing a statement will enhance performance if the statement is executed many times.

If box.prepare succeeds, prepared_table contains:

• stmt_id: integer – an identifier generated by a hash of the statement string
• execute: function
• params: map [name : string, type : string] – parameter descriptions
• unprepare: function
• metadata: map [name : string, type : string] (This is present only for SELECT or PRAGMA statements and has the same contents as the result set metadata for box.execute)
• param_count: integer – number of parameters

This can be used by prepared_table:execute() and by prepared_table:unprepare().

The prepared statement cache (which is also called the prepared statement holder) is "shared", that is, there is one cache for all sessions. However, session X cannot execute a statement prepared by session Y. BR For monitoring the cache, see box.info().sql. BR For changing the cache size, use sql.cache_size.

Prepared statements will "expire" (become invalid) if any database object is dropped or created or altered – even if the object is not mentioned in the SQL statement, even if the create or drop or alter is rolled back, even if the create or drop or alter is done in a different session.