ravendb.ravendb.database module – Manage RavenDB databases

Note

This module is part of the ravendb.ravendb collection (version 1.0.4).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install ravendb.ravendb. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: ravendb.ravendb.database.

New in ravendb.ravendb 1.0.0

Synopsis

• Create or delete a RavenDB database, and optionally apply per-database settings.

• Supports secured connections using client certificates and optional CA verification.

• Check mode is supported to simulate creation, deletion, or settings changes without applying them.

• Supports creating encrypted databases by assigning a secret key (generated or user-provided) and distributing it to all cluster nodes.

• Supports fixed placement by specifying exact cluster node tags to host the database (topology members).

• Supports applying per-database settings (database_settings) and triggering a safe database reload so changes take effect.

Requirements

The below requirements are needed on the host that executes this module.

• python >= 3.9

• ravendb python client

• ASP.NET Core Runtime

• requests

• Role ravendb.ravendb.ravendb_python_client_prerequisites must be installed before using this module.

Parameters

Parameter	Comments
ca_cert_path string	Path to a trusted CA certificate file to verify the RavenDB server’s certificate.
certificate_path string	Path to a client certificate (PEM format) for secured communication.
database_name string / required	Name of the database. Must be a valid name containing only letters, numbers, dashes, and underscores.
database_settings dictionary	Dictionary of database-level settings to apply. Keys and values are normalized to strings and compared against current customized settings. When differences exist, the module updates settings and toggles the database state to reload them safely. Default: {}
encrypted boolean	Create the database as encrypted. When true, the module ensures a secret key is assigned (generated or read from file) and distributed to all cluster nodes before creation. Requires certificate_path to access admin endpoints. Choices: false ← (default) true
encryption_key string	Path to a file that contains the raw encryption key (plain text). Mutually exclusive with generate_encryption_key. Used only when encrypted=true.
encryption_key_output_path string	When generate_encryption_key=true, write the generated key to this local file with safe permissions. Ignored if generate_encryption_key=false.
generate_encryption_key boolean	If true, asks the server to generate a new encryption key via the admin API. Mutually exclusive with encryption_key. Used only when encrypted=true. Choices: false ← (default) true
replication_factor integer	Number of server nodes to replicate the database to. Must be a positive integer. Only used when creating a database. Required on creation; ignored for existing databases.
state string	Desired state of the database. If present, the database will be created if it does not exist, and settings will be reconciled. If absent, the database will be deleted if it exists. If omitted (null), the module reconciles settings on an existing database but will not create or delete it. If the database does not exist and state is omitted, the task fails with guidance to use state=present. Choices: "present" "absent"
topology_members list / elements=string	Optional list of cluster node tags to host this database (fixed placement). When provided, its length must equal replication_factor. Honored only on creation. If the database already exists, providing topology_members will fail. Default: []
url string / required	URL of the RavenDB server. Must include the scheme (http or https), hostname, and port.

Attributes

Attribute	Support	Description
check_mode	Support: full	Can run in check_mode and return changed status prediction without modifying target. If not supported, the action will be skipped.

Notes

Note

• The role ravendb.ravendb.ravendb_python_client_prerequisites must be applied before using this module.

• Requires the ASP.NET Core Runtime to be installed on the target system.

See Also

See also

RavenDB documentation

Official RavenDB documentation

Examples

- name: Create a RavenDB database
  ravendb.ravendb.database:
    url: "http://{{ ansible_host }}:8080"
    database_name: "my_database"
    replication_factor: 3
    state: present

- name: Create RF=2 database on specific nodes A and C (fixed placement)
  ravendb.ravendb.database:
    url: "http://{{ ansible_host }}:8080"
    database_name: "placed_db"
    replication_factor: 2
    topology_members: ["A", "C"]
    state: present

- name: Create an encrypted database with a generated key and save it locally (requires client cert)
  become: true
  ravendb.ravendb.database:
    url: "https://{{ ansible_host }}:443"
    database_name: "secure_db"
    replication_factor: 1
    certificate_path: "admin.client.combined.pem"
    ca_cert_path: "ca_certificate.pem"
    encrypted: true
    generate_encryption_key: true
    encryption_key_output_path: "/home/$USER/secure_db.key"
    state: present

- name: Create an encrypted database using a pre-provisioned key file
  ravendb.ravendb.database:
    url: "https://{{ ansible_host }}:443"
    database_name: "secure_db2"
    replication_factor: 1
    certificate_path: "admin.client.combined.pem"
    ca_cert_path: "ca_certificate.pem"
    encrypted: true
    encryption_key: "/home/$USER/secure_db2.key"
    state: present

- name: Update database settings (idempotent) – will not create database if absent (state omitted)
  ravendb.ravendb.database:
    url: "http://{{ ansible_host }}:8080"
    database_name: "my_database"
    database_settings:
      Indexing.MapBatchSize: "64"

- name: Apply settings in check mode (no changes will be made)
  ravendb.ravendb.database:
    url: "http://{{ ansible_host }}:8080"
    database_name: "my_database"
    database_settings:
      Indexing.MapBatchSize: "64"
  check_mode: yes

- name: Delete a RavenDB database
  ravendb.ravendb.database:
    url: "http://{{ ansible_host }}:8080"
    database_name: "my_database"
    state: absent

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
changed boolean	Indicates if any change was made (or would have been made in check mode). Returned: always Sample: true
msg string added in ravendb.ravendb 1.0.0	Human-readable message describing the result or error. Returned: always Sample: "Database 'my_database' created successfully."

Authors

• Omer Ratsaby (@thegoldenplatypus)

Collection links

• Issue Tracker
• Homepage
• Repository (Sources)