> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt ## Resource: Connect an External Database ## Article: Connect an External Database ## Article Link: https://dev.wix.com/docs/studio-two/code-your-site/work-with-data/external-databases/connect-an-external-database.md ## Article Content: # Connect an External Database Connect an [external database](https://dev.wix.com/docs/studio-two/code-your-site/work-with-data/external-databases/about-external-databases.md) to a Studio Two site so the site can work with the database's tables as CMS collections. You can connect with code for one site, or by building a [Wix app](https://dev.wix.com/docs/build-apps/get-started/overview/about-wix-apps.md) with an External Database Provider extension and installing it on each site that needs the database. Both ways need an [adapter](https://dev.wix.com/docs/studio-two/code-your-site/work-with-data/external-databases/about-external-databases.md#adapters) for the database, running at a public HTTPS URL. ## Connect with code A connection made with code takes two calls to the [External Database Connections API](https://dev.wix.com/docs/api-reference/business-solutions/cms/external-databases/external-database-connection/introduction?apiView=SDK.md). The first call creates the connection and returns the values that the adapter needs to verify requests from Wix. After you configure the adapter with those values, the second call gives Wix the adapter's URL. Run both calls in a Wix Data script in the Code tab. Wix Data scripts can call the External Database Connections API without importing it. To connect with code: 1. In the Studio Two editor, open the **Code** tab. 2. To open the Command Palette, press `Command+Shift+P` on macOS or `Control+Shift+P` on Windows. 3. Select **Wix Data: Write Query**. An empty script opens. 4. In the script, call [Create External Database Connection](https://dev.wix.com/docs/api-reference/business-solutions/cms/external-databases/external-database-connection/create-external-database-connection?apiView=SDK.md) with a name for the connection and the `WIX_SERVICE_PLUGIN` connection type: ```js externalDatabaseConnections.createExternalDatabaseConnection( { name: 'myDatabase' }, 'WIX_SERVICE_PLUGIN' ) ``` The name becomes the prefix of the database's collection IDs, such as `myDatabase/products`. It can be up to 255 characters, and you can't change it later. 5. To run the script, click the play icon, **Wix Data: Run Query**, at the top right of the script tab. The response opens in a `result.json` tab: ```json { "name": "myDatabase", "connectionStatus": { "successful": false, "causeOfFailure": "NONE", "hasCollections": "UNKNOWN" }, "protocolVersion": "V3", "publicKey": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----", "applicationId": "" } ``` `connectionStatus.successful` stays `false` until you add the adapter's URL. 6. Copy `publicKey` and `applicationId` from the response, and configure your adapter with them. The adapter uses `publicKey` to verify each request's signature, and checks that the token's `aud` claim matches `applicationId`. For the full list of checks, see [Validating request signatures](https://dev.wix.com/docs/build-apps/develop-your-app/develop-a-self-managed-app/supported-extensions/backend-extensions/service-plugins/add-self-managed-service-plugin-extensions-with-rest.md#validating-request-signatures).
__Important:__ Save `publicKey` now. Retrieving the connection later doesn't return it.
7. Replace the script's code with a call to [Update External Database Connection](https://dev.wix.com/docs/api-reference/business-solutions/cms/external-databases/external-database-connection/update-external-database-connection?apiView=SDK.md). Pass the connection name and the adapter's base URL: ```js externalDatabaseConnections.updateExternalDatabaseConnection('myDatabase', { endpoint: 'https://my-adapter.example.com' }) ``` An update replaces all of the connection's settings with the ones you pass. Include every setting that you want to keep. 8. Run the script. When the response shows `connectionStatus.successful` as `true`, the site can use the database's collections. To see them, [check the connection](#check-the-connection). > **Note:** For each connection that you make with code, Wix adds an app called External Database to Custom Apps in your Wix account. The app holds the connection's adapter URL. Deleting the connection doesn't remove the app. If you lose the connection's `publicKey`, find it on the app's homepage. Click the **More Actions** icon and select **View ID & keys**. ## Connect with an app A connection made with an app uses an External Database Provider extension. You set up the extension in the app's dashboard, outside the Studio Two editor. When a site installs the app, Wix connects the site to the adapter. To connect with an app: 1. Go to **[Custom Apps](https://manage.wix.com/account/custom-apps)** and select an app, or click **Create New App**. 2. In the app's dashboard, go to **Develop > Extensions** and click **Create Extension**. 3. Search for **External Database Provider**. On the **External Database Provider** card, click **Create**. ![The extension picker in the app dashboard, filtered to the External Database Provider extension](https://wixmp-833713b177cebf373f611808.wixmp.com/images/dea41cf4ca7849c6532db850e1454433.png) 4. If the app doesn't have a namespace, the **Set a namespace for your app** dialog opens. Enter a namespace and click **Set Namespace**. The namespace identifies the app, and you can't change it later. 5. In the **JSON Editor**, configure the extension: ```json { "uriConfig": { "baseUri": "https://my-adapter.example.com" }, "namespace": "@my-account/my-app", "componentName": "myExternalDatabase" } ``` The configuration has these properties: - `uriConfig.baseUri`: Required. The adapter's base URL. Wix Data adds each endpoint's path to it, such as `/v3/items/query`. - `uriConfig.alternativeUris`: Optional. A list of full URLs for individual endpoints that don't use the base URL. Each item has a `methodName` and an `absoluteUri`. - `namespace`: Required. It becomes the prefix of the database's collection IDs. For a private app, you can choose any namespace. For a public app, it must match the app's namespace. - `componentName`: Optional. A name for the extension that appears in the app's dashboard. For details, see the [External Database service plugin](https://dev.wix.com/docs/api-reference/business-solutions/cms/external-databases/external-database-service-plugin/introduction.md) reference. 6. Click **Save**. 7. Configure your adapter to verify requests from Wix with the app's public key and app ID. To find them, go to the app's homepage in the app dashboard, click the **More Actions** icon, and select **View ID & keys**. For the full list of checks, see [Validating request signatures](https://dev.wix.com/docs/build-apps/develop-your-app/develop-a-self-managed-app/supported-extensions/backend-extensions/service-plugins/add-self-managed-service-plugin-extensions-with-rest.md#validating-request-signatures). 8. Install the app on the site: 1. Go to **Distribute > App distribution**. 2. Under **Install app on a site**, click **Install on Site**. If the app doesn't have a released version, release one when prompted. 3. Select the site and approve the app's permissions. ## Check the connection After you connect, check that the database's collections appear on the site. To check the connection: 1. In the Studio Two editor, open the **Code** tab. 2. In the row of icons at the top of the sidebar, click the database icon to open the **Wix Data** view. ![The top of the Code tab's sidebar, with the Wix Data icon highlighted and the Wix Data view open](https://wixmp-833713b177cebf373f611808.wixmp.com/images/983b41f68c3cda4c4e10eb8deb25d301.png) 3. Click **Refresh Collections**. The database appears as a group named after its prefix, with its collections inside. ![The Wix Data view, showing an external database group that contains a Notes collection and its fields](https://wixmp-833713b177cebf373f611808.wixmp.com/images/fbecee0d885cee4211928674a2efb8ca.png) 4. To see a collection's fields, expand the collection. If the database doesn't appear, check the connection's status. ### Check the status of a connection made with code In a Wix Data script, call [Get External Database Connection](https://dev.wix.com/docs/api-reference/business-solutions/cms/external-databases/external-database-connection/get-external-database-connection?apiView=SDK.md) with the connection name, and run the script: ```js externalDatabaseConnections.getExternalDatabaseConnection('myDatabase') ``` In the response, `connectionStatus.causeOfFailure` shows why the connection failed: - `COMMUNICATION_FAILURE`: Wix reached the adapter but couldn't communicate with it. Check that the adapter implements the External Database service plugin endpoints at the base URL. - `DESTINATION_HOST_UNREACHABLE`: Wix couldn't reach the adapter's host. Check the URL and that the adapter is running. - `UNAUTHORIZED`: The adapter rejected the request. Check the adapter's request verification settings. - `DESTINATION_ENDPOINT_NOT_DEFINED`: The connection has no adapter URL. Update the connection with the `endpoint`. `connectionStatus.hasCollections` shows `NO` when the adapter responded but exposes no collections. ### Check the status of a connection made with an app Call [List Data Collections](https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/data-collections/list-data-collections?apiView=SDK.md) and look for `EXTERNAL`-type collections whose ID starts with the connection's namespace. If they're missing, the connection isn't working, though this method doesn't report why. To investigate: - Check that the app is installed on the site, under **Distribute > App distribution**. - Check that `uriConfig.baseUri` in the extension's configuration is set and correct. - Check that the adapter is running and reachable at that URL. - Check that the adapter implements the External Database service plugin endpoints at the base URL. - Confirm the adapter is configured with the app's correct `publicKey` and `applicationId`, found under **View ID & keys** on the app's homepage, so it can verify requests from Wix. - Check the adapter's own logs to see whether Wix is reaching it, and what it returns. ## Remove a connection Removing a connection removes the database's collections from the site. It doesn't change the data in the database.
__Caution:__ You can't restore a removed connection. To connect the database again, create a new connection. Site code that refers to the database's collections stops working.
### Remove a connection made with code Call [Delete External Database Connection](https://dev.wix.com/docs/api-reference/business-solutions/cms/external-databases/external-database-connection/delete-external-database-connection?apiView=SDK.md) in a Wix Data script, and run the script: ```js externalDatabaseConnections.deleteExternalDatabaseConnection('myDatabase') ``` The `result.json` tab doesn't update after a deletion. To confirm that the connection is gone, click **Refresh Collections** in the **Wix Data** view. ### Remove a connection made with an app Uninstall the app from the site. Uninstalling the app removes its collections from the site. ## See also - [About External Databases](https://dev.wix.com/docs/studio-two/code-your-site/work-with-data/external-databases/about-external-databases.md) - [About the Code Tab](https://dev.wix.com/docs/studio-two/get-started/about-the-code-tab.md) - [About the External Database Connections API](https://dev.wix.com/docs/api-reference/business-solutions/cms/external-databases/external-database-connection/introduction?apiView=SDK.md) - [About the External Database Service Plugin](https://dev.wix.com/docs/api-reference/business-solutions/cms/external-databases/external-database-service-plugin/introduction.md)