(feat)db: add org-roam-db-update-on-save (org-roam#1720)

Adds new variable org-roam-db-update-on-save, which when set to nil, will disable db updates on file save. Closes org-roam#1717.
heyste · Aug 1, 2021 · 48d1c15 · 48d1c15
1 parent e8b720f
commit 48d1c15
Show file tree

Hide file tree

Showing 4 changed files with 114 additions and 57 deletions.
diff --git a/doc/org-roam.org b/doc/org-roam.org
@@ -388,7 +388,36 @@ To build the cache manually, run ~M-x org-roam-db-sync~. Cache builds may
 take a while the first time, but subsequent builds are often instantaneous
 because they only reprocess modified files.
 
-** Customizing Node Caching
+** Creating and Linking Nodes
+
+Org-roam makes it easy to create notes and link them together. There are 2 main
+functions for creating nodes:
+
+- ~org-roam-node-insert~: creates a node if it does not exist, and inserts a
+  link to the node at point.
+- ~org-roam-node-find~: creates a node if it does not exist, and visits the
+  node.
+- ~org-roam-capture~: creates a node if it does not exist, and restores the
+  current window configuration upon completion.
+
+Let's first try ~org-roam-node-find~. Calling ~M-x org-roam-node-find~ will
+show a list of titles for nodes that reside in ~org-roam-directory~. It should
+show nothing right now, since there are no notes in the directory. Enter the
+title of the note you wish to create, and press ~RET~. This begins the note
+creation process. This process uses ~org-capture~'s templating system, and can
+be customized (see [[*The Templating System][The Templating System]]). Using the default template, pressing
+~C-c C-c~ finishes the note capture.
+
+Now that we have a node, we can try inserting a link to the node using ~M-x
+org-roam-node-insert~. This brings up the list of nodes, which should contain
+the node you just created. Selecting the node will insert an ~id:~ link to the
+node. If you instead entered a title that does not exist, you will once again be
+brought through the node creation process.
+
+One can also conveniently insert links via the completion-at-point functions
+Org-roam provides (see [[id:70083bfd-d1e3-42b9-bf83-5b05708791c0][Completion]]).
+* Customizing Node Caching
+** What to cache
 
 By default, all nodes (any headline or file with an ID) are cached by Org-roam.
 There are instances where you may want to have headlines with ID, but not have
@@ -414,34 +443,21 @@ all headlines with the ~ATTACH~ tag from the Org-roam database, one can set:
         (not (member "ATTACH" (org-get-tags)))))
 #+end_src
 
-** TODO Creating and Linking Nodes
+** When to cache
 
-Org-roam makes it easy to create notes and link them together. There are 2 main
-functions for creating nodes:
+By default, Org-roam is eager in caching: each time an Org-roam file is modified
+and saved, it updates the database for the corresponding file. This keeps the
+database up-to-date, causing the least surprise when using the interactive
+commands.
 
-- ~org-roam-node-insert~: creates a node if it does not exist, and inserts a
-  link to the node at point.
-- ~org-roam-node-find~: creates a node if it does not exist, and visits the
-  node.
-- ~org-roam-capture~: creates a node if it does not exist, and restores the
-  current window configuration upon completion.
+However, depending on how large your Org files are, database updating can be a
+slow operation. You can disable the automatic updating of the database by
+setting ~org-roam-db-update-on-save~ to ~nil~.
 
-Let's first try ~org-roam-node-find~. Calling ~M-x org-roam-node-find~ will
-show a list of titles for nodes that reside in ~org-roam-directory~. It should
-show nothing right now, since there are no notes in the directory. Enter the
-title of the note you wish to create, and press ~RET~. This begins the note
-creation process. This process uses ~org-capture~'s templating system, and can
-be customized (see [[*The Templating System][The Templating System]]). Using the default template, pressing
-~C-c C-c~ finishes the note capture.
-
-Now that we have a node, we can try inserting a link to the node using ~M-x
-org-roam-node-insert~. This brings up the list of nodes, which should contain
-the node you just created. Selecting the node will insert an ~id:~ link to the
-node. If you instead entered a title that does not exist, you will once again be
-brought through the node creation process.
+- Variable: org-roam-db-update-on-save
 
-One can also conveniently insert links via the completion-at-point functions
-Org-roam provides (see [[id:70083bfd-d1e3-42b9-bf83-5b05708791c0][Completion]]).
+If t, update the Org-roam database upon saving the file. Disable this if your
+files are large and updating the database is slow.
 
 * The Org-roam Buffer
 

diff --git a/doc/org-roam.texi b/doc/org-roam.texi
@@ -67,6 +67,7 @@ General Public License for more details.
 * A Brief Introduction to the Zettelkasten Method::
 * Installation::
 * Getting Started::
+* Customizing Node Caching::
 * The Org-roam Buffer::
 * Node Properties::
 * Completion::
@@ -104,9 +105,13 @@ Getting Started
 * The Org-roam Node::
 * Links between Nodes::
 * Setting up Org-roam::
-* Customizing Node Caching::
 * Creating and Linking Nodes::
 
+Customizing Node Caching
+
+* What to cache::
+* When to cache::
+
 The Org-roam Buffer
 
 * Navigating the Org-roam Buffer::
@@ -562,7 +567,6 @@ your Emacs configuration folder like this:
 * The Org-roam Node::
 * Links between Nodes::
 * Setting up Org-roam::
-* Customizing Node Caching::
 * Creating and Linking Nodes::
 @end menu
 
@@ -645,35 +649,8 @@ To build the cache manually, run @code{M-x org-roam-db-sync}. Cache builds may
 take a while the first time, but subsequent builds are often instantaneous
 because they only reprocess modified files.
 
-@node Customizing Node Caching
-@section Customizing Node Caching
-
-By default, all nodes (any headline or file with an ID) are cached by Org-roam.
-There are instances where you may want to have headlines with ID, but not have
-them cached by Org-roam.
-
-To exclude a headline from the Org-roam database, set the @code{ROAM_EXCLUDE}
-property to a non-nil value. For example:
-
-@example
-* Foo
-  :PROPERTIES:
-  :ID:       foo
-  :ROAM_EXCLUDE: t
-  :END:
-@end example
-
-One can also set @code{org-roam-db-node-include-function}. For example, to exclude
-all headlines with the @code{ATTACH} tag from the Org-roam database, one can set:
-
-@example
-(setq org-roam-db-node-include-function
-      (lambda ()
-        (not (member "ATTACH" (org-get-tags)))))
-@end example
-
 @node Creating and Linking Nodes
-@section @strong{TODO} Creating and Linking Nodes
+@section Creating and Linking Nodes
 
 Org-roam makes it easy to create notes and link them together. There are 2 main
 functions for creating nodes:
@@ -709,6 +686,59 @@ brought through the node creation process.
 One can also conveniently insert links via the completion-at-point functions
 Org-roam provides (see @ref{Completion}).
 
+@node Customizing Node Caching
+@chapter Customizing Node Caching
+
+@menu
+* What to cache::
+* When to cache::
+@end menu
+
+@node What to cache
+@section What to cache
+
+By default, all nodes (any headline or file with an ID) are cached by Org-roam.
+There are instances where you may want to have headlines with ID, but not have
+them cached by Org-roam.
+
+To exclude a headline from the Org-roam database, set the @code{ROAM_EXCLUDE}
+property to a non-nil value. For example:
+
+@example
+* Foo
+  :PROPERTIES:
+  :ID:       foo
+  :ROAM_EXCLUDE: t
+  :END:
+@end example
+
+One can also set @code{org-roam-db-node-include-function}. For example, to exclude
+all headlines with the @code{ATTACH} tag from the Org-roam database, one can set:
+
+@example
+(setq org-roam-db-node-include-function
+      (lambda ()
+        (not (member "ATTACH" (org-get-tags)))))
+@end example
+
+@node When to cache
+@section When to cache
+
+By default, Org-roam is eager in caching: each time an Org-roam file is modified
+and saved, it updates the database for the corresponding file. This keeps the
+database up-to-date, causing the least surprise when using the interactive
+commands.
+
+However, depending on how large your Org files are, database updating can be a
+slow operation. You can disable the automatic updating of the database by
+setting @code{org-roam-db-update-on-save} to @code{nil}.
+
+@defvar org-roam-db-update-on-save
+@end defvar
+
+If t, update the Org-roam database upon saving the file. Disable this if your
+files are large and updating the database is slow.
+
 @node The Org-roam Buffer
 @chapter The Org-roam Buffer
 

diff --git a/org-roam-db.el b/org-roam-db.el
@@ -84,6 +84,13 @@ value like `most-positive-fixnum'."
   :type 'function
   :group 'org-roam)
 
+(defcustom org-roam-db-update-on-save t
+  "If t, update the Org-roam database upon saving the file.
+Disable this if your files are large and updating the database is
+slow."
+  :type 'boolean
+  :group 'org-roam)
+
 (defconst org-roam-db-version 16)
 (defconst org-roam--sqlite-available-p
   (with-demoted-errors "Org-roam initialization: %S"
@@ -523,9 +530,13 @@ If the file exists, update the cache with information."
           (org-roam-db-map-links
            (list #'org-roam-db-insert-link)))))))
 
+(defun org-roam-db--update-on-save ()
+  "."
+  (when org-roam-db-update-on-save (org-roam-db-update-file)))
+
 (defun org-roam-db--update-on-save-h ()
   "."
-  (add-hook 'after-save-hook #'org-roam-db-update-file nil t))
+  (add-hook 'after-save-hook #'org-roam-db--update-on-save nil t))
 
 (add-hook 'org-roam-find-file-hook #'org-roam-db--update-on-save-h)
 

diff --git a/org-roam.el b/org-roam.el
@@ -317,7 +317,7 @@ Org-roam."
   ;; Disable local hooks for all org-roam buffers
   (dolist (buf (org-roam-buffer-list))
     (with-current-buffer buf
-      (remove-hook 'after-save-hook #'org-roam-db-update-file t))))
+      (remove-hook 'after-save-hook #'org-roam-db--update-on-save t))))
 
 ;;; Hooks and advices
 (defun org-roam--file-setup ()