Set up database connections
Connectors that work with databases (the SQL Database Executor job types) don't carry their own credentials. Instead, you create a connection once: the server, database, and login for a system, stored centrally and reused by any job that needs it. Credentials are kept secure and delivered to the agent only at run time; they never appear in a job definition or in job output.
The SQL Database Executor job types do not run in this build. You can create and save database connections, but every job that would use one fails before it reaches the database, with External plugin sql-executor requires pluginDownloadUrl and pluginChecksum.
Set up a connection for each database a workflow needs to reach: for example, your core banking database, a reporting warehouse, or a partner system.
Database jobs need a server and login. Put those in each job and credentials sprawl across workflows and show up in definitions and job output, which is a security and maintenance problem.
Connection types
| Connection | Required | Optional | Use with |
|---|---|---|---|
| SQL Server | Server, Database | Port (default 1433), Username, Password, Windows Authentication, Trust Server Certificate | MS SQL Script, MS SQL Job, MS SQL DTExec (SSIS) |
| MySQL | Host, Database, Username | Port (default 3306), Password | MySQL Script |
| Oracle | Connection String | Username, Password | Oracle Script |
| ODBC | Connection String | Username, Password | Other DB Script (ODBC) |
On Oracle and ODBC, the Connection String is treated as a secret in its own right, not just the password beside it — an ODBC/OleDB string conventionally carries the password inline. It is masked when you reopen the connection, so leave it blank to keep the stored value.
SQL Server connections
Connections to SQL Server are always encrypted (TLS). Two settings deserve attention:
- Trust Server Certificate: leave this off when the server presents a certificate from a trusted certificate authority. Turn it on only when the server uses a self-signed or internal-CA certificate; otherwise the connection fails on a certificate error. Installing a properly trusted certificate is the more secure long-term option.
- Windows Authentication: turn this on to connect with a Windows account instead of a SQL login.
Best practices
- Use a least-privilege database account scoped to what the workflows actually need.
- Create a separate connection per environment (for example, test vs. production) so jobs can't accidentally run against the wrong database.
- Keep connection credentials current. An expired or rotated password shows up as a login failure on every job that uses the connection.
Agent prerequisites
Some connections require software on the agent that runs the job:
- ODBC: the ODBC driver/DSN named in the connection string must be installed on the agent.
- Oracle: the agent must meet the Oracle client prerequisites.
See Prepare agents for connectors.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Connection fails on a certificate error (SQL Server) | Self-signed / internal-CA certificate, Trust Server Certificate off | Turn on Trust Server Certificate, or install a trusted certificate. |
| "Login failed" | Wrong credentials, or SQL vs. Windows auth mismatch | Verify the login; set Windows Authentication to match the server. |
| ODBC connection fails | Driver/DSN not installed on the agent | Install the ODBC driver/DSN on the agent. |
| Oracle connection fails | Wrong connection string, or missing Oracle client on the agent | Verify the connection string; confirm agent prerequisites. |
Related topics