Integrate Your AWS Databases with Your Wix Site

Note: This feature is only available for sites with certain premium plans. If you need to use this feature, you can upgrade your site. Learn more about premium plans.

Wix allows users to connect an external database to Wix sites using an external database adaptor. Once the connection is set up, users can interact with these databases and use them to populate site elements as though they were Wix CMS collections.

With an external database adaptor, you can use your database hosted on GCP (Google Cloud Platform), and fully integrate it into your Wix site. This means your GCP data can be managed via the Wix Data APIs (REST|SDK), and used (with or without datasets) to populate Wix UI elements like repeatersand tables.

Overview

This article walks you through the following:

  1. Creating secrets to securely store your database credentials and your Wix Secret Key.
  2. Creating and deploying a new App Runner service to host the Wix database adaptor.
  3. Testing your service
  4. Connecting your Wix site to your database.

This tutorial assumes you already have your own database on AWS with a table containing some data. If you don't have this set up, refer to the AWS documentation for instructions.

This tutorial uses a container image with all the functionality needed to interface between your database and your Wix site. If you want to look under the hood, you can have a look at the service plugin specifications for external database collections, and an overview of what's involved in building your own adaptor.

Supported Databases

We currently support the following AWS databases:

Prerequisites for Read-Write Access to Your Database Tables:
If you want your table to be read-write on your Wix site, it must contain the following columns:

  • _id
  • _createdDate
  • _updatedDate
  • _owner

Tables without these columns will be read-only in your Wix site.

Step 1 | Create secrets to securely store your database credentials and your Wix Secret Key

The external database adaptor requires you to set some environment variables. Some of these variables, like the DB credentials, are sensitive and should not be visible. Use the AWS Secrets Manager to store and access these variables securely.

Note: We don't provide specific instructions for any configuration in AWS, as AWS's UI and flows may change. For further details on any of the instructions below, see the AWS Secrets Manager documentation.

Create a New Secret for RDS Databases

For RDS databases, you need to store 5 secret values:

  • USERNAME The username used to connect to your database instance.

  • PASSWORD The password used to connect to your database instance.

  • DB The name of the database to connect to.

  • SECRET_KEY A secret key used to connect your Wix site to the adaptor. To create a level of authentication between your site and the adaptor, each request your site sends to the adaptor contains this value in the payload.

  • PERMISSIONS (optional) A stringified JSON object that defines the read and write permissions for the tables in your database. It's important to note the following about setting permissions:

    • If you don't set permissions, they default to admin. With admin permissions, only site admins can read or write to the external database from a Wix site. API calls or CMS connections to the database don't work for anyone who isn't a site admin. This means site code that communicates with the external database might not work for site visitors.
    • When setting up permissions, make sure you use the ID of the table you want to read and write to, and not the database ID.

    Note: Customizing permissions for external databases is currently a developer preview feature, and may change. Changes to permissions settings are not reflected in the Wix Editor.

Learn more about configuring database permissions

You can use the PERMISSIONS secret to customize the permission settings for each table in a database. The JSON object contains one key, collectionPermissions, whose value is an array of objects. Each object in this array contains the permissions settings for one of the collections in the database, using the following parameters:

  • id: The collection ID.
  • read: An array of strings representing which roles can read from the collection. Options: 'Admin', 'Member', 'Visitor'
  • write: An array of strings representing which roles can write to the collection. Options: 'Admin', 'Member', 'Visitor'

Example PERMISSIONS value:

Copy

Note that you need to store the PERMISSIONS JSON object as a string. To do this, first write the object as usual and use a tool such as your browser's developer tools console to stringify it.

Note When you store a new secret and select Credentials for Amazon RDS database, the Secrets Manager automatically stores the USERNAME, PASSWORD, and other connection information for you. You will need to manually add the SECRET_KEY, DB, and PERMISSIONS (optional) values as shown in the steps below.

Create a new role for an RDS instance

Create a new role for an RDS Instance in AWS's IAM manager console with permission to access the above secrets. See the IAM documentation for more details. You'll assign this role to the App Runner service you create in the next step.

Step 2 | Create and deploy a new App Runner service to host the Wix database adaptor

Now you'll create the service that will run the adaptor and make it available to your Wix site.

For further details on any of the instructions below, see the AWS Management Console documentation.

  1. Create a new AWS App Runner from the AWS Management Console.

  2. Enter the following as the Container Image URL:

    Copy
  3. Add the following additional key/value pairs:

    SourceEnvironment variable nameEnvironment variable value
    Plain textCLOUD_VENDORAll databases: aws
    Plain textTYPEMySQL database: mysql
    PostgreSQL database: postgres
    Aurora_mysql:mysql
    Aurora_postgresql:postgres
    Plain textSECRET_NAMEAll databases:
    The secret you created for your database. Ours is tutorial_secret
  4. Assign the runner the role you created in step 1.

  5. Create and deploy the service.

  6. Record the URL of you App Runner.

Step 3 | Test Your Service

You can test that your service is working by making a quick request using Curl.

Use the Curl command below, replacing the URL with the URL of your App Runner, and replacing the secretKey value with your secret.

Copy

The output provides a list of tables and their columns from your database. If you have python installed, you can pipe the output to python -m json.tool and it will give you nicely formatted JSON.

The formatted output containing a list of tables and their columns:

Copy

Step 4 | Connect your Wix site to your database

Now that you have a database and an adaptor service, you're ready to add the database as an external collection on your site.

Note: You can only add external collections to your site if you have a premium plan.

  1. Go to the Databases section of the Code sidebar (Wix Editor) or the Code sidebar (Wix Studio).

  2. Click the icon next to External Databases and select Add external database.

  3. Choose Amazon Web Services as the provider of the external collection being added, then click Next.

  4. Enter a name for your external collection's namespace.

  5. Copy and paste your adaptor service's URL into the endpoint URL field.

  6. Enter your database adaptor's secret key.

  7. Click Connect.

The Content Management System (CMS) displays the tables. If your table contains the _id, _createdDate, _updatedDate, and _owner fields, you can add data to the table directly from the CMS.

Did this help?