Navigation

Update an Existing Stitch Application

MongoDB Stitch applications can be updated by importing a local application directory with the stitch-cli import command.

Prerequisites

Procedure

1

Prepare the Application Directory

Export your application to a local application directory. Alternatively, create a new application directory that contains a stitch.json file with your application’s app_id.

{
  "app_id": "<Your Application ID>"
}
2

Add or Update Application Entities

Add sub-directories and configuration files for any new entities you’re importing, or update the values in existing entity files. All entity files must conform to the Application File Schema.

Note

If you are importing any new entities that require sensitive values (e.g. auth tokens, client secrets, etc.), ensure that those values are included in secrets.json or the import will fail.

3

Authenticate a MongoDB Atlas User

To import or update a MongoDB Stitch application with stitch-cli, users must authenticate with Atlas using an API Key.

stitch-cli login --username=cloud.username --api-key=my-api-key
4

Run the Import Command

Run the following command in your application directory:

stitch-cli import --strategy=merge

Note

The import command has several optional arguments. For a complete list, see the import reference documentation.

5

Review and Confirm Import Diff

Before committing the import, stitch-cli will show you a diff of the changes that will be made to your application. Review the diff to ensure that all changes are correct then confirm the import.

After successfully importing your application, stitch-cli will immediately export the application to update your local application directory with any system-generated values.

Import Strategies

When performing an application import, there are two built-in strategies for handling existing entities: merge and replace.

All imports follow the merge strategy unless otherwise specified.

Merge

stitch-cli import --strategy=merge

Under the merge strategy, entities in the application directory are added to the application non-destructively. Any existing entities in an application are left unchanged if they are not represented in the imported application directory.

If an imported entity’s id value matches the id of an existing entity, the existing entity will be updated to match the imported entity. If an entity is imported with an id that does not match an existing entity, the import will fail. Entities without id values will be assigned system-generated id values before being imported as new entities.

Note

If an imported entity has an id field, the value must be an ObjectID or the merge will fail.

Example

An existing application has three functions:

{ "id": <ObjectID 1>, "name": "FunctionA", ... }
{ "id": <ObjectID 2>, "name": "FunctionB", ... }
{ "id": <ObjectID 3>, "name": "FunctionC", ... }
A local application directory is imported with the merge strategy.
The directory contains configuration files for the following functions:
{ "id": <ObjectID 1>, "name": "FunctionA_Updated!", ... }
{ "name": "FunctionD", ... }

After importing, the application has the following functions:

{ "id": <ObjectID 1>, "name": "FunctionA_Updated!" }
{ "id": <ObjectID 2>, "name": "FunctionB", ... }
{ "id": <ObjectID 3>, "name": "FunctionC", ... }
{ "id": <ObjectID 4>, "name": "FunctionD", ... }

FunctionA was updated based on its imported configuration file. FunctionB and FunctionC were not included in the imported application directory, so they remained unchanged after importing with the merge strategy. FunctionD was imported as a new entity and assigned a system-generated id value.

Replace

stitch-cli import --strategy=replace

Under the replace strategy, any existing entities in an application are deleted if they are not represented in the imported application directory.

If an imported entity has no id value or has an id value that does not match an existing entity’s id, stitch-cli will assign it a system-generated id. Unlike in the merge strategy, importing an entity with a non-ObjectID id value will not throw an error.

Example

An existing application has three functions:

{ "id": <ObjectID 1>, "name": "FunctionA", ... }
{ "id": <ObjectID 2>, "name": "FunctionB", ... }
{ "id": <ObjectID 3>, "name": "FunctionC", ... }
A local application directory is imported with the replace strategy.
The directory contains configuration files for the following functions:
{ "id": <ObjectID 1>, "name": "FunctionA_Updated!", ... }
{ "name": "FunctionD", ... }
{ "id": "non-ObjectID-value", "name": "FunctionE", ... }

After importing, the application has the following functions:

{ "id": <ObjectID 1>, "name": "FunctionA_Updated!" }
{ "id": <ObjectID 4>, "name": "FunctionD", ... }
{ "id": <ObjectID 5>, "name": "FunctionE", ... }

FunctionA was updated based on its imported configuration file. FunctionB and FunctionC were not included in the imported application directory, so they are not present in the app after importing with the replace strategy. FunctionD and FunctionE were imported as new entities and assigned system-generated id values.