simple-couchdb-sync/README.md

Simple CouchDB Sync

Simple CouchDB Sync is an Obsidian plugin that synchronizes vault files through a CouchDB database.

Features

• Manual synchronization command and ribbon action.
• Live synchronization for file create, modify, delete, rename events, and periodic remote pulls.
• Visible Obsidian status bar text with the latest sync result.
• Syncs Markdown notes and binary attachments.
• Uses Obsidian requestUrl, so it can work on desktop and mobile, including Android.
• Stores CouchDB connection settings inside the plugin settings tab.
• One-button plugin update from the Gitea repository.

Default Test Configuration

• Server: https://obsidian.dinlo.ru
• Database: obsidian-test
• User: test
• Password: testpassword

You can change these values in Obsidian under Settings -> Community plugins -> Simple CouchDB Sync.

Installation From Gitea On Desktop

The repository contains a ready-to-load Obsidian plugin. No build step is required.

1. Open the Obsidian vault folder on your computer.
2. Create this folder if it does not exist:

<vault>/.obsidian/plugins/simple-couchdb-sync/

3. Download these files from the Gitea repository and place them into that folder:

manifest.json
main.js
styles.css

4. Restart Obsidian, or run "Reload app without saving" from the command palette.
5. Open Settings -> Community plugins.
6. Disable Safe mode or Restricted mode if Obsidian asks for it.
7. Enable Simple CouchDB Sync.
8. Open the plugin settings and verify the CouchDB server, database, username, and password.
9. Press Sync in the plugin settings, or use the command Sync vault with CouchDB.
10. Keep Live sync enabled on every device that should receive remote changes automatically.

For your test vault, the target folder is:

C:\Users\dimir\Documents\ObsidianTest\Test\.obsidian\plugins\simple-couchdb-sync

If Git is installed, you can clone the repository directly into the plugin folder:

cd "C:\Users\dimir\Documents\ObsidianTest\Test\.obsidian\plugins"
git clone https://nnootteess.dinlo.ru/dimon/simple-couchdb-sync.git simple-couchdb-sync

Repository URL:

https://nnootteess.dinlo.ru/dimon/simple-couchdb-sync

Installation From Gitea On Android

Android Obsidian can load the same plugin files, but the folder must be copied into the mobile vault.

1. Enable Community plugins in Obsidian for Android.
2. Using a file manager, open your vault folder on the phone.
3. Create this folder:

<vault>/.obsidian/plugins/simple-couchdb-sync/

4. From the Gitea repository, download these files:

manifest.json
main.js
styles.css

5. Copy the three files into:

<vault>/.obsidian/plugins/simple-couchdb-sync/

6. Fully close and reopen Obsidian on Android.
7. Go to Settings -> Community plugins and enable Simple CouchDB Sync.
8. Open the plugin settings and enter the same CouchDB connection settings as on desktop.
9. Run Sync vault with CouchDB.
10. Keep Live sync enabled if the phone should pull changes from CouchDB automatically.

For easier Android updates, install an Android Git client such as Termux or a file manager with Git support, then clone the repository into the same plugin folder. After updating files, restart Obsidian so it reloads main.js.

Updating The Plugin

The plugin includes a one-button updater.

1. Open Obsidian Settings -> Community plugins -> Simple CouchDB Sync.
2. In Plugin updates, keep the Gitea raw URL as:

https://nnootteess.dinlo.ru/dimon/simple-couchdb-sync/raw/branch/main

3. Press Check and update.
4. Restart Obsidian, or disable and re-enable the plugin.

Manual update is also possible. When the repository changes, update these three files in the plugin folder:

manifest.json
main.js
styles.css

Then restart Obsidian or disable and re-enable the plugin.

Live Sync Behavior

Live sync must be enabled on every device where automatic updates are expected.

• When a local file changes, the plugin queues it and syncs after a short delay.
• On the configured interval, the plugin checks CouchDB for changes created on other devices.
• The status bar shows the latest result, including pushed and pulled file counts.
• If live sync is disabled, use the Sync button manually on each device.

CouchDB Notes

The plugin stores one CouchDB document per vault file. Document ids are derived from file paths. Deleted files are represented by tombstone documents so deletion can propagate between devices.

The CouchDB user needs read and write access to the database. If the database does not exist, the plugin will try to create it.