Skip to content

Commit 4c0d0a1

Browse files
biozalblaugold
biozal
and
blaugold
authored
docs: add docs for databases, pre-built databases, documents, blobs (cbl-dart#430)
Co-authored-by: Gabriel Terwesten <[email protected]>
1 parent 3d4b91a commit 4c0d0a1

29 files changed

+1578
-88
lines changed

‎docs/docs/blobs.mdx

+107
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
---
2+
description: Couchbase Lite Concepts — Data Model — Blobs
3+
related_content:
4+
- name: Databases
5+
url: /databases
6+
- name: Documents
7+
url: /documents
8+
- name: Indexing
9+
url: /indexing
10+
---
11+
12+
# Blobs
13+
14+
## Introduction
15+
16+
Couchbase Lite for Dart uses blobs to store the contents of images, other media
17+
files and similar format files as binary objects.
18+
19+
The blob itself is not stored in the document. It is held in a separate
20+
content-addressable store indexed from the document and retrieved only
21+
on-demand.
22+
23+
When a document is synchronized, the Couchbase Lite replicator adds an
24+
`_attachments` dictionary to the document's properties if it contains a blob
25+
— see [Figure 1](#).
26+
27+
## Blob Objects
28+
29+
The blob as an object appears in a document as dictionary property — see, for
30+
example _avatar_ in [Figure 1](#).
31+
32+
Other properties include `length` (the length in bytes), and optionally
33+
`content_type` (typically, its MIME type).
34+
35+
The blob's data (an image, audio or video content) is not stored in the
36+
document, but in a separate content-addressable store, indexed by the `digest`
37+
property — see [Using Blobs](#using-blobs).
38+
39+
### Constraints
40+
41+
- Couchbase Lite <br /> Blobs can be arbitrarily large. They are only read on
42+
demand, not when you load a the document.
43+
44+
- Capella App Services/Sync Gateway <br /> The maximum content size is 20 MB per
45+
blob. If a document's blob is over 20 MB, the document will be replicated but
46+
not the blob.
47+
48+
## Using Blobs
49+
50+
The `api|Blob` API lets you access the blob's data content as in-memory data
51+
(`api|dart:typed_data|Uint8List`) or as a `api|dart:async|Stream` of
52+
`api|dart:typed_data|Uint8List`s.
53+
54+
The code in [Example 1](#) shows how you might add a blob to a document and save
55+
it to the database. Here we use avatar as the property key and a jpeg file as
56+
the blob data.
57+
58+
<CodeExample id={1} title="Working with Blobs">
59+
60+
```dart
61+
final data = getAsset('avatar.jpg');
62+
if (data == null) { return; }
63+
64+
final blob = Blob.fromData('image/jpeg', data);
65+
doc.setBlob(blob, key: 'avatar');
66+
await database.saveDocument(doc);
67+
68+
final image = doc.blob('avatar');
69+
```
70+
71+
</CodeExample>
72+
73+
## Syncing
74+
75+
When a document containing a blob object is synchronized, the Couchbase Lite
76+
replicator generates an `_attachments` dictionary with an auto-generated name
77+
for each blob attachment. This is different to the `avatar` key and is used
78+
internally to access the blob content.
79+
80+
If you view a sync'd blob document in either Capella's Admin Interface or
81+
Couchbase Server's Admin Console, you will see something similar to
82+
[Figure 1](#), which shows the document with its generated `_attachments`
83+
dictionary, including the digest.
84+
85+
<Figure id={1} title="Sample Blob Document">
86+
87+
```json
88+
{
89+
"_attachments": {
90+
"blob_1": {
91+
"content_type": "image/jpeg",
92+
"digest": "sha1-F1Tfe61RZP4zC9UYT6JFmLTh2s8=",
93+
"length": 8112955,
94+
"revpos": 2,
95+
"stub": true
96+
}
97+
},
98+
"avatar": {
99+
"@type": "blob",
100+
"content_type": "image/jpeg",
101+
"digest": "sha1-F1Tfe61RZP4zC9UYT6JFmLTh2s8=",
102+
"length": 8112955
103+
}
104+
}
105+
```
106+
107+
</Figure>

‎docs/docs/databases.mdx

+202
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
---
2+
description: Working with Couchbase Lite databases with Dart.
3+
related_content:
4+
- name: Blobs
5+
url: /blob
6+
- name: Documents
7+
url: /documents
8+
- name: Indexing
9+
url: /indexing
10+
---
11+
12+
import Tabs from '@theme/Tabs'
13+
import TabItem from '@theme/TabItem'
14+
15+
# Databases
16+
17+
## Create or Open Database
18+
19+
You can create a new database and-or open an existing database, using the
20+
`api|Database` class. The database class provides both synchronous and
21+
asynchronous methods for opening and closing databases (see
22+
[explanation for Synchronous and Asynchronous APIs](/key-concepts.mdx#sync-and-async-apis)).
23+
Just pass in a database name and optionally a `api|DatabaseConfiguration` - see
24+
[Example 1](#).
25+
26+
Things to watch for include:
27+
28+
- If the named database does not exist in the specified, or default, location
29+
then a new one is created.
30+
- The database is created in a default location unless you specify a directory
31+
for it — see: `api|DatabaseConfiguration.directory`.
32+
33+
:::tip
34+
35+
Best Practice is to always specify the path to the database explicitly.
36+
37+
:::
38+
39+
See [Supported Platforms](./supported-platforms.mdx) for the default location
40+
for each platform.
41+
42+
<CodeExample id={1} title="Opening a Database">
43+
44+
<APITabs>
45+
<APITab api="Async">
46+
47+
```dart
48+
final database = await Database.openAsync('my-database');
49+
```
50+
51+
</APITab>
52+
<APITab api="Sync">
53+
54+
```dart
55+
final database = Database.openSync('my-database');
56+
```
57+
58+
</APITab>
59+
</APITabs>
60+
61+
</CodeExample>
62+
63+
## Close Database
64+
65+
You are advised to incorporate the closing of all open database into your
66+
application workflow.
67+
68+
Closing a database is simple, just call use `api|Database.close`. See
69+
[Example 2](#). This also closes active replications, listeners, and-or live
70+
queries connected to the database.
71+
72+
<CodeExample id={2} title="Closing a Database">
73+
74+
```dart
75+
await database.close();
76+
```
77+
78+
</CodeExample>
79+
80+
## Database Encryption
81+
82+
<EnterpriseFeatureCallout />
83+
84+
Couchbase Lite includes the ability to encrypt Couchbase Lite databases. This
85+
allows mobile applications to secure data at rest, when it is being stored on
86+
the device. The algorithm used to encrypt the database is 256-bit AES.
87+
88+
### Enabling
89+
90+
To enable encryption, use `api|DatabaseConfiguration.encryptionKey` to set the
91+
encryption key of your choice. Provide this encryption key every time the
92+
database is opened - see [Example 3](#).
93+
94+
<CodeExample id={3} title="Opening an Encrypted Database">
95+
96+
```dart
97+
final key = await EncryptionKey.passwordAsync('secret password');
98+
final config = DatabaseConfiguration(encryptionKey: key);
99+
final database = await Database.openAsync('my-database', config);
100+
```
101+
102+
</CodeExample>
103+
104+
### Persiting
105+
106+
Couchbase Lite does not persist the key. It is the application's responsibility
107+
to manage the key and store it in a platform specific secure store such as
108+
Apple's
109+
[Keychain](https://developer.apple.com/documentation/security/keychain_services)
110+
or Android's
111+
[Keystore](https://developer.android.com/training/articles/keystore).
112+
113+
### Opening
114+
115+
An encrypted database can only be opened with the same language SDK that was
116+
used to encrypt it in the first place. So a database encrypted using the Dart
117+
SDK, and then exported, is readable only by the Dart or C SDK.
118+
119+
### Changing
120+
121+
To change an existing encryption key, open the database using its existing
122+
encryption-key and use `api|Database.changeEncryptionKey` to set the required
123+
new encryption-key value.
124+
125+
### Removing
126+
127+
To remove encryption, open the database using its existing encryption-key and
128+
use `api|Database.changeEncryptionKey` with a `null` value as the encryption
129+
key.
130+
131+
## Database Maintenance
132+
133+
From time to time it may be necessary to perform certain maintenance activities
134+
on your database, for example to compact the database file, removing unused
135+
documents and blobs no longer referenced by any documents.
136+
137+
Couchbase Lite's API provides the `api|Database.performMaintenance` method. The
138+
available maintenance operations, including compact are as shown in the enum
139+
`api|enum:MaintenanceType` to accomplish this.
140+
141+
This is a resource intensive operation and is not performed automatically. It
142+
should be run on-demand using the API. If in doubt, consult Couchbase support.
143+
144+
## Command Line Tool
145+
146+
cblite is a command-line tool for inspecting and querying Couchbase Lite
147+
databases.
148+
149+
You can download and build it from the couchbaselabs
150+
[GitHub repository](https://github.com/couchbaselabs/couchbase-mobile-tools/blob/master/README.cblite.md).
151+
Note that the cblite tool is not supported by the
152+
[Couchbase Support Policy](https://www.couchbase.com/support-policy).
153+
154+
## Couchbase Lite for VSCode
155+
156+
Couchbase Lite for VSCode is a Visual Studio Code extension that provides a user
157+
interface for inspecting and querying Couchbase Lite databases. You can find
158+
more information about this extension from it's
159+
[GitHub repository](https://github.com/couchbaselabs/vscode-cblite).
160+
161+
## Troubleshooting
162+
163+
You should use console logs as your first source of diagnostic information. If
164+
the information in the default logging level is insufficient you can focus it on
165+
database errors and generate more verbose messages (see `api|enum:LogLevel`)
166+
— see: [Example 4](#).
167+
168+
<CodeExample id={4} title="Increase level of Database Log Messages">
169+
170+
<EmbedderTabs>
171+
<EmbedderTab embedder="Dart">
172+
173+
```dart
174+
Database.log.console.level = LogLevel.verbose;
175+
```
176+
177+
:::note
178+
179+
On standalone Dart, logging is configured to directly log to stdandard output
180+
and does not go through Dart.
181+
182+
:::
183+
184+
</EmbedderTab>
185+
<EmbedderTab embedder="Flutter">
186+
187+
```dart
188+
Database.log.custom!.level = LogLevel.verbose;
189+
```
190+
191+
:::note
192+
193+
On Flutter, logging is configured to use a custom logger that calls Dart's
194+
`api|dart:core|fn:print` function. Console logging is disabled. This is because
195+
not all Flutter platforms (e.g. Android) support console logging.
196+
197+
:::
198+
199+
</EmbedderTab>
200+
</EmbedderTabs>
201+
202+
</CodeExample>

0 commit comments

Comments
 (0)