Crate bear_query 

bear-query

A completely read-only, minimal-contention library for querying Bear app’s SQLite database.

Safety Guarantees

This library implements multiple layers of protection to ensure minimal interference with Bear:

1. Read-Only File Access: Opens with SQLITE_OPEN_READ_ONLY
2. No Internal Locks: Uses SQLITE_OPEN_NO_MUTEX to minimize lock contention
3. Query-Only Mode: Enforces PRAGMA query_only = ON at SQLite level
4. Short-Lived Connections: Connections are only open during each query
5. Busy Timeout: 5000ms timeout handles database contention gracefully

How It Works

Bear does not use SQLite’s WAL (Write-Ahead Logging) mode by default. To minimize interference, this library uses short-lived connections that are opened only when needed and closed immediately after use.

Each method call:

• Opens a read-only connection with a 5000ms busy timeout
• Executes the query
• Automatically closes the connection

This approach ensures minimal lock contention with Bear’s write operations.

Normalized Schema

This library automatically normalizes Bear’s Core Data schema through Common Table Expressions (CTEs). All queries (both typed methods and the generic query() API) have access to these normalized views:

notes Table

The normalized view of all notes in Bear.

Column	Type	Description
id	TEXT	Bear’s UUID for the note (primary identifier)
core_db_id	INTEGER	Internal Core Data primary key (for joins)
title	TEXT	Note title
content	TEXT	Full note content (Markdown)
modified	DATETIME	Last modification timestamp (converted from Core Data epoch)
created	DATETIME	Creation timestamp (converted from Core Data epoch)
is_pinned	INTEGER	1 if pinned, 0 otherwise
is_trashed	INTEGER	1 if in trash, 0 otherwise
is_archived	INTEGER	1 if archived, 0 otherwise

tags Table

The normalized view of all tags.

Column	Type	Description
id	INTEGER	Tag’s primary key
name	TEXT	Tag name (e.g., “work/projects”)
modified	DATETIME	Last modification timestamp

note_tags Table

Junction table linking notes to their tags (many-to-many relationship).

Column	Type	Description
note_id	TEXT	Note UUID (references notes.id)
tag_id	INTEGER	Tag ID (references tags.id)

note_links Table

Links between notes (bidirectional wiki-style links).

Column	Type	Description
from_note_id	TEXT	Source note UUID (references notes.id)
to_note_id	TEXT	Target note UUID (references notes.id)

Core Data Epoch Conversion

Bear uses Apple’s Core Data timestamp format (seconds since 2001-01-01 00:00:00 UTC). This library automatically converts all timestamps to standard SQLite datetime format.

The conversion is done via a CTE: unixepoch('2001-01-01')

Schema Discovery

The library discovers variable schema elements at initialization:

• Junction table column names (e.g., Z_5NOTES, Z_13TAGS)
• These numbers may vary across Bear versions

For full schema details, see the SCHEMA.md documentation file.

Example

use bear_query::{BearDb, NotesQuery, SearchQuery, SortOn};

// Create a handle (no connection opened yet)
let db = BearDb::new()?;

// Each method opens a connection, queries, and closes
let all_tags = db.tags()?;
let recent_notes = db.notes(NotesQuery::default())?;

for note in recent_notes {
    let title = note.title();
    if title.is_empty() {
        println!("[Untitled]");
    } else {
        println!("{}", title);
    }
}

// Search notes by title and/or content
let search_results = db.search(SearchQuery::new("rust"))?;

// Advanced search with filters
let filtered_results = db.search(
    SearchQuery::new("project")
        .title_only()
        .sort_by(SortOn::Title.asc())
        .limit(20)
)?;

Modules

polars_prelude

Structs

BearDb

Handle to Bear’s database. All operations use short-lived connections internally.

Note

A note from Bear’s database.

NoteId

Bear note identifier (UUID-based).

NotesQuery

Query options for filtering notes.

Queryable

A wrapper around a database connection that automatically applies normalizing CTEs to queries. This abstracts away Bear’s Core Data quirks (Z_ prefixes, numbered columns, epoch timestamps).

SearchQuery

Query builder for searching notes.

Tag

A tag from Bear’s database.

TagId

Unique identifier for a Bear tag.

TagsMap

Collection of tags from Bear’s database.

Enums

BearError

SortOn

What field to sort by.

SortOrder

Sort order for search results.