Go Headless

Build Apps

Client

API Preview

Ricos

Develop Websites

REST

Velo

GraphQL (Alpha)

externalDatabaseConnection

ExternalDatabaseConnection

Options for creating an external database connection.

options

CreateExternalDatabaseConnectionOptions

Creates a new external database connection.

The `externalDatabaseConnection` parameter must include a `name`, `endpoint`, and `configuration` details for the external database.
If any of these are missing, the external database connection isn't created.

import { externalDatabaseConnections } from "wix-data.v2";
import { elevate } from "wix-auth";

const elevatedCreateExternalDbConnection = elevate(externalDatabaseConnections.createExternalDatabaseConnection);

/* Sample externalDatabaseConnection object:
 *  
 * {
 *   capabilities: {
 *     collectionModificationsSupported: false,
 *     fieldTypes: []
 *   },
 *   configuration: {
 *     secretKey: '74dbd6d6-ec5b-4668-8229-c77379bc6431'
 *   },
 *   endpoint: 'https://example.com/my-external-database',
 *   name: 'connectionOne'
 * }
 */


export async function myCreateExternalDbConnectionFunction(newExternalDatabaseConnection) {
  try {
    const createExternalDbConnectionResponse = await elevatedCreateExternalDbConnection(newExternalDatabaseConnection);
    
    const dbConnectionStatus = createExternalDbConnectionResponse.connectionStatus; 
    const dbCapabilities = createExternalDbConnectionResponse.capabilities; 
    
    console.log('Successfully created an external database connection. Full response:', createExternalDbConnectionResponse);
    
    return createExternalDbConnectionResponse; 
  } catch (error) {
    console.error(error);
    // Handle the error
  }
}

/* Promise resolves to:
 * 
 * {
 *   "capabilities": {
 *     "collectionModificationsSupported": false,
 *     "fieldTypes": []
 *   }
 *   "configuration": {
 *     "secretKey": "74dbd6d6-ec5b-4668-8229-c77379bc6431"
 *   },
 *   "connectionStatus": {
 *     "causeOfFailure": "NONE",
 *     "hasCollections": "YES"
 *     "successful": true,
 *   },
 *   "endpoint": "https://example.com/my-external-database",
 *   "name": "connectionOne",
 *   "protocolVersion": "V2",
 * }
 */

Create an external database connection (dashboard page code) 

import { Permissions, webMethod } from "wix-web-module";
import { externalDatabaseConnections } from "wix-data.v2";
import { elevate } from "wix-auth";

const elevatedCreateExternalDbConnection = elevate(externalDatabaseConnections.createExternalDatabaseConnection);

/* Sample externalDatabaseConnection object:
 *  
 * {
 *   capabilities: {
 *     collectionModificationsSupported: false,
 *     fieldTypes: []
 *   },
 *   configuration: {
 *     secretKey: '74dbd6d6-ec5b-4668-8229-c77379bc6431'
 *   },
 *   endpoint: 'https://example.com/my-external-database',
 *   name: 'connectionOne'
 * }
 */

export const myCreateExternalDbConnectionFunction = webMethod (
  Permissions.Admin, 
  async (newExternalDatabaseConnection) => {
    try {
      const createExternalDbConnectionResponse = await elevatedCreateExternalDbConnection(newExternalDatabaseConnection);

      const dbConnectionStatus = createExternalDbConnectionResponse.connectionStatus; 
      const dbCapabilities = createExternalDbConnectionResponse.capabilities; 

      console.log('Successfully created an external database connection. Full response:', createExternalDbConnectionResponse);

      return createExternalDbConnectionResponse; 
    } catch (error) {
      console.error(error);
      // Handle the error
    }
  }
)

/* Promise resolves to:
 * 
 * {
 *   "capabilities": {
 *     "collectionModificationsSupported": false,
 *     "fieldTypes": []
 *   }
 *   "configuration": {
 *     "secretKey": "74dbd6d6-ec5b-4668-8229-c77379bc6431"
 *   },
 *   "connectionStatus": {
 *     "causeOfFailure": "NONE",
 *     "hasCollections": "YES"
 *     "successful": true,
 *   },
 *   "endpoint": "https://example.com/my-external-database",
 *   "name": "connectionOne",
 *   "protocolVersion": "V2",
 * }
 */

Create an external database connection (export from backend code) 

createExternalDatabaseConnection

Details of external database connection created.

Name of the external database connection to delete.

name

string

Deletes an external database connection.

> **Note:** Once an external database connection is deleted, it can't be restored. To reconnect the database you need to create a new external database connection.

import { externalDatabaseConnections } from "wix-data.v2";
import { elevate } from "wix-auth";

const elevatedDeleteExternalDbConnection = elevate(externalDatabaseConnections.deleteExternalDatabaseConnection);

/* 
 * Sample name value: 'ConnectionOne'
 */

export async function myDeleteExternalDbConnection (name) {
  try {
    await elevatedDeleteExternalDbConnection(name);

    return;
  } catch (error) {
    console.error(error);
    // Handle the error
  }        
}

/* Promise resolves to void */

Delete an external database connection (dashboard page code)

import { Permissions, webMethod } from "wix-web-module";
import { externalDatabaseConnections } from "wix-data.v2";
import { elevate } from "wix-auth";

const elevatedDeleteExternalDbConnection = elevate(externalDatabaseConnections.deleteExternalDatabaseConnection);

/* 
 * Sample name value: 'ConnectionOne'
 */

export const myDeleteExternalDbConnection = webMethod(
  Permissions.Admin,
  async (name) => {
    try {
      await elevatedDeleteExternalDbConnection(name);

      return;
    } catch (error) {
      console.error(error);
      // Handle the error
    }        
  }
)

/* Promise resolves to void */

Delete an external database connection (export from backend code) 

deleteExternalDatabaseConnection

void

Name of the external database connection to retrieve.

Retrieves an external database connection by name.

import { externalDatabaseConnections } from "wix-data.v2";
import { elevate } from "wix-auth";

const elevatedGetExternalDbConnection = elevate(externalDatabaseConnections.getExternalDatabaseConnection);

/* 
 * Sample name value: 'ConnectionOne'
 */

export async function myGetExternalDbConnection (name) {
  try {
    const getExternalDbConnectionResponse = await elevatedGetExternalDbConnection(name);

    const connectionSuccessful = getExternalDbConnectionResponse.connectionStatus.successful; 
    const dbEndpoint = getExternalDbConnectionResponse.endpoint;

    console.log(`Retrieved the ${name} external database connection, which is ${connectionSuccessful ? 'successful' : 'unsuccessful'}`);
    console.log(`It is mounted at ${dbEndpoint}`);

    return getExternalDbConnectionResponse;
  } catch (error) {
    console.error(error);
    // Handle the error
  }        
}

/* Promise resolves to:
 * 
 * {
 *   "capabilities": {
 *     "collectionModificationsSupported": true,
 *     "fieldTypes": []
 *   }
 *   "configuration": {
 *     "secretKey": "74dbd6d6-ec5b-4668-8229-c77379bc6431"
 *   },
 *   "connectionStatus": {
 *     "causeOfFailure": "NONE",
 *     "hasCollections": "YES"
 *     "successful": true,
 *   },
 *   "endpoint": "https://example.com/my-external-database",
 *   "name": "connectionOne",
 *   "protocolVersion": "V2"
 * }
 */

Get an external database connection (dashboard page code) 

import { Permissions, webMethod } from "wix-web-module";
import { externalDatabaseConnections } from "wix-data.v2";
import { elevate } from "wix-auth";

const elevatedGetExternalDbConnection = elevate(externalDatabaseConnections.getExternalDatabaseConnection);

/* 
 * Sample name value: 'ConnectionOne'
 */

export const myGetExternalDbConnection = webMethod(
  Permissions.Admin,
  async (name) => {
    try {
      const getExternalDbConnectionResponse = await elevatedGetExternalDbConnection(name);

      const connectionSuccessful = getExternalDbConnectionResponse.connectionStatus.successful; 
      const dbEndpoint = getExternalDbConnectionResponse.endpoint;

      console.log(`Retrieved the ${name} external database connection, which is ${connectionSuccessful ? 'successful' : 'unsuccessful'}`);
      console.log(`It is mounted at ${dbEndpoint}`);

      return getExternalDbConnectionResponse;
    } catch (error) {
      console.error(error);
      // Handle the error
    }        
  }
)

/* Promise resolves to:
 * 
 * {
 *   "capabilities": {
 *     "collectionModificationsSupported": true,
 *     "fieldTypes": []
 *   }
 *   "configuration": {
 *     "secretKey": "74dbd6d6-ec5b-4668-8229-c77379bc6431"
 *   },
 *   "connectionStatus": {
 *     "causeOfFailure": "NONE",
 *     "hasCollections": "YES"
 *     "successful": true,
 *   },
 *   "endpoint": "https://example.com/my-external-database",
 *   "name": "connectionOne",
 *   "protocolVersion": "V2"
 * }
 */

Get an external database connection (export from backend code) 

getExternalDatabaseConnection

Details of the external database connection requested.

ListExternalDatabaseConnectionsOptions

Retrieves a list of all external database collections associated with the site or project.

import { externalDatabaseConnections } from "wix-data.v2";
import { elevate } from "wix-auth";

const elevatedListExternalDbConnections = elevate(externalDatabaseConnections.listExternalDatabaseConnections);

export async function myListExternalDatabaseConnectionsFunction() {
  try {
    const listExternalDbConnectionsResponse = await elevatedListExternalDbConnections();

    const firstConnectionName = listExternalDbConnectionsResponse.externalDatabaseConnections[0].name;
    const firstConnectionHaveCollections = listExternalDbConnectionsResponse.externalDatabaseConnections[0].connectionStatus.hasCollections;

    console.log('Here is a list of all current external database connections: ', listExternalDbConnectionsResponse.externalDatabaseConnections);

    return listExternalDbConnectionsResponse;
  } catch (error) {
    console.error(error);
    // Handle the error
  }
}

/* Promise resolves to:
 * [
 *   {
 *     "capabilities": {
 *       "collectionModificationsSupported": false,
 *       "fieldTypes": []
 *     }
 *     "configuration": {
 *       "secretKey": "fkapmf9s-kf5z-lg04-mfia-kfo294pamvi5"
 *     },
 *     "connectionStatus": {
 *       "successful": true,
 *       "causeOfFailure": "NONE",
 *       "hasCollections": "YES"
 *     },
 *     "endpoint": "https://example.com/my-external-database",
 *     "name": "connection1",
 *     "protocolVersion": "V2",
 *   },
 *   {
 *     "capabilities": {
 *       "collectionModificationsSupported": false,
 *       "fieldTypes": []
 *     }
 *     "configuration": {
 *       "secretKey": "ukapguvn-kf5z-kfo4-kg94-nfoem4pamfi6"
 *     },
 *     "connectionStatus": {
 *       "successful": true,
 *       "causeOfFailure": "NONE",
 *       "hasCollections": "YES"
 *     },
 *     "endpoint": "https://example.com/my-external-database",
 *     "name": "connectionFour",
 *     "protocolVersion": "V2",
 *   },
 *   {
 *     "capabilities": {
 *       "collectionModificationsSupported": false,
 *       "fieldTypes": []
 *     }
 *     "configuration": {
 *       "secretKey": "kf0pguvn-mgoi-kfo4-kg94-nfoefds5mfi6"
 *     },
 *     "connectionStatus": {
 *       "successful": true,
 *       "causeOfFailure": "NONE",
 *       "hasCollections": "YES"
 *     },
 *     "endpoint": "https://example.com/my-external-database",
 *     "name": "connectionThree",
 *     "protocolVersion": "V2",
 *   },
 *   {
 *     "capabilities": {
 *       "collectionModificationsSupported": false,
 *       "fieldTypes": []
 *     }
 *     "configuration": {
 *       "secretKey": "fergfy84-kf5z-fdsf-kg94-nfoegfdg67i6"
 *     },
 *     "connectionStatus": {
 *       "successful": true,
 *       "causeOfFailure": "NONE",
 *       "hasCollections": "YES"
 *     },
 *     "endpoint": "https://example.com/my-external-database",
 *     "name": "connectionTwo",
 *     "protocolVersion": "V2",
 *   },
 *   {
 *     "applicationId": "8b7e9a62-t5hd-4372-gres-c6fb7762600b"
 *     "connectionStatus": {
 *       "successful": false,
 *       "causeOfFailure": "DESTINATION_ENDPOINT_NOT_DEFINED",
 *       "hasCollections": "UNKNOWN"
 *     },
 *     "name": "extDbSpi",
 *     "protocolVersion": "V3",
 *   }
 * ]
 */

List existing external database connections (dashboard page code) 

import { Permissions, webMethod } from "wix-web-module";
import { externalDatabaseConnections } from "wix-data.v2";
import { elevate } from "wix-auth";

const elevatedListExternalDbConnections = elevate(externalDatabaseConnections.listExternalDatabaseConnections);

export const myListExternalDatabaseConnectionsFunction = webMethod(
  Permissions.Admin,
  async () => {
    try {
      const listExternalDbConnectionsResponse = await elevatedListExternalDbConnections();

      const firstConnectionName = listExternalDbConnectionsResponse.externalDatabaseConnections[0].name;
      const firstConnectionHaveCollections = listExternalDbConnectionsResponse.externalDatabaseConnections[0].connectionStatus.hasCollections;

      console.log('Here is a list of all current external database connections: ', listExternalDbConnectionsResponse.externalDatabaseConnections);

      return listExternalDbConnectionsResponse; 
    } catch (error) {
      console.error(error);
      // Handle the error
    }
  }
)

/* Promise resolves to:
 * [
 *   {
 *     "capabilities": {
 *       "collectionModificationsSupported": false,
 *       "fieldTypes": []
 *     }
 *     "configuration": {
 *       "secretKey": "fkapmf9s-kf5z-lg04-mfia-kfo294pamvi5"
 *     },
 *     "connectionStatus": {
 *       "successful": true,
 *       "causeOfFailure": "NONE",
 *       "hasCollections": "YES"
 *     },
 *     "endpoint": "https://example.com/my-external-database",
 *     "name": "connection1",
 *     "protocolVersion": "V2",
 *   },
 *   {
 *     "capabilities": {
 *       "collectionModificationsSupported": false,
 *       "fieldTypes": []
 *     }
 *     "configuration": {
 *       "secretKey": "ukapguvn-kf5z-kfo4-kg94-nfoem4pamfi6"
 *     },
 *     "connectionStatus": {
 *       "successful": true,
 *       "causeOfFailure": "NONE",
 *       "hasCollections": "YES"
 *     },
 *     "endpoint": "https://example.com/my-external-database",
 *     "name": "connectionFour",
 *     "protocolVersion": "V2",
 *   },
 *   {
 *     "capabilities": {
 *       "collectionModificationsSupported": false,
 *       "fieldTypes": []
 *     }
 *     "configuration": {
 *       "secretKey": "kf0pguvn-mgoi-kfo4-kg94-nfoefds5mfi6"
 *     },
 *     "connectionStatus": {
 *       "successful": true,
 *       "causeOfFailure": "NONE",
 *       "hasCollections": "YES"
 *     },
 *     "endpoint": "https://example.com/my-external-database",
 *     "name": "connectionThree",
 *     "protocolVersion": "V2",
 *   },
 *   {
 *     "capabilities": {
 *       "collectionModificationsSupported": false,
 *       "fieldTypes": []
 *     }
 *     "configuration": {
 *       "secretKey": "fergfy84-kf5z-fdsf-kg94-nfoegfdg67i6"
 *     },
 *     "connectionStatus": {
 *       "successful": true,
 *       "causeOfFailure": "NONE",
 *       "hasCollections": "YES"
 *     },
 *     "endpoint": "https://example.com/my-external-database",
 *     "name": "connectionTwo",
 *     "protocolVersion": "V2",
 *   },
 *   {
 *     "applicationId": "8b7e9a62-t5hd-4372-gres-c6fb7762600b"
 *     "connectionStatus": {
 *       "successful": false,
 *       "causeOfFailure": "DESTINATION_ENDPOINT_NOT_DEFINED",
 *       "hasCollections": "UNKNOWN"
 *     },
 *     "name": "extDbSpi",
 *     "protocolVersion": "V3",
 *   }
 * ]
 */

List existing external database connections (export from backend code) 

import { Permissions, webMethod } from "wix-web-module";
import { externalDatabaseConnections } from "wix-data.v2";
import { elevate } from "wix-auth";

const elevatedListExternalDbConnections = elevate(externalDatabaseConnections.listExternalDatabaseConnections);

/* Sample options object:
 * 
 * {
 *   paging: {
 *     limit: 3,
 *     offset: 1
 *   }
 * }
 */

export const myListExternalDatabaseConnectionsFunctionOptions = webMethod(
  Permissions.Admin,
  async (options) => {
    try {
      const listExternalDbConnectionsResponse = await elevatedListExternalDbConnections(options);

      const firstConnectionName = listExternalDbConnectionsResponse.externalDatabaseConnections[0].name;
      const firstConnectionHaveCollections = listExternalDbConnectionsResponse.externalDatabaseConnections[0].connectionStatus.hasCollections;

      console.log('Here is a list of all current external database connections: ', listExternalDbConnectionsResponse.externalDatabaseConnections);

      return listExternalDbConnectionsResponse; 
    } catch (error) {
      console.error(error);
      // Handle the error
    }
  }
)

/* Promise resolves to:
 * {
 *   "externalDatabaseConnections": [
 *     {
 *       "capabilities": {
 *         "collectionModificationsSupported": false,
 *         "fieldTypes": []
 *       }
 *       "configuration": {
 *         "secretKey": "kvod85qz-fk40-mfi5-mfi4-mflqpmgl4f1"
 *       },
 *       "connectionStatus": {
 *         "successful": true,
 *         "causeOfFailure": "NONE",
 *         "hasCollections": "YES"
 *       },
 *       "endpoint": "https://example.com/my-external-database",
 *       "name": "connectionFour",
 *       "protocolVersion": "V2",
 *     },
 *     {
 *       "capabilities": {
 *         "collectionModificationsSupported": false,
 *         "fieldTypes": []
 *       }
 *       "configuration": {
 *         "secretKey": "lfoe8tfd-fl35-mfo4-mfd1-mvkf99bjfi30"
 *       },
 *       "connectionStatus": {
 *         "successful": true,
 *         "causeOfFailure": "NONE",
 *         "hasCollections": "YES"
 *       },
 *       "endpoint": "https://example.com/my-external-database",
 *       "name": "connectionThree",
 *       "protocolVersion": "V2",
 *     },
 *     {
 *       "capabilities": {
 *         "collectionModificationsSupported": false,
 *         "fieldTypes": []
 *       }
 *       "configuration": {
 *         "secretKey": "fkapguvn-kf5z-kfo4-kg94-nfoem4pamfi6"
 *       },
 *       "connectionStatus": {
 *         "successful": true,
 *         "causeOfFailure": "NONE",
 *         "hasCollections": "YES"
 *       },
 *       "endpoint": "https://example.com/my-external-database",
 *       "name": "connectionTwo",
 *       "protocolVersion": "V2",
 *     }
 *   ],
 *   "pagingMetadata": {
 *     "count": 3,
 *     "offset": 1,
 *     "total": 5,
 *     "tooManyToCount": false
 *   }
 * }
 */ 

List existing external database connections with pagination 

listExternalDatabaseConnections

ListExternalDatabaseConnectionsResponse

Name of the external database connection.
An external database connection may connect to one or more external data collections or tables.
These are represented as `connectionName/dataCollectionId`.

Updated external database connection details. The existing connection is replaced with this version.

UpdateExternalDatabaseConnection

Updates an external database connection.

An external database collection name must be provided in `name`.
If an existing external database connection is found with the same name, that connection's details are updated.
If no external database connection has that name, the request fails.

> **Note:** After an external database connection is updated, it only contains the values provided in the request. All previous values are lost.

import { externalDatabaseConnections } from "wix-data.v2";
import { elevate } from "wix-auth";

const elevatedUpdateExternalDatabaseConnection = elevate(externalDatabaseConnections.updateExternalDatabaseConnection);

/* 
 * Sample name value: 'connectionOne'
 *
 * Sample externalDatabaseConnection object:
 * 
 * {
 *   capabilities: {
 *     collectionModificationsSupported: false,
 *     fieldTypes: []
 *   },
 *   configuration: {
 *     secretKey: '74dbd6d6-ec5b-4668-8229-c77379bc6431',
 *     username: 'Jane Doe'
 *   },
 *   endpoint: 'https://example.com/my-external-database'
 * }
 */

export async function myUpdateExternalDatabaseConnectionFunction(name, externalDatabaseConnection) {
  try {
    const updateExternalDatabaseConnectionResponse = await elevatedUpdateExternalDatabaseConnection(name, externalDatabaseConnection);

    console.log(`The ${name} connection was updated with the new values. It is currently mounted at ${updateExternalDatabaseConnectionResponse.endpoint}`);

    return updateExternalDatabaseConnectionResponse; 
  } catch (error) {
    console.error(error);
    // Handle the error
  }
}

/* Promise resolves to:
 * {
 *   "capabilities": {
 *     "collectionModificationsSupported": false,
 *     "fieldTypes": []
 *   }
 *   "configuration": {
 *     "secretKey": "74dbd6d6-ec5b-4668-8229-c77379bc6431",
 *     "username": "Jane Doe"
 *   },
 *   "connectionStatus": {
 *     "successful": true,
 *     "causeOfFailure": "NONE",
 *     "hasCollections": "YES"
 *   },
 *   "endpoint": "https://example.com/my-external-database",
 *   "name": "connection1",
 *   "protocolVersion": "<connection-protocol-version>"
 * }
 */

Update an existing external database connection (dashboard page code) 

import { Permissions, webMethod } from "wix-web-module";
import { externalDatabaseConnections } from "wix-data.v2";
import { elevate } from "wix-auth";

const elevatedUpdateExternalDatabaseConnection = elevate(externalDatabaseConnections.updateExternalDatabaseConnection);

/* 
 * Sample name value: 'connectionOne'
 *
 * Sample externalDatabaseConnection object:
 * 
 * {
 *   capabilities: {
 *     collectionModificationsSupported: false,
 *     fieldTypes: []
 *   },
 *   configuration: {
 *     secretKey: '74dbd6d6-ec5b-4668-8229-c77379bc6431',
 *     username: 'Jane Doe'
 *   },
 *   endpoint: 'https://example.com/my-external-database'
 * }
 */

export const myUpdateExternalDatabaseConnectionFunction = webMethod(
  Permissions.Admin,
  async (name, externalDatabaseConnection) => {
    try {
      const updateExternalDatabaseConnectionResponse = await elevatedUpdateExternalDatabaseConnection(name, externalDatabaseConnection);

      console.log(`The ${name} connection was updated with the new values. It is currently mounted at ${updateExternalDatabaseConnectionResponse.endpoint}`);

      return updateExternalDatabaseConnectionResponse; 
    } catch (error) {
      console.error(error);
      // Handle the error
    }
  }
)

/* Promise resolves to:
 * {
 *   "capabilities": {
 *     "collectionModificationsSupported": false,
 *     "fieldTypes": []
 *   }
 *   "configuration": {
 *     "secretKey": "74dbd6d6-ec5b-4668-8229-c77379bc6431",
 *     "username": "Jane Doe"
 *   },
 *   "connectionStatus": {
 *     "successful": true,
 *     "causeOfFailure": "NONE",
 *     "hasCollections": "YES"
 *   },
 *   "endpoint": "https://example.com/my-external-database",
 *   "name": "connection1",
 *   "protocolVersion": "<connection-protocol-version>"
 * }
 */

Update an existing external database connection (export from backend code) 

updateExternalDatabaseConnection

Updated external database connection details.

---
title: Introduction
---

# About the External Database Connections API

&nbsp;

<div style="background-color: #FEF1D1; padding: 18px 24px; border-radius: 6px; border: 1px solid #FDB10C; box-sizing: border-box; display: inline-block">
    <b>Developer Preview</b>
    <br/>
    <span>APIs in <a href="https://www.wix.com/velo/reference/api-overview/developer-preview">Developer Preview</a> are subject to change and are not intended for use in production.<br/><a href="mailto:velo-preview-feedback@wix.com">Send us</a> your suggestions for improving this API. Your feedback is valuable to us.</span>
</div>

&nbsp;

The External Database Connections API enables you to connect an external database to a Wix site.

## Internal vs. external databases

Wix provides a comprehensive platform with integrated database capabilities. You can use the [Data Collections API](https://www.wix.com/velo/reference/wix-data-v2/collections) to create, modify, and delete data collections in a Wix site, and you can use [`wix-data`](https://www.wix.com/velo/reference/wix-data) to access and manage data within those collections.

Wix's database capabilities cover a wide range of use cases for apps that need to store data. However, certain projects have very specific requirements that make it necessary to use an external database. For example, you may need to access existing data that is already stored on an external service, or you may need your data to be stored in a relational database.

Once the connection between an external database and a Wix site is established, you can access the collection using Wix Data APIs, including [`wix-data`](https://www.wix.com/velo/reference/wix-data), in the same way you would with a native collection. You can also access the collection through the Content Management System(CMS).

For more information on connecting external databases with a Wix site, see [Integrating External Databases with Your Wix Site](https://support.wix.com/en/article/velo-integrating-external-databases-with-your-wix-site).

## Preparing an external database

Before the External Database Connections API can connect a Wix site with an external database, you need to prepare the external database by creating an [external database adaptor](https://support.wix.com/en/article/velo-integrating-external-databases-with-your-wix-site#what-is-an-external-database-adaptor).

An external database adaptor is a server that translates Wix data requests from a Wix site into an external database's protocol, and translates the response back into a format that Wix APIs can read. This enables Wix APIs, projects, and sites to treat the external database exactly as if it was an internal data collection.

If your database is hosted on one of the major cloud platforms, you can consult one of our tutorials for instructions on how to [deploy an external database adaptor](https://support.wix.com/en/article/velo-integrating-external-databases-with-your-wix-site#deploy-an-external-database-adaptor).

Otherwise, for details on the required specifications for an external database adaptor, see the [External Database Collections SPI](https://www.wix.com/velo/reference/spis/external-database-collections).

## Ensuring read-write access

If you want to enable read-write access to your external database using [`wix-data`](https://www.wix.com/velo/reference/wix-data), ensure your external database's table or schema includes the following fields:
* `_id`
* `_createdDate`
* `_updatedDate`
* `_owner`
If these fields are absent, access to the external database is read-only. You may prefer this option for data that your app only needs to retrieve and doesn't need to manage.

## Supported databases

The External Database Connections API works with several kinds of databases. For a full list, see [Supported Databases](https://support.wix.com/en/article/velo-integrating-external-databases-with-your-wix-site#supported-databases).


velo-deps_wix-data.v2_external-database-connections

Capabilities

Whether the external database supports creating new collections, updating the structure of existing collections, or deleting them.

collectionModificationsSupported

boolean

Field types the external database supports.
This field only applies when `collectionModificationsSupported` is `true`.

fieldTypes

CauseOfFailure

CollectionsFound

ConnectionStatus

If and why a connection attempt failed.
+ `NONE`: No connection failure.
+ `COMMUNICATION_FAILURE`: General communication failure.
+ `DESTINATION_HOST_UNREACHABLE`: External database host is unreachable.
+ `UNAUTHORIZED`: Unauthorized to access external database.
+ `DESTINATION_ENDPOINT_NOT_DEFINED`: `Endpoint` property is not set.

causeOfFailure

Whether the external database has existing collections. Possible values are:
+ `UNKNOWN`: The attempt to connect to the external database failed, so status is unknown.
+ `NO`: External database does not have any existing collections.
+ `YES`: External database has existing collections.

hasCollections

Whether the connection was established successfully.

successful

ConnectionType

connectionType

capabilities

Settings passed to the external database connection as part of each request.
These settings can relate to authentication, tenancy, or provide any other information needed for processing a request.
Their content and structure depend on the specific requirements of the external database's API.

configuration

Status of the external database connection. Includes whether the connection was established successfully, and if not, the reason for the failure.

connectionStatus

Base URL for provisioning and managing data in the external database. For example: `https://example.com/my-external-database`.

endpoint

FieldType

paging

Paging

externalDatabaseConnections

pagingMetadata

PagingMetadata

limit

number

Number of items to skip in the current sort order.

offset

Number of items returned in the response.

count

Flag that indicates the server failed to calculate the `total` field.

tooManyToCount

Total number of items that match the query.

createExternalDatabaseConnection( )