Database connection string
The database connection string is a character string that is used to define and configure the connection between an application and a Starcounter database. It consists of a number of option assignments, separated by semicolons (see sample).
The options are further explored in the sections below.
Databaseoption is required in the connection string, and consists of an absolute or relative path to the directory where the Starcounter database files are located, or should be located if they do not yet exist.
Relative paths define the path to the database directory in relation to the current directory, which is in turn given by the context in which the connecting application is started. It could, for example, be the Visual Studio project folder if the app is started from the Visual Studio debugger.
OpenModeoption defines how to interpret the database path on connection. It can have the following string values:
StartModeoption defines how to start and/or connect to the database process once the database files have been located and/or created.
StopModeoption defines whether to stop the database process once the connection to it is closed, for example when an application is terminated.
Neveroption is not effective when the application process is forcibly killed, for example from a task manager or by
Ctrl + C. In this case operating system will kill the corresponding database process as well.
ContextCountoption defines the number of database contexts to use in the database connection.
"Database context", as used here, should not be confused with
IDatabaseContextas used in the .NET API for transactions. In the context of database connections, database contexts refer to the entry points to the database from the applications' point of view. When an application thread has a database context assigned, it can read and write to the database.
The same database context may be used between multiple application threads, for example if the application uses async/await. Starcounter manages this automatically.
Each Starcounter database has a maximum of 31 database contexts available for allocation between multiple application processes. By default, each Starcounter application tries to allocate twice as many contexts as CPU cores available, with a minimum of 2 and a maximum of 24.
The ideal configuration is to have a database context per CPU core. Having more database contexts than CPU cores might increase performance in certain concurrent database access workloads. Having fewer database contexts than CPU cores might decrease performance of concurrent database access during high concurrent load.
ContextCountoption to manually adjust the number of database contexts to occupy in this connection.
This string defines the
Databaseoption using a relative path to a database
Sample, located in the
.databasedirectory of the current directory. If such a directory does not exist at the time of connection, or if it does not contain a Starcounter database, the
CreateIfNotExistsensures that it is created. If the database process is not running already, the
StartIfNotRunningensures that it should be started. And when the app disconnects from the database, it will stop the database process if it was started by this app, since the
StopModeoption is defined as
IfWeStarted. Lastly, we set the number of occupied database contexts in this connection to 10.