Managing modules | Tarantool
Tarantool
Check out the new release policy
Administration Managing modules

Managing modules

This section covers the installation and reloading of Tarantool modules. To learn about writing your own module and contributing it, check the Contributing a module section.

Modules in Lua and C that come from Tarantool developers and community contributors are available in the following locations:

  • Tarantool modules repository (see below)
  • Tarantool deb/rpm repositories (see below)

See README in tarantool/rocks repository for detailed instructions.

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 shard on Ubuntu, say:

    $ sudo apt-get install tarantool-shard
    

Once these steps are complete, you can:

  • load any module with

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

    for example:

    tarantool> shard = require('shard')
    
  • 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').

You can reload any Tarantool application or module with zero downtime.

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

Note

In this example, we use recommended administration practices based on instance files and tarantoolctl utility.

  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 tarantoolctl:

    $ tarantoolctl eval my_app /etc/tarantool/instances.enabled/my_app.lua
    

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.

Found what you were looking for?
Feedback