> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usedatabrain.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Update Datasource
> Update the credentials and configuration of an existing datasource. The API validates and tests the new credentials before applying changes.
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 /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:
1. In **Settings** page, navigate to the **Service Tokens** section.
2. Click the **"Generate Token"** button to create a new service token if you don't have one already.
```bash Authentication theme={"dark"}
curl --request PUT \
--url https://api.usedatabrain.com/api/v2/datasource \
--header 'Authorization: Bearer dbn_live_...' \
--header 'Content-Type: application/json'
```
## Headers
Bearer token for API authentication. Use your service token.
```
Authorization: Bearer dbn_live_abc123...
```
Must be set to `application/json` for all requests.
```
Content-Type: application/json
```
## Request Body
The type of datasource. Must match the existing datasource type. See [Create Datasource](/developer-docs/helpers/api-reference/create-datasource) for supported types.
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.
The name of the existing datasource to update. Must match exactly as it was created.
* Use the [List Datasources API](/developer-docs/helpers/api-reference/list-datasources) to see all datasource names
* Check the response from datasource creation
* Available in the DataBrain dashboard when viewing datasources
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.
* **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
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.
Data type of the client identifier column. Must be either `NUMBER` or `STRING`.
**Required when** `tenancyLevel` is `TABLE`.
Schema name where the client mapping table is located.
**Required when** `tenancyLevel` is `TABLE`.
Name of the table that contains client mapping information.
**Required when** `tenancyLevel` is `TABLE`.
Column name in the mapping table that stores the client identifier.
**Required when** `tenancyLevel` is `TABLE`.
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.
Datasource-specific credential fields. The required fields depend on the `datasourceType`.
Snowflake account hostname (e.g., `your-account.snowflakecomputing.com`)
Snowflake username
Snowflake role to use
Snowflake warehouse name
Snowflake database name
Snowflake schema name
Authentication method: `"username/password"` or `"Key-pair authentication"`
Password (required if credentials is `"username/password"`)
Private key (required if credentials is `"Key-pair authentication"`)
Passphrase for the private key (optional)
Database hostname or IP address
Database port number (1-65535)
Database username
Database password
Database name
Schema name
Enable SSL mode (optional)
SSH tunnel setting: `"enable"` or `"disable"` (optional)
SSH server hostname (required if sshTunnel is `"enable"`)
SSH server port (required if sshTunnel is `"enable"`)
SSH username (required if sshTunnel is `"enable"`)
SSH private key (required if sshTunnel is `"enable"`)
CockroachDB hostname or IP address
Database port number (1-65535)
Database username
Database password
Database name
Schema name
Enable SSL mode (optional)
SSH tunnel setting: `"enable"` or `"disable"` (optional)
SSH server hostname (required if sshTunnel is `"enable"`)
SSH server port (required if sshTunnel is `"enable"`)
SSH username (required if sshTunnel is `"enable"`)
SSH private key (required if sshTunnel is `"enable"`)
JSON string containing Google Cloud service account credentials
Google Cloud project ID
BigQuery dataset location (e.g., `"US"`, `"EU"`)
BigQuery dataset ID (optional)
Database hostname or IP address
Database port number (1-65535)
Database username. Note: Uses `user` not `username` for these datasource types.
Database password
SQL Server hostname or IP address. Note: Uses `server` not `host` for MSSQL.
Database port number (1-65535)
Database username. Note: Uses `user` not `username` for MSSQL.
Database password
Database name (optional)
Disable database selection (optional)
Optional MSSQL read-only routing hint. When `true`, Databrain connects with read-only intent for MSSQL workloads.
Database hostname or IP address
Database port number (1-65535)
Database username
Database password
Database name
Databricks server hostname
Databricks HTTP path
Databricks access token
Server type: `"elastic-cloud"`, `"open-cloud"`, or `"self-managed"`
Cloud ID (required if server\_type is `"elastic-cloud"` or `"open-cloud"`)
Server URL (required if server\_type is `"self-managed"`)
Username (required unless `disableAuth` is `true`)
Password (required unless `disableAuth` is `true`)
Disable authentication (optional, default `false`). Only valid when server\_type is `"self-managed"`.
Ignore certificate verification (optional)
Ignore SSL (optional)
Server type: `"elastic-cloud"`, `"open-cloud"`, or `"self-managed"`
Cloud ID (required if server\_type is `"elastic-cloud"` or `"open-cloud"`)
Server URL (required if server\_type is `"self-managed"`)
Username (required unless `disableAuth` is `true`)
Password (required unless `disableAuth` is `true`)
Disable authentication (optional, default `false`). Only valid when server\_type is `"self-managed"`.
Ignore certificate verification (optional)
Ignore SSL (optional)
Firebolt client ID
Firebolt client secret
Firebolt account name
Database name
Engine name
Schema name (optional)
Athena database name
S3 output bucket for query results
AWS access key ID
AWS region
AWS secret access key
Datasource ID (optional)
Trino hostname or IP address
Database port number (1-65535)
Trino catalog name
Schema name
Username
Password
SSH tunnel setting: `"enable"` or `"disable"` (optional)
SSH host (required if sshTunnel is `"enable"`)
SSH port (required if sshTunnel is `"enable"`)
SSH username (required if sshTunnel is `"enable"`)
SSH private key (required if sshTunnel is `"enable"`)
Name for the CSV datasource
S3 bucket name
Path within the bucket (optional, can be empty string)
AWS region (e.g., `"us-east-1"`)
Table level: `"File"` or `"Folder"` (optional)
AWS access key ID
AWS secret access key
## Response
The name of the updated datasource (same as credentials.name).
Error field, null when successful. Not included in successful responses.
## Examples
```bash cURL - PostgreSQL Example theme={"dark"}
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"
}
}'
```
```bash cURL - Snowflake Example theme={"dark"}
curl --request PUT \
--url https://api.usedatabrain.com/api/v2/datasource \
--header 'Authorization: Bearer dbn_live_abc123...' \
--header 'Content-Type: application/json' \
--data '{
"datasourceType": "snowflake",
"credentials": {
"name": "analytics-snowflake",
"host": "account.snowflakecomputing.com",
"username": "user@example.com",
"role": "ANALYST",
"warehouse": "COMPUTE_WH",
"database": "ANALYTICS",
"schema": "PUBLIC",
"credentials": "username/password",
"password": "updatedpassword"
}
}'
```
```bash cURL - MSSQL Example theme={"dark"}
curl --request PUT \
--url https://api.usedatabrain.com/api/v2/datasource \
--header 'Authorization: Bearer dbn_live_abc123...' \
--header 'Content-Type: application/json' \
--data '{
"datasourceType": "mssql",
"credentials": {
"name": "production-mssql",
"server": "sqlserver.example.com",
"port": 1433,
"user": "sqluser",
"password": "updatedpassword",
"database": "analytics",
"readOnlyIntent": true
}
}'
```
```bash cURL - CockroachDB Example theme={"dark"}
curl --request PUT \
--url https://api.usedatabrain.com/api/v2/datasource \
--header 'Authorization: Bearer dbn_live_abc123...' \
--header 'Content-Type: application/json' \
--data '{
"datasourceType": "cockroachdb",
"credentials": {
"name": "production-cockroachdb",
"host": "cockroach.example.com",
"port": 26257,
"username": "dbuser",
"password": "updatedpassword",
"database": "analytics",
"schema": "public"
}
}'
```
```bash cURL - OpenSearch Example theme={"dark"}
curl --request PUT \
--url https://api.usedatabrain.com/api/v2/datasource \
--header 'Authorization: Bearer dbn_live_abc123...' \
--header 'Content-Type: application/json' \
--data '{
"datasourceType": "opensearch",
"credentials": {
"name": "production-opensearch",
"server_type": "self-managed",
"server_url": "https://opensearch.example.com:9200",
"username": "admin",
"password": "updatedpassword"
}
}'
```
```bash cURL - Elasticsearch Example theme={"dark"}
curl --request PUT \
--url https://api.usedatabrain.com/api/v2/datasource \
--header 'Authorization: Bearer dbn_live_abc123...' \
--header 'Content-Type: application/json' \
--data '{
"datasourceType": "elasticsearch",
"credentials": {
"name": "production-elasticsearch",
"server_type": "elastic-cloud",
"cloud_id": "my-deployment:dXMtZWFzdC0xLmF3cy5mb3VuZC5pbyQ...",
"username": "elastic",
"password": "updatedpassword"
}
}'
```
```bash cURL - Trino Example theme={"dark"}
curl --request PUT \
--url https://api.usedatabrain.com/api/v2/datasource \
--header 'Authorization: Bearer dbn_live_abc123...' \
--header 'Content-Type: application/json' \
--data '{
"datasourceType": "trino",
"credentials": {
"name": "production-trino",
"host": "trino.example.com",
"port": 8080,
"catalog": "hive",
"schema": "analytics",
"username": "trinouser",
"password": "updatedpassword"
}
}'
```
```bash cURL - Update With Tenancy Settings theme={"dark"}
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": "db.example.com",
"port": 5432,
"username": "dbuser",
"password": "newpassword",
"database": "analytics",
"schema": "public"
},
"tenancySettings": {
"tenancyLevel": "TABLE",
"clientColumnType": "STRING",
"schemaName": "public",
"tableName": "clients",
"tableClientNameColumn": "client_name",
"tablePrimaryKeyColumn": "client_id"
}
}'
```
```javascript Node.js theme={"dark"}
const response = await fetch('https://api.usedatabrain.com/api/v2/datasource', {
method: 'PUT',
headers: {
'Authorization': 'Bearer dbn_live_abc123...',
'Content-Type': 'application/json'
},
body: JSON.stringify({
datasourceType: 'postgres',
credentials: {
name: 'production-postgres',
host: 'new-db.example.com',
port: 5432,
username: 'dbuser',
password: 'newpassword',
database: 'analytics',
schema: 'public'
}
})
});
const data = await response.json();
if (data.error) {
console.error('Error:', data.error);
} else {
console.log('Datasource updated:', data.name);
}
```
```python Python theme={"dark"}
import requests
response = requests.put(
'https://api.usedatabrain.com/api/v2/datasource',
headers={
'Authorization': 'Bearer dbn_live_abc123...',
'Content-Type': 'application/json'
},
json={
'datasourceType': 'postgres',
'credentials': {
'name': 'production-postgres',
'host': 'new-db.example.com',
'port': 5432,
'username': 'dbuser',
'password': 'newpassword',
'database': 'analytics',
'schema': 'public'
}
}
)
data = response.json()
if data.get('error'):
print('Error:', data['error'])
else:
print('Datasource updated:', data['name'])
```
```json 200 - Success theme={"dark"}
{
"name": "production-postgres"
}
```
```json 400 - Bad Request theme={"dark"}
{
"error": {
"code": "INVALID_REQUEST_BODY",
"message": "Invalid credentials for postgres: \"host\" is required",
"status": 400
}
}
```
```json 400 - Datasource Not Found theme={"dark"}
{
"error": {
"code": "DATASOURCE_NAME_ERROR",
"message": "Invalid datasource name",
"status": 400
}
}
```
```json 400 - Connection Test Failed theme={"dark"}
{
"error": {
"code": "CREDENTIAL_TEST_FAILED",
"message": "Failed to connect to datasource",
"status": 400
}
}
```
```json 401 - Unauthorized theme={"dark"}
{
"error": {
"code": "AUTHENTICATION_ERROR",
"message": "AUTHENTICATION_ERROR",
"status": 401
}
}
```
```json 500 - Tenancy Settings Failed theme={"dark"}
{
"error": {
"code": "TENANCY_SETTINGS_UPDATE_FAILED",
"message": "Failed to update tenancy settings",
"status": 500
}
}
```
## 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
View all datasources to verify the update
Manually sync the datasource schema if needed
Create a new datasource instead of updating
Remove a datasource you no longer need