| {"version":3,"sources":["webpack:///./src/pages/docs/Connecting to Databases/ui.mdx"],"names":["_frontmatter","layoutProps","MDXLayout","DefaultLayout","MDXContent","components","props","mdxType","alt","src","parentName","isMDXComponent"],"mappings":"0PAQaA,G,UAAe,S,+NAC5B,IAAMC,EAAc,CAClBD,gBAEIE,EAAYC,IACH,SAASC,EAAT,GAGZ,IAFDC,EAEC,EAFDA,WACGC,EACF,8BACD,OAAO,YAACJ,EAAD,eAAeD,EAAiBK,EAAhC,CAAuCD,WAAYA,EAAYE,QAAQ,cAG5E,sMACA,qBAAG,mBAAKC,IAAI,eAAeC,IAAI,2GAC/B,2FACA,sIAAqH,0BAAYC,WAAW,KAAvB,cAArH,6HACA,wfACA,6KACA,sJACA,iBAAQ,CACN,GAAM,yDADR,yDAGA,4HACA,uBAAK,gCAAMA,WAAW,OAAU,CAC5B,UAAa,oBADZ,2VAaL,6GACA,iBAAQ,CACN,GAAM,kBADR,kBAGA,sBACE,kBAAIA,WAAW,MAAf,qFAA0G,0BAAYA,WAAW,MAAvB,qBAA1G,qIAEF,uBAAK,gCAAMA,WAAW,OAAU,CAC5B,UAAa,oBADZ,sJAOL,iBAAQ,CACN,GAAM,yDADR,yDAGA,kFACA,sBACE,kBAAIA,WAAW,MAAf,YACA,kBAAIA,WAAW,MAAf,YACA,kBAAIA,WAAW,MAAf,SACA,kBAAIA,WAAW,MAAf,aAEF,gSACA,sBACE,kBAAIA,WAAW,MAAK,0BAAYA,WAAW,MAAvB,qBAApB,qJAAwO,6BAAGA,WAAW,MAAS,CAC3P,KAAQ,kIAD4N,OAAxO,MAGA,kBAAIA,WAAW,MAAK,0BAAYA,WAAW,MAAvB,kBAApB,mMACA,kBAAIA,WAAW,MAAK,0BAAYA,WAAW,MAAvB,8BAApB,8EACA,kBAAIA,WAAW,MAAK,0BAAYA,WAAW,MAAvB,yBAApB,2GAAkM,0BAAYA,WAAW,MAAvB,0BAAlM,MAEF,4FACA,sBACE,kBAAIA,WAAW,MAAK,0BAAYA,WAAW,MAAvB,0DAApB,gFACA,kBAAIA,WAAW,MAAK,0BAAYA,WAAW,MAAvB,sDAApB,gFACA,kBAAIA,WAAW,MAAK,0BAAYA,WAAW,MAAvB,wCAApB,6BAAmI,0BAAYA,WAAW,MAAvB,UAAnI,uDAA8O,0BAAYA,WAAW,MAAvB,iBAA9O,4FAAqY,6BAAGA,WAAW,MAAS,CACxZ,KAAQ,4HADyX,WAArY,OAIF,8FAA6E,0BAAYA,WAAW,KAAvB,kDAA7E,kCAA0M,0BAAYA,WAAW,KAAvB,wBAA1M,+DAA0U,0BAAYA,WAAW,KAAvB,qBAA1U,sCACA,iK,6NAKJN,EAAWO,gBAAiB","file":"component---src-pages-docs-connecting-to-databases-ui-mdx-de24fce0dfa9063cc9fc.js","sourcesContent":["import * as React from 'react'\n /* @jsx mdx */\nimport { mdx } from '@mdx-js/react';\n/* @jsxRuntime classic */\n\n/* @jsx mdx */\n\nimport DefaultLayout from \"/home/runner/work/superset/superset/docs/node_modules/gatsby-theme-docz/src/base/Layout.js\";\nexport const _frontmatter = {};\nconst layoutProps = {\n _frontmatter\n};\nconst MDXLayout = DefaultLayout;\nexport default function MDXContent({\n components,\n ...props\n}) {\n return <MDXLayout {...layoutProps} {...props} components={components} mdxType=\"MDXLayout\">\n\n\n <p>{`Here is the documentation on how to leverage the new DB Connection UI. This will provide admins the ability to enhance the UX for users who want to connect to new databases.`}</p>\n <p><img alt=\"db-conn-docs\" src=\"https://user-images.githubusercontent.com/27827808/125499607-94e300aa-1c0f-4c60-b199-3f9de41060a3.gif\" /></p>\n <p>{`There are now 3 steps when connecting to a database in the new UI:`}</p>\n <p>{`Step 1: First the admin must inform superset what engine they want to connect to. This page is powered by the `}<inlineCode parentName=\"p\">{`/available`}</inlineCode>{` endpoint which pulls on the engines currently installed in your environment, so that only supported databases are shown.`}</p>\n <p>{`Step 2: Next, the admin is prompted to enter database specific parameters. Depending on whether there is a dynamic form available for that specific engine, the admin will either see the new custom form or the legacy SQLAlchemy form. We currently have built dynamic forms for (Redshift, MySQL, Postgres, and BigQuery). The new form prompts the user for the parameters needed to connect (for example, username, password, host, port, etc.) and provides immediate feedback on errors.`}</p>\n <p>{`Step 3: Finally, once the admin has connected to their DB using the dynamic form they have the opportunity to update any optional advanced settings.`}</p>\n <p>{`We hope this feature will help eliminate a huge bottleneck for users to get into the application and start crafting datasets.`}</p>\n <h3 {...{\n \"id\": \"how-to-setup-up-preferred-database-options-and-images\"\n }}>{`How to setup up preferred database options and images`}</h3>\n <p>{`We added a new configuration option where the admin can define their preferred databases, in order:`}</p>\n <pre><code parentName=\"pre\" {...{\n \"className\": \"language-python\"\n }}>{`# A list of preferred databases, in order. These databases will be\n# displayed prominently in the \"Add Database\" dialog. You should\n# use the \"engine_name\" attribute of the corresponding DB engine spec\n# in \\`superset/db_engine_specs/\\`.\nPREFERRED_DATABASES: List[str] = [\n \"PostgreSQL\",\n \"Presto\",\n \"MySQL\",\n \"SQLite\",\n]\n`}</code></pre>\n <p>{`For copyright reasons the logos for each database are not distributed with Superset.`}</p>\n <h3 {...{\n \"id\": \"setting-images\"\n }}>{`Setting images`}</h3>\n <ul>\n <li parentName=\"ul\">{`To set the images of your preferred database, admins must create a mapping in the `}<inlineCode parentName=\"li\">{`superset_text.yml`}</inlineCode>{` file with engine and location of the image. The image can be host locally inside your static/file directory or online (e.g. S3)`}</li>\n </ul>\n <pre><code parentName=\"pre\" {...{\n \"className\": \"language-python\"\n }}>{`DB_IMAGES:\n postgresql: \"path/to/image/postgres.jpg\"\n bigquery: \"path/to/s3bucket/bigquery.jpg\"\n snowflake: \"path/to/image/snowflake.jpg\"\n`}</code></pre>\n <h3 {...{\n \"id\": \"how-to-add-new-database-engines-to-available-endpoint\"\n }}>{`How to add new database engines to available endpoint`}</h3>\n <p>{`Currently the new modal supports the following databases:`}</p>\n <ul>\n <li parentName=\"ul\">{`Postgres`}</li>\n <li parentName=\"ul\">{`Redshift`}</li>\n <li parentName=\"ul\">{`MySQL`}</li>\n <li parentName=\"ul\">{`BigQuery`}</li>\n </ul>\n <p>{`When the user selects a database not in this list they will see the old dialog asking for the SQLAlchemy URI. New databases can be added gradually to the new flow. In order to support the rich configuration a DB engine spec needs to have the following attributes:`}</p>\n <ol>\n <li parentName=\"ol\"><inlineCode parentName=\"li\">{`parameters_schema`}</inlineCode>{`: a Marshmallow schema defining the parameters needed to configure the database. For Postgres this includes username, password, host, port, etc. (`}<a parentName=\"li\" {...{\n \"href\": \"https://github.com/apache/superset/blob/accee507c0819cd0d7bcfb5a3e1199bc81eeebf2/superset/db_engine_specs/base.py#L1309-L1320\"\n }}>{`see`}</a>{`).`}</li>\n <li parentName=\"ol\"><inlineCode parentName=\"li\">{`default_driver`}</inlineCode>{`: the name of the recommended driver for the DB engine spec. Many SQLAlchemy dialects support multiple drivers, but usually one is the official recommendation. For Postgres we use \"psycopg2\".`}</li>\n <li parentName=\"ol\"><inlineCode parentName=\"li\">{`sqlalchemy_uri_placeholder`}</inlineCode>{`: a string that helps the user in case they want to type the URI directly.`}</li>\n <li parentName=\"ol\"><inlineCode parentName=\"li\">{`encryption_parameters`}</inlineCode>{`: parameters used to build the URI when the user opts for an encrypted connection. For Postgres this is `}<inlineCode parentName=\"li\">{`{\"sslmode\": \"require\"}`}</inlineCode>{`.`}</li>\n </ol>\n <p>{`In addition, the DB engine spec must implement these class methods:`}</p>\n <ul>\n <li parentName=\"ul\"><inlineCode parentName=\"li\">{`build_sqlalchemy_uri(cls, parameters, encrypted_extra)`}</inlineCode>{`: this method receives the distinct parameters and builds the URI from them.`}</li>\n <li parentName=\"ul\"><inlineCode parentName=\"li\">{`get_parameters_from_uri(cls, uri, encrypted_extra)`}</inlineCode>{`: this method does the opposite, extracting the parameters from a given URI.`}</li>\n <li parentName=\"ul\"><inlineCode parentName=\"li\">{`validate_parameters(cls, parameters)`}</inlineCode>{`: this method is used for `}<inlineCode parentName=\"li\">{`onBlur`}</inlineCode>{` validation of the form. It should return a list of `}<inlineCode parentName=\"li\">{`SupersetError`}</inlineCode>{` indicating which parameters are missing, and which parameters are definitely incorrect (`}<a parentName=\"li\" {...{\n \"href\": \"https://github.com/apache/superset/blob/accee507c0819cd0d7bcfb5a3e1199bc81eeebf2/superset/db_engine_specs/base.py#L1404\"\n }}>{`example`}</a>{`).`}</li>\n </ul>\n <p>{`For databases like MySQL and Postgres that use the standard format of `}<inlineCode parentName=\"p\">{`engine+driver://user:password@host:port/dbname`}</inlineCode>{` all you need to do is add the `}<inlineCode parentName=\"p\">{`BasicParametersMixin`}</inlineCode>{` to the DB engine spec, and then define the parameters 2-4 (`}<inlineCode parentName=\"p\">{`parameters_schema`}</inlineCode>{` is already present in the mixin).`}</p>\n <p>{`For other databases you need to implement these methods yourself. The BigQuery DB engine spec is a good example of how to do that.`}</p>\n\n </MDXLayout>;\n}\n;\nMDXContent.isMDXComponent = true;\n "],"sourceRoot":""} |