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

Adds new variable org-roam-db-update-on-save, which when set to nil,
will disable db updates on file save. Closes #1717.

doc/org-roam.org

@@ -388,33 +388,7 @@ 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
-
-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 ~ROAM_EXCLUDE~
-property to a non-nil value. For example:
-
-#+begin_src org
-,* Foo
-  :PROPERTIES:
-  :ID:       foo
-  :ROAM_EXCLUDE: t
-  :END:
-#+end_src
-
-One can also set ~org-roam-db-node-include-function~. For example, to exclude
-all headlines with the ~ATTACH~ tag from the Org-roam database, one can set:
-
-#+begin_src org
-(setq org-roam-db-node-include-function
-      (lambda ()
-        (not (member "ATTACH" (org-get-tags)))))
-#+end_src
-
-** TODO Creating and Linking Nodes
 
 Org-roam makes it easy to create notes and link them together. There are 2 main
 functions for creating nodes:
@@ -442,6 +416,48 @@ 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
+them cached by Org-roam.
+
+To exclude a headline from the Org-roam database, set the ~ROAM_EXCLUDE~
+property to a non-nil value. For example:
+
+#+begin_src org
+,* Foo
+  :PROPERTIES:
+  :ID:       foo
+  :ROAM_EXCLUDE: t
+  :END:
+#+end_src
+
+One can also set ~org-roam-db-node-include-function~. For example, to exclude
+all headlines with the ~ATTACH~ tag from the Org-roam database, one can set:
+
+#+begin_src org
+(setq org-roam-db-node-include-function
+      (lambda ()
+        (not (member "ATTACH" (org-get-tags)))))
+#+end_src
+
+** 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 ~org-roam-db-update-on-save~ to ~nil~.
+
+- Variable: org-roam-db-update-on-save
+
+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
 

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
 

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)
 

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 ()