Configure a Database Connection
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:
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.
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.
Test the Connection: Ensure the Database Connection is configured correctly and that data is flowing.
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 ofMyP@ssw0rd!would be encoded intoMyP%40ssw0rd%21.
For information about creating connection strings, jump to the section for your database type:
MySQL, Oracle, and Postgres
Select the appropriate tab for information about building a connection string for these database types:
A MySQL connection string requires this information:
- Protocol: Verify that your database is using a secure SSL or TLS connection and that you have the required certificates. Otherwise, your connection will need to use a non-secure protocol, which is not recommended. Append an
sto your connection string header to enforce the secure SSL/TLS connection protocol. For example:mysqls://. - Username: The database user account that has the necessary permissions to read tables and run queries. As a best practice, ensure that this account follows the principle of least privilege and has the minimum permissions required by Cribl Stream.
- Password: The password associated with the specified database user account.
- Host: The hostname or IP address where the MySQL database server is running.
- Port: MySQL uses a default port of
3306, but you should confirm this with your database administrator. It is possible that your deployment runs on a non-standard port. - Database name: The specific name of the database (schema) on the server that contains the tables or data to collect.
- Optional parameters: Any additional parameters that are needed for extra settings or security, such as the SSL mode. For example:
?sslmode=requireor?sslmode=verify-full&sslrootcert=/path/to/ca.crt.
Use that information to build a connection string. MySQL connection strings use this syntax:
mysqls://username:password@host:port/databasename?option=valueExamples:
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.keyOracle provides two methods for connecting to databases: Easy Connect or Oracle Net Connection. Check with your database administrator to determine which connection method is required for your database.
Although it is not part of the actual connection string, you will also need a valid username and password to connect to your Oracle database. This account needs the necessary permissions to read tables and run queries.
An Easy Connect connection string requires this information:
- Host: The hostname or IP address where the Oracle database server is running.
- Service name: The service name of the specific database instance that contains the data to collect.
Use that information to build a connection string. Easy Connect uses this syntax:
<host_name>/<service_name>Examples of Easy Connect connection strings:
oracle-prod-vip.corp.net/FINANCE_PDB1 # default port
192.168.10.50:1523/HR_DATABASE_SID # non-standard portFor mTLS, add the tcps:// prefix and specify the TCPS port (the officially registered port is 2484, but confirm with your database administrator): tcps://oracle-prod-vip.corp.net:2484/FINANCE_PDB1
An Oracle Net Connection requires this information:
- Protocol: The communication protocol used for the connection. For standard connections over a network, this is typically TCP.
- Host: The hostname or IP address where the Oracle database server is running.
- Port: Oracle uses a default port of
1521, but you should confirm this with your database administrator. It is possible that your deployment runs on a non-standard port. - Service name: The service name of the specific database instance that contains the data to collect.
Use that information to build a connection string. Oracle Net Connections use this syntax:
(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=your_host_name)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=your_service_name)))Examples of Oracle Net Connection connection strings:
(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)))For mTLS, replace PROTOCOL=TCP with PROTOCOL=TCPS and use the TCPS port: (DESCRIPTION=(ADDRESS=(PROTOCOL=TCPS)(HOST=oracle-prod-vip.corp.net)(PORT=2484))(CONNECT_DATA=(SERVICE_NAME=FINANCE_PDB1)))
See Configure Oracle mTLS for the additional TLS settings required in the Database Connection form.
A Postgres connection string requires this information:
- Username: The database user account that has the necessary permissions to read tables and run queries. As a best practice, ensure that this account follows the principle of least privilege and has the minimum permissions required by Cribl Stream.
- Password: The password associated with the specified database user account.
- Host: The hostname or IP address where the Postgres database server is running.
- Port: Postgres uses a default port of
5432, but you should confirm this with your database administrator. It is possible that your deployment runs on a non-standard port. - Database name: The specific name of the database (schema) on the server that contains the tables or data to collect.
- Optional parameters: Any additional parameters that are needed for extra settings or security, such as the SSL mode. For example:
?sslmode=requireor?sslmode=verify-full&sslrootcert=/path/to/ca.crt.
Use that information to build a connection string. Postgres connection strings use this syntax:
postgresql://username:password@hostname:port/databasename?option=valueExamples:
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=requireSQL 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:
If your SQL Server authenticates with a service principal, you must first register an application with Microsoft Entra ID (formerly known as Azure Active Directory) as a prerequisite. To prevent connection errors, you will need to use its ID and credentials in your configuration. To register an application with Microsoft Entra ID:
Register an application using the instructions from Microsoft: Register an application in Microsoft Entra ID. You can use the default settings as needed.
Generate credentials for the application: Add and manage application credentials in Microsoft Entra ID.
CREATE USER [<app_display_name>] FROM EXTERNAL PROVIDER; ALTER ROLE db_owner ADD MEMBER [<app_display_name>];After registering the application, get the following information from your Azure Portal:
- Server Name: The Fully Qualified Domain Name (FQDN) or IP address of the machine hosting the SQL Server instance.
- Database Name: The name of the specific logical database catalog on the SQL Server instance that contains the tables or data you want to collect.
- Port: The TCP/IP port number on which the SQL Server is listening for connections. The default port is
1433, but it is possible that your deployment runs on a non-standard port. - Tenant ID: The Directory (tenant) ID for your Azure instance.
- Client ID: The Application (client) ID for your app registration.
- Client Secret: The secret value you generated for your service principal.
Use that information to build a configuration object. SQL Server configuration objects that authenticate with a service principal use this syntax:
{
"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
}
}Example:
{
"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
}
}A Database Connection for a SQL Server that authenticates with Windows Challenge/Response, also known as Microsoft New Technology LAN Manager (NTLM), requires this information:
- Username: A Windows Domain User Account that has the necessary permissions to read tables and run queries. As a best practice, ensure that this account follows the principle of least privilege and has the minimum permissions required by Cribl Stream.
- Password: The password associated with the specified Windows Domain User Account.
- Domain: The NetBIOS name (or sometimes the full FQDN) of the Windows Active Directory domain that hosts the specified Windows Domain User Account. This name is necessary for the NTLM protocol to locate the Domain Controller for authentication.
- Server: The hostname or IP address of the SQL Server instance.
- Port: SQL Server uses a default port of
1433, but you should confirm this with your database administrator. It is possible that your deployment has configured your SQL Server to run on a non-standard port. - Database name: The specific name of the database (schema) on the server that contains the tables or data to collect.
Use that information to build a configuration object. SQL Server configuration objects that authenticate with NTLM use this syntax:
{
"authentication": {
"type": "ntlm",
"options": {
"userName": "username",
"password": "password",
"domain": "domain"
}
},
"options": {
"connectTimeout": 15000,
"trustServerCertificate": true
},
"port": 1433,
"server": "hostname",
"database": "databasename"
}Example:
{
"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:
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.
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, orOracle.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. TLS (Oracle only): When the selected database type is Oracle, a TLS section appears for configuring mutual TLS (mTLS). See Configure Oracle mTLS for details.
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 ofMyP@ssw0rd!would be encoded intoMyP%40ssw0rd%21.
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 to15000(15 sec.) for SQL Server databases. For both, the minimum allowed value is1000(1 sec.), and the maximum is60000(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 default15000(15 seconds), be sure that you know why. Long-running queries can affect other parts of the system. The minimum is1000(1 second).
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:
Ensure the Database Connection is committed and deployed.
Teleport to the Worker Node and open the Database Connection on that Worker Node.
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.
Configure Oracle mTLS
Cribl Stream supports mutual TLS (mTLS) for Oracle Database Connections operating in THIN mode. mTLS requires the Oracle server to present a valid certificate and requires Cribl Stream to present a client certificate during the TLS handshake.
Prerequisites
Before configuring mTLS for an Oracle connection, verify the following:
Oracle server configured for TCPS: The Oracle listener must accept TCPS connections. Port
2484is the officially registered TCPS port, but the actual port depends on your listener configuration. Confirm the port and service name with your database administrator.Client certificate in Cribl Stream: The TLS client certificate and private key must be stored in the Cribl Stream certificate store. Go to Settings > Security > Certificates to add the certificate. The certificate must be in PEM format.
Connect string uses the
tcpsprotocol: The connection string must specifytcpsas the protocol. See mTLS (TCPS) Connection Strings for examples.
TLS Settings
When Database type is set to Oracle, a TLS section appears in the Database Connection form. Configure the following fields:
| Field | Description |
|---|---|
| TLS (toggle) | Enable to activate the TLS section and configure mTLS. |
| Certificate | Select the client certificate to present during the TLS handshake. This list is populated from certificates managed under Settings > Security > Certificates. |
| Reject Unauthorized | When enabled (default), Cribl Stream validates the Oracle server’s TLS certificate. Disable only in controlled test environments where the server uses a self-signed certificate. |
Configure an Oracle mTLS Connection
Add the client certificate to the Cribl Stream certificate store at Settings > Security > Certificates, if not already present.
Follow the steps in Configure a Database Connection to open the New Database Connection modal and set Database type to
Oracle.In the Authentication method dropdown, select Connection String, then enter a
tcpsconnect string in the field that appears, for example:(DESCRIPTION=(ADDRESS=(PROTOCOL=TCPS)(HOST=oracle-prod.corp.net)(PORT=2484))(CONNECT_DATA=(SERVICE_NAME=FINANCE_PDB1)))Under TLS, toggle TLS on to expand the TLS settings.
In the Certificate dropdown, select the client certificate you added in step 1.
Leave Reject Unauthorized enabled unless the Oracle server uses a self-signed certificate in a controlled test environment.
Select Save, then commit and deploy.
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.