pinboard-notes-backup: Back up the notes you've saved to Pinboard

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

A command-line application to back up your notes from the Pinboard bookmarking service to a local SQLite database.


[Skip to Readme]

Properties

Versions 1.0.4, 1.0.4.1, 1.0.5, 1.0.5, 1.0.5.1, 1.0.5.2, 1.0.5.3
Change log None available
Dependencies aeson (>=0.8 && <1.5), ansi-wl-pprint (==0.6.*), base (>=4.7 && <5), bytestring (==0.10.*), containers (>=0.5 && <0.7), http-client (>=0.5 && <0.7), http-types (==0.12.*), mtl (==2.2.*), optparse-applicative (>=0.11 && <0.15), req (>=1.0 && <2.2), sqlite-simple (==0.4.*), text (==1.2.*), time (>=1.5 && <1.10), transformers (>=0.4 && <0.6) [details]
License GPL-3.0-only
Copyright 2016-2017, 2019 Benjamin D. Esham
Author Benjamin Esham
Maintainer benjamin@esham.io
Category Backup, CLI, Pinboard
Home page https://github.com/bdesham/pinboard-notes-backup
Source repo head: git clone git://github.com/bdesham/pinboard-notes-backup.git
Uploaded by bdesham at 2019-09-15T16:30:12Z

Downloads

Maintainer's Corner

For package maintainers and hackage trustees


Readme for pinboard-notes-backup-1.0.5

[back to package description]

pinboard-notes-backup Build Status

Back up the notes you’ve saved to Pinboard.

Installation

Homebrew

If you’re using Homebrew, you can just run

brew install pinboard-notes-backup

Nix

If you’re using the Nix package manager, run

nix-env -i -A nixpkgs.pinboard-notes-backup

If you use NixOS, run

nix-env -i -A nixos.pinboard-notes-backup

Manual installation

Prebuilt binaries are available for OS X and Linux—find them on the page for the most recent release. To install the program from one of these,

  1. Download the archive for your OS and unpack it.

  2. Copy the pnbackup binary to some directory in your PATH, like /usr/local/bin.

  3. Optional: Install the man page by running

    install -D --mode=444 pnbackup.1 /usr/local/share/man/man1
    
  4. Optional: Generate and install a Bash completion script by running

    mkdir -p /usr/local/etc/bash_completion.d
    pnbackup --bash-completion-script $(which pnbackup) > \
        /usr/local/etc/bash_completion.d/pnbackup.bash
    
  5. Optional: Generate and install a Zsh completion script by running

    mkdir -p /usr/local/share/zsh/site-functions
    pnbackup --zsh-completion-script $(which pnbackup) > \
        /usr/local/share/zsh/site-functions/_pnbackup
    

Building from source

This is a Haskell program that you can build using Stack. With Stack installed, just type

stack setup

to download and install GHC (the Haskell compiler) and then

stack install

to build the pnbackup binary and install it. (The default installation directory is ~/.local/bin; pass an argument like --local-bin-path=/usr/local/bin to change this.)

Usage

First you’ll need to grab your Pinboard API token from Pinboard’s password settings page. It’s a string like “maciej:abc123456”.

To save your notes to a file called “Notes.sqlite”, run

pnbackup -t maciej:abc123456 Notes.sqlite

replacing the example API token with your own. This will put all of your notes into a SQLite database called “Notes.sqlite”.

Each time you run the program, it will fetch the list of your notes from the Pinboard server. It will then download any notes that are new or that have been updated on the server, and it will delete any notes that have been deleted from the server. The program does one-way synchronization only: it will update your local database to match what’s on the server but it will never make any changes on the server.

The Pinboard API requires a three-second wait time between each request, and the text of each note must be downloaded in a separate request, so the initial download of your notes may take a while. Subsequent syncs will generally be much shorter, depending on how often you add or modify notes and how often you run pnbackup. If you want to see exactly what pnbackup is doing as it works, pass it the -v or --verbose flags.

Data format

Your notes are stored in a table called “notes” with the following schema:

CREATE TABLE notes (
    id TEXT NOT NULL UNIQUE,
    title TEXT NOT NULL,
    text TEXT NOT NULL,
    hash TEXT NOT NULL,
    created DATETIME NOT NULL,
    updated DATETIME NOT NULL
);

These columns correspond exactly to the fields listed on the Pinboard API page.

Why SQLite and not some plain-text format? In the words of Paul Ford,

SQLite is incredibly well-documented. It’s also instantly usable as a database from the command line with no pre-processing at all, even for very large files, and there are immediately usable SQLite APIs for every programming language. Plus it’s incredibly easy to turn SQLite data into plain text, it has freely available extensions for geo, full-text, and hierarchical data, and it’s tiny and public-domain.

If you've used this application to back up your notes to a file called Notes.sqlite, you could use this quick and dirty Python script to print them in JSON format:

#!/usr/bin/env python3

from json import dumps
import sqlite3

conn = sqlite3.connect("Notes.sqlite")
conn.row_factory = sqlite3.Row
curs = conn.cursor()
curs.execute("SELECT * FROM notes")
print(dumps([dict(r) for r in curs.fetchall()]))

Author

This program was created by Benjamin Esham.

This project is hosted on GitHub. Please feel free to submit pull requests.

Version history

These version numbers approximately follow the Haskell Package Versioning Policy (PVP). (I say “approximately” because this package contains no libraries—only an executable—and so it does not actually provide an API per se.)

License

The scripts in the “travis_scripts” folder were adapted from scripts written by Taylor Fausak for the Octane project. They are released under the license of that project.

The rest of the code in this repository is released under the following terms:

Copyright © 2016–2017, 2019 Benjamin D. Esham.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

The GNU General Public License can be found in the file LICENSE.txt.