Create Database Operation

Use CreateDatabaseOperation to create a new database from the Client API, as described below.
To create a new database from the Studio, see Create database.
This operation requires a client certificate with a security clearance of Operator or ClusterAdmin.
To learn which operations are allowed at each level, see Security clearance and permissions.
In this article:
- Create new database
- Syntax

Create new database

Example I - Create non-sharded database

The following simple example creates a non-sharded database with the default replication factor of 1.

Create_db_sync
Create_db_async
Create_using_builder_sync
Create_using_builder_async

// Define the create database operation, pass an instance of DatabaseRecord
var createDatabaseOp = new CreateDatabaseOperation(new DatabaseRecord("DatabaseName"));

// Execute the operation by passing it to Maintenance.Server.Send
store.Maintenance.Server.Send(createDatabaseOp);

// Define the create database operation, pass an instance of DatabaseRecord
var createDatabaseOp = new CreateDatabaseOperation(new DatabaseRecord("DatabaseName"));

// Execute the operation by passing it to Maintenance.Server.SendAsync
await store.Maintenance.Server.SendAsync(createDatabaseOp);

// Define the create database operation
var createDatabaseOp = new CreateDatabaseOperation(builder => builder
   // Call 'Regular' to create a non-sharded database
  .Regular("DatabaseName"));

// Execute the operation by passing it to Maintenance.Server.Send
store.Maintenance.Server.Send(createDatabaseOp);

// Define the create database operation
var createDatabaseOp = new CreateDatabaseOperation(builder => builder
   // Call 'Regular' to create a non-sharded database
  .Regular("DatabaseName"));

// Execute the operation by passing it to Maintenance.Server.SendAsync
await store.Maintenance.Server.SendAsync(createDatabaseOp);

Example II - Create sharded database

The following example creates a sharded database with 3 shards, each with a replication factor of 2.
In addition, it enables:
- revisions
- document expiration
- and applies some settings to the database.

Create_db_sync
Create_db_async
Create_using_builder_sync
Create_using_builder_async

// Define the database record:
var databaseRecord = new DatabaseRecord("ShardedDatabaseName") {
  
  // Configure sharding:
  Sharding = new ShardingConfiguration()
  {
      // Ensure nodes "A", "B", and "C" are available in the cluster
      // before executing the database creation.
      Shards = new Dictionary<int, DatabaseTopology>()
      {
          {0, new DatabaseTopology { Members = new List<string> { "A", "B" }}},
          {1, new DatabaseTopology { Members = new List<string> { "A", "C" }}},
          {2, new DatabaseTopology { Members = new List<string> { "B", "C" }}}
      }
  },
  
  // Enable revisions on all collections:
  Revisions = new RevisionsConfiguration()
  {
      Default = new RevisionsCollectionConfiguration()
      {
          Disabled = false, MinimumRevisionsToKeep = 5
      }
  },
  
  // Enable the document expiration feature:
  Expiration = new ExpirationConfiguration()
  {
      Disabled = false
  },
  
  // Apply some database configuration setting:
  Settings = new Dictionary<string, string>()
  {
      {"Databases.QueryTimeoutInSec", "500"}
  }
};

// Define the create database operation
var createDatabaseOp = new CreateDatabaseOperation(databaseRecord);

// Execute the operation by passing it to Maintenance.Server.Send
store.Maintenance.Server.Send(createDatabaseOp);

// Define the database record:
var databaseRecord = new DatabaseRecord("ShardedDatabaseName") {
  
  // Configure sharding:
  Sharding = new ShardingConfiguration()
  {
      // Ensure nodes "A", "B", and "C" are available in the cluster
      // before executing the database creation.
      Shards = new Dictionary<int, DatabaseTopology>()
      {
          {0, new DatabaseTopology { Members = new List<string> { "A", "B" }}},
          {1, new DatabaseTopology { Members = new List<string> { "A", "C" }}},
          {2, new DatabaseTopology { Members = new List<string> { "B", "C" }}}
      }
  },
  
  // Enable revisions on all collections:
  Revisions = new RevisionsConfiguration()
  {
      Default = new RevisionsCollectionConfiguration()
      {
          Disabled = false, MinimumRevisionsToKeep = 5
      }
  },
  
  // Enable the document expiration feature:
  Expiration = new ExpirationConfiguration()
  {
      Disabled = false
  },
  
  // Apply some database configuration setting:
  Settings = new Dictionary<string, string>()
  {
      {"Databases.QueryTimeoutInSec", "500"}
  }
};

// Define the create database operation
var createDatabaseOp = new CreateDatabaseOperation(databaseRecord);

// Execute the operation by passing it to Maintenance.Server.SendAsync
await store.Maintenance.Server.SendAsync(createDatabaseOp);

// Define the create database operation
var createDatabaseOp = new CreateDatabaseOperation(builder => builder
      
  // Call 'Sharded' to create a sharded database
  .Sharded("ShardedDatabaseName", topology => topology
      // Ensure nodes "A", "B", and "C" are available in the cluster
      // before executing the database creation.
      .AddShard(0, new DatabaseTopology {Members = new List<string> {"A", "B"}})
      .AddShard(1, new DatabaseTopology {Members = new List<string> {"A", "C"}})
      .AddShard(2, new DatabaseTopology {Members = new List<string> {"B", "C"}}))
  // Enable revisions on all collections:
  .ConfigureRevisions(new RevisionsConfiguration()
  {
      Default = new RevisionsCollectionConfiguration()
      {
          Disabled = false, MinimumRevisionsToKeep = 5
      }
  })
  // Enable the document expiration feature:
  .ConfigureExpiration(new ExpirationConfiguration()
  {
      Disabled = false
  })
  // Apply some database configuration setting:
  .WithSettings(new Dictionary<string, string>()
  {
      { "Databases.QueryTimeoutInSec", "500" }
  })
);

// Execute the operation by passing it to Maintenance.Server.Send
store.Maintenance.Server.Send(createDatabaseOp);

// Define the create database operation
var createDatabaseOp = new CreateDatabaseOperation(builder => builder
      
  // Call 'Sharded' to create a sharded database
  .Sharded("ShardedDatabaseName", topology => topology
      // Ensure nodes "A", "B", and "C" are available in the cluster
      // before executing the database creation.
      .AddShard(0, new DatabaseTopology {Members = new List<string> {"A", "B"}})
      .AddShard(1, new DatabaseTopology {Members = new List<string> {"A", "C"}})
      .AddShard(2, new DatabaseTopology {Members = new List<string> {"B", "C"}}))
  // Enable revisions on all collections:
  .ConfigureRevisions(new RevisionsConfiguration()
  {
      Default = new RevisionsCollectionConfiguration()
      {
          Disabled = false, MinimumRevisionsToKeep = 5
      }
  })
  // Enable the document expiration feature:
  .ConfigureExpiration(new ExpirationConfiguration()
  {
      Disabled = false
  })
  // Apply some database configuration setting:
  .WithSettings(new Dictionary<string, string>()
  {
      { "Databases.QueryTimeoutInSec", "500" }
  })
);

// Execute the operation by passing it to Maintenance.Server.SendAsync
await store.Maintenance.Server.SendAsync(createDatabaseOp);

Example III - Ensure database does not exist before creating

To ensure the database does not already exist before creating it, follow this example:

Sync
Async

var databaseName = "MyDatabaseName";

try
{
  // Try to fetch database statistics to check if the database exists
  store.Maintenance.ForDatabase(databaseName)
      .Send(new GetStatisticsOperation());
}
catch (DatabaseDoesNotExistException)
{
  try
  {
      // The database does not exist, try to create:
      var createDatabaseOp = new CreateDatabaseOperation(
          new DatabaseRecord(databaseName));
      
      store.Maintenance.Server.Send(createDatabaseOp);
  }
  catch (ConcurrencyException)
  {
      // The database was created by another client before this call completed
  }
}

var databaseName = "MyDatabaseName";

try
{
  // Try to fetch database statistics to check if the database exists:
  await store.Maintenance.ForDatabase(databaseName)
      .SendAsync(new GetStatisticsOperation());
}
catch (DatabaseDoesNotExistException)
{
  try
  {
      // The database does not exist, try to create:
      var createDatabaseOp = new CreateDatabaseOperation(
          new DatabaseRecord(databaseName));
      
      await store.Maintenance.Server.SendAsync(createDatabaseOp);
  }
  catch (ConcurrencyException)
  {
      // The database was created by another client before this call completed
  }
}

Syntax

// CreateDatabaseOperation overloads:
// ==================================
public CreateDatabaseOperation(DatabaseRecord databaseRecord) {}
public CreateDatabaseOperation(DatabaseRecord databaseRecord, int replicationFactor) {}
public CreateDatabaseOperation(Action<IDatabaseRecordBuilderInitializer> builder) {}

Parameter	Description
databaseRecord	Instance of `DatabaseRecord` containing database configuration. See The Database Record below.
replicationFactor	Number of nodes the database should be replicated to. If not specified, the value is taken from `databaseRecord.Topology.ReplicationFactor`, or defaults to `1` if that is not set. If `Topology` is provided, the `replicationFactor` is ignored.
builder	Callback used to initialize and fluently configure a new DatabaseRecord. Receives an `IDatabaseRecordBuilderInitializer` on which you invoke builder methods to construct the record. See The Database Record Builder below.

The Database Record:

The DatabaseRecord is a collection of database configurations:

DatabaseRecord constructors	Description
DatabaseRecord()	Initialize a new database record.
DatabaseRecord(`string` databaseName)	Initialize a new database record with the specified database name.

Note:

Only the properties listed in the table below can be configured in the DatabaseRecord object passed to CreateDatabaseOperation.
For example, although ongoing task definitions are public on the DatabaseRecord class, setting them during database creation will result in an exception. To define ongoing tasks (e.g., backups, ETL, replication), use the appropriate dedicated operation after the database has been created.

DatabaseRecord properties	Type	Description
Analyzers	`Dictionary<string, AnalyzerDefinition>`	A dictionary defining the Custom Analyzers available to the database.
AutoIndexes	`Dictionary<string, AutoIndexDefinition>`	Auto-index definitions for the database.
Client	`ClientConfiguration`	Client behavior configuration.
ConflictSolverConfig	`ConflictSolver`	Define the strategy used to resolve Replication conflicts.
DataArchival	`DataArchivalConfiguration`	Data Archival configuration for the database.
DatabaseName	`string`	The database name.
Disabled	`bool`	Set the database initial state. `true` - disable the database. `false` - (default) the database will be enabled. This can be modified later via ToggleDatabasesStateOperation.
DocumentsCompression	`DocumentsCompressionConfiguration`	Configuration settings for Compressing documents.
ElasticSearchConnectionStrings	`Dictionary<string, ElasticSearchConnectionString>`	Define ElasticSearch Connection Strings, keyed by name.
Encrypted	`bool`	`true` - create an Encrypted database. Note: Use `PutSecretKeyCommand` to send your secret key to the server BEFORE creating the database. `false` - (default) the database will not be encrypted.
Expiration	`ExpirationConfiguration`	Expiration configuration for the database.
Indexes	`Dictionary<string, IndexDefinition>`	Define Indexes that will be created with the database - no separate deployment needed.
Integrations	`IntegrationConfigurations`	Configuration for Integrations, e.g. `PostgreSqlConfiguration`.
LockMode	`DatabaseLockMode`	Set the database lock mode. (default: `Unlock`) This can be modified later via `SetDatabasesLockOperation`.
OlapConnectionStrings	`Dictionary<string, OlapConnectionString>`	Define OLAP Connection Strings, keyed by name.
QueueConnectionStrings	`Dictionary<string, QueueConnectionString>`	Define Queue Connection Strings, keyed by name.
RavenConnectionStrings	`Dictionary<string, RavenConnectionString>`	Define Raven Connection Strings, keyed by name.
Refresh	`RefreshConfiguration`	Refresh configuration for the database.
Revisions	`RevisionsConfiguration`	Revisions configuration for the database.
RevisionsForConflicts	`RevisionsCollectionConfiguration`	Set the revisions configuration for conflicting documents.
RollingIndexes	`Dictionary<string, RollingIndex>`	Dictionary mapping index names to their deployment configurations.
Settings	`Dictionary<string, string>`	Configuration settings for the database.
Sharding	`ShardingConfiguration`	The sharding configuration.
Sorters	`Dictionary<string, SorterDefinition>`	A dictionary defining the Custom Sorters available to the database.
SqlConnectionStrings	`Dictionary<string, SqlConnectionString>`	Define SQL Connection Strings, keyed by name.
Studio	`StudioConfiguration`	Studio Configuration.
TimeSeries	`TimeSeriesConfiguration`	Time series configuration for the database.
Topology	`DatabaseTopology`	Optional topology configuration. Defaults to `null`, in which case the server will determine which nodes to place the database on, based on the specified `ReplicationFactor`.
UnusedDatabaseIds	`HashSet<string>`	Set database IDs that will be excluded when creating new change vectors.

The Database Record Builder:

public interface IDatabaseRecordBuilderInitializer
{
  public IDatabaseRecordBuilder Regular(string databaseName);
  public IShardedDatabaseRecordBuilder Sharded(string databaseName, Action<IShardedTopologyConfigurationBuilder> builder);
  public DatabaseRecord ToDatabaseRecord();
}

public interface IShardedDatabaseRecordBuilder : IDatabaseRecordBuilderBase
{
}

// Available configurations:
// =========================

public interface IDatabaseRecordBuilder : IDatabaseRecordBuilderBase
{
  public IDatabaseRecordBuilderBase WithTopology(DatabaseTopology topology);
  public IDatabaseRecordBuilderBase WithTopology(Action<ITopologyConfigurationBuilder> builder);
  public IDatabaseRecordBuilderBase WithReplicationFactor(int replicationFactor);
}

public interface IDatabaseRecordBuilderBase
{
  DatabaseRecord ToDatabaseRecord();

  IDatabaseRecordBuilderBase ConfigureClient(ClientConfiguration configuration);
  IDatabaseRecordBuilderBase ConfigureDocumentsCompression(DocumentsCompressionConfiguration configuration);
  IDatabaseRecordBuilderBase ConfigureExpiration(ExpirationConfiguration configuration);
  IDatabaseRecordBuilderBase ConfigureRefresh(RefreshConfiguration configuration);
  IDatabaseRecordBuilderBase ConfigureRevisions(RevisionsConfiguration configuration);
  IDatabaseRecordBuilderBase ConfigureStudio(StudioConfiguration configuration);
  IDatabaseRecordBuilderBase ConfigureTimeSeries(TimeSeriesConfiguration configuration);

  IDatabaseRecordBuilderBase Disabled();
  IDatabaseRecordBuilderBase Encrypted();

  IDatabaseRecordBuilderBase WithAnalyzers(params AnalyzerDefinition[] analyzerDefinitions);
  IDatabaseRecordBuilderBase WithConnectionStrings(Action<IConnectionStringConfigurationBuilder> builder);
  IDatabaseRecordBuilderBase WithIndexes(params IndexDefinition[] indexDefinitions);
  IDatabaseRecordBuilderBase WithIntegrations(Action<IIntegrationConfigurationBuilder> builder);
  IDatabaseRecordBuilderBase WithLockMode(DatabaseLockMode lockMode);
  IDatabaseRecordBuilderBase WithSettings(Dictionary<string, string> settings);
  IDatabaseRecordBuilderBase WithSettings(Action<Dictionary<string, string>> builder);
  IDatabaseRecordBuilderBase WithSorters(params SorterDefinition[] sorterDefinitions);
}

Create new database​

Example I - Create non-sharded database​

Example II - Create sharded database​

Example III - Ensure database does not exist before creating​

Syntax​

The Database Record:​

The Database Record Builder:​

Create new database

Example I - Create non-sharded database

Example II - Create sharded database

Example III - Ensure database does not exist before creating

Syntax

The Database Record:

The Database Record Builder: