Database Connections are reusable configuration objects in Cribl Stream that enable Database Collectors to access and retrieve data from a MySQL, Oracle, Postgres, or SQL Server database. You can reference the same Database Connection in multiple Database Collectors, which helps streamline Database Collector setup.

Overview of Database Collector Configuration ​

The workflow for setting up a new Database Collector has these phases:

1. Create a Connection String or Configuration Object: Before you start, you need to gather access and authentication information for your database. Using that information, build a connection string or configuration object that you will use to establish a valid connection to the database.

2. Configure a Database Connection: Database Collectors rely on Cribl Stream Database Connections, which are reusable objects that you can re-use with multiple Database Collectors to authenticate to the same database.

3. Test the Connection: Ensure the Database Connection is configured correctly and that data is flowing.

4. Configure a Database Collector: Configure a Database Collector to input data from an upstream database. You can then route this data to a Pipeline for further data processing.

Create a Connection String or Configuration Object ​

To get started with a Database Collector, you need to gather important details and authentication information about your target database. Using that information, you can build a connection string. A connection string is a structured text string that contains all the required parameters for Cribl Stream to establish a valid connection to the database.

In addition to connection strings, SQL Server databases can also accept a configuration object, which is a structured data format (such as JSON) that organizes the required database access into defined fields.

Connection strings should be properly escaped, especially when your password might contain a special character. For example, characters like @, :, /, ?, #, or % may be interpreted as delimiters inside a URI. If they aren’t escaped, the connection string can break or fail to authenticate. Use percent-encoding (URL encoding) for these characters. For example, a password of MyP@ssw0rd! would be encoded into MyP%40ssw0rd%21.

For information about creating connection strings, jump to the section for your database type:

• MySQL, Oracle, and Postgres
• SQL Server

MySQL, Oracle, and Postgres ​

Select the appropriate tab for information about building a connection string for these database types:

mysqls://username:password@host:port/databasename?option=value

mysqls://audit_user:L0gM3In#@mysql-staging.net:3307/staging_logs
mysqls://cribl_reader:S3cur3R3@d3r!@prod_mysql_db.company.net:3306/production_logs?sslmode=verify-identity
mysql://dev_read:devpass123@192.168.1.5:3306/dev_data?sslmode=verify-full&sslrootcert=/path/to/ca.crt&sslcert=/path/to/client.crt&sslkey=/path/to/client.key.../mydb?sslmode=verify-full&sslrootcert=/path/to/ca.crt&sslcert=/path/to/client.crt&sslkey=/path/to/client.key

<host_name>/<service_name>

oracle-prod-vip.corp.net/FINANCE_PDB1 # default port
192.168.10.50:1523/HR_DATABASE_SID # non-standard port

(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=your_host_name)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=your_service_name)))

(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=oracle-prod-vip.corp.net)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=FINANCE_PDB1)))
(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=192.168.10.50)(PORT=1523))(CONNECT_DATA=(SERVICE_NAME=HR_DATABASE_SID)))

postgresql://username:password@hostname:port/databasename?option=value

postgresql://cribl_reader:P0stGresR3ad@pg-prod-us-west.company.net:5432/telemetry_data?sslmode=verify-full
postgresql://cribl_reader:P0stGresR3ad@10.0.10.25:5433/telemetry_data?sslmode=require

SQL Server ​

The necessary requirements for SQL Server depend on how you will authenticate Cribl Stream with the server. Select the appropriate tab for your authentication type:

{
  "server":  "<your-server-name.database.windows.net>",
  "database": "<your-database-name>",
  "port": 1433,
  "authentication": {
    "type": "azure-active-directory-service-principal-secret",
    "options": {
      "tenantId": "<your-tenant-id>",
      "clientId": "<your-application-id>",
      "clientSecret": "<your-client-secret-value>"
    }
  },
  "options": {
    "encrypt": true,
    "trustServerCertificate": false
  }
}

{
  "server": "prod-sql-metrics.database.windows.net",
  "database": "Application_Telemetry",
  "port": 1433,
  "authentication": {
    "type": "azure-active-directory-service-principal-secret",
    "options": {
      "tenantId": "8e20f01a-1e4b-4c5d-b0a9-1f2a3c4d5e6f",
      "clientId": "1c3b5d7e-9f0a-2b3c-4d5e-6f7a8b9c0d1e",
      "clientSecret": "V3ryS3cr3tT0k3n@2025!"
    }
  },
  "options": {
    "encrypt": true,
    "trustServerCertificate": false
  }
}

{
  "authentication": {
    "type": "ntlm",
    "options": {
      "userName": "username",
      "password": "password",
      "domain": "domain"
    }
  },
  "options": {
    "connectTimeout": 15000,
    "trustServerCertificate": true
  },
  "port": 1433,
  "server": "hostname",
  "database": "databasename"
}

{
  "authentication": {
    "type": "ntlm",
    "options": {
      "userName": "cribl_reader",
      "password": "W1ndowsP@ssw0rd!",
      "domain": "CORP"
    }
  },
  "options": {
    "connectTimeout": 15000,
    "trustServerCertificate": true
  },
  "port": 1433,
  "server": "sql-prod-02.corp.local",
  "database": "Finance_Audit"
}

Configure a Database Connection ​

After creating a connection string or configuration object for your database type, the next step is to configure a Database Connection for the target database. Database Connections are reusable Knowledge objects that you can use and re-use to connect the same database to multiple Database Collectors as needed.

When you change a Database Connection, it impacts all Database Collectors that use that Database Connection. Make changes with caution.

To configure or update a Database Connection:

1. Select Worker Groups from the sidebar, and choose a Worker Group. Then, on the Worker Groups submenu, select Processing, then Knowledge, then Database Connections. Select Add Database Connection.

   You can also create a new Database Connection directly from a Database Collector. While configuring a Database Collector, select Create next to the Connection field to open the New Database Connection modal.

2. In the New Database Connection modal, configure the following settings:

   • ID: Enter a unique ID for this connection. A descriptive ID will help all users recognize the connection by purpose.

   • Database type: Select your database type: MySQL, SQL Server, Postgres, or Oracle.

   • Authentication method: The available options available depend on your database type:

     Authentication Method	Description
     Connection String	Enter the connection string you created in the previous Create a Connection String or Configuration Object step.
     Connection String Secret	Rather than storing the connection string in the Database Connection object, you can add it to secret store and then select the stored connection string. Select Create to add it to the secret store.
     Config (SQL Server only)	Enter the JSON connection configuration object you created in the previous Create a Connection String or Configuration Object step. The object uses the Tedious driver and the node-mssql client.
     Stored Credentials (Oracle only)	Use the secret store for both your database login and connection details. Select a username and password secret for the Credentials secret field and a text secret for the Connection string secret field to ensure secure, centralized management.

     Connection strings should be properly escaped, especially when your password might contain a special character. For example, characters like @, :, /, ?, #, or % may be interpreted as delimiters inside a URI. If they aren’t escaped, the connection string can break or fail to authenticate. Use percent-encoding (URL encoding) for these characters. For example, a password of MyP@ssw0rd! would be encoded into MyP%40ssw0rd%21.

3. Optionally, configure the Additional Settings:

   • Connection timeout (ms): How long, in milliseconds, Cribl Stream should wait before assuming that a connection has failed. This defaults to 10000 (10 sec.) for MySQL databases, and to 15000 (15 sec.) for SQL Server databases. For both, the minimum allowed value is 1000 (1 sec.), and the maximum is 60000 (1 minute).

   • Request timeout (ms): This setting appears only where Database type is set to SQL Server. Defines how long Cribl Stream should wait before assuming that a request has failed. If a query requires a longer timeout than the default 15000 (15 seconds), be sure that you know why. Long-running queries can affect other parts of the system. The minimum is 1000 (1 second).

4. Select Save to save your changes.

Validate that your Database Connection is working as expected and that data is flowing by testing your connection, as explained in the next section.

Test the Connection ​

You can test the connection to the database inside the Database Connection by selecting the Test Connection button inside the Database Connection object. This initiates an API call that pings the database to check whether the connection is valid.

Be aware that when you select Test Connection on the Leader Node, the system only tests the database connection for the Leader Node itself. However, the Leader Node is usually not the node that needs to connect to the database while collecting data. Usually that operation is performed by a Worker Node.

To test the connection from a specific Worker Node:

1. Ensure the Database Connection is committed and deployed.

2. Teleport to the Worker Node and open the Database Connection on that Worker Node.

3. Select Test Connection.

   • Success: If the test is successful, a success message displays in the lower right corner of the screen.
   • Failure: If the test fails, an error message display at the top of the screen. Connection test failures are logged in the logs for the Worker Group.

If the connection fails, check that the IP for the Worker Node is on the allow list for that database.

Next Steps ​

After configuring a Database Connection and validating that data is flowing, you can then configure a Database Collectors to access and retrieve data from a MySQL, Oracle, Postgres, or SQL Server database.