/database/

POST

/database/

Database

Create a new Database.

Request

Body Params application/json

allow_csv_upload

boolean

optional

Allow to upload CSV file data into this databaseIf selected, please set the schemas allowed for csv upload in Extra.

allow_ctas

boolean

optional

Allow CREATE TABLE AS option in SQL Lab

allow_cvas

boolean

optional

Allow CREATE VIEW AS option in SQL Lab

allow_dml

boolean

optional

Allow users to run non-SELECT statements (UPDATE, DELETE, CREATE, ...) in SQL Lab

allow_multi_schema_metadata_fetch

boolean

optional

Allow SQL Lab to fetch a list of all tables and all views across all database schemas. For large data warehouse with thousands of tables, this can be expensive and put strain on the system.

allow_run_async

boolean

optional

Operate the database in asynchronous mode, meaning that the queries are executed on remote workers as opposed to on the web server itself. This assumes that you have a Celery worker setup as well as a results backend. Refer to the installation docs for more information.

cache_timeout

integer <int32> | null

optional

Duration (in seconds) of the caching timeout for charts of this database. A timeout of 0 indicates that the cache never expires. Note this defaults to the global timeout if undefined.

database_name

string

required

A database name to identify this connection.

>= 1 characters<= 250 characters

encrypted_extra

string | null

optional

JSON string containing additional connection configuration.
This is used to provide connection information for systems like Hive, Presto, and BigQuery, which do not conform to the username:password syntax normally used by SQLAlchemy.

expose_in_sqllab

boolean

optional

Expose this database to SQLLab

extra

string

optional

JSON string containing extra configuration elements.
1. The engine_params object gets unpacked into the sqlalchemy.create_engine call, while the metadata_params gets unpacked into the sqlalchemy.MetaData call.
2. The metadata_cache_timeout is a cache timeout setting in seconds for metadata fetch of this database. Specify it as "metadata_cache_timeout": {"schema_cache_timeout": 600, "table_cache_timeout": 600}. If unset, cache will not be enabled for the functionality. A timeout of 0 indicates that the cache never expires.
3. The schemas_allowed_for_csv_upload is a comma separated list of schemas that CSVs are allowed to upload to. Specify it as "schemas_allowed_for_csv_upload": ["public", "csv_upload"]. If database flavor does not support schema or any schema is allowed to be accessed, just leave the list empty
4. the version field is a string specifying the this db's version. This should be used with Presto DBs so that the syntax is correct
5. The allows_virtual_table_explore field is a boolean specifying whether or not the Explore button in SQL Lab results is shown.

force_ctas_schema

string | null

optional

When allowing CREATE TABLE AS option in SQL Lab, this option forces the table to be created in this schema

>= 0 characters<= 250 characters

impersonate_user

boolean

optional

If Presto, all the queries in SQL Lab are going to be executed as the currently logged on user who must have permission to run them.
If Hive and hive.server2.enable.doAs is enabled, will run the queries as service account, but impersonate the currently logged on user via hive.server2.proxy.user property.

server_cert

string | null

optional

Optional CA_BUNDLE contents to validate HTTPS requests. Only available on certain database engines.

sqlalchemy_uri

string

required

Refer to the SqlAlchemy docs for more information on how to structure your URI.

>= 1 characters<= 1024 characters

Example

{
    "allow_csv_upload": true,
    "allow_ctas": true,
    "allow_cvas": true,
    "allow_dml": true,
    "allow_multi_schema_metadata_fetch": true,
    "allow_run_async": true,
    "cache_timeout": 0,
    "database_name": "string",
    "encrypted_extra": "string",
    "expose_in_sqllab": true,
    "extra": "string",
    "force_ctas_schema": "string",
    "impersonate_user": true,
    "server_cert": "string",
    "sqlalchemy_uri": "string"
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST '/database/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "allow_csv_upload": true,
    "allow_ctas": true,
    "allow_cvas": true,
    "allow_dml": true,
    "allow_multi_schema_metadata_fetch": true,
    "allow_run_async": true,
    "cache_timeout": 0,
    "database_name": "string",
    "encrypted_extra": "string",
    "expose_in_sqllab": true,
    "extra": "string",
    "force_ctas_schema": "string",
    "impersonate_user": true,
    "server_cert": "string",
    "sqlalchemy_uri": "string"
}'

Responses

🟢201Created

application/json

Database added

Body

number

optional

result

object (DatabaseRestApi.post)

optional

allow_csv_upload

boolean

optional

Allow to upload CSV file data into this databaseIf selected, please set the schemas allowed for csv upload in Extra.

allow_ctas

boolean

optional

Allow CREATE TABLE AS option in SQL Lab

allow_cvas

boolean

optional

Allow CREATE VIEW AS option in SQL Lab

allow_dml

boolean

optional

Allow users to run non-SELECT statements (UPDATE, DELETE, CREATE, ...) in SQL Lab

allow_multi_schema_metadata_fetch

boolean

optional

Allow SQL Lab to fetch a list of all tables and all views across all database schemas. For large data warehouse with thousands of tables, this can be expensive and put strain on the system.

allow_run_async

boolean

optional

cache_timeout

integer <int32> | null

optional

Duration (in seconds) of the caching timeout for charts of this database. A timeout of 0 indicates that the cache never expires. Note this defaults to the global timeout if undefined.

database_name

string

required

A database name to identify this connection.

>= 1 characters<= 250 characters

encrypted_extra

string | null

optional

expose_in_sqllab

boolean

optional

Expose this database to SQLLab

extra

string

optional

force_ctas_schema

string | null

optional

When allowing CREATE TABLE AS option in SQL Lab, this option forces the table to be created in this schema

>= 0 characters<= 250 characters

impersonate_user

boolean

optional

server_cert

string | null

optional

Optional CA_BUNDLE contents to validate HTTPS requests. Only available on certain database engines.

sqlalchemy_uri

string

required

Refer to the SqlAlchemy docs for more information on how to structure your URI.

>= 1 characters<= 1024 characters

Example

{
    "id": 0,
    "result": {
        "allow_csv_upload": true,
        "allow_ctas": true,
        "allow_cvas": true,
        "allow_dml": true,
        "allow_multi_schema_metadata_fetch": true,
        "allow_run_async": true,
        "cache_timeout": 0,
        "database_name": "string",
        "encrypted_extra": "string",
        "expose_in_sqllab": true,
        "extra": "string",
        "force_ctas_schema": "string",
        "impersonate_user": true,
        "server_cert": "string",
        "sqlalchemy_uri": "string"
    }
}

🔵302302

🟠400Bad Request

🟠401Unauthorized

🟠404Record Not Found

🔴500Server Error

/database/

/database/_info