CouchbaseLite: Why Are Periods (.) Not Allowed in Database Names?

We’ve noticed warning messages in CouchbaseLite Java across all versions. The warning is as follows:

2023-10-27 09:58:22 10-27 04:28:22.629     44 W/CouchbaseLite/DATABASE: "com.tgsys.platform.compliance" is not considered a valid database name. A valid name should start with a letter or digit and can include letters, digits, dashes, or underscores, up to a limit of 100 characters.

Could someone shed light on why database names cannot contain periods (“.”)?

This seems like kind of an odd question: there are lots of characters that are not legal in database names. Why the concern, specifically, about dots?

The reason, though, is that they are syntactically significant in our naming grammar: periods separate the names of scopes from the names of collections. Disallowing them in database names prevents ambiguity. Among other things, it allows us to specify a fully qualified collection name as <db>“.” <scope>“.” <collection>, in SqlLite queries.

1 Like

Generally, we’ve been using periods in folder names and other naming conventions on our platform. When we apply dots in database names, our queries are structured as


While CBLite currently issues a warning about using periods, it doesn’t strictly prohibit them, and it still functions. My main concern is understanding the long-term implications of this. Will it cause issues down the line, especially considering the syntactical significance of periods in your naming grammar, as you’ve mentioned?

I strongly recommend that you adopt another strategy for naming your databases: this absolutely will cause problems, down the line.

We will certainly try to maintain backwards compatibility for as long as we can. You should have plenty of time to adapt. That said, there are no promises.

After upgrading couchbase-lite-ios, we have started seeing this warning as well. Our database is name “user.db”. I would guess this is a pretty common practice!

The problem is that I don’t see any API for renaming a database (that is already in production). Any plans for that?

You want:

    @NonNull File path,
    @NonNull String name,
    @NonNull DatabaseConfiguration config)
  • path is the full path to the existing database (returned by Database.getPath)
  • name is the new name for the database
  • config is the standard database configuration (returned by Database.getConfig)
1 Like