About External Databases

An external database is a database that you host outside Wix and connect to a Studio Two site. After you connect it, the database's tables appear in the site's CMS as collections. Site code reads and writes them with the same Data API that it uses for the site's other collections.

Connect an external database when the site's data needs to stay outside Wix, for example because other systems already use it. To decide between the CMS and an external database, and to compare what each supports, see Choose Your Database.

How a connection works

Wix doesn't connect to the database directly. Instead, Wix Data sends each request to an adapter, which is a web service that you host at a public HTTPS URL. The adapter runs the request against the database and returns the result in the format that Wix Data requires.

Each request goes through these stages:

1. Site code or the CMS sends a Data API request for an external collection, such as a query.
2. Wix Data sends the request to the adapter as a signed JSON web token, or JWT. The adapter verifies the signature to confirm that the request comes from Wix.
3. The adapter runs the request against the database.
4. The adapter returns the result to Wix Data, which passes it back to the site code or the CMS.

Adapters

Every external database connection needs an adapter. An adapter implements the External Database service plugin. The service plugin defines the endpoints that Wix Data calls under the adapter's base URL, such as /v3/items/query.

An adapter must implement at least these endpoints:

• Get Capabilities: Reports what the database supports, such as which field types it accepts and whether Wix can create or change its collections.
• List Collections: Lists the collections that the database exposes.
• Query Data Items: Returns the items that match a query.

The other endpoints are optional. Implement the endpoints for the operations that you want the site to support, such as Insert Data Items and Update Data Items.

You can build your own adapter, or deploy Wix's open-source adapter, velo-external-db, which supports several databases, including MySQL and PostgreSQL. Deploy it from its default branch, which implements the External Database service plugin, not from the adapter-v2 branch, which implements a legacy protocol.

Ways to connect

The Studio Two editor has no UI for connecting an external database. Connect one with code or with an app. Both ways use the same kind of adapter:

• Code: Connects one site. Set it up with a script that you run from the Wix Data view in the site's Code tab.
• App: Connects every site that installs the app. Build a Wix app, add an External Database Provider extension in the app's dashboard, and install the app on each site that needs the database.

Connect with code to give one site access to a database. Connect with an app to reuse the same adapter on several sites, or to let other Wix users install it.

External collections

Each collection that the adapter exposes appears on the site with an ID in the form <prefix>/<collectionId>:

• For a connection made with code, the prefix is the connection name. For example, myDatabase/products.
• For a connection made with an app, the prefix is the namespace in the app's External Database Provider extension.

Use the full ID wherever you name the collection, such as in a Data API query.

What the site can do with an external collection depends on the adapter and the database:

• To add, update, and remove items, the database table must have _id, _createdDate, _updatedDate, and _owner fields. Without these fields, the collection is read-only.
• To create collections or change their fields from Wix, the adapter must report support for collection changes in its Get Capabilities response.

Like CMS collections, external collections have CMS Data Sources, so you can display their items on pages and in dynamic pages.

External collections never trigger data events, and their query results are never cached.

Connecting an external database doesn't require a premium plan.

See also

• Connect an External Database
• About the External Database Service Plugin
• About the External Database Connections API