Using CBLManager replaceDatabaseNamed

I’m new to CBL and Couchbase in general and I’m working on upgrading the CBL SDK from 1.1 to 1.1.1 in an iOS app. There is a change in the replaceDatabaseNamed API which now requires a withAttachements parameter. The API looks straight forward, I pass it a db name and a path an I want to replace or install such database.

Even though the documentation says that I can pass nil as an argument the compiler throws a warning if I do that. So my guess that is why with v1.1.1 the API returns NO, for the same database in the same phone.

The error I get is SQLLite code: 14 “unable to open database file”

            BOOL ok = [self.manager replaceDatabaseNamed:DB_ENVIRONMENT

What should I pass to this parameter?
attachmentsPath Path of the associated attachments directory, or nil if there are no attachments.

I might be missing some core CBL concept here but I couldn’t find any migration documentation from the previous API which didn’t have this paramater.

We haven’t changed or removed any method in 1.1.1. It might be confusing you that there are two similarly-named methods.

-replaceDatabaseNamed:withDatabaseFile:withAttachments:error: is for installing a CBL-1.0-format database (a file with a “.cblite” extension and possibly a matching directory with the same name followed by " attachments".)

-replaceDatabaseNamed:withDatabaseDir:error: is for installing a CBL-1.1-format database (a directory with a “.cblite2” extension). This doesn’t have a parameter for the attachments path because the attachments are already inside that directory.

I might be importing the wrong library then because the header file doesn’t have this API. I’m using CocoaPods,

pod ‘couchbase-lite-ios’, ‘~> 1.1.1’

However, the header file does match the documentation which doesn’t include replaceDatabaseNamed:withDatabaseDir:error:

Oops, I have once again forgotten that the file-format change doesn’t occur until 1.2. (I’m working on the master branch so that’s the header I was looking at.) Sorry to add to the confusion!

Anyway … the Wayback machine tells me that the withAttachments: parameter was present in version 1.1, and even back in 1.0. So the API has not changed.

What did change, it seems, is that the attachmentsPath parameter is now marked as not allowing nil. This is a mistake — nil is valid. I’ll get that fixed for 1.2. You can work around it by either passing nil and disabling that compiler warning at the point of the call (there are pragmas for that), or by passing a valid but nonexistent path.

1 Like

Thanks for looking into this @jens!

I’m not only new to CBL but also new to the app I’m trying to update. Your answer does clarify the history of the API that has the withAttachments parameter.

But what about the history of replaceDatabaseNamed:withDatabaseDir:error: ? It looks like it is not part of 1.1.1 but it was at some point available in previous versions and now it will be available again in 1.2? Looking at the commit history in my team’s repo I see that we use replaceDatabaseNamed:withDatabaseFile:withAttachments at some point and then switch back to replaceDatabaseNamed:withDatabaseDir. I’ve been told and it looks like we got a beta SDK at some point directly from your support team (I’m requesting more info internally about that).

In any case, these two API are not interchangeable, are they? the db extension in the device in the current implementation is cblite2 and not cblite. It looks like for us to migrate again to replaceDatabaseNamed:withDatabaseFile:withAttachments we would need to change the extension to cblite. However, it looks like we do want to stay in a CBL-1.1-format.

It looks like we might need to stay in the previous version 1.1.0 and wait for 1.2 to be released where replaceDatabaseNamed:withDatabaseDir has been added back. Correct?

The withDatabaseDir: version has never been in a release. You’ll need to check what exact version of Couchbase Lite you’re building with … I suspect you’ve still got an unreleased version. Which is OK, but it affects the answer to this question.