From 9a8b7ed417ec37e98e2d17c54666523d24192337 Mon Sep 17 00:00:00 2001 From: Joannis Orlandos Date: Tue, 2 Jan 2018 14:08:16 +0100 Subject: [PATCH] basic mongodb docs --- 3.0/docs/databases/mongodb/basics.md | 0 3.0/docs/databases/mongodb/bson.md | 0 3.0/docs/databases/mongodb/getting-started.md | 109 ++++++++++++++++++ 3.0/docs/databases/mongodb/interpreting.md | 107 +++++++++++++++++ 3.0/docs/routing/basics.md | 2 +- 3.0/mkdocs.yml | 7 +- 6 files changed, 221 insertions(+), 4 deletions(-) create mode 100644 3.0/docs/databases/mongodb/basics.md create mode 100644 3.0/docs/databases/mongodb/bson.md create mode 100644 3.0/docs/databases/mongodb/getting-started.md create mode 100644 3.0/docs/databases/mongodb/interpreting.md diff --git a/3.0/docs/databases/mongodb/basics.md b/3.0/docs/databases/mongodb/basics.md new file mode 100644 index 00000000..e69de29b diff --git a/3.0/docs/databases/mongodb/bson.md b/3.0/docs/databases/mongodb/bson.md new file mode 100644 index 00000000..e69de29b diff --git a/3.0/docs/databases/mongodb/getting-started.md b/3.0/docs/databases/mongodb/getting-started.md new file mode 100644 index 00000000..533a8e39 --- /dev/null +++ b/3.0/docs/databases/mongodb/getting-started.md @@ -0,0 +1,109 @@ +# Using MongoDB + +The [vapor/mongodb](https://github.com/OpenKitten/MongoKitten) package is an extremely performant, reactive and pure swift MonogDB driver. It provides a simple interface to MongoDB for powerful features. + +On top of [vapor/mysql](https://github.com/vapor/mysql), we have built [vapor/fluent-sqlite](https://github.com/vapor/fluent-sqlite) which allows SQLite databases to be used with Fluent. + +## Just MongoDB + +This package works really well with _and_ without Fluent. To include this package in your project, simply add it to your Package manifest. + +```swift +// swift-tools-version:4.0 +import PackageDescription + +let package = Package( + name: "Project", + dependencies: [ + ... + .package(url: "https://github.com/OpenKitten/MongoKitten.git", .revision("master/5.0")), + ], + targets: [ + .target(name: "Project", dependencies: ["MongoKitten", ... ]) + ] +) +``` + +If this is your first time adding a dependency, you should read our introduction to [Package.swift](../../getting-started/spm.md). + +If this is your first time using MongoDB, have a look at the [setup guides](https://docs.mongodb.com/manual/administration/install-community/). + +The official documentation assumed either the MongoDB shell or one of their more popular (official) drivers. +Please refer to [the MongoKitten interpretation guide](interpreting.md) before reading the [official documentation](https://docs.mongodb.com/manual/tutorial/getting-started/). + +Use `import MongoKitten` to access the APIs. + +## With Fluent + +MySQL works well Fluent, you just need to make sure to add the [vapor/fluent-mysql](https://github.com/vapor/fluent-mysql) package to your project. + +To do this, add the Fluent MySQL package to your Package manifest. + +```swift +// swift-tools-version:4.0 +import PackageDescription + +let package = Package( + name: "Project", + dependencies: [ + ... + .package(url: "https://github.com/vapor/fluent-mysql.git", .revision("beta")), + ], + targets: [ + .target(name: "Project", dependencies: ["FluentMySQL", ... ]) + ] +) +``` + +If this is your first time adding a dependency, you should read our introduction to [Package.swift](../../getting-started/spm.md). + +Use `import FluentMySQL` to access MySQL's Fluent compatible APIs. [Learn more about the Fluent APIs here](../../fluent/getting-started/provider.md) + +### Setting up services + +In order to set up MySQL with Fluent you first need to register the Fluent provider: + +```swift +try services.provider(FluentProvider()) +``` + +After this, you need to register the MySQL config and database. + +```swift +services.instance(FluentMySQLConfig()) + +var databaseConfig = DatabaseConfig() + +let username = "" +let password = "" +let database = "" + +let db = MySQLDatabase(hostname: "localhost", user: username, password: password, database: database) +databaseConfig.add(database: db, as: .mysql) +services.instance(databaseConfig) +``` + +Notice the variable `mysqlDB`. This is an identifier for the MySQL database. +You need to create an identifier for each database you attach to Fluent. + +The following identifer can be global, or as a static variable in an extension on `DatabaseIdentifier`. + +```swift +extension DatabaseIdentifier { + static var mysql: DatabaseIdentifier { + return .init("foo") + } +} +``` + +Last, you can specify migrations for Fluent to execute. This can be used for creating and altering schemas and migrating data within the table. + +Fluent `Model`s that conform to the protocol `Migration` automatically inherit a migration for schema creation. Nothing needs to be programmed for this. + +```swift +var migrationConfig = MigrationConfig() +migrationConfig.add(model: MyModel.self, database: .mysql) +services.instance(migrationConfig) +``` + +More info on working with Fluent can be found [here](../../fluent/getting-started/getting-started.md). diff --git a/3.0/docs/databases/mongodb/interpreting.md b/3.0/docs/databases/mongodb/interpreting.md new file mode 100644 index 00000000..1cc8c3ec --- /dev/null +++ b/3.0/docs/databases/mongodb/interpreting.md @@ -0,0 +1,107 @@ +# Interpreting official MongoDB tutorials + +https://docs.mongodb.com/manual/reference/ has a lot of tutorials on every detail of MongoDB. +Using them in MongoKitten can be a bit tricky. This guide will explain how they are best applied. + +## Documents/BSON Data + +MongoDB writes Documents in a JSON-like syntax. The following Documents are taken from the documentation on the MongoDB website. + +```js +var document0 = { + "_id" : ObjectId("512bc95fe835e68f199c8686"), + "author" : "dave", + "score" : 80, + "views" : NumberLong(100), + "awesome": true, + "users": [ + { _id: 2, user: "ijk123", status: "A" }, + { _id: 3, user: "xyz123", status: "P" }, + { _id: 4, user: "mop123", status: "P" } + ] +} +``` + +These Documents read to this equivalent in BSON. + +```swift +let document0: Doucment = [ + "_id": try ObjectId("512bc95fe835e68f199c8686") + "author": "dave", + "score": Int32(80), + "views": 100, + "aweosme": true, + "users": [ + ["_id": 2, "user": "ijk123", "status": "A"], + ["_id": 3, "user": "xyz123", "status": "P"], + ["_id": 4, "user": "mop123", "status": "P"] + ] +] +``` + +As you see, ObjectId works similarly but initializing an creating ObjectId from a String can throw an error. +More information about BSON, the MongoDB data type [on this page](bson.md). + +Integers in MongoDB are Int32 by default, MongoKitten uses Int64 by default. +MongoDB and MongoKitten can often use the 2 interchangeably with the exception of large numbers that do not fit in an Int32 (and are requested as Int32). + +In Swift your dictionary literals don’t start with `{` and don’t end with `}` but instead also use `[` and `]` for dictionaries. + +Dictionaries in Swift require a `String` to have quotes (`"`) around them. In JavaScript syntax this is optional. + +## Selecting databases/collections + +In the shell `use mydatabase` selects the database named "mydatabase". From here you can use `db.mycollection.find()` to fetch all data in the collection. + +In MongoKitten, you can subscript the server and database. +Subscripting the server selects a database, and subscripting the database selects a collection. +Usually you'll be working with a single database, so the following code connects to a single database named "example-db". + +```swift +// Connect to the localhost database `example-db` without credentials +let database = try Database.connect(server: "mongodb://localhost:27017", database: "mongokitten-example-db", worker: eventLoop).await(on: eventLoop) + +// Select a collection +let mycollection = mydatabase["mycollection"] + +// Query all entities +try mycollection.find() +``` + +## Common operations in collections + +Most operations are available on a collection object. +By typing `mycollection.` , Swift will autocomplete a list of available methods. + +For inserting you can use `insert` which have various parameters which you can use. +Most parameters have a default and can thus be left out of not needed. + +```swift + +``` + +## Aggregates +If you followed this article you should know the basics of MongoKitten aggregates. If you, at any point, need a specific stage, you can look for the stage by the MongoDB name in the documentation or make use of autocomplete. +All aggregates can be quickly accessed using by simply typing a dot (.) inside the pipeline array literal like you would for enum cases. This will autocomplete to all available static functions that can help you create a stage. If you miss a stage or want to create a stage manually you can do so by providing a BSONDocument like this: +let stage = Stage([ + "$match": [ + "username": [ + "$eq": "Joannis" + ] + ] +]) +The stage must be equal to the Document representation of the stage operators described here. +You can then add this stage as one of the values in the array. +Queries +MongoDB queries can work if converted to a Document. If you do this, you must either use a literal query like below or write it using the query builder described here. +let query = Query(document) +let literalQuery: Query = [ + "age": [ + "$gte": 15 + ] +] +Sorting and Projecting +Sorts and projections have quite a bit of sugarcoating around them for readability and MongoDB-newcomers as explained here. +Both objects can be wrapped around a Document like you can with Query : +let sort = Sort(document) +let projection = Projection(document) diff --git a/3.0/docs/routing/basics.md b/3.0/docs/routing/basics.md index 12980cd7..28d7dacf 100644 --- a/3.0/docs/routing/basics.md +++ b/3.0/docs/routing/basics.md @@ -16,7 +16,7 @@ It responds with `"Hello world!"` using futures. ```swift router.on(.get, to: "hello", "world") { request in - return try Response(body: "Hello world!") + return try Response(body: "Hello world!") } ``` diff --git a/3.0/mkdocs.yml b/3.0/mkdocs.yml index 30ecb16e..b4f2b487 100644 --- a/3.0/mkdocs.yml +++ b/3.0/mkdocs.yml @@ -57,9 +57,10 @@ pages: - 'Transaction': 'fluent/transaction.md' - 'Database': 'fluent/database.md' - 'Databases': - # - 'SQLite': - # - 'Package': 'databases/sqlite/getting-started.md' - # - 'Overview': 'databases/sqlite/overview.md' + - 'MongoDB': + - 'Getting Started': 'databases/mongodb/getting-started.md' + - 'Basics': 'databases/mongodb/basics.md' + - 'Interpreting tutorials': 'databases/mongodb/interpreting.md' - 'MySQL': - 'Getting Started': 'databases/mysql/getting-started.md' - 'Basics': 'databases/mysql/basics.md'