API Reference › core-backend› SQLiteDb › CloudSqlite › CloudSqlite.CloudContainer

CloudSqlite.CloudContainer Interface

A CloudSqlite container that may be connected to a CloudCache. A CloudContainer maps a container in a cloud blob-storage account to a local cache, so that the contents of a database in the container may be accessed as if it were a local file.

Notes:

  • all methods and accessors of this interface (other than initializeContainer) require that the connect method be successfully called first. Otherwise they will throw an exception or return meaningless values.
  • before a SQLiteDb in a container may be opened for write access, the container's write lock must be held (see CloudSqlite.CloudContainer.acquireWriteLock.)
  • a single CloudContainer may hold more than one SQLiteDb, but often they are 1:1.
  • the write lock is per-Container, not per-SQLiteDb (which is the reason they are often 1:1)
  • the accessToken (a SAS key) member provides time limited, restricted, access to the container. It must be refreshed before it expires.
  • when a CloudContainer is created, it may either be readonly or writeable. If a container is never meant to be used for writes, it is slightly more efficient to indicate that by passing writeable: false

Methods

Name Description
abandonChanges(): void Abandon any local changes in this container.  
acquireWriteLock(user: string): void Attempt to acquire the write lock for this CloudContainer.  
checkForChanges(): void Poll cloud storage for changes from other processes.  
clearWriteLock(): void Destroy any currently valid write lock from this or any other process.  
connect(cache: CloudSqlite.CloudCache): void Connect this CloudContainer to a CloudCache for accessing and/or modifying its contents.  
copyDatabase(dbName: string, toAlias: string): Promise<void> Create a copy of an existing database within this CloudContainer with a new name.  
deleteDatabase(dbName: string): Promise<void> Remove a database from this CloudContainer.  
disconnect(args?: { detach?: boolean }): void Disconnect this CloudContainer from its CloudCache.  
initializeContainer(args: { blockSize: number, checksumBlockNames?: boolean }): void initialize a cloud blob-store container to be used as a new CloudContainer.  
queryDatabase(dbName: string): undefined | CloudSqlite.CachedDbProps Get the status of a specific database in this CloudContainer.  
queryDatabaseHash(dbName: string): string Get the SHA1 hash of the content of a database.  
queryDatabases(globArg?: string): string[] Get the list of database names in this CloudContainer.  
releaseWriteLock(): void Release the write lock if it is currently held.  
uploadChanges(): Promise<void> Upload any changed blocks from the databases in this CloudContainer.  

Properties

Name Type Description
cache Readonly CloudSqlite.CloudCache | undefined    
onConnect (container: CloudSqlite.CloudContainer, cache: CloudSqlite.CloudCache) => void | undefined    
onConnected (container: CloudSqlite.CloudContainer) => void | undefined    
onDisconnect (container: CloudSqlite.CloudContainer, detach: boolean) => void | undefined    
onDisconnected (container: CloudSqlite.CloudContainer, detach: boolean) => void | undefined    

Defined in

Last Updated: 24 June, 2025