Skip to Content

Datasource APIs

Update a datasource

Replace the credentials or tenancy of a datasource you already connected.

PUT
/api/v2/datasource

Use it to change a password, a host, or the tenancy setup. Databrain tests the new credentials and reads the schema again.

curl --request PUT https://api.usedatabrain.com/api/v2/datasource \  --header "Authorization: Bearer $DATABRAIN_SERVICE_TOKEN" \  --header "Content-Type: application/json" \  --data '{    "datasourceType": "postgres",    "credentials": {      "name": "Sales warehouse",      "host": "db.example.com",      "port": 5432,      "username": "databrain_reader",      "password": "<new password>",      "database": "analytics",      "schema": "public"    }  }'

Auth

A service token. See Authentication.

Limits

10 requests in 5 minutes per organization, shared with create, sync and schema discovery.

Authorization

ApiToken
headerAuthorizationBearer <token>

A service token or a data app API token.

Body

The body is the same as Create a datasource, with the same credential fields per type. These rules are different:

  • credentials.name picks the datasource to update. You cannot rename a datasource with this call.
  • credentials replaces all stored credentials. Send every required field again, not only the ones that change.
  • datasourceType is used only to check and test the credentials. It does not change the type of the datasource. Send the type it already has.
  • tenancySettings is optional. If you leave out tenancyLevel, the stored level stays.
  • Microsoft Fabric (microsoft fabric) can be updated here, with server, port, database, clientId, and user and password or clientSecret.
datasourceTypestringrequired

One of the types in the table below, in lower case.

One of: snowflakepostgrespostgresqlcockroachdbredshiftmysqlmongodbclickhousesinglestorebigquerydatabrickselasticsearchopensearchmssqlawss3csvfireboltathenatrinomicrosoft fabric
credentialsobjectrequired

Connection fields for the type. credentials.name is the datasource name and must be unique in your organization.

52 fields in credentials
namestringrequired

The datasource name, unique in your organization.

hoststring

For postgres, mysql, mongodb, clickhouse, singlestore, snowflake, trino. See Credentials by type.

portinteger

For postgres, mysql, mongodb, clickhouse, singlestore, mssql, trino. See Credentials by type.

usernamestring

For postgres, snowflake, trino. See Credentials by type.

passwordstring

For postgres, mysql, mongodb, clickhouse, singlestore, mssql, snowflake, elasticsearch, opensearch, trino. See Credentials by type.

databasestring

For postgres, singlestore, mssql, snowflake, athena, firebolt. See Credentials by type.

schemastring

For postgres, snowflake, firebolt, trino. See Credentials by type.

sslModestring

For postgres. See Credentials by type.

sshTunnelstring

For postgres, mssql, trino. See Credentials by type.

One of: enabledisable
sshHoststring

For postgres, mssql, trino. See Credentials by type.

sshPortinteger

For postgres, mssql, trino. See Credentials by type.

For postgres, mssql, trino. See Credentials by type.

For postgres, mssql, trino. See Credentials by type.

userstring

For mysql, mongodb, clickhouse, singlestore, mssql. See Credentials by type.

serverstring

For mssql. See Credentials by type.

For mssql. See Credentials by type.

rolestring

For snowflake. See Credentials by type.

warehousestring

For snowflake. See Credentials by type.

For snowflake, databricks. See Credentials by type.

For snowflake. See Credentials by type.

For snowflake. See Credentials by type.

For bigquery. See Credentials by type.

For bigquery. See Credentials by type.

For bigquery. See Credentials by type.

For bigquery. See Credentials by type.

For databricks. See Credentials by type.

httpPathstring

For databricks. See Credentials by type.

tokenstring

For databricks. See Credentials by type.

For databricks. See Credentials by type.

queryTagsstring

For databricks. See Credentials by type.

For elasticsearch, opensearch. See Credentials by type.

One of: elastic-cloudopen-cloudself-managed
cloud_idstring

For elasticsearch, opensearch. See Credentials by type.

For elasticsearch, opensearch. See Credentials by type.

For elasticsearch, opensearch. See Credentials by type.

For elasticsearch, opensearch. See Credentials by type.

For awss3. See Credentials by type.

For awss3. See Credentials by type.

For awss3. See Credentials by type.

One of: FileFolder

For athena. See Credentials by type.

client_idstring

For firebolt. See Credentials by type.

For firebolt. See Credentials by type.

accountstring

For firebolt. See Credentials by type.

For firebolt. See Credentials by type.

catalogstring

For trino. See Credentials by type.

clientIdstring

databricks with OAuth service principal, and microsoft fabric: the app's client id.

tenantIdstring

microsoft fabric: the Microsoft Entra tenant id. Can be empty.

elasticsearch and opensearch, self-managed only: true connects without a username and password.

Default: false
s3Regionstring

AWS region of the bucket. Required for awss3 and athena.

AWS access key id. Required for awss3 and athena.

AWS secret access key. Required for awss3 and athena.

athena only. Optional.

Tenancy for this datasource.

6 fields in tenancySettings

TABLE (a tenant column) or DATABASE (a schema or database per tenant)

Required for TABLE. Schema of the table that lists your tenants.

tableNamestring

Required for TABLE. Table that lists your tenants.

Required for TABLE. Column with the tenant name.

Required for TABLE. Column with the tenant id, the value you send as clientId

Required for TABLE. STRING or NUMBER

Default: STRING

Response

{  "name": "Sales warehouse"}

The response can also have warnings, as on create.

Errors

Statuserror.codeWhy
400INVALID_REQUEST_BODYA field is missing, unknown or wrong, or the host is refused
400DATASOURCE_NAME_ERRORNo datasource has this credentials.name
400DATASOURCE_NOT_FOUNDThe datasource was removed while you updated it
400CREDENTIAL_TEST_FAILEDDatabrain could not connect with the new credentials. Nothing was changed
400TENANCY_SETTINGS_CREATE_FAILED or TENANCY_SETTINGS_UPDATE_FAILEDThe credentials were saved, the tenancy was not
400SCHEMA_CACHE_FAILEDCredentials and tenancy were saved, the schema was not read. Run sync
403DATABRICKS_OAUTH_NOT_ENABLEDDatabricks OAuth is not on for your organization
429Rate limit

The steps are not one transaction. A later step can fail after an earlier one is saved.

For errors that every endpoint returns, see Authentication.

Example Request
curl -X PUT 'https://api.usedatabrain.com/api/v2/datasource' \  -H 'Content-Type: application/json' \  -d '{  "datasourceType": "postgres",  "credentials": {    "name": "Sales warehouse",    "host": "db.example.com",    "port": 5432,    "username": "databrain_reader",    "password": "<new password>",    "database": "analytics",    "schema": "public"  }}'
Example Response
{  "name": "Sales warehouse"}