"use strict";(self.webpackChunkdocs_v_2=self.webpackChunkdocs_v_2||[]).push([[4281],{62571:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>l,contentTitle:()=>i,default:()=>u,frontMatter:()=>a,metadata:()=>s,toc:()=>d});var r=n(83117),o=(n(67294),n(3905));const a={title:"Adding New Drivers in Docker",hide_title:!0,sidebar_position:2,version:1},i=void 0,s={unversionedId:"databases/docker-add-drivers",id:"databases/docker-add-drivers",title:"Adding New Drivers in Docker",description:"Adding New Database Drivers in Docker",source:"@site/docs/databases/docker-add-drivers.mdx",sourceDirName:"databases",slug:"/databases/docker-add-drivers",permalink:"/docs/databases/docker-add-drivers",draft:!1,editUrl:"https://github.com/apache/superset/tree/master/docs/docs/databases/docker-add-drivers.mdx",tags:[],version:"current",sidebarPosition:2,frontMatter:{title:"Adding New Drivers in Docker",hide_title:!0,sidebar_position:2,version:1},sidebar:"tutorialSidebar",previous:{title:"Installing Database Drivers",permalink:"/docs/databases/installing-database-drivers"},next:{title:"Using Database Connection UI",permalink:"/docs/databases/db-connection-ui"}},l={},d=[{value:"Adding New Database Drivers in Docker",id:"adding-new-database-drivers-in-docker",level:2},{value:"1. Determine the driver you need",id:"1-determine-the-driver-you-need",level:3},{value:"2. Install the driver in the container",id:"2-install-the-driver-in-the-container",level:3},{value:"3. Connect to MySQL",id:"3-connect-to-mysql",level:3},{value:"4. Troubleshooting",id:"4-troubleshooting",level:3}],c={toc:d},p="wrapper";function u(e){let{components:t,...n}=e;return(0,o.kt)(p,(0,r.Z)({},c,n,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("h2",{id:"adding-new-database-drivers-in-docker"},"Adding New Database Drivers in Docker"),(0,o.kt)("p",null,"Superset requires a Python database driver to be installed for each additional type of database you want to connect to."),(0,o.kt)("p",null,"In this example, we'll walk through how to install the MySQL connector library. The connector library installation process is the same for all additional libraries."),(0,o.kt)("h3",{id:"1-determine-the-driver-you-need"},"1. Determine the driver you need"),(0,o.kt)("p",null,"Consult the ",(0,o.kt)("a",{parentName:"p",href:"/docs/databases/installing-database-drivers"},"list of database drivers")," and find the PyPI package needed to connect to your database. In this example, we're connecting to a MySQL database, so we'll need the ",(0,o.kt)("inlineCode",{parentName:"p"},"mysqlclient")," connector library."),(0,o.kt)("h3",{id:"2-install-the-driver-in-the-container"},"2. Install the driver in the container"),(0,o.kt)("p",null,"We need to get the ",(0,o.kt)("inlineCode",{parentName:"p"},"mysqlclient")," library installed into the Superset docker container (it doesn't matter if it's installed on the host machine). We could enter the running container with ",(0,o.kt)("inlineCode",{parentName:"p"},"docker exec -it <container_name> bash")," and run ",(0,o.kt)("inlineCode",{parentName:"p"},"pip install mysqlclient")," there, but that wouldn't persist permanently."),(0,o.kt)("p",null,"To address this, the Superset ",(0,o.kt)("inlineCode",{parentName:"p"},"docker compose")," deployment uses the convention of a ",(0,o.kt)("inlineCode",{parentName:"p"},"requirements-local.txt")," file. All packages listed in this file will be installed into the container from PyPI at runtime. This file will be ignored by Git for the purposes of local development."),(0,o.kt)("p",null,"Create the file ",(0,o.kt)("inlineCode",{parentName:"p"},"requirements-local.txt")," in a subdirectory called ",(0,o.kt)("inlineCode",{parentName:"p"},"docker")," that exists in the directory with your ",(0,o.kt)("inlineCode",{parentName:"p"},"docker-compose.yml")," or ",(0,o.kt)("inlineCode",{parentName:"p"},"docker-compose-non-dev.yml")," file."),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},"# Run from the repo root:\ntouch ./docker/requirements-local.txt\n")),(0,o.kt)("p",null,"Add the driver identified in step above.  You can use a text editor or do it from the command line like:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},'echo "mysqlclient" >> ./docker/requirements-local.txt\n')),(0,o.kt)("p",null,(0,o.kt)("strong",{parentName:"p"},"If you are running a stock (non-customized) Superset image"),", you are done.  Launch Superset with ",(0,o.kt)("inlineCode",{parentName:"p"},"docker compose -f docker-compose-non-dev.yml up")," and the driver should be present."),(0,o.kt)("p",null,"You can check its presence by entering the running container with ",(0,o.kt)("inlineCode",{parentName:"p"},"docker exec -it <container_name> bash")," and running ",(0,o.kt)("inlineCode",{parentName:"p"},"pip freeze"),".  The PyPI package should be present in the printed list."),(0,o.kt)("p",null,(0,o.kt)("strong",{parentName:"p"},"If you're running a customized docker image"),", rebuild your local image with the new driver baked in:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},"docker compose build --force-rm\n")),(0,o.kt)("p",null,"After the rebuild of the Docker images is complete, relaunch Superset by running ",(0,o.kt)("inlineCode",{parentName:"p"},"docker compose up"),"."),(0,o.kt)("h3",{id:"3-connect-to-mysql"},"3. Connect to MySQL"),(0,o.kt)("p",null,"Now that you've got a MySQL driver installed in your container, you should be able to connect to your database via the Superset web UI."),(0,o.kt)("p",null,"As an admin user, go to Settings -> Data: Database Connections and click the +DATABASE button. From there, follow the steps on the ",(0,o.kt)("a",{parentName:"p",href:"/docs/databases/db-connection-ui"},"Using Database Connection UI page"),"."),(0,o.kt)("p",null,"Consult the page for your specific database type in the Superset documentation to determine the connection string and any other parameters you need to input.  For instance, on the ",(0,o.kt)("a",{parentName:"p",href:"/docs/databases/mysql"},"MySQL page"),", we see that the connection string to a local MySQL database differs depending on whether the setup is running on Linux or Mac."),(0,o.kt)("p",null,'Click the \u201cTest Connection\u201d button, which should result in a popup message saying, "Connection looks good!".'),(0,o.kt)("h3",{id:"4-troubleshooting"},"4. Troubleshooting"),(0,o.kt)("p",null,"If the test fails, review your docker logs for error messages.  Superset uses SQLAlchemy to connect to databases; to troubleshoot the connection string for your database, you might start Python in the Superset application container or host environment and try to connect directly to the desired database and fetch data. This eliminates Superset for the purposes of isolating the problem."),(0,o.kt)("p",null,"Repeat this process for each different type of database you want Superset to be able to connect to."))}u.isMDXComponent=!0},3905:(e,t,n)=>{n.d(t,{Zo:()=>c,kt:()=>m});var r=n(67294);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);t&&(r=r.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,r)}return n}function i(e){for(var t=1;t<arguments.length;t++){var n=null!=arguments[t]?arguments[t]:{};t%2?a(Object(n),!0).forEach((function(t){o(e,t,n[t])})):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(n)):a(Object(n)).forEach((function(t){Object.defineProperty(e,t,Object.getOwnPropertyDescriptor(n,t))}))}return e}function s(e,t){if(null==e)return{};var n,r,o=function(e,t){if(null==e)return{};var n,r,o={},a=Object.keys(e);for(r=0;r<a.length;r++)n=a[r],t.indexOf(n)>=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r<a.length;r++)n=a[r],t.indexOf(n)>=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var l=r.createContext({}),d=function(e){var t=r.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):i(i({},t),e)),n},c=function(e){var t=d(e.components);return r.createElement(l.Provider,{value:t},e.children)},p="mdxType",u={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},h=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,a=e.originalType,l=e.parentName,c=s(e,["components","mdxType","originalType","parentName"]),p=d(n),h=o,m=p["".concat(l,".").concat(h)]||p[h]||u[h]||a;return n?r.createElement(m,i(i({ref:t},c),{},{components:n})):r.createElement(m,i({ref:t},c))}));function m(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=n.length,i=new Array(a);i[0]=h;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s[p]="string"==typeof e?e:o,i[1]=s;for(var d=2;d<a;d++)i[d]=n[d];return r.createElement.apply(null,i)}return r.createElement.apply(null,n)}h.displayName="MDXCreateElement"}}]);