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).
Connection string options
Name
Type
Required
Default value
Description
Database
string
Yes
None
A path string defining the database to use.
OpenMode
enum
No
CreateIfNotExists
Specifies the database creation strategy.
StartMode
enum
No
StartIfNotRunning
Specifies the database startup strategy.
StopMode
enum
No
IfWeStarted
Specifies the database shut down strategy.
ContextCount
integer
No
2 – 24
Specifies the number of database contexts allocated for this connection.
The options are further explored in the sections below.
Database
The Database option 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.
OpenMode
The OpenMode option defines how to interpret the database path on connection. It can have the following string values:
Value
Description
Open
Opens the database directory from the path specified in the Database option, if it exist. If the directory does not exist, or if there is no Starcounter database located there, an exception is thrown.
CreateIfNotExists
Opens the database directory from the path specified in the Database option, if it exist. If the directory does not exist, or if there is no Starcounter database located there, it will create the necessary directories and database files, and then open the database directory.
StartMode
The StartMode option defines how to start and/or connect to the database process once the database files have been located and/or created.
Value
Description
RequireStarted
Expects the database process to already be running and will connect to it if it is, or throw an exception if it is not.
StartIfNotRunning
Connects to the database process if it is already running, or starts and connects to it if it is not.
StartExclusive
In this case we expect no database process to be already running. If a database process is already running, an exception is thrown. Otherwise, a new process is created and connected to.
StopMode
The StopMode option defines whether to stop the database process once the connection to it is closed, for example when an application is terminated.
Value
Description
IfWeStarted
Stops the database process if and only if it was started by the current application.
Never
Leaves the database process running, regardless of how it was started.
Note: the Never option 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.
ContextCount
The ContextCount option defines the number of database contexts to use in the database connection.
"Database context", as used here, should not be confused with IDatabaseContext as 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.
Use ContextCount option to manually adjust the number of database contexts to occupy in this connection.
Example
Database=./.database/Sample;OpenMode=CreateIfNotExists;StartMode=StartIfNotRunning;StopMode=IfWeStarted;ContextCount=10
This string defines the Database option using a relative path to a database Sample, located in the .database directory 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 OpenMode option of CreateIfNotExists ensures that it is created. If the database process is not running already, the StartMode option ofStartIfNotRunningensures 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 StopMode option is defined asIfWeStarted. Lastly, we set the number of occupied database contexts in this connection to 10.

Transactions

Database creation options

Last modified 2yr ago

Copy link

Outline

Connection string options

Connection string options

`Database`

`OpenMode`

`StartMode`

`StopMode`

`ContextCount`

Example