Skip to main content

Add or Update a Per-Database Connection String

Add a connection string - from Studio​

The screenshots below show how to add a RavenDB connection string from Studio.
Use the same flow for other connection string types; only the type-specific fields change.
For links to the type-specific articles, see Connection string per type.

Add connection string 1

  1. Open your database and go to Settings > Connection Strings.
  2. Click Add new.

Add connection string 2

Select a connection string type from the dropdown.

Add connection string 3

For a RavenDB connection string, fill in:

  1. Type - The selected connection string type.
  2. Name - A unique name for the connection string.
  3. Database - The destination database name.
  4. Discovery URLs - One or more URLs used to discover the destination RavenDB server topology.
  5. Test connection - Verifies that RavenDB can reach the destination using the details you entered.
    On success, you can save the connection string.
    On failure, RavenDB displays the error returned by the destination so you can correct the details
    (for example, a wrong URL, database name, or invalid credentials) and test again.
  6. Save connection string - Saves the connection string.

Adding a per-database connection string while creating a task​

  • You don't have to open the Connection Strings view first. When you create a task that uses a connection string, the task setup dialog lets you select an existing connection string or create a new one inline.

  • Connection strings created this way are saved in the database and also appear in
    Settings > Connection Strings.

Update a connection string - from Studio​

The Settings > Connection Strings view lists the connection strings available to the current database,
grouped by connection string type.

Per-database connection strings can be edited from this view.
Inherited server-wide connection strings are also shown here, but they are read-only from the database scope.
To edit an inherited connection string see Update a server-wide connection string - from Studio

Add connection string 4

Click the edit button next to a per-database connection string to open its settings.

The connection string Name is read-only when editing.
If you want the connection string to have a different name, create a new per-database connection string,
then update every task or AI agent in the database that references the old connection string.

After making changes, test the connection and save it.

Editing a connection string that is in use​

  • A connection string cannot be deleted while tasks or AI agents reference it, but it can be edited.

  • The saved changes replace the existing definition and apply to every task or AI agent in the database that uses this connection string. This is useful for changes such as rotating credentials or updating a destination URL without recreating each task.

  • For AI connection strings, some options cannot be edited while the connection string is used by an Embeddings Generation or GenAI task. This includes settings that affect the model or generated embeddings, such as the connector, model, or embedding dimensions. Connection details such as API keys or endpoints can still be edited.

Add a connection string - from the Client API​

Use PutConnectionStringOperation to add a connection string to a database.

The operation is sent through the database maintenance store: store.Maintenance.Send(...).
By default, it is applied to the default database.
To apply it to a different database, see switch operations to a different database.

For every connection string type, create the matching connection string class
(e.g.: RavenConnectionString, SqlConnectionString, etc.) and pass it to PutConnectionStringOperation.

For type-specific fields and links to full examples, see Connection string per type.
The following example adds a RavenDB connection string.

Example​

// Define a connection string to a RavenDB database destination
// ============================================================
var ravenDBConStr = new RavenConnectionString
{
    Name = "ravendb-connection-string-name",
    Database = "target-database-name",
    TopologyDiscoveryUrls = new[] { "https://rvn2:8080" }
};

// Deploy (send) the connection string to the server via the PutConnectionStringOperation
// ======================================================================================
var putConnectionStringOp = new PutConnectionStringOperation<RavenConnectionString>(ravenDBConStr);
PutConnectionStringResult connectionStringResult = store.Maintenance.Send(putConnectionStringOp);

Update a connection string - from the Client API​

Use the same PutConnectionStringOperation to update an existing per-database connection string.

To update a connection string, send a connection string with the same Name.
The submitted definition replaces the existing per-database connection string with that name.
The change applies to every task or AI agent in the database that references this connection string.

To use a different name, create a new connection string and update the tasks or AI agents that reference the old one.

Connection string per type​

Each connection string type uses the same add/update flow, but has its own destination-specific fields.
The specific fields and complete examples are documented in the relevant task or feature article:

Syntax​

The PutConnectionStringOperation operation​

public PutConnectionStringOperation(T connectionString)
    where T : ConnectionString

ParameterTypeDescription
connectionStringRavenConnectionStringObject that defines the RavenDB connection string.
connectionStringSqlConnectionStringObject that defines the SQL connection string.
connectionStringSnowflakeConnectionStringObject that defines the Snowflake connection string.
connectionStringOlapConnectionStringObject that defines the OLAP connection string.
connectionStringElasticSearchConnectionStringObject that defines the Elasticsearch connection string.
connectionStringQueueConnectionStringObject that defines the connection string for the queue broker tasks - Queue ETL (Kafka, RabbitMQ, Azure Queue Storage, Amazon SQS) and Queue Sink (Kafka, RabbitMQ, Azure Service Bus).
connectionStringAiConnectionStringObject that defines the AI connection string.

The ConnectionString base class​

All the connection string class types inherit from this abstract class:

public abstract class ConnectionString
{
    // A name for the connection string
    public string Name { get; set; }
    
    // The connection string type
    public abstract ConnectionStringType Type { get; } 
}

public enum ConnectionStringType
{
    None,
    Raven,
    Sql,
    Olap,
    ElasticSearch,
    Queue,
    Snowflake,
    Ai
}

Connection string type-specific fields and complete examples are documented in the task or feature articles listed under
Connection string per type.

In this article