Connecting to a different database

This guide walks you through pointing an existing Team assistant instance at a different Microsoft SQL Server database. You will edit the Docker Compose environment file, run the schema upgrade, and restart the services from the tas-manager menu.

Prerequisites

Before connecting a new database, follow these rules — ignoring them can corrupt data:

  1. The Team assistant version must be newer than the schema version of the existing database, or the database schema must be empty. An older Team assistant must never be connected to a newer schema.
  2. Only one Team assistant instance may be connected to a given database. Connecting a second instance to the same database will corrupt it.
  3. If the new database is a clone of another environment, disable the Team assistant crons before connecting the new instance so that the cloned scheduled jobs do not run. Run this SQL command against the database:
    UPDATE CRONS SET CRON_STATUS='N'
  4. If the Team assistant version is newer than the newly connected database, the database schema migration must be run manually (step 5 below).
Ignoring these rules — especially connecting an older version to a newer schema, or connecting a second instance to the same database — can irreversibly corrupt data.

Procedure

1. Open the system shell

In the main menu, go to:

Management → System → [!] Open system shell (advanced users only)

Confirm the warning dialog. You are now at the shell command line. The Docker Compose environment file you will edit is $TAS_COMPOSE_PATH/.env (default ~/tas-compose/.env).

2. Open the environment file in the nano editor

Open the file in the nano text editor:

nano "$TAS_COMPOSE_PATH/.env"

Working in the nano editor:

  • Move around with the arrow keys and type directly to edit.
  • Save: press Ctrl+O, then Enter to confirm the file name.
  • Exit: press Ctrl+X.
  • Exit without saving: press Ctrl+X, then N when asked whether to save.

3. Add or edit the database variables

Set the following required variables. If a variable already exists in the file, edit its value in place; otherwise add it on a new line.

Variable

Purpose

Example

TAS_DB_VENDOR

Database engine (SQL Server)

mssql

TAS_DB_HOSTNAME

Hostname or IP of the database server

sql.example.local

TAS_DB_PORT

TCP port

1433

TAS_DB_NAME

Database name

TAS

TAS_DB_SCHEMA

Schema name

tas

TAS_DB_USERNAME

Login user

tas_app

TAS_DB_PASSWORD

Login password

your-password

The variables below are optional — set them only when the target server requires them. Consult your database administrator or the Team assistant release notes for the exact values.

Variable

Purpose

TAS_DB_ENCRYPTION

Enable TLS encryption for the connection

TAS_DB_ENCRYPTION_IGNORE_CERTIFICATE

Trust the server certificate (e.g. self-signed)

TAS_DB_ENCRYPTION_METHOD

TLS encryption method

TAS_DB_NTLM_AUTH_ENABLED

Enable Windows/NTLM authentication

TAS_DB_NTLM_AUTH_DOMAIN

NTLM authentication domain

TAS_DB_MAX_POOL_CONNECTION

Maximum connection pool size

TAS_DB_MAX_ROWS

Maximum number of rows returned per query

TAS_DB_REQUEST_TIMEOUT

Query request timeout

Do not remove unrelated keys managed by tas-manager (for example TAS_FRONTEND_IMAGE, TAS_BACKEND_IMAGE, TAS_COMPOSE_DB_BACKUP_PATH).

4. Save and return to the menu

Save the file (Ctrl+O, Enter) and exit nano (Ctrl+X). Then type exit to leave the system shell and return to the tas-manager menu.

5. Run the database schema upgrade

In the main menu, go to:

Management → Team assistant → Run database schema upgrade

Confirm the prompt and wait for completion.

Running it is recommended every time to ensure the schema matches the deployed Team assistant version. You can skip it only when the target database schema is already at exactly the same version as Team assistant — running it in that case is harmless.

6. Restart the Team assistant services

In the main menu, go to:

Management → Team assistant → Manage services → Restart Team assistant

This restarts tas-frontend, tas-backend, and tas-backend-cron. Use Restart all services instead if you want to restart the entire set.

A restart is recommended every time so that the new database settings take effect; strictly speaking it is unnecessary only when the schema was already up to date and the services have already been restarted after the .env change. When in doubt, restart.

Troubleshooting

Database unreachable / connection refused

Verify TAS_DB_HOSTNAME and TAS_DB_PORT. Check that the database server is reachable from the shell (network route, firewall) and that SQL Server is accepting TCP connections on that port.

Login failed / incorrect credentials

Re-check TAS_DB_USERNAME, TAS_DB_PASSWORD, and TAS_DB_NAME. Verify that the login exists on the target server and has rights to the database and the TAS_DB_SCHEMA schema.

TLS / certificate errors

Set TAS_DB_ENCRYPTION to match the server's requirement. For a self-signed or untrusted certificate, set TAS_DB_ENCRYPTION_IGNORE_CERTIFICATE.

Schema version mismatch / migration refuses to run

This is rule 1: the Team assistant version must be newer than the schema, or the schema must be empty. Verify the versions and run the schema upgrade (step 5).

Cloned database still runs scheduled jobs

This is rule 3: before starting the instance, run UPDATE CRONS SET CRON_STATUS='N' against the database.

For details, see the startup output shown via Manage services and the container logs. For detailed diagnostic instructions — checking service status, reading logs, and testing the database connection — see the article Diagnosing Team assistant service status.

Frantisek Brych Updated by Frantisek Brych

Diagnosing services

Contact

Syca (opens in a new tab)

Powered by HelpDocs (opens in a new tab)