mirror of
https://github.com/org-roam/org-roam
synced 2025-08-01 12:17:21 -05:00
docs: update caching docs
Now that emacsql handles choosing an appropriate backend/connector, we
do not need to provide these instructions. If there are issues, emacsql
has good error messages that tell the user what they need to do to get
things working.
In general:
- If the user is on Emacs >= 29, emacsql will use the built-in sqlite
functionality that comes with Emacs.
- If the user is on Emacs < 29, emacsql will use a module-based
connector that requires the user to have certain libraries available
on their machine. emacsql will tell the user what is needed if they
do not have it already.
Ref: #2486
Close: #2502
Close: #2415
This commit is contained in:
Dustin Farris
@ -153,9 +153,8 @@ dependencies. These include:
|
||||
- dash
|
||||
- f
|
||||
- s
|
||||
- org (9.4 is the minimal required version!)
|
||||
- org (9.6 is the minimum required version!)
|
||||
- emacsql
|
||||
- emacsql-sqlite
|
||||
- magit-section
|
||||
- filenotify-recursive
|
||||
|
||||
|
||||
@ -224,7 +224,6 @@ dependencies that it requires. These include:
|
||||
- s
|
||||
- org
|
||||
- emacsql
|
||||
- emacsql-sqlite
|
||||
- magit-section
|
||||
|
||||
You can install this manually as well, or get the latest version from MELPA. You
|
||||
@ -423,43 +422,8 @@ can set ~org-roam-node-display-template~ as such:
|
||||
|
||||
* Customizing Node Caching
|
||||
** How to cache
|
||||
|
||||
Org-roam uses a sqlite database to perform caching, but there are multiple Emacs
|
||||
libraries that can be used. The default used by Org-roam is
|
||||
[[https://github.com/magit/emacsql/blob/main/emacsql-sqlite-builtin.el][~emacs-sqlite-builtin~]]. Below the pros and cons of each package is used:
|
||||
|
||||
[[https://melpa.org/#/emacsql-sqlite-builtin][**emacsql-sqlite-builtin**]]
|
||||
|
||||
~emacsql-sqlite-builtin~ uses the in-built SQLite support for Emacs 29 and
|
||||
later. This is the default option if you are using a version of Emacs that
|
||||
supports it.
|
||||
|
||||
#+begin_src emacs-lisp
|
||||
(setq org-roam-database-connector 'sqlite-builtin)
|
||||
#+end_src
|
||||
|
||||
[[https://github.com/cireu/emacsql-sqlite3][**emacs-sqlite3**]]
|
||||
|
||||
~emacs-sqlite3~ uses the official sqlite3 binary that can be obtained from your
|
||||
system's package manager. This is useful if you have issues producing the
|
||||
~sqlite3~ binary required by the other packages. However, it is not recommended
|
||||
because it has some compatibility issues with Emacs, but should work for most
|
||||
regular cases. See [[https://nullprogram.com/blog/2014/02/06/][Chris Wellon's blog post]] for more information.
|
||||
|
||||
To use ~emacsql-sqlite3~, ensure that the package is installed, and set:
|
||||
|
||||
#+begin_src emacs-lisp
|
||||
(setq org-roam-database-connector 'sqlite3)
|
||||
#+end_src
|
||||
|
||||
[[https://melpa.org/#/emacsql-sqlite-module][**emacssql-sqlite-module**]] (previously emacsql-libsqlite3)
|
||||
|
||||
~emacs-sqlite-module~ is a relatively young package which uses an Emacs module that
|
||||
exposes parts of the SQLite C API to Emacs Lisp.
|
||||
|
||||
#+begin_src emacs-lisp
|
||||
(setq org-roam-database-connector 'sqlite-module)
|
||||
#+end_src
|
||||
Org-roam uses a SQLite database to perform caching. This integration is
|
||||
managed by the [[https://github.com/magit/emacsql][emacsql]] library. It should "just work".
|
||||
|
||||
** What to cache
|
||||
|
||||
@ -481,7 +445,7 @@ property to a non-nil value. For example:
|
||||
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
|
||||
#+begin_src emacs-lisp
|
||||
(setq org-roam-db-node-include-function
|
||||
(lambda ()
|
||||
(not (member "ATTACH" (org-get-tags)))))
|
||||
|
||||
@ -441,8 +441,6 @@ org
|
||||
@item
|
||||
emacsql
|
||||
@item
|
||||
emacsql-sqlite
|
||||
@item
|
||||
magit-section
|
||||
@end itemize
|
||||
|
||||
@ -685,42 +683,8 @@ can set @code{org-roam-node-display-template} as such:
|
||||
@node How to cache
|
||||
@section How to cache
|
||||
|
||||
Org-roam uses a sqlite database to perform caching, but there are multiple Emacs
|
||||
libraries that can be used. The default used by Org-roam is
|
||||
@uref{https://github.com/magit/emacsql/blob/main/emacsql-sqlite-builtin.el, @code{emacs-sqlite-builtin}}. Below the pros and cons of each package is used:
|
||||
|
||||
@uref{https://melpa.org/#/emacsql-sqlite-builtin, @strong{@strong{emacsql-sqlite-builtin}}}
|
||||
|
||||
@code{emacsql-sqlite-builtin} uses the in-built SQLite support for Emacs 29 and
|
||||
later. This is the default option if you are using a version of Emacs that
|
||||
supports it.
|
||||
|
||||
@lisp
|
||||
(setq org-roam-database-connector 'sqlite-builtin)
|
||||
@end lisp
|
||||
|
||||
@uref{https://github.com/cireu/emacsql-sqlite3, @strong{@strong{emacs-sqlite3}}}
|
||||
|
||||
@code{emacs-sqlite3} uses the official sqlite3 binary that can be obtained from your
|
||||
system's package manager. This is useful if you have issues producing the
|
||||
@code{sqlite3} binary required by the other packages. However, it is not recommended
|
||||
because it has some compatibility issues with Emacs, but should work for most
|
||||
regular cases. See @uref{https://nullprogram.com/blog/2014/02/06/, Chris Wellon's blog post} for more information.
|
||||
|
||||
To use @code{emacsql-sqlite3}, ensure that the package is installed, and set:
|
||||
|
||||
@lisp
|
||||
(setq org-roam-database-connector 'sqlite3)
|
||||
@end lisp
|
||||
|
||||
@uref{https://melpa.org/#/emacsql-sqlite-module, @strong{@strong{emacssql-sqlite-module}}} (previously emacsql-libsqlite3)
|
||||
|
||||
@code{emacs-sqlite-module} is a relatively young package which uses an Emacs module that
|
||||
exposes parts of the SQLite C API to Emacs Lisp.
|
||||
|
||||
@lisp
|
||||
(setq org-roam-database-connector 'sqlite-module)
|
||||
@end lisp
|
||||
Org-roam uses a SQLite database to perform caching. This integration is
|
||||
managed by the @uref{https://github.com/magit/emacsql, emacsql} library. It should ``just work''.
|
||||
|
||||
@node What to cache
|
||||
@section What to cache
|
||||
@ -743,11 +707,11 @@ property to a non-nil value. For 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
|
||||
@lisp
|
||||
(setq org-roam-db-node-include-function
|
||||
(lambda ()
|
||||
(not (member "ATTACH" (org-get-tags)))))
|
||||
@end example
|
||||
@end lisp
|
||||
|
||||
Org-roam relied on the obtained Org AST for the buffer to parse links. However,
|
||||
links appearing in some places (e.g. within property drawers) are not considered
|
||||
|
||||
@ -80,7 +80,9 @@
|
||||
(require 'magit-section)
|
||||
|
||||
(require 'emacsql)
|
||||
;; emacsql-sqlite provides an interface to a chosen emacsql SQLite backend (e.g. emacs-sqlite-builtin)
|
||||
;; REVIEW: is this require needed?
|
||||
;; emacsql-sqlite provides a common interface to an emacsql SQLite backend (e.g. emacs-sqlite-builtin)
|
||||
;; not to be confused with a backend itself named emacsql-sqlite that existed in emacsql < 4.0.
|
||||
(require 'emacsql-sqlite)
|
||||
|
||||
(require 'org)
|
||||
|
||||
Reference in New Issue
Block a user