1 // Licensed under the Apache License, Version 2.0 (the "License"); you may not 2 // use this file except in compliance with the License. You may obtain a copy of 3 // the License at 4 // 5 // http://www.apache.org/licenses/LICENSE-2.0 6 // 7 // Unless required by applicable law or agreed to in writing, software 8 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 9 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 10 // License for the specific language governing permissions and limitations under 11 // the License. 12 13 /* 14 Package fs provides an experimental filesystem-backed Kivik driver. This driver 15 is an experimental work in progress, and subject to change without notice. 16 Please refer to the GitHub page for current status and ongoing changes. 17 https://github.com/go-kivik/kivik/x/fsdb 18 19 Bug reports, feature requests, and pull requests are always welcome. Current 20 development is primarily focused around using fsdb for testing of CouchDB 21 applications, and bootstrapping CouchDB applications. 22 23 # General Usage 24 25 Use the `fs` driver name when using this driver. The DSN should be an existing 26 directory on the local filesystem. Access control is managed by your filesystem 27 permissions. 28 29 import ( 30 "github.com/go-kivik/kivik/v4" 31 _ "github.com/go-kivik/kivik/v4/x/fsdb" // The Filesystem driver 32 ) 33 34 client, err := kivik.New("fs", "/home/user/some/path") 35 36 Database names represent directories under the path provided to `kivik.New`. 37 For example: 38 39 db := client.DB(ctx, "foo") 40 41 would look for document files in `/home/usr/some/path/foo`. 42 43 # Connection Strings 44 45 This driver supports three types of connection strings to the New() method: 46 47 - Local filesystem path. This may be relative or absolute. Examples: 48 `/home/user/some/path` and './some/path' 49 - A full file:// URL. Example: 'file:///home/user/some/path' 50 - An empty string (""), which requires the full path to the database is passed 51 to the `DB()` method. In this case, the argument to `DB()` accepts the first 52 two formats, with the final path element being the database name. Some 53 client-level methods, such as AllDBs(), are unavailable, when using an empty 54 connection string. 55 56 # Handling of Filenames 57 58 CouchDB allows databases and document IDs to contain a slash (/) 59 character. This is not permitted in most operating systems/filenames, to 60 be stored directly on the filesystem this way. Therefore, it is necessary 61 for this package to escape certain characters in filenames. This is done 62 as conservatively as possible. The escaping rules are: 63 64 - It contains a slash (i.e. '_design/index'), or a URL-encoded slash 65 (i.e. '%2F' or '%2f') 66 - When escaping a literal slash (/) or a literal percent sign (%), are 67 escaped using standard URL escaping. No other characters are escaped. 68 */ 69 package fs 70