---
title: "Test database connection"
method: POST
path: "/database/connections/test"
tags: ["DatabaseConnection"]
---

# Test database connection

`POST /database/connections/test`

Test an existing database connection to validate connection parameters

## Request body

- DatabaseConnectionTestParameters — Entity containing the connection details that will be used for testing a database connection
  - `workspace_id` string — Workspace ID
  - `environment_id` string — Environment ID
  - `database_connection` DatabaseConnection — Entity containing the connection details for a configured database
    - `id` string — Database connection ID
    - `workspace_id` string — Workspace ID
    - `name` string — Database name
    - `description` string — Databaes description
    - `database_type` 'mariadb' | 'mongodb' | 'mssql' | 'mysql' | 'oracle' | 'postgres'
    - `connection_properties` DatabaseConnectionProperties — Database connection details
      - `host` string — Host address of database connection
      - `port` integer — Port number of database connection
      - `database` string — Database name
      - `credentials_id` string — Credential ID to use when connecting to database
      - `link_agent_label` string — DEPRECATED - use link_agent_labels
      - `link_agent_labels` string[] — Link agent override to use when connecting to database (optional)
      - `driver_properties` object — Additional database connection properties
    - `connection_overrides` DatabaseConnectionPropertiesOverride[] — Set of connection_property overrides that apply to this database connection
      - `environment_id` string — Environment ID associated with override
      - `connection_properties` DatabaseConnectionProperties — Database connection details
        - `host` string — Host address of database connection
        - `port` integer — Port number of database connection
        - `database` string — Database name
        - `credentials_id` string — Credential ID to use when connecting to database
        - `link_agent_label` string — DEPRECATED - use link_agent_labels
        - `link_agent_labels` string[] — Link agent override to use when connecting to database (optional)
        - `driver_properties` object — Additional database connection properties
    - `created_by_id` string
    - `created_time` integer
    - `last_updated_by_id` string
    - `last_updated_time` integer
    - `deleted_by_id` string
    - `deleted_time` integer

## Response `200`

Database query execution

- DatabaseQueryExecution
  - `id` string — DatabaseQueryExecution ID
  - `workspace_id` string — Workspace ID
  - `database_connection_id` string — Database connection ID
  - `environment_id` string — Environment ID
  - `execution_command` 'get_schema' | 'test_connection' — Command to run against database
  - `snippet_id` string — ID of reusable SQL query to execute
  - `query` string — Base64 encoded SQL query to execute
  - `query_parameters` DatabaseQueryParameter[] — Runtime query parameters to apply
    - `id` string — Parameter ID
    - `type` 'String' | 'Number' | 'Boolean' — Parameter datatype. Defaults to string if not provided. (optional)
    - `value` string — String value of provided parameter
  - `status` 'scheduled' | 'running' | 'complete' | 'failure' — Current status of query execution
  - `results_metadata` DatabaseQueryResultMetadata
    - `status` 'success' | 'failed' | 'error' — Query results status
    - `duration` integer — Duration of query in milliseconds
    - `message` string — Message returned from database on a successful query, if any
    - `error_message` string — Error message returned from database query, if any
    - `row_count` integer — Row count in result set
    - `column_count` integer — Columns count in result set
    - `rows_affected` integer — Count of rows affacted count by query
    - `additional_properties` object — Key value map for additional properties
  - `results_uri` string — GCS storage bucket location of the query results
  - `test_context_id` string — The test run id if the query is being executed during a cloud run or the user's id for a local run
  - `created_time` integer
  - `created_by_id` string
  - `last_updated_time` integer
  - `last_updated_by_id` string
  - `completed_time` integer

## Other responses

- `400` — Invalid or missing parameter
- `401` — User not authenticated
- `403` — User not authorized
- `408` — Request timed out
- `default` — Unknown error

---

[API](https://skmtc.net/mabl/apis/mabl-api.md) · [All operations](https://skmtc.net/mabl/apis/mabl-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mabl/mabl-api/revisions/d0fc0114da66/schema)