Upgrade to MongoSK 2

[Romitou]

⚠️ The support of the first versions of MongoSK will be dropped from March 31, 2020.

---

A new version of MongoSK bringing a lot of features is under development! Promised, this new version will be much more stable than the first one. 😛 The decision to create a new major version was mainly taken in order to change syntaxes more easily, something that could not be done with the first version in order to maintain backwards compatible syntaxes. You will have understood it, this new version will certainly not work with your version of MongoSK.

🤔 So, how to update?

I will explain step by step below the syntaxes to modify in order to work with MongoSK 2.
The major modification is to add the mandatory prefix mongo to each syntax. This avoids conflicts with other addons.

🙋 I need help!

These changes may be binding, but are necessary to work with MongoSK v2. If you need help to update your scripts, I remain of course fully available on my Discord server or in GitHub discussions.

---

🔑 Mongo servers

This term has been revised to be better understood by users. From now on, we will no longer talk about clients, but directly about MongoDB servers. The way a server is retrieved and used has been changed, as follows:

View code

# Old code
on script load:
    connect to the mongo host "mongodb://127.0.0.1" with name "test"
    set {client} to client named "test"
    # set {database} to mongo database named "mongosk" of {client}
    # </> ...

# New code
on script load:
    set {mongoclient} to mongosk server with connection string "mongodb://mongosk:[email protected]/?retryWrites=true&w=majority"
    # set {mongodatabase} to mongo database named "mongosk" from {mongoclient}
    # </> ...

---

🔬 Mongo filters

In this expression, the mongo part has become obligatory, as well as the addition of the word field.

View code

# Old code
set {_filter} to new mongo filter where "points" is greater or equal to 100
set {_players::*} to all documents with filter {_filter} in {collection}
set {_players::*} to all documents where "points" is greater or equal to 100 in {collection}

# New code
set {_filter} to new mongo filter where field "points" is greater than or equal to 100
set {_players::*} to all mongo documents with filter {_filter} of collection {collection}
set {_players::*} to all mongo documents with mongo filter where field "points" is greater than or equal to 100 of collection {collection}

---

📋 Mongo values

This expression has been reworked, adding only the mongo prefix to the syntaxes.

View code

# Old code
loop list "example" of {_document}:
	broadcast "%loop-value%"
set list "example" of {_document} to 10, 54 and 203
add 41 to list "example" of {_document}							

# New code
loop mongo list "example" of {_document}:
	broadcast "%loop-value%"
set mongo list "example" of {_document} to 10, 54 and 203
add 41 to mongo list "example" of {_document}	

---

📥 Save documents

From now on, you have several possibilities to save a document. Firstly, the insertion effect, which will always create a new document with a different identifier each time, even if the inserted document already contains one. If you want to update a document, replace it, you will have to use another expression. The same applies to deleting documents, both linked to the same expression.

View code

# Old code
set {_collection} to collection named "example" of database "mongosk" with client "test"
save {_doc} in {_collection}

# New code
set {_collection} to mongo collection named "example" of mongo database "mongosk" of mongo server with connection string "mongodb://mongosk:[email protected]/?retryWrites=true&w=majority"
insert mongo document {_doc} into {_collection}

Examples of replacing and deleting documents:

# New code
set first mongo document with mongosk filter where field "_id" equals "507f1f77bcf86cd799439011" of collection {mycollection} to {_mydoc}
delete all mongosk documents of collection {mycollection}
delete first mongo document with mongosk filter where field "_id" equals "507f1f77bcf86cd799439011" of collection {mycollection}

---

🗃 All Mongo documents

This expression no longer exists and is now directly integrated into the query expression. The equivalent is simply not to specify a search filter.

View code

# Old code
set {_docs::*} to all documents of {mycollection}

# New code
# Query expression pattern: (1¦first|2¦all) mongo[(sk|db)] document[s] [(with|by) [filter] %-mongoskfilter%] (of|from) collection %mongoskcollection%
set {_docs::*} to all mongo documents of collection {mycollection}

---

As for the effects of creation and deletion of databases and collections, they have not been integrated in the first version of MongoSK v2. They will be added soon.