Managing modules

Installing a module from a repository

See README in tarantool/rocks repository for detailed instructions.

Installing a module from deb/rpm

Follow these steps:

1. Install Tarantool as recommended on the download page.

2. Install the module you need. Look up the module’s name on Tarantool rocks page and put the prefix “tarantool-” before the module name to avoid ambiguity:

   $ # for Ubuntu/Debian: $ sudo apt-get install tarantool-<module-name> $ # for RHEL/CentOS/Amazon: $ sudo yum install tarantool-<module-name> 

   For example, to install the module vshard on Ubuntu, say:

   $ sudo apt-get install tarantool-vshard 

Once these steps are complete, you can:

• load any module with

  tarantool> name = require('module-name') 

  for example:

  tarantool> vshard = require('vshard') 

• search locally for installed modules using package.path (Lua) or package.cpath (C):

  tarantool> package.path --- - ./?.lua;./?/init.lua; /usr/local/share/tarantool/?.lua;/usr/local/share/ tarantool/?/init.lua;/usr/share/tarantool/?.lua;/usr/share/tarantool/?/ini t.lua;/usr/local/share/lua/5.1/?.lua;/usr/local/share/lua/5.1/?/init.lua;/ usr/share/lua/5.1/?.lua;/usr/share/lua/5.1/?/init.lua; ... tarantool> package.cpath --- - ./?.so;/usr/local/lib/x86_64-linux-gnu/tarantool/?.so;/usr/lib/x86_64-li nux-gnu/tarantool/?.so;/usr/local/lib/tarantool/?.so;/usr/local/lib/x86_64 -linux-gnu/lua/5.1/?.so;/usr/lib/x86_64-linux-gnu/lua/5.1/?.so;/usr/local/ lib/lua/5.1/?.so; ... 

  Note

  Question-marks stand for the module name that was specified earlier when saying require('module-name').

Reloading a module in Lua

Here’s an example that illustrates the most typical case – “update and reload”.

1. Update the application file.

   For example, a module in /usr/share/tarantool/app.lua:

   local function start() -- initial version box.once("myapp:v1.0", function() box.schema.space.create("somedata") box.space.somedata:create_index("primary") ... end) -- migration code from 1.0 to 1.1 box.once("myapp:v1.1", function() box.space.somedata.index.primary:alter(...) ... end) -- migration code from 1.1 to 1.2 box.once("myapp:v1.2", function() box.space.somedata.index.primary:alter(...) box.space.somedata:insert(...) ... end) end -- start some background fibers if you need local function stop() -- stop all background fibers and clean up resources end local function api_for_call(xxx) -- do some business end return { start = start, stop = stop, api_for_call = api_for_call } 

2. Update the instance file.

   For example, /etc/tarantool/instances.enabled/my_app.lua:

   #!/usr/bin/env tarantool -- -- hot code reload example -- box.cfg({listen = 3302}) -- ATTENTION: unload it all properly! local app = package.loaded['app'] if app ~= nil then -- stop the old application version app.stop() -- unload the application package.loaded['app'] = nil -- unload all dependencies package.loaded['somedep'] = nil end -- load the application log.info('require app') app = require('app') -- start the application app.start({some app options controlled by sysadmins}) 

   The important thing here is to properly unload the application and its dependencies.

3. Manually reload the application file.

   For example, using tt:

   $ tt connect my_app -f /etc/tarantool/instances.enabled/my_app.lua 

Reloading a module in C

After you compiled a new version of a C module (*.so shared library), call box.schema.func.reload(‘module-name’) from your Lua script to reload the module.