tarantool / tarantool/doc

[5pt] vshard.storage.enable/disable()

Open
#2,510 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

ecosystem feature vshard
Dominant language
CSS
Stars
15
Forks
49
Avg merge
1d 13h
Merged PRs (30d)
3

Description

Product: Tarantool, vshard
Root document: https://www.tarantool.io/en/doc/latest/reference/reference_rock/vshard/vshard_api/
SME: @ Gerold103

Seems the description of the vshard.storage.disable()/enable() functions is missing in the reference. Need to add sections for those functions including the info below in Details.

Details

vshard.storage.disable() makes most of the vshard.storage
functions throw an error. As Lua exception, not via nil, err
pattern.

vshard.storage.enable() reverts the disable.

By default the storage is enabled.

Additionally, the storage is forcefully disabled automatically
until vshard.storage.cfg() is finished and the instance finished
recovery (its box.info.status is 'running', for example).

Auto-disable protects from usage of vshard functions before the
storage's global state is fully created.

Manual vshard.storage.disable() helps to achieve the same for
user's application. For instance, a user might want to do some
preparatory work after vshard.storage.cfg before the application
is ready for requests. Then the flow would be:

vshard.storage.disable()
vshard.storage.cfg(...)
-- Do your preparatory work here ...
vshard.storage.enable()

The routers handle the errors signaling about the storage being disabled in a
special way. They put connections to such instances into a backoff state for
some time and will try to use other replicas. For example, assume a replicaset
has replicas 'replica_1' and 'replica_2'. Assume 'replica_1' is disabled due to
any reason. If a router will try to talk to 'replica_1', it will get a special
error and will transparently retry to 'replica_2'.

When 'replica_1' is enabled again, the router will notice it too and will send
requests to it again.

It all works exclusively for read-only requests. Read-write requests can only be
sent to a master, which is one per replicaset. They are not retried.
Requested by @Gerold103 in https://github.com/tarantool/vshard/commit/2eb17c4e0e1c23bb2b68df7b2632f31317e39c95.

More info: https://github.com/tarantool/vshard/commit/5d935fc2783148b45aff584a60d039462488cd56

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Open the vshard API reference linked as the root document and locate the existing vshard.storage function sections. Add reference sections for disable() and enable() using the supplied behavior, lifecycle details, example, and router handling notes. Done means both functions are documented clearly in the reference and the documentation build accepts the changes.

Written by the indexing model from the issue text.

Assessment

Tech stack
lua
Domain
distributed-systems, documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
50/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.