_create-database-java.mdx

import Admonition from '@theme/Admonition'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock';

• 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
    • Example I - Create database
    • Example II - Ensure database does not exist before creating
  • Syntax

Sizing the database group

The default replication factor is 1, which puts the database on a single node. For high availability, set the replication factor to at least 3 so the database survives losing a node and stays synchronized through internal replication.

If the database also uses cluster-wide transactions, prefer an odd replication factor (3, 5, or 7).
A cluster-wide transaction commits only after a majority of the database group's voting members have accepted it, and an odd group size means that majority is always a clean (n/2 + 1) - never a tie.

For the full reasoning, see Cluster: Best Practices.

Create new database

Example I - Create database

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

{`DatabaseRecord databaseRecord = new DatabaseRecord(); databaseRecord.setDatabaseName("MyNewDatabase"); store.maintenance().server().send(new CreateDatabaseOperation(databaseRecord)); `}

Example II - Ensure database does not exist before creating

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

{`public void ensureDatabaseExists(IDocumentStore store, String database, boolean createDatabaseIfNotExists) \{ database = ObjectUtils.firstNonNull(database, store.getDatabase());

if (StringUtils.isBlank(database)) \{
    throw new IllegalArgumentException("Value cannot be null or whitespace");
\}

try \{
    store.maintenance().forDatabase(database).send(new GetStatisticsOperation());
\} catch (DatabaseDoesNotExistException e) \{
    if (!createDatabaseIfNotExists) \{
        throw e;
    \}

    try \{
        DatabaseRecord databaseRecord = new DatabaseRecord();
        databaseRecord.setDatabaseName(database);
        store.maintenance().server().send(new CreateDatabaseOperation(databaseRecord));
    \} catch (ConcurrencyException ce) \{
        // The database was already created before calling CreateDatabaseOperation
    \}
\}

} `}

Syntax

{`public CreateDatabaseOperation(DatabaseRecord databaseRecord)

public CreateDatabaseOperation(DatabaseRecord databaseRecord, int replicationFactor) `}

Parameter	Type	Description
databaseRecord	DatabaseRecord	Instance of DatabaseRecord containing database configuration.
replicationFactor	int	Number of nodes the database should be replicated to. If not specified, the value is taken from topology.replicationFactor, or defaults to 1 if that is not set. If topology is provided, the replicationFactor is ignored.

DatabaseRecord

DatabaseRecord is a collection of database configurations.

constructor	Description
DatabaseRecord(string databaseName)	Initialize a new database record

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.

Property	Type	Description
analyzers	Map<String, AnalyzerDefinition>	A dictionary defining the Custom Analyzers available to the database.
autoIndexes	Map<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	boolean (default: false)	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	Map<String, ElasticSearchConnectionString>	Define ElasticSearch Connection Strings, keyed by name.
encrypted	boolean (default: false)	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	Map<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	Map<String, OlapConnectionString>	Define OLAP Connection Strings, keyed by name.
queueConnectionStrings	Map<String, QueueConnectionString>	Define Queue Connection Strings, keyed by name.
ravenConnectionStrings	Map<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	Map<String, RollingIndex>	Dictionary mapping index names to their deployment configurations.
settings	Map<String, String>	Configuration settings for the database.
sharding	ShardingConfiguration	The sharding configuration.
sorters	Map<String, SorterDefinition>	A dictionary defining the Custom Sorters available to the database.
sqlConnectionStrings	Map<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	Set<String>	Set database IDs that will be excluded when creating new change vectors.