How to connect an external database to Wix Studio Two

4 days ago

4 min read

Updated: 2 days ago

The Studio Two editor has no UI for this, so you connect an external database with code or with an app. Both ways need an adapter, a web service you host at a public HTTPS URL, which passes Wix Data requests to your database. Once connected, the database's tables appear as CMS collections.

Status: The sources do not mention a beta or rollout limit. They state that connecting an external database does not require a premium plan.

Before you start

An adapter for your database that implements the External Database service plugin and runs at a public HTTPS URL. At minimum it needs Get Capabilities, List Collections and Query Data Items.
Optional: Wix's open-source adapter velo-external-db, deployed from its default branch and not from adapter-v2, which implements a legacy protocol.
For the app route: a Wix app in Custom Apps that you can install on the site.
Access to the Code tab of the Studio Two site.

Step by step

Choose code or app. Connect with code to give one site access to the database. Connect with an app to reuse the adapter on several sites or let other Wix users install it.
Create the connection with code. In the Code tab, open the Command Palette (Command+Shift+P on macOS, Control+Shift+P on Windows) and select Wix Data: Write Query. In the empty script, call Create External Database Connection with a connection name and the WIX_SERVICE_PLUGIN type. The name becomes the prefix of your collection IDs, can be up to 255 characters and cannot be changed later.
Run the script and save the keys. Click Wix Data: Run Query. Copy publicKey and applicationId from the result.json response. Save publicKey right away, because retrieving the connection later does not return it.
Configure the adapter. Give the adapter publicKey and applicationId. It uses the key to verify each request's signature and checks that the token's aud claim matches applicationId.
Add the adapter URL with code. Replace the script with a call to Update External Database Connection, passing the connection name and the adapter's base URL. An update replaces all settings, so include every setting you want to keep. Run it and wait for connectionStatus.successful to be true.
Or set up an app extension. In Custom Apps, select or create an app. Under Develop > Extensions, create an External Database Provider extension and set a namespace if prompted. In the JSON Editor, set uriConfig.baseUri and namespace, optionally uriConfig.alternativeUris and componentName, then click Save.
Configure the adapter and install the app. Find the app's public key and app ID on the app homepage under More Actions > View ID & keys, and configure the adapter with them. Then go to Distribute > App distribution, click Install on Site, release a version if prompted, select the site and approve the permissions.
Check that the collections appear. In the Code tab, open the Wix Data view with the database icon and click Refresh Collections. The database shows as a group named after its prefix. Expand a collection to see its fields.
Troubleshoot a failed connection. For a code connection, call Get External Database Connection and read connectionStatus.causeOfFailure. For an app connection, call List Data Collections and look for EXTERNAL collections with your namespace, then check the install, base URI, adapter and keys.
Remove the connection if needed. For a code connection, call Delete External Database Connection in a script and run it. For an app connection, uninstall the app from the site. The data in the database is not changed.

Good to know

Collection IDs use the form prefix/collectionId, for example myDatabase/products. Use the full ID in Data API queries.
Add, update and remove only work if the table has _id, _createdDate, _updatedDate and _owner fields. Otherwise the collection is read-only.
Creating collections or changing fields from Wix requires the adapter to report support for collection changes in Get Capabilities.
External collections never trigger data events, and their query results are never cached. They do have CMS data sources, so you can show them on pages and dynamic pages.
Each code connection adds an External Database app to Custom Apps. Deleting the connection does not remove that app. A removed connection cannot be restored.

parnii note

Build and test the adapter against a test database before you connect a live one. Store the publicKey as soon as the first call returns it.

FAQ

Can I connect an external database in the Studio Two editor without code?

No. The Studio Two editor has no UI for it. You connect with a Wix Data script in the Code tab, or with a Wix app that has an External Database Provider extension.

Do I need an adapter to connect an external database to Wix?

Yes. Wix does not connect to the database directly. An adapter you host at a public HTTPS URL implements the External Database service plugin and runs requests against the database.

What if I lose the publicKey of a code connection?

Find it on the homepage of the External Database app in Custom Apps. Click the More Actions icon and select View ID & keys. Retrieving the connection does not return it.