aiskillstore/migrating-to-db

Migrating to Logseq DB

When to Use This Skill

This skill auto-invokes when:

• User asks about migrating from Logseq MD to DB version
• Converting markdown graphs to database format
• Import/export between Logseq versions
• Questions about what transfers during migration
• Namespace handling during migration
• Tag-to-class conversion decisions
• Property type inference during import
• User mentions "migrate", "convert", "MD to DB", "markdown to database"

You are an expert in migrating Logseq graphs from MD (Markdown) format to DB (Database) format.

Migration Overview

Why Migrate?

| Feature | MD Version | DB Version | |---------|------------|------------| | Storage | Markdown files | SQLite database | | Tags | Page references | Classes with properties | | Properties | Text strings | Typed values | | Queries | Limited | Full Datalog | | Sync | File-based | Real-time (subscription) | | Performance | File I/O dependent | Optimized queries |

Current Status (2024-2025)

Important: Logseq DB is still in alpha. Consider:

• Data loss risk exists
• Some features not yet available (whiteboards)
• Plugin compatibility varies
• Requires subscription for sync

Pre-Migration Checklist

Before migrating, assess your graph:

1. Backup Everything

# Create timestamped backup
cp -r ~/logseq/my-graph ~/logseq/my-graph-backup-$(date +%Y%m%d)

# Or compress
tar -czvf my-graph-backup.tar.gz ~/logseq/my-graph

2. Audit Current Structure

Pages to review:

• [ ] Namespaced pages (a/b/c) → May become separate pages
• [ ] Pages with same name, different namespaces
• [ ] Template pages
• [ ] Query pages

Properties to review:

• [ ] Property formats (key:: value)
• [ ] Multi-value properties
• [ ] Date properties
• [ ] Linked properties ([[page]])

Tags to review:

• [ ] Simple tags (#tag)
• [ ] Page tags ([[tag]])
• [ ] Nested tags (#parent/child)

3. Identify Migration Decisions

| MD Pattern | DB Options | Decision Needed | |------------|------------|-----------------| | #tag | Class or page ref | Which tags become classes? | | [[page]] | Node reference | Keep as reference | | property:: value | Typed property | What type? | | namespace/page | Separate page or hierarchy | Flatten or nest? |

Migration Process

Step 1: Export from MD Version

1. Open your MD graph in Logseq
2. Go to Settings → Export
3. Choose Export to EDN (for full data)
4. Save the export file

Step 2: Prepare Import Settings

When importing to DB, you'll choose:

Tag Handling:

• Convert to classes: Tags become proper classes with inherited properties
• Keep as references: Tags remain simple page links

Namespace Handling:

• Flatten: a/b/c → single page "a/b/c"
• Hierarchical: Creates page hierarchy

Property Handling:

• Infer types: Logseq guesses types (number, date, etc.)
• All as text: Everything stays as strings

Step 3: Create New DB Graph

1. Create new DB-based graph in Logseq
2. Use Import feature
3. Select your exported data
4. Configure migration options
5. Review and confirm

Step 4: Post-Migration Validation

;; Check page count matches
[:find (count ?p)
 :where [?p :block/tags ?t]
        [?t :db/ident :logseq.class/Page]]

;; Check for orphaned blocks
[:find (pull ?b [:block/title])
 :where [?b :block/title _]
        (not [?b :block/page _])
        (not [?b :block/tags ?t]
             [?t :db/ident :logseq.class/Page])]

;; Verify properties migrated
[:find ?prop-name (count ?b)
 :where [?b ?prop _]
        [?p :db/ident ?prop]
        [?p :block/title ?prop-name]
        [(clojure.string/starts-with? (str ?prop) ":user.property")]]

Common Migration Issues

Issue 1: Lost Property Types

Symptom: Numbers/dates stored as strings

Solution: Manually update property types

;; In DB, update property type
{:db/ident :user.property/rating
 :logseq.property/type :number}  ; was :default

Issue 2: Tag/Class Confusion

Symptom: Tags didn't become proper classes

Solution: Convert pages to classes

1. Open the tag page
2. Add #Tag to make it a class
3. Define properties on the class

Issue 3: Broken References

Symptom: [[page]] links not working

Cause: Page names changed during migration

Solution: Use find/replace or query to identify broken refs

[:find ?ref-text
 :where
 [?b :block/title ?title]
 [(re-find #"\[\[.*?\]\]" ?title) ?ref-text]
 (not [_ :block/title ?ref-text])]

Issue 4: Namespace Flattening

Symptom: project/tasks and project/notes merged

Solution: Pre-migration, rename pages to avoid conflicts

Issue 5: Query Compatibility

Symptom: Old queries don't work

Reason: Different attribute names

| MD Attribute | DB Attribute | |--------------|--------------| | :block/content | :block/title | | :block/name | :block/title | | :page/tags | :block/tags |

Migration Strategies

Strategy 1: Big Bang Migration

• Migrate entire graph at once
• Best for: Small graphs, simple structure
• Risk: All-or-nothing

Strategy 2: Parallel Operation

• Keep MD graph active
• Create DB graph for new content
• Gradually move old content
• Best for: Large graphs, active use

Strategy 3: Selective Migration

• Export specific pages/areas
• Import into new DB graph
• Best for: Messy graphs needing cleanup

Best Practices

Before Migration

1. Clean up your graph

   • Remove unused pages
   • Standardize property names
   • Fix broken links

2. Document your structure

   • List all tags and their purposes
   • Document property meanings
   • Map namespaces

3. Plan your classes

   • Which tags become classes?
   • What properties do they need?
   • Define inheritance hierarchy

During Migration

1. Start small - Test with a subset
2. Compare counts - Pages, blocks, properties
3. Check critical pages - Most important content first
4. Verify queries - Update and test all queries

After Migration

1. Don't delete MD graph - Keep as backup
2. Monitor for issues - Note problems for feedback
3. Update workflows - Adapt to new features
4. Explore new capabilities - Classes, typed properties

Feature Comparison

Available in DB Version

• ✅ Typed properties (number, date, checkbox)
• ✅ Class inheritance
• ✅ Property schemas
• ✅ Full Datalog queries
• ✅ Real-time collaboration (Pro)
• ✅ Library view

Not Yet Available (Alpha)

• ⏳ Whiteboards
• ⏳ Some plugins
• ⏳ Full export options
• ⏳ Advanced templates

Different Behavior

• 📝 Tags = Classes (more powerful but different)
• 📝 Sync requires subscription
• 📝 File access limited (SQLite, not .md)

Resources

• Logseq DB Documentation
• DB Unofficial FAQ
• Migration Feedback Thread