Created under a MIT-style license.
CouchDB is a database that completely embraces the web. Store your data with JSON documents. Access your documents with your web browser, via HTTP.
A basic understanding of CouchDB is required to use this library. Detailed information can be found at the official documentation site.
The connection to the database, along with authentication, is hadled via CouchDbClient
for both web and server environments.
Available three types of authentication:
- Basic
- Cookie
- Proxy
For Basic
authentication simply pass username
and password
to constructor:
final c = CouchDbClient(username: 'name', password: 'pass');
For Cookie
authentication you also must provide auth
parameter and then call authenticate()
method
(note that cookies are valid for 10
minutes by default, other expiration you may specify in Expiration
header):
final c = CouchDbClient(username: 'name', password: 'pass', auth: 'cookie');
final res = await c.authenticate();
authenticate()
,logout()
are suitable only forcookie
authentication.userInfo()
are suitable for all auth types.
For Proxy
authentication pass username
to constructor and provide
X-Auth-CouchDB-UserName
: username (by default is used username
that is passed to constructor, so it can be skipped);X-Auth-CouchDB-Roles
: comma-separated (,) list of user roles;X-Auth-CouchDB-Token
: authentication token. When proxy_use_secret
is set (which is strongly recommended!), this header provides an HMAC of the username to authenticate and the secret token to prevent requests from untrusted sources (by default are used username
and secret
that are passed to constructor, so it can be skipped).headers:
final c = CouchDbClient(username: 'name', auth: 'proxy', secret: 'lakLdsjhUhadsfEd'); // just example
c.modifyRequestHeaders(<String, String>{
'X-Auth-CouchDB-Roles': 'users,blogger'
});
Note that
X-Auth-CouchDB-Token
isn't required if proxy_use_secret sets tofalse
.
[couch_httpd_auth]
proxy_use_secret = false
Otherwise you may provide
secret
option which is used to generate token. The secret key should be the same on the client and the CouchDB node:
[couch_httpd_auth]
secret = 92de07df7e7a3fe14808cef90a7cc0d91
To use this authentication method make sure that the {chttpd_auth, proxy_authentication_handler} value in added to the list of the active chttpd/authentication_handlers:
[chttpd]
authentication_handlers = {chttpd_auth, cookie_authentication_handler}, {chttpd_auth, proxy_authentication_handler}, {chttpd_auth, default_authentication_handler}
You can communicate with the server directly if you wish via the http client methods such as get()
and post()
, however, other classes provide functions which can abstract away the particulars of HTTP, therefore using these client methods directly is not the way you will typically use this library.
Every supported method: HEAD
, GET
, POST
, PUT
and COPY
- has an Accept
header with default value as application/json
, and POST
and PUT
both have a Content-Type
header with default value as application/json
.
You can override this if you need.
All requests, both those by the basic http methods, as well as those by the other classes we will go over in a moment, return a DbResponse
object. It is contain an DbResponse.json
property (Map
type) that contain JSON that was sent by CouchDB, DbResponse.raw
property (String
type) for responses that aren't valid JSON (numbers, lists, files) and DbResponse.headers
property that contains headers of the response.
In order to gets concrete object representation of the response you may call methods of the DbResponse
class that can return:
- ServerModelResponse
- DatabaseModelResponse
- DocumentModelResponse
- DesignDocumentModelResponse
- LocalDocumentModelResponse
- ErrorResponse
Each of these class have specific properties that can be provided by CouchDB according to categories of API decribed below.
All of the API is divided into five areas or categories, each representing a different aspect of the database overall. These five categories are:
1. Server
2. Database
3. Documents
4. Design documents
5. Local documents
Represented by the ServerModel
class. This class provides server-level interaction with CouchDB, such as managing replication or obtaining basic information about the server. Also it includes info about authentication and current user (methods in CouchDbClient
class).
A Database in CouchDB is a single document store located on the given database server. This part of the API is represented by the DatabaseModel
class. You will use this class for interacting with your data on a database level; for example creating a new database or preforming a query to search for certain documents.
You will use the DocumentModel
class to interact with the data on a document level. This would include functions such as fetching a specific document, adding a new document, or attaching a file to a document. Note that this class does not model the documents themselves, but rather your interactions with them. The documents themselves are represented as Map
s.
Represented by the DesignDocumentModel
, design documents provide views of data in the database.
Local documents are no different than normal documents, with the exception that they are not copied to other instances of CouchDB during replication. You will interact with them via the LocalDocumentModel
class.
If your application aren't on the same origin with CouchDB instance or you using different ports on server, then the remote CouchDB must be configured with the following options:
[httpd]
enable_cors = true
[cors]
origins = *
credentials = true
methods = GET, PUT, POST, HEAD, DELETE, COPY
headers = accept, authorization, content-type, origin, referer, x-csrf-token
(Change these settings either in Fauxton or in the local.ini file).
A simple usage example:
import 'package:couchdb/couchdb.dart';
Future<void> main() async {
final client = CouchDbClient(username: 'name', password: 'password');
final dbModel = DatabaseModel(client);
final docModel = DocumentModel(client)
try {
final DbResponse commonResponse = await dbModel.allDocs('some_db');
final DatabaseModelResponse response1 = commonResponse.databaseModelResponse();
for (var i in response1.rows) {
// Some code here
}
final DbResponse response2 = await docModel.doc('another_db', 'some_id');
var thing = response2.json['some_attribute'];
} on CouchDbException catch (e) {
print('$e - error');
}
}
Please file feature requests and bugs at the issue tracker.
With ❤️ to CouchDB
secret
fiels to CouchDbClient
class for proxy authentication.authenticate()
, logout()
and userInfo()
methods to CouchDbClient
class.ServerModelResponse
class.CouchDbWebClient
and CouchDbServerClient
to CouchDbClient
class.streamed()
method to CouchDbClient
class.DatabaseModel.changesIn()
and DatabaseModel.postChangesIn()
methods to return stream of event responses (fix for alive connection)....Response
classes final.revsDiff
property in DbResponse
class.Split DbResponse
to five classes corresponds to categories of CouchDB:
1. Server
2. Database
3. Documents
4. Design documents
5. Local documents
Change signatures of some methods (check your code for error and reference to Docs).
Add purgedInfosLimit()
and setPurgedInfosLimit()
to DatabaseModel
class.
Improve docs in API docs (add return's JSON example).
Move headers
to separate field in DbResponse
from json.
Improved README.
2.1.0-dev.9.4
.cors
field to CouchDbWebClient
class.cors
parameter from constructor of CouchDbServerClient
and CouchDbBaseClient
classes._headers
field, headers
getter and improve modifyRequestHeaders()
method of CouchDbBaseClient
class.CouchDb(Server/Web)Client
to CouchDbBaseClient
._client
from CouchDb(Server/Web)Client
and change constructors from being factory
to usual.cors
field to CouchDbBaseClient
class and its constructor.getAllDocs()
to allDocs()
, getAllDesignDocs()
to allDesignDocs()
,
getBulkDocs()
to bulkDocs()
, getDocsByKeys()
to docsByKeys()
methods of DatabaseModel
class.getDesignDoc()
to designDoc()
, getAttachment()
to attachment()
methods
of DesignDocumentModel
class.getDoc()
to doc()
, getAttachment()
to attachment()
methods of DocumentModel
class.getLocalDocs()
to localDocs()
, getLocalDocsWithKeys()
to localDocsWithKeys()
,
getLocalDoc()
to localDoc()
methods of LocalDocumentModel
class.getClusterSetup()
to clusterSetupStatus()
method of ServerModel
class.includeDocs
parameter to allDocs()
method of DatabaseModel
class.ServerModel
class.DesignDocumentModel
class.CouchDb(Server/Web)Client
classes.raw
field to DbResponse
class (prior rawBody
).body
parameter of post()
method in CouchDb(Server/Web)Client
to Object
type.schedulerJobs()
, schedulerDocs()
, schedulerDocsWithReplicatorDbName()
, schedulerDocsWithDocId()
,
nodeStats()
, systemStatsForNode()
, up()
and uuids()
methods of ServerModel
class.DbResponse
class.toString()
method of CouchDbException
class - it shows error code, name error and reason.allNodes
, clusterNodes
, history
, replicationIdVersion
, sessionId
and sourceLastSeq
fields to DbResponse
class.configureCouchDb()
, dbUpdates()
, membership()
and replicate()
methods of ServerModel
class.CouchDbWebClient
and CouchDbServerClient
to the separate export.rawBody
field from DbResponse
class.state
field to DbResponse
class.couchDbInfo()
, activeTasks()
, allDbs()
, dbsInfo()
and getClusterSetup()
methods of ServerModel
class.CouchDb(Server/Web)Client
classes.CouchDbWebClient
class for interacting with CouchDB.example/README.md
.attachmentInfo()
, getAttachment()
, insertAttachment()
and deleteAttachment()
methods of DocumentModel
class.setRevsLimit()
method of DatabaseModel
class.put()
now accept any body type.rawBody
field of DbRespone
class.insertDoc()
, deleteDoc()
and copyDoc()
methods of DocumentModel
class.CouchDb(Server/Web)Client
can set custom headers.docInfo()
and getDoc()
methods of DocumentModel
class.DatabaseModel
methods.head()
method of CouchDb(Server/Web)Client
classes.CouchDbServerClient
for interacting with CouchDB.DatabaseBaseModel
methods.example/README.md
import 'package:couchdb/couchdb.dart';
Future<void> main() async {
final client = CouchDbClient(username: 'name', password: 'password');
final dbModel = DatabaseModel(client);
final docModel = DocumentModel(client)
try {
final DbResponse commonResponse = await dbModel.allDocs('some_db');
final DatabaseModelResponse response1 = commonResponse.databaseModelResponse();
for (var i in response1.rows) {
// Some code here
}
final DbResponse response2 = await docModel.doc('another_db', 'some_id');
var thing = response2.json['some_attribute'];
} on CouchDbException catch (e) {
print('$e - error');
}
}
import 'dart:html';
import 'package:couchdb/couchdb.dart';
Future<void> main(List<String> args) async {
final ButtonElement btn = querySelector('#data');
final DivElement output = querySelector('#output');
final c = CouchDbClient(username: 'name', password: 'pass', cors: true);
final dm = DocumentModel(c);
btn.onClick.listen((event) async {
try {
final DbResponse commonResponse = await dbModel.doc('some_db', 'some_doc_id');
final DocumentModelResponse response1 = commonResponse.documentModelResponse();
final Map<String, Object> doc = response1.doc;
// Some code here
// There properties are extracted from [doc] in order to gets direct access
final String id = response1.id;
final String rev = response1.rev;
final Object attachment = response1.attachment;
// Another code here
} on CouchDbException catch (e) {
window.console.log('${e.code} - error');
}
});
}
Add this to your package's pubspec.yaml file:
dependencies:
couchdb: ^0.4.1
You can install packages from the command line:
with pub:
$ pub get
with Flutter:
$ flutter packages get
Alternatively, your editor might support pub get
or flutter packages get
.
Check the docs for your editor to learn more.
Now in your Dart code, you can use:
import 'package:couchdb/couchdb.dart';
Version | Uploaded | Documentation | Archive |
---|---|---|---|
0.4.1 | Feb 11, 2019 |
|
|
0.4.0 | Feb 10, 2019 |
|
|
0.3.0 | Feb 9, 2019 |
|
|
0.2.1 | Jan 23, 2019 |
|
|
0.2.0 | Jan 23, 2019 |
|
|
0.1.4+1 | Jan 17, 2019 |
|
|
0.1.4 | Jan 2, 2019 |
|
|
0.1.3 | Dec 29, 2018 |
|
|
0.1.2 | Dec 27, 2018 |
|
|
0.1.1 | Dec 11, 2018 |
|
|
Popularity:
Describes how popular the package is relative to other packages.
[more]
|
56
|
Health:
Code health derived from static analysis.
[more]
|
100
|
Maintenance:
Reflects how tidy and up-to-date the package is.
[more]
|
100
|
Overall:
Weighted score of the above.
[more]
|
78
|
We analyzed this package on Feb 14, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:
Detected platforms: Flutter, web, other
No platform restriction found in primary library
package:couchdb/couchdb.dart
.
Package | Constraint | Resolved | Available |
---|---|---|---|
Direct dependencies | |||
Dart SDK | >=2.1.0-dev.9.4 <3.0.0 | ||
crypto | ^2.0.6 | 2.0.6 | |
http | ^0.12.0+1 | 0.12.0+1 | |
meta | ^1.1.7 | 1.1.7 | |
Transitive dependencies | |||
async | 2.0.8 | ||
charcode | 1.1.2 | ||
collection | 1.14.11 | ||
convert | 2.1.1 | ||
http_parser | 3.1.3 | ||
path | 1.6.2 | ||
source_span | 1.5.4 | ||
string_scanner | 1.0.4 | ||
term_glyph | 1.1.0 | ||
typed_data | 1.1.6 | ||
Dev dependencies | |||
test | ^1.5.3 |