Skip to main content
Version: Next

Connection Strings

Cortex can connect to Microsoft SQL Server, PostgreSQL, or SQLite. SQL Server is recommended.

You will need at minimum a Cortex connection string for Cortex's own data store. If you are using Cortex with Cherwell, you will also need a Default (or Cherwell) connection string pointing to your Cherwell database.

Constructing a Connection String​

Cortex accepts standard .NET connection strings - a series of semicolon-separated key-value pairs. A typical connection string looks like this:

server=server-hostname,1433;uid=username;password=the-password;database=Cherwell;MultipleActiveResultSets=true

Helpful references:

Required Settings​

  • server - The hostname or FQDN and port of your SQL Server instance, or the name of a named local instance.

  • Authentication - Choose one of the following:

    • SQL Authentication (recommended)
      • uid or user id - the SQL username
      • password - the SQL password
    • Windows Authentication (common in high-security environments, requires additional IIS configuration - see below)
      • Integrated Security=true

  • database or initial catalog - The name of the database.

  • MultipleActiveResultSets - Must be set to true.

Alternate Database Engines​

All connection strings are treated as SQL Server by default. Cortex also supports PostgreSQL and SQLite for both the Default/Cherwell and Cortex connections.

To use a different engine, add the engine option to the connection string:

engine=postgres;server=server-hostname,5432;uid=username;password=the-password;database=Cherwell

Valid values are postgres and sqlite.

note

MultipleActiveResultSets=true is SQL Server-specific and will cause PostgreSQL and SQLite connections to fail if included. Remove it when using those engines.

Functionality is limited when using SQLite for the Default/Cherwell connection. There is no supported migration path from SQL Server to SQLite (though there is one from SQL Server to PostgreSQL).

Windows Authentication for SQL Server​

warning

Windows Authentication for the SQL Server connection only affects how Cortex connects to the database. User authentication to Cortex itself must still be configured separately via SAML or OpenID Connect.

This option is only supported when running Cortex on Windows with IIS, connecting to Microsoft SQL Server. It is not supported with PostgreSQL or SQLite.

  1. In IIS Manager, configure the Application Pool that Cortex runs under to use a specific Windows user account. This account must have access to the SQL Server instance.
  2. Update your connection string to use Integrated Security instead of a username and password:
server=server-hostname,1433;Integrated Security=true;database=Cherwell;MultipleActiveResultSets=true

Optional Settings​

These settings may be required depending on your environment or security requirements.

  • Encrypt - Recommended to be true. Can be set to false if the database is on the same machine.
  • TrustServerCertificate - Set to true if your SQL Server uses a self-signed certificate or an untrusted chain. See Installation Troubleshooting for when this is needed.

Troubleshooting​

If you encounter connection errors, see:

Installation Troubleshooting