From 9f6b90f25378349f79ad59841a75c7c91b82b329 Mon Sep 17 00:00:00 2001 From: tanner0101 Date: Tue, 13 Mar 2018 21:19:13 -0400 Subject: [PATCH] deploy --- build/3.0/fluent/models/index.html | 2 +- build/3.0/search/search_index.json | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/build/3.0/fluent/models/index.html b/build/3.0/fluent/models/index.html index 09674537..8bfec57b 100644 --- a/build/3.0/fluent/models/index.html +++ b/build/3.0/fluent/models/index.html @@ -1622,7 +1622,7 @@

Models are the heart of Fluent. Unlike ORMs in other languages, Fluent doesn't return untyped arrays or dictionaries for queries. Instead, you query the database using models. This allows the Swift compiler to catch many errors that have burdened ORM users for ages.

Info

-

This guide provides an overview of the Model protocol and its associated methods and properties. If you are just getting started, check find the guide for your database at Fluent → Getting Started.

+

This guide provides an overview of the Model protocol and its associated methods and properties. If you are just getting started, check out the guide for your database at Fluent → Getting Started.

Model is a protocol in the Fluent module. It extends the AnyModel protocol which can be used for type-erasure.

Conformance

diff --git a/build/3.0/search/search_index.json b/build/3.0/search/search_index.json index 0bd4cb19..944b068e 100644 --- a/build/3.0/search/search_index.json +++ b/build/3.0/search/search_index.json @@ -692,12 +692,12 @@ }, { "location": "/fluent/models/", - "text": "Fluent Models\n\n\nModels are the heart of Fluent. Unlike ORMs in other languages, Fluent doesn't return untyped arrays or dictionaries for queries. Instead, you query the database using models. This allows the Swift compiler to catch many errors that have burdened ORM users for ages.\n\n\n\n\nInfo\n\n\nThis guide provides an overview of the \nModel\n protocol and its associated methods and properties. If you are just getting started, check find the guide for your database at \nFluent \n Getting Started\n.\n\n\n\n\nModel\n is a protocol in the \nFluent\n module. It extends the \nAnyModel\n protocol which can be used for type-erasure. \n\n\nConformance\n\n\nBoth \nstruct\ns and \nclass\nes can conform to \nModel\n, however you must pay special attention to Fluent's return types if you use a \nstruct\n. Since Fluent works asynchronously, any mutations to a value-type (\nstruct\n) model must return a new copy of the model as a future result.\n\n\nNormally, you will conform your model to one of the convenience models available in your database-specific package (i.e., \nPostgreSQLModel\n). However, if you want to customize additional properties, such as the model's \nidKey\n, you will want to use the \nModel\n protocol itself.\n\n\nLet's take a look at what a basic \nModel\n conformance looks like.\n\n\n/// A simple user.\n\n\nfinal\n \nclass\n \nUser\n:\n \nModel\n \n{\n\n \n/// See `Model.Database`\n\n \ntypealias\n \nDatabase\n \n=\n \nFooDatabase\n\n\n \n/// See `Model.ID`\n\n \ntypealias\n \nID\n \n=\n \nInt\n\n\n \n/// See `Model.idKey`\n\n \nstatic\n \nlet\n \nidKey\n:\n \nIDKey\n \n=\n \n\\\n.\nid\n\n\n \n/// The unique identifier for this user.\n\n \nvar\n \nid\n:\n \nInt\n?\n\n\n \n/// The user\ns full name.\n\n \nvar\n \nname\n:\n \nString\n\n\n \n/// The user\ns current age in years.\n\n \nvar\n \nage\n:\n \nInt\n\n\n \n/// Creates a new user.\n\n \ninit\n(\nid\n:\n \nInt\n?\n \n=\n \nnil\n,\n \nname\n:\n \nString\n,\n \nage\n:\n \nInt\n)\n \n{\n\n \nself\n.\nid\n \n=\n \nid\n\n \nself\n.\nname\n \n=\n \nname\n\n \nself\n.\nage\n \n=\n \nage\n\n \n}\n\n\n}\n\n\n\n\n\n\n\n\nTip\n\n\nUsing \nfinal\n prevents your class from being sub-classed. This makes your life easier.\n\n\n\n\nAssociated Types\n\n\nModel\n defines a few associated types that help Fluent create type-safe APIs for you to use. Take a look at \nAnyModel\n if you need a type-erased version with no associated types.\n\n\nDatabase\n\n\nThis type indicates to Fluent which database you intend to use with this model. Using this information, Fluent can dynamically add appropriate methods and data types to any \nQueryBuilder\ns you create with this model.\n\n\nfinal\n \nclass\n \nUser\n:\n \nModel\n \n{\n\n \n/// See `Model.Database`\n\n \ntypealias\n \nDatabase\n \n=\n \nFooDatabase\n\n \n/// ...\n\n\n}\n\n\n\n\n\n\nIt is possible to make this associated type generic by adding a generic type to your class or struct (i.e, \nUser\nT\n). This is useful for cases where you are attempting to create generic extensions to Fluent, like perhaps an additive service provider.\n\n\nfinal\n \nclass\n \nUser\nD\n:\n \nModel\n \nwhere\n \nD\n:\n \nDatabase\n \n{\n\n \n/// See `Model.Database`\n\n \ntypealias\n \nDatabase\n \n=\n \nD\n\n \n/// ...\n\n\n}\n\n\n\n\n\n\nYou can add further conditions to \nD\n, such as \nQuerySupporting\n or \nSchemaSupporting\n. You can also dynamically extend and conform your generic model using \nextension User where D: ... { }\n.\n\n\nThat said, for most cases, you should stick to using a concrete type-alias wherever possible. Fluent 3 is designed to allow you to harness the power of your database by creating a strong connection between your models and the underlying driver. \n\n\nID\n\n\nThis property defines the type your model will use for its unique identifier.\n\n\nfinal\n \nclass\n \nUser\n:\n \nModel\n \n{\n\n \n/// See `Model.ID`\n\n \ntypealias\n \nID\n \n=\n \nUUID\n\n \n/// ...\n\n\n}\n\n\n\n\n\n\nThis will usually be something like \nInt\n, \nUUID\n, or \nString\n although you can theoretically use any type you like.\n\n\nProperties\n\n\nThere are several overridable properties on \nModel\n that you can use to customize how Fluent interacts with your database.\n\n\nName\n\n\nThis \nString\n will be used as a unique identifier for your model whenever Fluent needs one.\n\n\nfinal\n \nclass\n \nUser\n:\n \nModel\n \n{\n\n \n/// See `Model.name`\n\n \nstatic\n \nlet\n \nname\n \n=\n \nuser\n\n \n/// ...\n\n\n}\n\n\n\n\n\n\nBy default, this is the type name of your model lowercased.\n\n\nEntity\n\n\nEntity is a generic word used to mean either \"table\" or \"collection\", depending on which type of backend you are using for Fluent.\n\n\nfinal\n \nclass\n \nGoose\n:\n \nModel\n \n{\n\n \n/// See `Model.entity`\n\n \nstatic\n \nlet\n \nentity\n \n=\n \ngeese\n\n \n/// ...\n\n\n}\n\n\n\n\n\n\nBy default, this property will be \nname\n pluralized. Overriding this property is useful in situations where language fails you and the plural form of a word is very irregular.\n\n\nID Key\n\n\nThe ID key is a writeable \nkey path\n that points to your model's unique identifier property.\n\n\nUsually this will be a property named \nid\n (for some databases it is \n_id\n). However you can theoretically use any key you like.\n\n\nfinal\n \nclass\n \nUser\n:\n \nModel\n \n{\n\n \n/// See `Model.ID`\n\n \ntypealias\n \nID\n \n=\n \nString\n\n\n \n/// See `Model.entity`\n\n \nstatic\n \nlet\n \nidKey\n \n=\n \n\\\n.\nusername\n\n\n \n/// The user\ns unique username\n\n \nvar\n \nusername\n:\n \nString\n?\n\n\n \n/// ...\n\n\n}\n\n\n\n\n\n\nThe \nidKey\n property must point to an optional, writeable (\nvar\n) property with type matching \nID\n.\n\n\nLifecycle\n\n\nThere are several lifecycle methods on \nModel\n that you can override to hook into Fluent events.\n\n\n\n\n\n\n\n\nmethod\n\n\ndescription\n\n\nthrowing\n\n\n\n\n\n\n\n\n\n\nwillCreate\n\n\nCalled before Fluent saves your model (for the first time)\n\n\nCancels the save.\n\n\n\n\n\n\ndidCreate\n\n\nCalled after Fluent saves your model (for the first time)\n\n\nSave completes. Query fails.\n\n\n\n\n\n\nwillUpdate\n\n\nCalled before Fluent saves your model (subsequent saves)\n\n\nCancels the save.\n\n\n\n\n\n\ndidUpdate\n\n\nCalled after Fluent saves your model (subsequent saves)\n\n\nSave completes. Query fails.\n\n\n\n\n\n\nwillRead\n\n\nCalled before Fluent returns your model from a fetch query.\n\n\nCancels the fetch.\n\n\n\n\n\n\nwillDelete\n\n\nCalled before Fluent deletes your model.\n\n\nCancels the delete.\n\n\n\n\n\n\n\n\nHere's an example of overriding the \nwillUpdate(on:)\n method.\n\n\nfinal\n \nclass\n \nUser\n:\n \nModel\n \n{\n\n \n/// ...\n\n\n \n/// See `Model.willUpdate(on:)`\n\n \nfunc\n \nwillUpdate\n(\non\n \nconnection\n:\n \nDatabase\n.\nConnection\n)\n \nthrows\n \n-\n \nFuture\nSelf\n \n{\n\n \n/// Throws an error if the username is invalid\n\n \ntry\n \nvalidateUsername\n()\n\n\n \n/// Return the user. No async work is being done, so we must create a future manually.\n\n \nreturn\n \nFuture\n.\nmap\n(\non\n:\n \nconnection\n)\n \n{\n \nself\n \n}\n\n \n}\n\n\n}\n\n\n\n\n\n\nCRUD\n\n\nThe model offers basic CRUD method (create, read, update, delete).\n\n\nCreate\n\n\nThis method creates a new row / item for an instance of your model in the database.\n\n\nIf your model does not have an ID, calls to \n.save(on:)\n will redirect to this method.\n\n\nlet\n \ndidCreate\n \n=\n \nuser\n.\ncreate\n(\non\n:\n \nreq\n)\n\n\nprint\n(\ndidCreate\n)\n \n/// Future\nUser\n\n\n\n\n\n\n\n\nInfo\n\n\nIf you are using a value-type (\nstruct\n), the instance of your model returned by \n.create(on:)\n will contain the model's new ID.\n\n\n\n\nRead\n\n\nTwo methods are important for reading your model from the database, \nfind(_:on:)\n and \nquery(on:)\n.\n\n\n/// Finds a user with ID == 1\n\n\nlet\n \nuser\n \n=\n \nUser\n.\nfind\n(\n1\n,\n \non\n:\n \nreq\n)\n\n\nprint\n(\nuser\n)\n \n/// Future\nUser?\n\n\n\n\n\n\n/// Finds all users with name == \nVapor\n\n\nlet\n \nusers\n \n=\n \nUser\n.\nquery\n(\non\n:\n \nreq\n).\nfilter\n(\n\\\n.\nname\n \n==\n \nVapor\n).\nall\n()\n\n\nprint\n(\nusers\n)\n \n/// Future\n[User]\n\n\n\n\n\n\nUpdate\n\n\nThis method updates the existing row / item associated with an instance of your model in the database.\n\n\nIf your model already has an ID, calls to \n.save(on:)\n will redirect to this method.\n\n\n/// Updates the user\n\n\nlet\n \ndidUpdate\n \n=\n \nuser\n.\nupdate\n(\non\n:\n \nreq\n)\n\n\nprint\n(\ndidUpdate\n)\n \n/// Future\nUser\n\n\n\n\n\n\nDelete\n\n\nThis method deletes the existing row / item associated with an instance of your model from the database.\n\n\n/// Deletes the user\n\n\nlet\n \ndidDelete\n \n=\n \nuser\n.\ndelete\n(\non\n:\n \nreq\n)\n\n\nprint\n(\ndidDelete\n)\n \n/// Future\nVoid\n\n\n\n\n\n\nMethods\n\n\nModel\n offers some convenience methods to make working with it easier.\n\n\nRequire ID\n\n\nThis method return's the models ID or throws an error.\n\n\nlet\n \nid\n \n=\n \ntry\n \nuser\n.\nrequireID\n()", + "text": "Fluent Models\n\n\nModels are the heart of Fluent. Unlike ORMs in other languages, Fluent doesn't return untyped arrays or dictionaries for queries. Instead, you query the database using models. This allows the Swift compiler to catch many errors that have burdened ORM users for ages.\n\n\n\n\nInfo\n\n\nThis guide provides an overview of the \nModel\n protocol and its associated methods and properties. If you are just getting started, check out the guide for your database at \nFluent \n Getting Started\n.\n\n\n\n\nModel\n is a protocol in the \nFluent\n module. It extends the \nAnyModel\n protocol which can be used for type-erasure. \n\n\nConformance\n\n\nBoth \nstruct\ns and \nclass\nes can conform to \nModel\n, however you must pay special attention to Fluent's return types if you use a \nstruct\n. Since Fluent works asynchronously, any mutations to a value-type (\nstruct\n) model must return a new copy of the model as a future result.\n\n\nNormally, you will conform your model to one of the convenience models available in your database-specific package (i.e., \nPostgreSQLModel\n). However, if you want to customize additional properties, such as the model's \nidKey\n, you will want to use the \nModel\n protocol itself.\n\n\nLet's take a look at what a basic \nModel\n conformance looks like.\n\n\n/// A simple user.\n\n\nfinal\n \nclass\n \nUser\n:\n \nModel\n \n{\n\n \n/// See `Model.Database`\n\n \ntypealias\n \nDatabase\n \n=\n \nFooDatabase\n\n\n \n/// See `Model.ID`\n\n \ntypealias\n \nID\n \n=\n \nInt\n\n\n \n/// See `Model.idKey`\n\n \nstatic\n \nlet\n \nidKey\n:\n \nIDKey\n \n=\n \n\\\n.\nid\n\n\n \n/// The unique identifier for this user.\n\n \nvar\n \nid\n:\n \nInt\n?\n\n\n \n/// The user\ns full name.\n\n \nvar\n \nname\n:\n \nString\n\n\n \n/// The user\ns current age in years.\n\n \nvar\n \nage\n:\n \nInt\n\n\n \n/// Creates a new user.\n\n \ninit\n(\nid\n:\n \nInt\n?\n \n=\n \nnil\n,\n \nname\n:\n \nString\n,\n \nage\n:\n \nInt\n)\n \n{\n\n \nself\n.\nid\n \n=\n \nid\n\n \nself\n.\nname\n \n=\n \nname\n\n \nself\n.\nage\n \n=\n \nage\n\n \n}\n\n\n}\n\n\n\n\n\n\n\n\nTip\n\n\nUsing \nfinal\n prevents your class from being sub-classed. This makes your life easier.\n\n\n\n\nAssociated Types\n\n\nModel\n defines a few associated types that help Fluent create type-safe APIs for you to use. Take a look at \nAnyModel\n if you need a type-erased version with no associated types.\n\n\nDatabase\n\n\nThis type indicates to Fluent which database you intend to use with this model. Using this information, Fluent can dynamically add appropriate methods and data types to any \nQueryBuilder\ns you create with this model.\n\n\nfinal\n \nclass\n \nUser\n:\n \nModel\n \n{\n\n \n/// See `Model.Database`\n\n \ntypealias\n \nDatabase\n \n=\n \nFooDatabase\n\n \n/// ...\n\n\n}\n\n\n\n\n\n\nIt is possible to make this associated type generic by adding a generic type to your class or struct (i.e, \nUser\nT\n). This is useful for cases where you are attempting to create generic extensions to Fluent, like perhaps an additive service provider.\n\n\nfinal\n \nclass\n \nUser\nD\n:\n \nModel\n \nwhere\n \nD\n:\n \nDatabase\n \n{\n\n \n/// See `Model.Database`\n\n \ntypealias\n \nDatabase\n \n=\n \nD\n\n \n/// ...\n\n\n}\n\n\n\n\n\n\nYou can add further conditions to \nD\n, such as \nQuerySupporting\n or \nSchemaSupporting\n. You can also dynamically extend and conform your generic model using \nextension User where D: ... { }\n.\n\n\nThat said, for most cases, you should stick to using a concrete type-alias wherever possible. Fluent 3 is designed to allow you to harness the power of your database by creating a strong connection between your models and the underlying driver. \n\n\nID\n\n\nThis property defines the type your model will use for its unique identifier.\n\n\nfinal\n \nclass\n \nUser\n:\n \nModel\n \n{\n\n \n/// See `Model.ID`\n\n \ntypealias\n \nID\n \n=\n \nUUID\n\n \n/// ...\n\n\n}\n\n\n\n\n\n\nThis will usually be something like \nInt\n, \nUUID\n, or \nString\n although you can theoretically use any type you like.\n\n\nProperties\n\n\nThere are several overridable properties on \nModel\n that you can use to customize how Fluent interacts with your database.\n\n\nName\n\n\nThis \nString\n will be used as a unique identifier for your model whenever Fluent needs one.\n\n\nfinal\n \nclass\n \nUser\n:\n \nModel\n \n{\n\n \n/// See `Model.name`\n\n \nstatic\n \nlet\n \nname\n \n=\n \nuser\n\n \n/// ...\n\n\n}\n\n\n\n\n\n\nBy default, this is the type name of your model lowercased.\n\n\nEntity\n\n\nEntity is a generic word used to mean either \"table\" or \"collection\", depending on which type of backend you are using for Fluent.\n\n\nfinal\n \nclass\n \nGoose\n:\n \nModel\n \n{\n\n \n/// See `Model.entity`\n\n \nstatic\n \nlet\n \nentity\n \n=\n \ngeese\n\n \n/// ...\n\n\n}\n\n\n\n\n\n\nBy default, this property will be \nname\n pluralized. Overriding this property is useful in situations where language fails you and the plural form of a word is very irregular.\n\n\nID Key\n\n\nThe ID key is a writeable \nkey path\n that points to your model's unique identifier property.\n\n\nUsually this will be a property named \nid\n (for some databases it is \n_id\n). However you can theoretically use any key you like.\n\n\nfinal\n \nclass\n \nUser\n:\n \nModel\n \n{\n\n \n/// See `Model.ID`\n\n \ntypealias\n \nID\n \n=\n \nString\n\n\n \n/// See `Model.entity`\n\n \nstatic\n \nlet\n \nidKey\n \n=\n \n\\\n.\nusername\n\n\n \n/// The user\ns unique username\n\n \nvar\n \nusername\n:\n \nString\n?\n\n\n \n/// ...\n\n\n}\n\n\n\n\n\n\nThe \nidKey\n property must point to an optional, writeable (\nvar\n) property with type matching \nID\n.\n\n\nLifecycle\n\n\nThere are several lifecycle methods on \nModel\n that you can override to hook into Fluent events.\n\n\n\n\n\n\n\n\nmethod\n\n\ndescription\n\n\nthrowing\n\n\n\n\n\n\n\n\n\n\nwillCreate\n\n\nCalled before Fluent saves your model (for the first time)\n\n\nCancels the save.\n\n\n\n\n\n\ndidCreate\n\n\nCalled after Fluent saves your model (for the first time)\n\n\nSave completes. Query fails.\n\n\n\n\n\n\nwillUpdate\n\n\nCalled before Fluent saves your model (subsequent saves)\n\n\nCancels the save.\n\n\n\n\n\n\ndidUpdate\n\n\nCalled after Fluent saves your model (subsequent saves)\n\n\nSave completes. Query fails.\n\n\n\n\n\n\nwillRead\n\n\nCalled before Fluent returns your model from a fetch query.\n\n\nCancels the fetch.\n\n\n\n\n\n\nwillDelete\n\n\nCalled before Fluent deletes your model.\n\n\nCancels the delete.\n\n\n\n\n\n\n\n\nHere's an example of overriding the \nwillUpdate(on:)\n method.\n\n\nfinal\n \nclass\n \nUser\n:\n \nModel\n \n{\n\n \n/// ...\n\n\n \n/// See `Model.willUpdate(on:)`\n\n \nfunc\n \nwillUpdate\n(\non\n \nconnection\n:\n \nDatabase\n.\nConnection\n)\n \nthrows\n \n-\n \nFuture\nSelf\n \n{\n\n \n/// Throws an error if the username is invalid\n\n \ntry\n \nvalidateUsername\n()\n\n\n \n/// Return the user. No async work is being done, so we must create a future manually.\n\n \nreturn\n \nFuture\n.\nmap\n(\non\n:\n \nconnection\n)\n \n{\n \nself\n \n}\n\n \n}\n\n\n}\n\n\n\n\n\n\nCRUD\n\n\nThe model offers basic CRUD method (create, read, update, delete).\n\n\nCreate\n\n\nThis method creates a new row / item for an instance of your model in the database.\n\n\nIf your model does not have an ID, calls to \n.save(on:)\n will redirect to this method.\n\n\nlet\n \ndidCreate\n \n=\n \nuser\n.\ncreate\n(\non\n:\n \nreq\n)\n\n\nprint\n(\ndidCreate\n)\n \n/// Future\nUser\n\n\n\n\n\n\n\n\nInfo\n\n\nIf you are using a value-type (\nstruct\n), the instance of your model returned by \n.create(on:)\n will contain the model's new ID.\n\n\n\n\nRead\n\n\nTwo methods are important for reading your model from the database, \nfind(_:on:)\n and \nquery(on:)\n.\n\n\n/// Finds a user with ID == 1\n\n\nlet\n \nuser\n \n=\n \nUser\n.\nfind\n(\n1\n,\n \non\n:\n \nreq\n)\n\n\nprint\n(\nuser\n)\n \n/// Future\nUser?\n\n\n\n\n\n\n/// Finds all users with name == \nVapor\n\n\nlet\n \nusers\n \n=\n \nUser\n.\nquery\n(\non\n:\n \nreq\n).\nfilter\n(\n\\\n.\nname\n \n==\n \nVapor\n).\nall\n()\n\n\nprint\n(\nusers\n)\n \n/// Future\n[User]\n\n\n\n\n\n\nUpdate\n\n\nThis method updates the existing row / item associated with an instance of your model in the database.\n\n\nIf your model already has an ID, calls to \n.save(on:)\n will redirect to this method.\n\n\n/// Updates the user\n\n\nlet\n \ndidUpdate\n \n=\n \nuser\n.\nupdate\n(\non\n:\n \nreq\n)\n\n\nprint\n(\ndidUpdate\n)\n \n/// Future\nUser\n\n\n\n\n\n\nDelete\n\n\nThis method deletes the existing row / item associated with an instance of your model from the database.\n\n\n/// Deletes the user\n\n\nlet\n \ndidDelete\n \n=\n \nuser\n.\ndelete\n(\non\n:\n \nreq\n)\n\n\nprint\n(\ndidDelete\n)\n \n/// Future\nVoid\n\n\n\n\n\n\nMethods\n\n\nModel\n offers some convenience methods to make working with it easier.\n\n\nRequire ID\n\n\nThis method return's the models ID or throws an error.\n\n\nlet\n \nid\n \n=\n \ntry\n \nuser\n.\nrequireID\n()", "title": "Models" }, { "location": "/fluent/models/#fluent-models", - "text": "Models are the heart of Fluent. Unlike ORMs in other languages, Fluent doesn't return untyped arrays or dictionaries for queries. Instead, you query the database using models. This allows the Swift compiler to catch many errors that have burdened ORM users for ages. Info This guide provides an overview of the Model protocol and its associated methods and properties. If you are just getting started, check find the guide for your database at Fluent Getting Started . Model is a protocol in the Fluent module. It extends the AnyModel protocol which can be used for type-erasure.", + "text": "Models are the heart of Fluent. Unlike ORMs in other languages, Fluent doesn't return untyped arrays or dictionaries for queries. Instead, you query the database using models. This allows the Swift compiler to catch many errors that have burdened ORM users for ages. Info This guide provides an overview of the Model protocol and its associated methods and properties. If you are just getting started, check out the guide for your database at Fluent Getting Started . Model is a protocol in the Fluent module. It extends the AnyModel protocol which can be used for type-erasure.", "title": "Fluent Models" }, {