Update Datasource - Databrain

curl --request PUT \
  --url https://api.usedatabrain.com/api/v2/datasource \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "datasourceType": "postgres",
    "credentials": {
      "name": "production-postgres",
      "host": "new-db.example.com",
      "port": 5432,
      "username": "dbuser",
      "password": "newpassword",
      "database": "analytics",
      "schema": "public"
    }
  }'

{
  "name": "production-postgres"
}

curl --request PUT \
  --url https://api.usedatabrain.com/api/v2/datasource \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "datasourceType": "postgres",
    "credentials": {
      "name": "production-postgres",
      "host": "new-db.example.com",
      "port": 5432,
      "username": "dbuser",
      "password": "newpassword",
      "database": "analytics",
      "schema": "public"
    }
  }'

{
  "name": "production-postgres"
}

curl --request PUT \
  --url https://api.usedatabrain.com/api/v2/datasource \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "datasourceType": "postgres",
    "credentials": {
      "name": "production-postgres",
      "host": "new-db.example.com",
      "port": 5432,
      "username": "dbuser",
      "password": "newpassword",
      "database": "analytics",
      "schema": "public"
    }
  }'

{
  "name": "production-postgres"
}

PUT

api

datasource

curl --request PUT \
  --url https://api.usedatabrain.com/api/v2/datasource \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "datasourceType": "postgres",
    "credentials": {
      "name": "production-postgres",
      "host": "new-db.example.com",
      "port": 5432,
      "username": "dbuser",
      "password": "newpassword",
      "database": "analytics",
      "schema": "public"
    }
  }'

{
  "name": "production-postgres"
}

Update an existing datasource’s credentials or configuration. The API validates the new credentials, tests the connection, and automatically refreshes the cached schema.

You can only update datasources that already exist in your organization. The datasource is identified by the name field in the credentials. After updating, the schema will be automatically re-cached.

Endpoint

PUT https://api.usedatabrain.com/api/v2/datasource

Self-hosted Databrain Endpoint

PUT <SELF_HOSTED_URL>/api/v2/datasource

Authentication

This endpoint requires a service token in the Authorization header. Service tokens differ from data app API keys and provide organization-level permissions. To access your service token:

In Settings page, navigate to the Service Tokens section.
Click the “Generate Token” button to create a new service token if you don’t have one already.

Headers

Authorization

string

required

Bearer token for API authentication. Use your service token.

Authorization: Bearer dbn_live_abc123...

Content-Type

string

required

Must be set to application/json for all requests.

Content-Type: application/json

Request Body

datasourceType

string

required

The type of datasource. Must match the existing datasource type. See Create Datasource for supported types.

credentials

object

required

Updated connection credentials for the datasource. Must include the name field matching the existing datasource name.

The credentials.name field must match the exact name of the existing datasource you want to update. This name is used to identify which datasource to update.

credentials.name

string

required

The name of the existing datasource to update. Must match exactly as it was created.

Show Finding datasource names

Use the List Datasources API to see all datasource names
Check the response from datasource creation
Available in the DataBrain dashboard when viewing datasources

tenancySettings

object

Multi-tenant configuration for the datasource. Defines how data is isolated between different tenants/clients. Optional - if not provided, existing tenancy settings will remain unchanged.

Show Tenancy configuration details

TABLE level: Uses a dedicated table to map client identifiers
DATABASE level: Each client has a separate database
If the datasource doesn’t have existing tenancy settings, new settings will be created
If tenancy settings already exist, they will be updated with the new values

tenancySettings.tenancyLevel

string

The level at which tenant isolation occurs. Must be one of: TABLE or DATABASE.

TABLE: Client mapping is stored in a specific table (most common)
DATABASE: Each client has a separate database instance

Required when tenancySettings is provided. If tenancySettings is omitted, this field is not needed.

tenancySettings.clientColumnType

string

Data type of the client identifier column. Must be either NUMBER or STRING.Required when tenancyLevel is TABLE.

tenancySettings.schemaName

string

Schema name where the client mapping table is located.Required when tenancyLevel is TABLE.

tenancySettings.tableName

string

Name of the table that contains client mapping information.Required when tenancyLevel is TABLE.

tenancySettings.tableClientNameColumn

string

Column name in the mapping table that stores the client identifier.Required when tenancyLevel is TABLE.

tenancySettings.tablePrimaryKeyColumn

string

Primary key column of the client mapping table.Required when tenancyLevel is TABLE.

Datasource-Specific Credentials

You must provide all required fields for the datasource type, even if only some values are changing. Partial updates are not supported.

When updating credentials, provide the complete credential structure for the datasource type. Partial updates are not supported.

credentials

object

Datasource-specific credential fields. The required fields depend on the datasourceType.

Snowflake

credentials.host

string

required

Snowflake account hostname (e.g., your-account.snowflakecomputing.com)

credentials.username

string

required

Snowflake username

credentials.role

string

required

Snowflake role to use

credentials.warehouse

string

required

Snowflake warehouse name

credentials.database

string

required

Snowflake database name

credentials.schema

string

required

Snowflake schema name

credentials.credentials

string

required

Authentication method: "username/password" or "Key-pair authentication"

credentials.password

string

Password (required if credentials is "username/password")

credentials.privateKey

string

Private key (required if credentials is "Key-pair authentication")

credentials.privateKeyPass

string

Passphrase for the private key (optional)

Postgres / Redshift

credentials.host

string

required

Database hostname or IP address

credentials.port

number

required

Database port number (1-65535)

credentials.username

string

required

Database username

credentials.password

string

required

Database password

credentials.database

string

required

Database name

credentials.schema

string

required

Schema name

credentials.sslMode

boolean

Enable SSL mode (optional)

credentials.sshTunnel

string

SSH tunnel setting: "enable" or "disable" (optional)

credentials.sshHost

string

SSH server hostname (required if sshTunnel is "enable")

credentials.sshPort

number

SSH server port (required if sshTunnel is "enable")

credentials.sshUsername

string

SSH username (required if sshTunnel is "enable")

credentials.sshPrivateKey

string

SSH private key (required if sshTunnel is "enable")

CockroachDB

credentials.host

string

required

CockroachDB hostname or IP address

credentials.port

number

required

Database port number (1-65535)

credentials.username

string

required

Database username

credentials.password

string

required

Database password

credentials.database

string

required

Database name

credentials.schema

string

required

Schema name

credentials.sslMode

boolean

Enable SSL mode (optional)

credentials.sshTunnel

string

SSH tunnel setting: "enable" or "disable" (optional)

credentials.sshHost

string

SSH server hostname (required if sshTunnel is "enable")

credentials.sshPort

number

SSH server port (required if sshTunnel is "enable")

credentials.sshUsername

string

SSH username (required if sshTunnel is "enable")

credentials.sshPrivateKey

string

SSH private key (required if sshTunnel is "enable")

BigQuery

credentials.credentials_json

string

required

JSON string containing Google Cloud service account credentials

credentials.project_id

string

required

Google Cloud project ID

credentials.dataset_location

string

required

BigQuery dataset location (e.g., "US", "EU")

credentials.dataset_id

string

BigQuery dataset ID (optional)

MySQL / MongoDB / ClickHouse

credentials.host

string

required

Database hostname or IP address

credentials.port

number

required

Database port number (1-65535)

credentials.user

string

required

Database username. Note: Uses user not username for these datasource types.

credentials.password

string

required

Database password

MSSQL

credentials.server

string

required

SQL Server hostname or IP address. Note: Uses server not host for MSSQL.

credentials.port

number

required

Database port number (1-65535)

credentials.user

string

required

Database username. Note: Uses user not username for MSSQL.

credentials.password

string

required

Database password

credentials.database

string

Database name (optional)

credentials.isDisableDatabase

boolean

Disable database selection (optional)

credentials.readOnlyIntent

boolean

Optional MSSQL read-only routing hint. When true, Databrain connects with read-only intent for MSSQL workloads.

SingleStore

credentials.host

string

required

Database hostname or IP address

credentials.port

number

required

Database port number (1-65535)

credentials.user

string

required

Database username

credentials.password

string

required

Database password

credentials.database

string

required

Database name

Databricks

credentials.serverHostname

string

required

Databricks server hostname

credentials.httpPath

string

required

Databricks HTTP path

credentials.token

string

required

Databricks access token

Elasticsearch

credentials.server_type

string

required

Server type: "elastic-cloud", "open-cloud", or "self-managed"

credentials.cloud_id

string

Cloud ID (required if server_type is "elastic-cloud" or "open-cloud")

credentials.server_url

string

Server URL (required if server_type is "self-managed")

credentials.username

string

Username (required unless disableAuth is true)

credentials.password

string

Password (required unless disableAuth is true)

credentials.disableAuth

boolean

Disable authentication (optional, default false). Only valid when server_type is "self-managed".

credentials.isIgnoreVerifyCert

boolean

Ignore certificate verification (optional)

credentials.isIgnoreSsl

boolean

Ignore SSL (optional)

OpenSearch

credentials.server_type

string

required

Server type: "elastic-cloud", "open-cloud", or "self-managed"

credentials.cloud_id

string

Cloud ID (required if server_type is "elastic-cloud" or "open-cloud")

credentials.server_url

string

Server URL (required if server_type is "self-managed")

credentials.username

string

Username (required unless disableAuth is true)

credentials.password

string

Password (required unless disableAuth is true)

credentials.disableAuth

boolean

Disable authentication (optional, default false). Only valid when server_type is "self-managed".

credentials.isIgnoreVerifyCert

boolean

Ignore certificate verification (optional)

credentials.isIgnoreSsl

boolean

Ignore SSL (optional)

Firebolt

credentials.client_id

string

required

Firebolt client ID

credentials.client_secret

string

required

Firebolt client secret

credentials.account

string

required

Firebolt account name

credentials.database

string

required

Database name

credentials.engineName

string

required

Engine name

credentials.schema

string

Schema name (optional)

Athena

credentials.database

string

required

Athena database name

credentials.outputBucket

string

required

S3 output bucket for query results

credentials.s3AccessKeyId

string

required

AWS access key ID

credentials.s3Region

string

required

AWS region

credentials.s3SecretAccessKey

string

required

AWS secret access key

credentials.datasourceId

string

Datasource ID (optional)

Trino

credentials.host

string

required

Trino hostname or IP address

credentials.port

number

required

Database port number (1-65535)

credentials.catalog

string

required

Trino catalog name

credentials.schema

string

required

Schema name

credentials.username

string

required

Username

credentials.password

string

required

Password

credentials.sshTunnel

string

SSH tunnel setting: "enable" or "disable" (optional)

credentials.sshHost

string

SSH host (required if sshTunnel is "enable")

credentials.sshPort

number

SSH port (required if sshTunnel is "enable")

credentials.sshUsername

string

SSH username (required if sshTunnel is "enable")

credentials.sshPrivateKey

string

SSH private key (required if sshTunnel is "enable")

CSV

credentials.name

string

required

Name for the CSV datasource

AWS S3

credentials.bucketName

string

required

S3 bucket name

credentials.datasetPath

string

Path within the bucket (optional, can be empty string)

credentials.s3Region

string

required

AWS region (e.g., "us-east-1")

credentials.tableLevel

string

Table level: "File" or "Folder" (optional)

credentials.s3AccessKeyId

string

required

AWS access key ID

credentials.s3SecretAccessKey

string

required

AWS secret access key

Response

name

string

The name of the updated datasource (same as credentials.name).

error

null

Error field, null when successful. Not included in successful responses.

Examples

Error Codes

Error Code	HTTP Status	Description
`INVALID_REQUEST_BODY`	400	Missing required fields or invalid credential structure
`DATASOURCE_NAME_ERROR`	400	Datasource not found
`CREDENTIAL_TEST_FAILED`	400	Connection test failed
`AUTHENTICATION_ERROR`	401	Invalid or missing service token
`SCHEMA_CACHE_FAILED`	500	Schema caching failed
`DATASOURCE_NOT_FOUND`	404	The specified datasource does not exist
`TENANCY_SETTINGS_CREATE_FAILED`	500	Failed to create tenancy settings for the datasource
`TENANCY_SETTINGS_UPDATE_FAILED`	500	Failed to update existing tenancy settings
`INTERNAL_SERVER_ERROR`	500	Server error occurred

Next Steps

List Datasources

View all datasources to verify the update

Sync Datasource

Manually sync the datasource schema if needed

Create Datasource

Create a new datasource instead of updating

Delete Datasource

Remove a datasource you no longer need

List Datasources

Delete Datasource

​Endpoint

​Self-hosted Databrain Endpoint

​Authentication

​Headers

​Request Body

​Datasource-Specific Credentials

​Response

​Examples

​Error Codes

​Next Steps

List Datasources

Sync Datasource

Create Datasource

Delete Datasource

Endpoint

Self-hosted Databrain Endpoint

Authentication

Headers

Request Body

Datasource-Specific Credentials

Response

Examples

Error Codes

Next Steps