ravendb.ravendb.connection_string module – Manage RavenDB connection strings

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.connection_string.

New in ravendb.ravendb 1.1.0

Synopsis

• Create or delete RavenDB connection strings for supported providers.

• Supported types - RAVEN, SQL, OLAP, ELASTIC_SEARCH, QUEUE, SNOWFLAKE, AI.

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

• Check mode is supported to simulate creation/deletion without applying changes.

• Validates server support and enforces minimum server versions where required.

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.
cs_type string	Connection string type. Choices: "RAVEN" ← (default) "SQL" "OLAP" "ELASTIC_SEARCH" "QUEUE" "SNOWFLAKE" "AI"
database_name string / required	Name of the database. Must be a valid name containing only letters, numbers, dashes, and underscores.
name string / required	Connection string name.
properties dictionary	Type-specific properties dictionary (see examples). Secrets may be inline or loaded from using Ansible lookups.
state string	Desired state of the connection string. If present, the item is created when absent (no in-place updates; existing items are left unchanged). If absent, the item is removed when present. Choices: "present" ← (default) "absent"
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 Raven connection string
  ravendb.ravendb.connection_string:
    url: "http://{{ ansible_host }}:8080"
    database_name: "MyDB"
    name: "raven-out"
    cs_type: RAVEN
    properties:
      database: "OtherDB"
      urls:
        - "http://node-a:8080"
        - "http://node-b:8080"
    state: present

- name: Create SQL connection string
  ravendb.ravendb.connection_string:
    url: "https://{{ ansible_host }}:443"
    database_name: "etl_db"
    certificate_path: "admin.client.combined.pem"
    ca_cert_path: "ca_certificate.pem"
    name: "sql-target"
    cs_type: SQL
    properties:
      connection_string: "{{ lookup('ansible.builtin.file', '/etc/ansible/secrets/sql_dsn.txt') | trim }}"
      factory_name: "Npgsql.NpgsqlFactory"
    state: present

- name: Create OLAP (GCS) connection string
  ravendb.ravendb.connection_string:
    url: "https://{{ ansible_host }}:443"
    database_name: "analytics"
    certificate_path: "admin.client.combined.pem"
    ca_cert_path: "ca_certificate.pem"
    name: "olap-gcs"
    cs_type: OLAP
    properties:
      google_cloud_settings:
        disabled: false
        bucket_name: "my-olap-bucket"
        remote_folder_name: "exports"
        google_credentials_json: "{{ lookup('ansible.builtin.file', '/etc/ansible/secrets//gcs.json') | trim }}"
        overriding_external_script:
          exec: "/usr/local/bin/olap.sh"
          arguments: ["--fast"]
          timeout_in_ms: 60000
    state: present

- name: Create ElasticSearch connection string
  ravendb.ravendb.connection_string:
    url: "http://{{ ansible_host }}:8080"
    database_name: "searchdb"
    name: "es-out"
    cs_type: ELASTIC_SEARCH
    properties:
      nodes: ["https://es1:9200","https://es2:9200"]
      authentication:
        basic:
          username: "elastic"
          password: "{{ lookup('ansible.builtin.file', '/etc/ansible/secrets/es_password.txt') | trim }}"
    state: present

# Queue (Azure Queue Storage) - requires RavenDB >= 6.2
- name: Create Queue (Azure Queue Storage) connection string
  ravendb.ravendb.connection_string:
    url: "http://{{ ansible_host }}:8080"
    database_name: "queue_db"
    name: "az-queue"
    cs_type: QUEUE
    properties:
      broker_type: "AZUREQUEUESTORAGE"
      azure_queue_storage_settings:
        connection_string: "{{ lookup('ansible.builtin.file', '/etc/ansible/secrets/az_queue_conn.txt') | trim }}"
    state: present

# Queue (Amazon SQS) - requires RavenDB >= 7.1
- name: Create Queue (Amazon SQS) connection string
  ravendb.ravendb.connection_string:
    url: "http://{{ ansible_host }}:8080"
    database_name: "queue_db"
    name: "sqs-out"
    cs_type: QUEUE
    properties:
      broker_type: "AMAZONSQS"
      amazon_sqs_settings:
        basic:
          access_key: "{{ lookup('ansible.builtin.file', '/etc/ansible/secrets/aws_access_key.txt') | trim }}"
          secret_key: "{{ lookup('ansible.builtin.file', '/etc/ansible/secrets/aws_secret_key.txt') | trim }}"
          region_name: "eu-central-1"
    state: present

# Snowflake - requires RavenDB >= 7.1
- name: Create Snowflake connection string
  ravendb.ravendb.connection_string:
    url: "http://{{ ansible_host }}:8080"
    database_name: "dw"
    name: "snowflake-dwh"
    cs_type: SNOWFLAKE
    properties:
      connection_string: "{{ lookup('ansible.builtin.file', '/etc/ansible/secrets/snowflake_dsn.txt') | trim }}"
    state: present

# AI (OpenAI) - requires RavenDB >= 7.1
- name: Create AI connection string (OpenAI)
  ravendb.ravendb.connection_string:
    url: "http://{{ ansible_host }}:8080"
    database_name: "ai_db"
    name: "openai-default"
    cs_type: AI
    properties:
      identifier: "default"
      model_type: "CHAT"
      openai_settings:
        api_key: "{{ lookup('ansible.builtin.file', '/etc/ansible/secrets/openai.key') | trim }}"
        base_url: "https://api.openai.com/v1"
    state: present

- name: Delete connection string
  ravendb.ravendb.connection_string:
    url: "http://{{ ansible_host }}:8080"
    database_name: "MyDB"
    name: "raven-out"
    cs_type: RAVEN
    state: absent

# Check mode (no changes)
- name: Would create Raven connection string (check mode)
  ravendb.ravendb.connection_string:
    url: "http://{{ ansible_host }}:8080"
    database_name: "MyDB"
    name: "raven-out"
    cs_type: RAVEN
    properties:
      database: "OtherDB"
      urls: ["http://node-a:8080"]
    state: present
  check_mode: yes

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.1.0	Human-readable message describing the result or error. Returned: always Sample: "Created connection string 'openai-default' (type AI)."

Authors

• Omer Ratsaby (@thegoldenplatypus)

Collection links

• Issue Tracker
• Homepage
• Repository (Sources)