About the External Database Service Plugin

As an external database provider, you can integrate with Wix to allow a Wix sites to access and manage data stored anywhere, as if it were hosted natively on Wix.

The integration is done via an app in the Wix App Market and by implementing the External Database service plugin. After the app is installed on a site, Wix triggers a call to your service whenever the site needs to access and interact with the external database.

Using the service plugin, you can design your app to:

  • Make external business data available to Wix sites.
  • Make an external database available to Wix site owners to store their business data.

Managing data with Wix

Wix offers a variety of data management solutions to accommodate common user needs at different scales. This includes support for internal databases that are hosted directly on Wix, as well as external databases hosted outside the Wix ecosystem.

You can store and manage data directly on Wix using the Wix Data API. Wix also supports managing data hosted on external databases. The External Database Connections API allows Wix Data to communicate with an external database as if it were hosted directly on Wix. Wix offers several out-of-the-box external database integrations for common platforms such as Google Cloud Platform (GCP), Amazon Web Services (AWS), or Microsoft Azure. These integrations translate Wix Data requests into the external database's protocol, and translate the response back into a format that Wix APIs can read.

To allow Wix Data to communicate with any other data source, implement the External Database service plugin.

Terminology

  • Collection: A schema that determines the structure of data items to be stored. The schema defines the fields each item contains and the data type of each field.
  • Item: A single data entry in a collection.
  • External Database: A database hosted by an external service outside of Wix.
  • External Database Service Provider: A 3rd-party service that implements an interface to allow Wix Data to interact with an external database.

Get started

Follow these steps to begin implementing your service plugin.

Choose a framework

You can implement this service plugin with the following frameworks:

Configure your service plugin

To configure and customize your plugin, you need to provide important information in the service plugin configuration file. You can configure your plugin in the Wix Dev Center. For details, see External Database Extension Configuration.

Define handler functions

Use externalDatabase.provideHandlers() to define the following handler functions that implement your custom business logic. Make sure you define all required functions.

FunctionRequired
aggregateDataItems()No
countDataItems()No
createCollection()No
deleteCollection()No
getCapabilities()Yes
insertDataItemReferences()No
insertDataItems()No
listCollections()Yes
queryDataItems()Yes
queryDistinctValues()No
queryReferencedDataItems()No
removeDataItemReferences()No
removeDataItems()No
truncateDataItems()No
updateCollection()No
updateDataItems()No

Code examples

Below is an example for implementing the External Database service plugin in your code.

CLI: Basic code structure

This is the basic code structure for implementing the External Database service plugin with the Wix CLI:

Copy

Self-hosted: Basic code structure

This is the basic code structure for implementing a self-hosted External Database service plugin:

Copy

See also

Did this help?

Extension Config


To configure and customize your service plugin, you need to provide important details in the plugin.json configuration file.

Note

If you created your service plugin extension with the CLI, required fields are automatically populated for you.

Configuration Params
namespacestring

The namespace of the external database. This can be used to access collections within the database, for example namespace/collectionId.


uriConfigSpiBaseUri

The URI where the service provider is deployed.

Did this help?

aggregateDataItems( )


Important: This is a handler function. Implement it only as part of the service plugin.


Runs an aggregation query on the specified data collection and returns the resulting list of items.

Method Declaration
Copy
Method Parameters
payloadAggregateDataItemsEnvelope
Returns
Return Type:AggregateDataItemsResponse | Promise<AggregateDataItemsResponse>
Did this help?

countDataItems( )


Important: This is a handler function. Implement it only as part of the service plugin.


Counts the number of items in the specified data collection that match the filtering preferences.

Method Declaration
Copy
Method Parameters
payloadCountDataItemsEnvelope
Returns
Return Type:CountDataItemsResponse | Promise<CountDataItemsResponse>
Did this help?

createCollection( )


Important: This is a handler function. Implement it only as part of the service plugin.


Creates a new data collection.

Method Declaration
Copy
Method Parameters
payloadCreateCollectionEnvelope
Returns
Return Type:CreateCollectionResponse | Promise<CreateCollectionResponse>
Did this help?

deleteCollection( )


Important: This is a handler function. Implement it only as part of the service plugin.


Deletes a data collection.

Method Declaration
Copy
Method Parameters
payloadDeleteCollectionEnvelope
Returns
Return Type:DeleteCollectionResponse | Promise<DeleteCollectionResponse>
Did this help?

getCapabilities( )


Important: This is a handler function. Implement it only as part of the service plugin.


Lists the global capabilities the external database supports.

Method Declaration
Copy
Method Parameters
payloadGetCapabilitiesEnvelope
Returns
Return Type:GetCapabilitiesResponse | Promise<GetCapabilitiesResponse>
Did this help?

insertDataItemReferences( )


Important: This is a handler function. Implement it only as part of the service plugin.


Inserts one or more item references into a referring field of the specified item.

Method Declaration
Copy
Method Parameters
payloadInsertDataItemReferencesEnvelope
Returns
Return Type:InsertDataItemReferencesResponse | Promise<InsertDataItemReferencesResponse>
Did this help?

insertDataItems( )


Important: This is a handler function. Implement it only as part of the service plugin.


Adds one or more items to a collection.

A data item object contains the _id and _owner fields. The response array must include the same items that were inserted, and each returned item must be added the _createdDate and _updatedDate fields.

However, data items can also be inserted without an _id field. In that case, it is the service provider's responsibility to generate a unique ID for each item.

Method Declaration
Copy
Method Parameters
payloadInsertDataItemsEnvelope
Returns
Return Type:InsertDataItemsResponse | Promise<InsertDataItemsResponse>
Did this help?

listCollections( )


Important: This is a handler function. Implement it only as part of the service plugin.


Retrieves a list of data collections and their details.

When collectionIds is empty, all existing collections are returned. If a specified collection does not exist, that collection can be ignored.

Method Declaration
Copy
Method Parameters
payloadListCollectionsEnvelope
Returns
Return Type:ListCollectionsResponse | Promise<ListCollectionsResponse>
Did this help?

queryDataItems( )


Important: This is a handler function. Implement it only as part of the service plugin.


Retrieves a list of items based on the provided filtering, sorting, and paging preferences.

Method Declaration
Copy
Method Parameters
payloadQueryDataItemsEnvelope
Returns
Return Type:QueryDataItemsResponse | Promise<QueryDataItemsResponse>
Errors
BadRequestWixErrorclass
CollectionAlreadyExistsWixErrorclass
CollectionChangeNotSupportedWixErrorclass
CollectionNotFoundWixErrorclass
ItemAlreadyExistsWixErrorclass
ItemNotFoundWixErrorclass
ReferenceAlreadyExistsWixErrorclass
ReferenceNotFoundWixErrorclass
ValidationWixErrorclass
Did this help?

queryDistinctValues( )


Important: This is a handler function. Implement it only as part of the service plugin.


Retrieves a list of distinct values for a given field for all items that match the query, without duplicates.

As with queryDataItems(), this function retrieves items based on the filtering, sorting, and paging preferences provided. However, this function does not return the full items that match the query. Rather, for items that match the query, it returns all unique values in the field specified in fieldName. If more than one item has the same value in that field, that value appears only once.

Method Declaration
Copy
Method Parameters
payloadQueryDistinctValuesEnvelope
Returns
Return Type:QueryDistinctValuesResponse | Promise<QueryDistinctValuesResponse>
Did this help?

queryReferencedDataItems( )


Important: This is a handler function. Implement it only as part of the service plugin.


Retrieves the items referenced in the specified field of a referring item. Reference fields refer to items that exist in different collections. Implement this function so callers can retrieve the full details of the referenced items.

This service plugin supports item multi-references, which means that data collections can have many-to-many relationships with other collections. For example, consider a scenario where a Movies collection includes a multi-reference Actors field, which might refer to several Actor items in an Actors collection. Users can therefore query the Movies collection to retrieve the Actor items referenced in each Movie item.

Notes:

  • This function does not retrieve the full referenced items of referenced items. For example, the referenced Actors collection might itself contain a multi-reference field with references to Award items in an Awards collection. When calling this function to retrieve the referenced items of any Movie item, the response contains the referenced Actor items, but only the IDs of the Award items. To retrieve the full Award items, the user must either call this function for the Actors collection, or the queryDataItems() function for the Awards collection.
  • This function might also be called when a user calls the isReferenced() function of the Data API.
Method Declaration
Copy
Method Parameters
payloadQueryReferencedDataItemsEnvelope
Returns
Return Type:QueryReferencedDataItemsResponse | Promise<QueryReferencedDataItemsResponse>
Did this help?

removeDataItemReferences( )


Important: This is a handler function. Implement it only as part of the service plugin.


Removes one or more item references from a referring field of the specified item.

Method Declaration
Copy
Method Parameters
payloadRemoveDataItemReferencesEnvelope
Returns
Return Type:RemoveDataItemReferencesResponse | Promise<RemoveDataItemReferencesResponse>
Did this help?

removeDataItems( )


Important: This is a handler function. Implement it only as part of the service plugin.


Removes one or more items from a collection. The response object must contain the removed item.

Method Declaration
Copy
Method Parameters
payloadRemoveDataItemsEnvelope
Returns
Return Type:RemoveDataItemsResponse | Promise<RemoveDataItemsResponse>
Did this help?

truncateDataItems( )


Important: This is a handler function. Implement it only as part of the service plugin.


Removes all items from a collection.

Method Declaration
Copy
Method Parameters
payloadTruncateDataItemsEnvelope
Returns
Return Type:TruncateDataItemsResponse | Promise<TruncateDataItemsResponse>
Did this help?

updateCollection( )


Important: This is a handler function. Implement it only as part of the service plugin.


Updates the structure of an existing data collection.

Some parameters, such as capabilities and pagingMode, are determined by the service provider. If the collection passed in the request contains these parameters, their values must be ignored. However, these fields must be included in the response collection with relevant values.

Method Declaration
Copy
Method Parameters
payloadUpdateCollectionEnvelope
Returns
Return Type:UpdateCollectionResponse | Promise<UpdateCollectionResponse>
Did this help?

updateDataItems( )


Important: This is a handler function. Implement it only as part of the service plugin.


Updates one or more items in a collection. Items must be completely replaced.

The response array must include the same items that were updated, and each returned item must be added the _createdDate and _updatedDate fields.

Method Declaration
Copy
Method Parameters
payloadUpdateDataItemsEnvelope
Returns
Return Type:UpdateDataItemsResponse | Promise<UpdateDataItemsResponse>
Did this help?