How to use C replicator api



I’m trying to understand how replication works using couchbase-lite-core. So far my understanding tells me that couchbase-lite-core servers both as a local store and a way to communicate with a cloud server. I just don’t understand if I really need to have a sync gateway in the middle. I find a lot of information but nothing very pratical. I know there are probably a lot of concepts and information that I’m still missing but at this point my questions are:

  • how do I sync a local couchbase-lite-core database with a server?
    a) do I use the serverUrl as the remoteUrl
    b) do I need to first setup a sync-gateway which will serve as proxy between the local database and the server database?
    c) is there any example on how to do that solely with C api?

I have already tried establish a connection. I have ran docker containers with both docker/couchbase-sandbox & docker/couchbase-sync-gateway and tried to create a replicator on the C api with their urls. Both failed with the message:

21:44:33.315045| WARNING: Caught unexpected C++ logic_error("No default C4SocketFactory registered; call c4socket_registerFactory())")
Unable to create Replicator for: No default C4SocketFactory registered; call c4socket_registerFactory())

Feeling kind of lost… Any tips?

Thanks in advance.

Best regards,



The defacto example of using LiteCore is Couchbase Lite itself.

a) This is the same as the Couchbase Lite setup: Use the URL and database path with the “ws” or “wss” scheme (i.e. ws:///)
b) Yes, you must use sync gateway
c) Not directly no, Couchbase Lite is basically “the example”


You do. That’s the main purpose of Sync Gateway: to act as a replication endpoint.

Both failed with the message:

As the error message says, you need to call c4socket_registerFactory. C4SocketFactory represents a networking implementation. We use different networking libraries on different platforms, so there’s an abstraction layer.

For cross-platform use and testing we have a factory in LiteCore; call RegisterC4CivetWebSocketFactory() (declared in CivetWebSocket.hh) to register it. This function isn’t exported by the DLL so you’ll need to be statically linking with LiteCore to use it.

Note: CivetWebSocketFactory doesn’t support TLS/SSL.


Jens, thanks for the reply and for the extra info. I have been able to successfully register C4CivetWebSocketFactory. I have a sync-gateway running and it seems to be connecting successfully:

23:09:40.333388| [DB]: {Shared#1}==> litecore::DataFile::Shared 0x7facc0d465c0 @0x7facc0d465c0
23:09:40.333435| [DB]: {Shared#1} instantiated on /private/tmp/database/db.sqlite3
23:09:40.333449| [DB]: {DB#2}==> litecore::SQLiteDataFile /tmp/database/db.sqlite3 @0x7facc0d49970
23:09:40.333460| [DB]: {DB#2} Opening database
23:09:40.334893| [DB]: {DB#3}==> litecore::SQLiteDataFile /tmp/database/db.sqlite3 @0x7facc0d51450
23:09:40.334913| [DB]: {DB#3} Opening database
23:09:40.335657| [Sync]: {Repl#4}==> litecore::repl::Replicator /tmp/database/ ->ws:// @0x7facc0d55e18
23:09:40.335673| [Sync]: {Repl#4} Push=continuous, Pull=continuous, Options={{}}
QString IC4Database::getAllDocuments(const QString &, int)
document body "{\"internal_created\":\"2019-02-07T23:08:09\"}" 0x7facc0d59568 "0000001" "1-5f94707dcae67bf0518d58e31b59cee2d2ba2a59"
document body "{\"internal_created\":\"2019-02-07T23:08:17\"}" 0x7facc0d59888 "0000002" "1-61f17ac4245cb90f8c9d9267d3208a76c9fe23aa"
document body "{\"internal_created\":\"2019-02-07T23:08:30\"}" 0x7facc0d57778 "0000003" "1-4047e95605811f0567e8149d34e50f656650295d"
Row count: 3
23:09:40.338296| [Sync]: {Repl#4} No local checkpoint 'cp-AfinoD8r6CJRdiOeODQ3vBXIjcE='

Thank you! Another milestone achieved. I still need to learn about working with the sync gateway, and then with the server it self. There is a lot of information to absorve and I can’t seem to find a complete and comprehensive, straight to the point, quick start guide covering the full process.

Thank you once again! Best regards


Congrats! BTW, I just finished writing a high-level guide to the Fleece API which should be useful when you’re working with document properties.


Thanks Jens. I will definitely take a look at it. Best!