You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
// END: Conditional Block -- applies to Android and JVM Java
28
31
29
-
// == Default Database Location
30
-
// By default, _Couchbase Lite on {param-title}_ creates databases in the following path location shown in <<default-path>>.
32
+
[#open-db]
33
+
== Create or Open Database
31
34
32
-
// [#default-path]
33
-
// .Default database path
34
-
// ====
35
-
// [source, {console}]
36
-
// ----
37
-
// <root dir>/.couchbase/<db name>.cblite // <.>
38
-
// ----
35
+
You can create a new database and-or open and existing database, using the {url-api-class-database} class.
36
+
Just pass in a database name and optionally a {url-api-class-databasecfg}-- see <<ex-dbopen>>.
39
37
40
-
// ifdef::is-java[<.> Where the <root dir> is the directory in which JVM was started.]
41
-
// ifdef::is-android[<.> Where the <root dir> can be identified using `context.getFilesDir()`]
38
+
Things to watch for include:
42
39
43
-
// ====
40
+
* Opening/Creating a database is an asynchronous process
41
+
* If the named database does not exist in the specified, or default, location then a new one is created
42
+
* The database is created in a default location unless you specify a directory for it -- see: {url-api-class-databasecfg} and {url-api-method-databasecfg-setdir}
43
+
+
44
+
--
45
+
TIP: Best Practice is to always specify the path to the database explicitly.
44
46
45
-
[#open-db]
46
-
== New Database
47
-
As the top-level entity in the API, new databases can be created using the `Database` class by passing in a name, configuration, or both.
48
-
The following example opens, or creates, a database using the `Database(String name, DatabaseConfiguration config)` method.
47
+
Typically, the default location for {param-title} is
Just as before, the database will be created in a default location.
58
-
Alternatively, the `Database(string name, DatabaseConfiguration config)` initializer can be used to provide specific options in the {url-api-references}/com/couchbase/lite/DatabaseConfiguration.html[`DatabaseConfiguration`] object.
59
-
60
68
<.> Here we are specifying the database directory path.
69
+
61
70
====
62
71
63
-
* Remember that:
64
-
** Opening (or creating) a database is asynchronous.
65
-
** Closing a database is a *synchronous* operation, it is effective immediately
72
+
== Close Database
73
+
You are advised to incorporate the closing of all open databases into your application workflow.
66
74
67
-
[NOTE]
68
-
--
69
-
You cannot close a database that is not fully open.
75
+
Closing a database is a simple, just use {url-api-method-database-close} -- see: <<ex-dbclose>>. +
76
+
However, there are a number of things to be aware of:
70
77
78
+
* Closing a database is a *synchronous* operation, it is effective immediately
79
+
* You cannot close a database that is not open. +
80
+
Remember that opening (or creating) a database is asynchronous.
71
81
So issuing a close immediately after initiating an open/create, may result in an error if that process has not completed.
It is the application's responsibility to manage the key and store it in a platform specific secure store such as Apple's https://developer.apple.com/documentation/security/keychain_services[Keychain] or Android's https://developer.android.com/training/articles/keystore[Keystore].
109
+
== Database Encryption
95
110
96
-
An encrypted database can only be opened with the same language SDK that was used to encrypt it in the first place (Swift, C#, Java, Java (Android) or Objective-C).
97
-
For example, if a database is encrypted with the Swift SDK and then exported, it will only be readable with the Swift SDK.
If you're migrating an application from Couchbase Lite 1.x to 2.x, note that the <<database-upgrade,automatic database upgrade>> functionality is *not supported* for encrypted databases.
102
-
Thus, to upgrade an encrypted 1.x database, you should do the following:
115
+
[#lbl-find-db-loc]
116
+
== Finding a Database File
103
117
104
-
// set the correct language name for 1.4 pages
105
-
ifeval::["{param-name}"=="{lang-name-android}"]
106
-
:param-language: {lang-name-java}
118
+
:tags: {empty}
119
+
ifdef::is-csharp[]
120
+
:tags: "tags=list-only"
107
121
endif::[]
108
-
. Disable encryption using the Couchbase Lite 1.x framework (see https://docs-archive.couchbase.com/couchbase-lite/1.4/{param-name}.html#database-encryption[1.x encryption guide])
109
-
. Open the database file with encryption enabled using the Couchbase Lite 2.x framework.
110
-
111
-
Since it is not possible to package Couchbase Lite 1.x and Couchbase Lite 2.x in the same application this upgrade path would require two successive upgrades.
112
-
If you are using Sync Gateway to synchronize the database content, it may be preferable to run a pull replication from a new 2.x database with encryption enabled and delete the 1.x local database.
`cblite` is a command-line tool for inspecting and querying Couchbase Lite 2.x databases.
127
-
128
-
You can download and build it from the couchbaselabs https://github.com/couchbaselabs/couchbase-mobile-tools/blob/master/README.cblite.md[GitHub repository].
129
-
130
-
NOTE: The `cblite` tool is not covered under the https://www.couchbase.com/support-policy[Couchbase Support Policy].
130
+
include::{root-partials}cli-tool.adoc[]
131
131
132
132
// end::cli-tool[]
133
133
134
-
== Logging
135
-
136
-
If you are using a Couchbase Lite release prior to 2.5 see <<pre-2x5-logging, Deprecated functionality>>
134
+
== Troubleshooting
135
+
You should use Couchbase's console logs as your first source of diagnostic information.
136
+
If the information in the default logging level is insufficient you can focus it on database errors and generate more verbose messages -- see: <<ex-logdb>>.
Copy file name to clipboardExpand all lines: modules/ROOT/pages/_partials/commons/common-sgw-replication-init.adoc
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -5,7 +5,7 @@
5
5
//
6
6
7
7
Use the `{url-api-class-replicator}` class's {url-api-constructor-replicator-init-config} constructor, to initialize the replicator with the configuration you have defined.
8
-
You can, optionally, add a change listener (see <<monitor-sync>>) before starting the replicator running using {url-api-method-replicator-start}.
8
+
You can, optionally, add a change listener (see <<lbl-repl-mon>>) before starting the replicator running using {url-api-method-replicator-start}.
You can monitor a replication’s status by using a combination of <<lbl-repl-chng>> and the `replication.status.activity` property -- see; {url-api-enum-replicator-activity}.
14
+
This enables you to know, for example, when the replication is actively transferring data and when it has stopped.
15
+
16
+
You can also choose to monitor document changes -- see: <<lbl-repl-evnts>>.
17
+
10
18
[#lbl-repl-chng]
11
19
== Change Listeners
20
+
Use this to monitor changes and to inform on sync progress; this is an optional step.
12
21
13
-
TIP: You should register the listener before starting your replication, to avoid having to do a restart to activate it.
22
+
.Best Practice
23
+
TIP: You should register the listener before starting your replication, to avoid having to do a restart to activate it ... and don't forget to save the token so you can remove the listener later
14
24
15
25
Use the {url-api-class-replicator} class to add a change listener as a callback to the Replicator ({url-api-method-replicator-add-change-listener}) -- see: <<ex-repl-mon>>.
16
26
You will then be asynchronously notified of state changes.
17
27
18
-
Use this to monitor changes and to inform on sync progress; this is an optional step.
28
+
Remove your change listener before stopping the replicator -- use the {url-api-method-replicator-rmv-change-listener} method to do this.
29
+
19
30
20
31
[#lbl-repl-status]
21
32
== Replicator Status
@@ -33,7 +44,6 @@ The returned _ReplicationStatus_ structure comprises:
33
44
** total -- the total number of changes to be processed
34
45
* {url-api-enum-replicator-error}-- the current error, if any
35
46
36
-
37
47
// Example 8
38
48
[[ex-repl-mon]]
39
49
.Monitor replication
@@ -162,7 +172,6 @@ This can be very useful in tracking the progress of a push sync, enabling the ap
Copy file name to clipboardExpand all lines: modules/ROOT/pages/_partials/commons/common-sgw-replication-stop.adoc
+17-4Lines changed: 17 additions & 4 deletions
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,20 @@
7
7
// {root-commons}sgw-replication.adoc
8
8
// ####
9
9
10
-
TIP: If you added an optional change listener (see <<lbl-repl-chng>> for how) you should also remove it using the {url-api-method-replicator-rmv-change-listener} method.
10
+
Stopping a replication is straightforward.
11
+
It is done using {url-api-method-replicator-stop}.
12
+
This initiates an asynchronous operation and so is not necessarily immediate.
13
+
Your app should account for this potential delay before attempting any subsequent operations, for example closing the database.
14
+
15
+
You can find further information on database operations in {xref-cbl-gp-database}.
16
+
17
+
.Best Practice
18
+
[TIP]
19
+
--
20
+
. When you start a change listener, save the returned token, you will need it when you remove the listener
21
+
. Remove any active change listener prior to stopping your replication
22
+
. Ensure the replication has completely stopped by checking for a replication status = STOPPED, before closing any associated database
0 commit comments