Forge SQL (Preview)

Forge SQL is a hosted storage capability that will let you use an SQL database for your app. With this capability, Forge will provision and host your app’s database (and, by extension, host your customer’s app data) on Atlassian infrastructure.

Forge SQL provisions a single database instance per installation. That is, each instance will be associated to a specific installation of your app. As a result, each app installation will have its own dedicated database instance; this instance will store only data specific to its corresponding installation.

Implementation

Forge SQL is based on a MYSQL-compliant, distributed SQL database. We've configured Forge SQL to comply with standard ANSI-compliant SQL. To allow for optimal data portability outcomes, we strongly encourage you use standard ANSI SQL syntax when interacting with the database.

Limitations

Forge SQL offers a multi-tenant SQL solution offering tenant isolation and stable query performance. To do so, we add a few constraints over and above TiDB’s limitations:

• Foreign keys are not supported. You can still perform JOIN operations, but DELETE operations will not be cascaded.

• Each READ operation has a 5-second timeout configured.

• Forge SQL API (for non-READ statements) will timeout after 10 seconds of execution.

• Each QUERY operation has a memory quota set to 16 MB.

• Within each minute, all concurrent invocations share a total query execution time of 62.5 seconds (per installation).

• Each SQL statement can only contain a single query.

The following limits also apply:

Data residency limitations

Forge SQL currently doesn’t support data residency. We plan to add data residency support in a future Forge SQL update.

For now, you understand and acknowledge that you are instructing Atlassian to provision all customer databases for Forge SQL in the US-WEST region.

Once Forge SQL adds data residency features, we will migrate all Production databases provisioned by SQL to their respective products' regions. The migration will require downtime, so we will announce this at least 30 days in advance (allowing affected developers and customers to plan accordingly).

SOC2 and ISO compliance

Forge SQL has not yet undergone external assessment for SOC 2 or ISO certification. As we continue development on Forge SQL, we will aim to include it in our standard audit certification reporting cycle.

Runs on Atlassian limitations

The Runs on Atlassian program requires that you only use storage with data residency features. As such, apps using Forge SQL are ineligible for this program for now.

Such apps will become eligible once Forge SQL adds data residency features.

Versioning

If you add Forge SQL to an existing app, admins of that app’s current installations must review and consent before updating.

As such, adding Forge SQL to an existing app will require a major version upgrade. This will be triggered through the sql module (which is required to enable Forge SQL on an app).

Schema management

Forge SQL provisions databases for each individual installation, thereby isolating each customer’s data. This helps secure each database and optimise its performance, at least in relation to each customer’s stored data.

With this implementation, your app’s database schema needs to be applied as soon as the app is installed. As such, schema management with Forge SQL is split into two phases:

• Queueing: Queue Data Definition Language (DDL) operations to create the database objects that make up your schema. You can use a special Forge SQL SDK for this, which will let you define each operation (and the order they should be run). To update your app’s schema, simply add DDL operations as needed.

• Execution: Using a scheduled trigger, Forge SQL can execute your queued DDL operations when the app is installed or whenever you update the schema. Forge SQL can track which DDL operations need to be executed on which specific installations, and which ones need to be re-run (in case of errors).

During the execution phase, Forge SQL will also take care of migrating data between older and newer schema versions.

Partitioning

Data in Forge hosted storage is namespaced. The namespace includes all metadata relevant to an app�s current installation. As a result:

• Only your app can read and write your stored data.
• An app can only access its data for the same environment.
• Keys or table names only need to be unique for an individual installation of your app.
• Data stored by your app for one product is not accessible from other products. For example, data stored in Jira is not accessible from Confluence or vice versa.
• Your app cannot read stored data from different sites, products, and app environments.
• Quotas and limits are not shared between individual installations of your app.

Monitoring

Forge SQL provides reliability and latency metrics to help you understand your app’s database interactions. It also provides some observability into the health of each provisioned database, as well as their respective schemas.

To view these metrics:

1. Access the developer console.
2. Select SQL in the left menu (under STORAGE).

From there, you can choose between the following observability options:

• Monitor: tracks your app’s reliability and performance. You can do this across all installations, or filter information by any combination of site, environment, or time frame. See
• Manage: provides insights on database schemas for individual installations.

See Monitor SQL for detailed information.