fs

README

Kivik FSDB

Experimental file system driver for Kivik.

This driver stores documents on a plain filesystem.

Status

This is very much a work in progress. Things are expected to change quickly.

Usage

This package provides an implementation of the github.com/go-kivik/kivik/driver interface. You must import the driver and can then use the full Kivik API. Please consult the Kivik wiki for complete documentation and coding examples.

package main

import (
    "context"

    "github.com/go-kivik/kivik/v4"
    _ "github.com/go-kivik/kivik/v4/x/fsdb" // The File system driver
)

func main() {
    client, err := kivik.New(context.TODO(), "fs", "")
    // ...
}

License

This software is released under the terms of the Apache 2.0 license. See LICENCE.md, or read the full license.

Documentation

Overview

Package fs provides an experimental filesystem-backed Kivik driver. This driver is very much a work in progress. Please refer to the GitHub page for current status and ongoing changes. https://github.com/go-kivik/kivik/x/fsdb

Bug reports, feature requests, and pull requests are always welcome. Current development is primarily focused around using fsdb for testing of CouchDB applications, and bootstraping CouchDB applications.

General Usage

Use the `fs` driver name when using this driver. The DSN should be an existing directory on the local filesystem. Access control is managed by your filesystem permissions.

import (
	"github.com/go-kivik/kivik/v4"
	_ "github.com/go-kivik/kivik/v4/x/fsdb" // The Filesystem driver
)

client, err := kivik.New("fs", "/home/user/some/path")

Database names represent directories under the path provided to `kivik.New`. For example:

db := client.DB(ctx, "foo")

would look for document files in `/home/usr/some/path/foo`.

Connection Strings

This driver supports three types of connection strings to the New() method:

• Local filesystem path. This may be relative or absolute. Examples: `/home/user/some/path` and './some/path'
• A full file:// URL. Example: 'file:///home/user/some/path'
• An empty string (""), which requires the full path to the database is passed to the `DB()` method. In this case, the argument to `DB()` accepts the first two formats, with the final path element being the database name. Some client-level methods, such as AllDBs(), are unavailable, when using an empty connection string.

Handling of Filenames

CouchDB allows databases and document IDs to contain a slash (/) character. This is not permitted in most operating systems/filenames, to be stored directly on the filesystem this way. Therefore, it is necessary for this package to escape certain characters in filenames. This is done as conservatively as possible. The escaping rules are:

• It contains a slash (i.e. '_design/index'), or a URL-encoded slash (i.e. '%2F' or '%2f')
• When escaping a literal slash (/) or a literal percent sign (%), are escaped using standard URL escaping. No other characters are escaped.

Index

• Constants

Constants

const (
	Version = "0.0.1"
	Vendor  = "Kivik File System Adaptor"
)

Identifying constants