migration.org

Migration Guide: Vulpea v1 to v2

Vulpea v2 is a complete rewrite. This guide helps you migrate from v1.

Overview of Changes

What’s Different

Aspect	v1	v2
Database	org-roam’s database	Custom database
Sync	Save hooks (blocking)	File watchers (async)
Dependencies	Requires org-roam	Standalone
API	Built on org-roam functions	Native functions
Performance	Limited by org-roam	Optimized for 100k+ notes

What’s the Same

• Note format (org files with IDs)
• Metadata syntax (description lists)
• Core concepts (tags, links, metadata)

Before You Migrate

We recommend testing v2 in a separate Emacs session before fully switching.

Note your current v1 configuration - you’ll need to translate settings to v2 equivalents.

;; v2 uses its own database, separate from org-roam-db-location
;; Can be stored in cache directory
(setq vulpea-db-location
      (expand-file-name "vulpea/vulpea.db" user-emacs-cache-directory))

Configuration Migration

Directory Configuration

v1:

;; Used org-roam-directory

v2:

;; Defaults to org-directory, so often no config needed!
;; Only set if different from org-directory:
(setq vulpea-db-sync-directories '("~/org/"))

Note: vulpea-default-notes-directory defaults to the first entry in vulpea-db-sync-directories, so you typically don’t need to set it.

Database Location

v1: Used org-roam’s database

v2:

(setq vulpea-db-location
      (expand-file-name "vulpea.db" user-emacs-directory))

Enabling Sync

v1: Relied on org-roam-db-autosync-mode

v2:

(vulpea-db-autosync-mode +1)

API Migration

Query Functions

Most query functions have similar names but may have different signatures.

v1 Function	v2 Equivalent
vulpea-db-query	vulpea-db-query
vulpea-db-get-by-id	vulpea-db-get-by-id
vulpea-db-get-title	Use vulpea-db-search-by-title
vulpea-db-query-by-tags-some	vulpea-db-query-by-tags-some
vulpea-db-query-by-tags-every	vulpea-db-query-by-tags-every
vulpea-db-query-by-links-some	vulpea-db-query-by-links-some
vulpea-db-query-by-links-every	vulpea-db-query-by-links-every

Note Creation

v1:

(vulpea-create title template-key nil nil 'immediate-finish)

v2:

(vulpea-create title
               nil  ; file-name (nil = use template)
               :tags '("project" "work")
               :head "#+created: %<[%Y-%m-%d]>")

Note: v2 always creates notes immediately (no capture buffer). The old immediate-finish parameter is gone.

Metadata

The metadata API is largely unchanged:

;; Both versions
(vulpea-note-meta-get note "key")
(vulpea-note-meta-get note "key" 'number)
(vulpea-note-meta-get-list note "key")

Buffer Functions

Buffer functions are unchanged:

• vulpea-buffer-title-get
• vulpea-buffer-title-set
• vulpea-buffer-tags-get
• vulpea-buffer-tags-set
• vulpea-buffer-meta-set

Database Migration

v2 uses a different database schema. You cannot reuse the v1/org-roam database.

Building Fresh Database

;; Configure v2
(setq vulpea-db-sync-directories '("~/org/"))
(setq vulpea-db-location "~/.emacs.d/vulpea.db")

;; Build database
(vulpea-db-sync-full-scan)

Your notes don’t change - only the database is rebuilt.

org-roam Compatibility

v2 does not depend on org-roam, but they can coexist:

• Each maintains its own database
• No conflicts between them
• Use either or both for queries

If you want to keep org-roam for some features while using Vulpea for others, both can be loaded simultaneously.

Breaking Changes Summary

1. Different database - Must rebuild, cannot migrate
2. No org-roam dependency - org-roam functions not available
3. Async sync - Updates happen in background, not on save
4. New configuration variables - Review all settings
5. API changes - Some functions renamed or have new signatures

Getting Help

If you encounter migration issues:

1. Check Troubleshooting for common problems
2. Open an issue at GitHub

Include:

• Your v1 configuration
• What you’re trying to migrate
• Error messages