createExternalDatabaseConnection( )

Developer Preview

Creates a new external database connection.

Description

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.

Admin Method

This function requires elevated permissions to run. This function is not universal and runs only on the backend.

Syntax

function createExternalDatabaseConnection(externalDatabaseConnection: ExternalDatabaseConnection, options: CreateExternalDatabaseConnectionOptions): Promise<ExternalDatabaseConnection>

createExternalDatabaseConnection Parameters

NAME

TYPE

DESCRIPTION

externalDatabaseConnection

ExternalDatabaseConnection

External database connection details.

options

Optional

CreateExternalDatabaseConnectionOptions

Options for creating an external database connection.

Returns

Details of external database connection created.

Return Type:

Promise<

ExternalDatabaseConnection

NAME

TYPE

DESCRIPTION

capabilities

Capabilities

The external database's capabilities.

configuration

Object

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.

connectionStatus

ConnectionStatus

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

endpoint

string

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

name

string

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.

Was this helpful?

Create an external database connection (dashboard page code)

Copy Code

1import { externalDatabaseConnections } from "wix-data.v2";
2import { elevate } from "wix-auth";
3
4const elevatedCreateExternalDbConnection = elevate(externalDatabaseConnections.createExternalDatabaseConnection);
5
6/* Sample externalDatabaseConnection object:
7 *  
8 * {
9 *   capabilities: {
10 *     collectionModificationsSupported: false,
11 *     fieldTypes: []
12 *   },
13 *   configuration: {
14 *     secretKey: '74dbd6d6-ec5b-4668-8229-c77379bc6431'
15 *   },
16 *   endpoint: 'https://example.com/my-external-database',
17 *   name: 'connectionOne'
18 * }
19 */
20
21
22export async function myCreateExternalDbConnectionFunction(newExternalDatabaseConnection) {
23  try {
24    const createExternalDbConnectionResponse = await elevatedCreateExternalDbConnection(newExternalDatabaseConnection);
25    
26    const dbConnectionStatus = createExternalDbConnectionResponse.connectionStatus; 
27    const dbCapabilities = createExternalDbConnectionResponse.capabilities; 
28    
29    console.log('Successfully created an external database connection. Full response:', createExternalDbConnectionResponse);
30    
31    return createExternalDbConnectionResponse; 
32  } catch (error) {
33    console.error(error);
34    // Handle the error
35  }
36}
37
38/* Promise resolves to:
39 * 
40 * {
41 *   "capabilities": {
42 *     "collectionModificationsSupported": false,
43 *     "fieldTypes": []
44 *   }
45 *   "configuration": {
46 *     "secretKey": "74dbd6d6-ec5b-4668-8229-c77379bc6431"
47 *   },
48 *   "connectionStatus": {
49 *     "causeOfFailure": "NONE",
50 *     "hasCollections": "YES"
51 *     "successful": true,
52 *   },
53 *   "endpoint": "https://example.com/my-external-database",
54 *   "name": "connectionOne",
55 *   "protocolVersion": "V2",
56 * }
57 */

Create an external database connection (export from backend code)

Copy Code

1import { Permissions, webMethod } from "wix-web-module";
2import { externalDatabaseConnections } from "wix-data.v2";
3import { elevate } from "wix-auth";
4
5const elevatedCreateExternalDbConnection = elevate(externalDatabaseConnections.createExternalDatabaseConnection);
6
7/* Sample externalDatabaseConnection object:
8 *  
9 * {
10 *   capabilities: {
11 *     collectionModificationsSupported: false,
12 *     fieldTypes: []
13 *   },
14 *   configuration: {
15 *     secretKey: '74dbd6d6-ec5b-4668-8229-c77379bc6431'
16 *   },
17 *   endpoint: 'https://example.com/my-external-database',
18 *   name: 'connectionOne'
19 * }
20 */
21
22export const myCreateExternalDbConnectionFunction = webMethod (
23  Permissions.Admin, 
24  async (newExternalDatabaseConnection) => {
25    try {
26      const createExternalDbConnectionResponse = await elevatedCreateExternalDbConnection(newExternalDatabaseConnection);
27
28      const dbConnectionStatus = createExternalDbConnectionResponse.connectionStatus; 
29      const dbCapabilities = createExternalDbConnectionResponse.capabilities; 
30
31      console.log('Successfully created an external database connection. Full response:', createExternalDbConnectionResponse);
32
33      return createExternalDbConnectionResponse; 
34    } catch (error) {
35      console.error(error);
36      // Handle the error
37    }
38  }
39)
40
41/* Promise resolves to:
42 * 
43 * {
44 *   "capabilities": {
45 *     "collectionModificationsSupported": false,
46 *     "fieldTypes": []
47 *   }
48 *   "configuration": {
49 *     "secretKey": "74dbd6d6-ec5b-4668-8229-c77379bc6431"
50 *   },
51 *   "connectionStatus": {
52 *     "causeOfFailure": "NONE",
53 *     "hasCollections": "YES"
54 *     "successful": true,
55 *   },
56 *   "endpoint": "https://example.com/my-external-database",
57 *   "name": "connectionOne",
58 *   "protocolVersion": "V2",
59 * }
60 */