Mercurial > libervia-backend

annotate doc/libervia-cli/pubsub_cache.rst @ 3669:23be54db81f1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc (cli/pubsub_cache): add a warning for `reset`
author Goffi <goffi@goffi.org>
date Wed, 08 Sep 2021 17:58:48 +0200
parents 21e7d46b988c
children d0b66efc6c0e
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
3612
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
1 .. _libervia-cli_pubsub_cache:
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
2
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
3 =====================================
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
4 pubsub/cache: PubSub Cache Management
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
5 =====================================
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
6
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
7 Libervia runs transparently a cache for pubsub. That means that according to internal
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
8 criteria, some pubsub items are stored locally.
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
9
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
10 The ``cache`` subcommands let user inspect and manipulate the internal cache.
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
11
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
12 get
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
13 ===
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
14
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
15 Retrieve items from internal cache only. Most end-users won't need to use this command, as
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
16 the usual ``pubsub get`` command will use cache transparently. However, it may be useful
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
17 to inspect local cache, notably for debugging.
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
18
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
19 The parameters are basically the same as for :ref:`li_pubsub_get`.
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
20
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
21 example
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
22 -------
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
23
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
24 Retrieve the last 2 cached items for personal blog::
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
25
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
26 $ li pubsub cache get -n urn:xmpp:microblog:0 -M 2
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
27
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
28 .. _li_pubsub_cache_sync:
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
29
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
30 sync
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
31 ====
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
32
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
33 Synchronise or resynchronise a pubsub node. If the node is already in cache, it will be
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
34 deleted then re-cached. Node will be put in cache even if internal policy doesn't request
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
35 a synchronisation for this kind of nodes. Node will be (re-)subscribed to keep cache
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
36 synchronised.
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
37
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
38 All items of the node (up to the internal limit which is high), will be retrieved and put
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
39 in cache, even if a previous version of those items have been deleted by the
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
40 :ref:`li_pubsub_cache_purge` command.
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
41
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
42
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
43 example
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
44 -------
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
45
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
46 Resynchronise personal blog::
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
47
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
48 $ li pubusb cache sync -n urn:xmpp:microblog:0
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
49
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
50 .. _li_pubsub_cache_purge:
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
51
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
52 purge
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
53 =====
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
54
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
55 Remove items from cache. This may be desirable to save resource, notably disk space.
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
56
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
57 Note that once a pubsub node is cached, the cache is the source of trust. That means that
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
58 if cache is not explicitly bypassed when retrieving items of a pubsub node (notably with
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
59 the ``-C, --no-cache`` option of :ref:`li_pubsub_get`), only items found in cache will be
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
60 returned, thus purged items won't be used or returned anymore even if they still exists on
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
61 the original pubsub service.
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
62
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
63 If you have purged items by mistake, it is possible to retrieve them either node by node
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
64 using :ref:`li_pubsub_cache_sync`, or by resetting the whole pubsub cache with
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
65 :ref:`li_pubsub_cache_reset`.
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
66
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
67 If you have a node or a profile (e.g. a component) caching a lot of items frequently, you
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
68 may use this command using a scheduler like cron_.
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
69
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
70 .. _cron: https://en.wikipedia.org/wiki/Cron
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
71
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
72 examples
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
73 --------
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
74
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
75 Remove all blog and event items from cache if they haven't been updated since 6 months::
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
76
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
77 $ li pubsub cache purge -t blog -t event -b "6 months ago"
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
78
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
79 Remove items from profile ``ap_gateway`` if they have been created more that 2 months
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
80 ago::
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
81
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
82 $ li pubsub cache purge -p ap_gateway --created-before "2 months ago"
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
83
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
84 .. _li_pubsub_cache_reset:
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
85
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
86 reset
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
87 =====
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
88
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
89 Reset the whole pubsub cache. This means that all nodes and all them items will be removed
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
90 from cache. After this command, cache will be re-filled progressively as if it where a new
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
91 one.
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
92
3669
23be54db81f1 doc (cli/pubsub_cache): add a warning for `reset`
Goffi <goffi@goffi.org>
parents: 3612
diff changeset
93 .. note::
23be54db81f1 doc (cli/pubsub_cache): add a warning for `reset`
Goffi <goffi@goffi.org>
parents: 3612
diff changeset
94
23be54db81f1 doc (cli/pubsub_cache): add a warning for `reset`
Goffi <goffi@goffi.org>
parents: 3612
diff changeset
95 Use this command with caution: even if cache will be re-constructed with time, that
23be54db81f1 doc (cli/pubsub_cache): add a warning for `reset`
Goffi <goffi@goffi.org>
parents: 3612
diff changeset
96 means that items will have to be retrieved again, that may be resource intensive both
23be54db81f1 doc (cli/pubsub_cache): add a warning for `reset`
Goffi <goffi@goffi.org>
parents: 3612
diff changeset
97 for your machine and for the pubsub services which will be used. That also means that
23be54db81f1 doc (cli/pubsub_cache): add a warning for `reset`
Goffi <goffi@goffi.org>
parents: 3612
diff changeset
98 searching items will return less results until all desired items are cached again.
23be54db81f1 doc (cli/pubsub_cache): add a warning for `reset`
Goffi <goffi@goffi.org>
parents: 3612
diff changeset
99
23be54db81f1 doc (cli/pubsub_cache): add a warning for `reset`
Goffi <goffi@goffi.org>
parents: 3612
diff changeset
100 Also note that all items of cached nodes are retrieved, even if you have previously
23be54db81f1 doc (cli/pubsub_cache): add a warning for `reset`
Goffi <goffi@goffi.org>
parents: 3612
diff changeset
101 purged items, they will be retrieved again.
23be54db81f1 doc (cli/pubsub_cache): add a warning for `reset`
Goffi <goffi@goffi.org>
parents: 3612
diff changeset
102
3612
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
103 example
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
104 -------
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
105
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
106 Reset the whole pubsub cache::
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
107
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
108 $ li pubsub cache reset