Improve model guide by ElijahAhianyo · Pull Request #515 · cot-rs/cot

ElijahAhianyo · 2026-03-20T17:24:00Z

Restructure the Docs, starting with the model docs. I've improved the docs to mention a large number of features/functionalities we support. I've also split the docs to span across multiple pages in a subcategory, making it easier and nicer to follow. Currently, we have 2 pages (overview and queries) for Models. The overview section is a bit nuanced as it makes mention of the CotORM, setting up models, and configuring them.

There's also a section of Relationships which I believe deserves its own page once we have the M2M feature implemented(or we can still put this in its own page and show how to do this using an intermediate through Model).

I would like to add another page for migrations, however, I'm keeping this PR ready at all times for review. Subsequent additions may or may not be included to this PR depending on when this gets merged

Related issue or discussion

Description

Type of change

Checklist

I've read the contributing guide
Tests pass locally (just test-all)
Code passes clippy (just clippy)
Code is properly formatted (cargo fmt)
New tests added (regression test for bugs, coverage for new features)
Documentation (both code and site) updated (if applicable)

github-actions · 2026-03-20T17:28:15Z

Bencher Report

Branch	elijah/model-docs-improve
Testbed	github-ubuntu-latest

Click to view all benchmark results

Benchmark	Latency	Benchmark Result milliseconds (ms) (Result Δ%)	Upper Boundary milliseconds (ms) (Limit %)
empty_router/empty_router	📈 view plot 🚷 view threshold	6.67 ms (+9.13%) Baseline: 6.11 ms	7.65 ms (87.24%)
json_api/json_api	📈 view plot 🚷 view threshold	1.20 ms (+11.55%) Baseline: 1.07 ms	1.31 ms (91.30%)
nested_routers/nested_routers	📈 view plot 🚷 view threshold	1.11 ms (+12.09%) Baseline: 0.99 ms	1.20 ms (92.97%)
single_root_route/single_root_route	📈 view plot 🚷 view threshold	1.05 ms (+10.02%) Baseline: 0.95 ms	1.16 ms (90.63%)
single_root_route_burst/single_root_route_burst	📈 view plot 🚷 view threshold	17.38 ms (-1.76%) Baseline: 17.69 ms	21.19 ms (82.01%)

🐰 View full continuous benchmarking report in Bencher

codecov · 2026-03-20T18:05:10Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

Flag	Coverage Δ
rust	`89.99% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

ElijahAhianyo · 2026-03-31T23:20:29Z

depends on cot-rs/cot-site#82 and cot-rs/cot-site#84

ElijahAhianyo · 2026-04-02T16:54:00Z

ElijahAhianyo · 2026-04-09T17:18:59Z

+
+```
+
+## Summary


Some pages have a Summary section while others don't. I'm not too sure which direction we'd want to go, but for the sake of consistency, do we require every page to have a Summary section? I, personally, am not a big fan, but I'm also indifferent if we have them or not

I'm also indifferent if we have them or not, I'd just push on being consistent and having them everywhere or nowhere

m4tx

Amazing stuff! There are some issues here and there - please make the changes before we can merge this.

Also, sometimes you put an additional newline after section headers, sometimes you do not - please make this consistent with the rest of the guides.

m4tx · 2026-05-11T16:39:42Z

+#[derive(Debug, Clone)]
+struct NewType(i32);
+
+impl FromDbValue for NewType {


I'm not exactly happy with how closely tied this is to the specific database backend one can use. I would expect this to be changed in the future when we'll finally land the ORM refactor.

I think it's fine to keep it as-is because there's not much we can do about this for now, but just adding this as a general comment.

m4tx · 2026-05-11T16:42:16Z

+struct MyProject;
+
+impl Project for MyProject {
+    fn config(&self) -> cot::Result<ProjectConfig> {


I'm not sure if it's good to put this here. The side effect of such change is that after adding this code, the TOML config will be completely ignored, which might be not what user might want.

I'd suggest either mentioning this (something in the lines of "keep in mind that adding this code will cause the TOML config to be ignored for other config parameters as well"), or remove this section altogether.

Got it, I think I'd prefer explicitly mentioning the side effect than taking out the section altogether

m4tx · 2026-05-11T16:45:55Z

+Saving a foreign key field is similar to saving a regular field. There are two variants of foreign key fields provided by cot:
+
+### `ForeignKey::Model`
+This is the most common variant which allows you to save a foreign key field with a model instance.


It might be worth noting that the instance needs to be saved to the database first.

mm, I'm struggling to make sense of how this fits into the sentence.

Something like this?

Remember, the instance the foreign key points to needs to be saved to the database before the instance containing the foreign key.

seqre · 2026-05-14T08:44:54Z

+Cot comes with its own ORM (Object-Relational Mapping) system, which is a layer of abstraction that allows you to interact with your database using objects instead of raw SQL queries. This makes it easier to work with your database and allows you to write more maintainable code. It abstracts over the specific database engine that you are using, so you can switch between different databases without changing your code. The Cot ORM is also capable of automatically creating migrations for you, so you can easily update your database schema as your application evolves, just by modifying the corresponding Rust structures.
+
+## Defining models
+To define a model in Cot, you need to create a new Rust structure that implements the [`Model`](trait@cot::db::Model) trait. This trait requires you to define the name of the table that the model corresponds to, as well as the fields that the table should have. Here's an example of a simple model that represents a link in a link shortener service:


I'd mention that while the trait requires all of that, we've created #[model] macro that does most of that for you. Otherwise we mention that you have to do that and then don't do that in the example

seqre · 2026-05-14T08:47:14Z

+
+There's some very useful stuff going on here, so let's break it down:
+
+* The [`#[model]`](attr@cot::db::model) attribute is used to mark the structure as a model. This is required for the Cot ORM to recognize it as such.


sth like this

Suggested change

* The [`#[model]`](attr@cot::db::model) attribute is used to mark the structure as a model. This is required for the Cot ORM to recognize it as such.

* The [`#[model]`](attr@cot::db::model) attribute macro is used to automatically implement the [`Model`](trait@cot::db::Model) trait for the structure. This is required for the Cot ORM to recognize it as a database model.

seqre · 2026-05-14T08:52:19Z

+```
+
+### `unique`
+This is used to mark a field as unique, which means that each value in this field must be unique across all rows in the table. For more information see the [model field reference](https://docs.rs/cot_macros/0.5.0/cot_macros/attr.model.html).


Shouldn't the link link to the latest version?

seqre · 2026-05-14T08:53:26Z

+```
+
+## Field Types
+To use a type in a model, they **must** implement the [`ToDbValue`](trait@cot::db::ToDbValue) and [`FromDbValue`](trait@cot::db::FromDbValue) traits. The [`ToDbValue`](trait@cot::db::ToDbValue) trait tells Cot how to serialize the field value into a format that can be stored in the database (e.g. a string, a number, a boolean, etc.) while the [`FromDbValue`](trait@cot::db::FromDbValue) trait tells Cot how to deserialize the field value from the database format back into the Rust type.


Suggested change

To use a type in a model, they **must** implement the [`ToDbValue`](trait@cot::db::ToDbValue) and [`FromDbValue`](trait@cot::db::FromDbValue) traits. The [`ToDbValue`](trait@cot::db::ToDbValue) trait tells Cot how to serialize the field value into a format that can be stored in the database (e.g. a string, a number, a boolean, etc.) while the [`FromDbValue`](trait@cot::db::FromDbValue) trait tells Cot how to deserialize the field value from the database format back into the Rust type.

To use a type in a model, it **must** implement the [`ToDbValue`](trait@cot::db::ToDbValue) and [`FromDbValue`](trait@cot::db::FromDbValue) traits. The [`ToDbValue`](trait@cot::db::ToDbValue) trait tells Cot how to serialize the field value into a format that can be stored in the database (e.g. a string, a number, a boolean, etc.) while the [`FromDbValue`](trait@cot::db::FromDbValue) trait tells Cot how to deserialize the field value from the database format back into the Rust type.

seqre · 2026-05-14T08:57:22Z

+As an alternative to setting the database configuration in the `TOML` file, you can also set it programmatically in the [`config`](trait@cot::project::Project#method.config) method of your project.
+Note that when you do this, the config values from the `TOML` file will be entirely ignored.
+
+Here's an example of how you can set the database configuration programmatically:


nit:

Suggested change

As an alternative to setting the database configuration in the `TOML` file, you can also set it programmatically in the [`config`](trait@cot::project::Project#method.config) method of your project.

Note that when you do this, the config values from the `TOML` file will be entirely ignored.

Here's an example of how you can set the database configuration programmatically:

As an alternative to setting the database configuration in the `TOML` file, you can also set it programmatically in the [`config`](trait@cot::project::Project#method.config) method of your project.

Note that when you do this, the config values from the `TOML` file will be entirely ignored. Here's an example of how you can do that:

seqre · 2026-05-14T09:07:08Z

+Saving a foreign key field is similar to saving a regular field. There are two variants of foreign key fields provided by cot:
+
+### `ForeignKey::Model`
+This is the most common variant which allows you to save a foreign key field with a model instance.


Something like this?

Remember, the instance the foreign key points to needs to be saved to the database before the instance containing the foreign key.

seqre · 2026-05-14T09:11:07Z

+results of a query.The [`Query`](struct@cot::db::query::Query) object can be accessed by calling the [`objects`](trait@cot::db::Model#method.objects) method on the model. The example below shows how to retrieve a
+Customer instance with the primary key of `5`.


nit:

Suggested change

results of a query.The [`Query`](struct@cot::db::query::Query) object can be accessed by calling the [`objects`](trait@cot::db::Model#method.objects) method on the model. The example below shows how to retrieve a

Customer instance with the primary key of `5`.

results of a query. The [`Query`](struct@cot::db::query::Query) object can be accessed by calling the [`objects`](trait@cot::db::Model#method.objects) method on the model. The example below shows how to retrieve a Customer instance with the primary key of `5`.

seqre · 2026-05-14T09:11:45Z

+The [`filter`](struct@cot::db::query::Query#method.filter) method takes a [`filter expression`](enum@cot::db::query::Expr). In the example above, the expression, `Expr::eq(Expr::field("id"), Expr::value("5"))`, is
+evaluated as `id = 5`.


nit:

Suggested change

The [`filter`](struct@cot::db::query::Query#method.filter) method takes a [`filter expression`](enum@cot::db::query::Expr). In the example above, the expression, `Expr::eq(Expr::field("id"), Expr::value("5"))`, is

evaluated as `id = 5`.

The [`filter`](struct@cot::db::query::Query#method.filter) method takes a [`filter expression`](enum@cot::db::query::Expr). In the example above, the expression, `Expr::eq(Expr::field("id"), Expr::value("5"))`, is evaluated as `id = 5`.

seqre · 2026-05-14T09:12:06Z

+Cot also provides the [`query!`](macro@cot::db::query) macro which provides a convenient way to write queries in a declarative style without having to manually construct [`Expr`](enum@cot::db::query::Expr) expressions.
+The example above can be rewritten as follows:


nit:

Suggested change

Cot also provides the [`query!`](macro@cot::db::query) macro which provides a convenient way to write queries in a declarative style without having to manually construct [`Expr`](enum@cot::db::query::Expr) expressions.

The example above can be rewritten as follows:

Cot also provides the [`query!`](macro@cot::db::query) macro which provides a convenient way to write queries in a declarative style without having to manually construct [`Expr`](enum@cot::db::query::Expr) expressions. The example above can be rewritten as follows:

seqre · 2026-05-14T09:13:22Z

+
+Note that this will fail if the primary key of the referenced model does not exist.
+
+## Retrieving objects


I think I'd start with the query!() macro to show how easy it is, and then show the manual way it's implemented inside it.

Improve model guide

c675cb2

break db docs into multiple pages

6043d59

github-actions Bot added the A-docs Area: Documentation label Mar 31, 2026

pre-commit-ci Bot and others added 2 commits March 31, 2026 23:18

chore(pre-commit.ci): auto fixes from pre-commit hooks

e28805f

Merge branch 'master' into elijah/model-docs-improve

b5f5dc4

change md_page to support new GuideItem syntax on cot-site

228717f

ElijahAhianyo mentioned this pull request Apr 2, 2026

Add Support for Subcategories in Guide cot-rs/cot-site#84

Open

ElijahAhianyo and others added 5 commits April 5, 2026 00:21

fix links

9f50f27

chore(pre-commit.ci): auto fixes from pre-commit hooks

4a03543

add some more docs on model field types and db config

bfe8228

delete db-models file

5019b83

Merge branch 'master' into elijah/model-docs-improve

08100cd

ElijahAhianyo commented Apr 9, 2026

View reviewed changes

ElijahAhianyo marked this pull request as ready for review April 9, 2026 17:19

ElijahAhianyo changed the title ~~[WIP]Improve model guide~~ Improve model guide Apr 9, 2026

some small improvements

fd3992d

ElijahAhianyo requested review from m4tx and seqre April 9, 2026 17:41

ElijahAhianyo mentioned this pull request Apr 16, 2026

feat: add tests for guide code snippets #552

Open

6 tasks

m4tx requested changes May 11, 2026

View reviewed changes

ElijahAhianyo added 2 commits May 13, 2026 00:05

address most comments

1801854

Merge branch 'master' into elijah/model-docs-improve

d280b6f

seqre requested changes May 14, 2026

View reviewed changes


		There's some very useful stuff going on here, so let's break it down:

		* The [`#[model]`](attr@cot::db::model) attribute is used to mark the structure as a model. This is required for the Cot ORM to recognize it as such.

		results of a query.The [`Query`](struct@cot::db::query::Query) object can be accessed by calling the [`objects`](trait@cot::db::Model#method.objects) method on the model. The example below shows how to retrieve a
		Customer instance with the primary key of `5`.

	results of a query.The [`Query`](struct@cot::db::query::Query) object can be accessed by calling the [`objects`](trait@cot::db::Model#method.objects) method on the model. The example below shows how to retrieve a
	Customer instance with the primary key of `5`.
	results of a query. The [`Query`](struct@cot::db::query::Query) object can be accessed by calling the [`objects`](trait@cot::db::Model#method.objects) method on the model. The example below shows how to retrieve a Customer instance with the primary key of `5`.

		The [`filter`](struct@cot::db::query::Query#method.filter) method takes a [`filter expression`](enum@cot::db::query::Expr). In the example above, the expression, `Expr::eq(Expr::field("id"), Expr::value("5"))`, is
		evaluated as `id = 5`.

		Cot also provides the [`query!`](macro@cot::db::query) macro which provides a convenient way to write queries in a declarative style without having to manually construct [`Expr`](enum@cot::db::query::Expr) expressions.
		The example above can be rewritten as follows:


		Note that this will fail if the primary key of the referenced model does not exist.

		## Retrieving objects


		```

		## Summary

Uh oh!

Conversation

ElijahAhianyo commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Related issue or discussion

Description

Type of change

Checklist

Uh oh!

github-actions Bot commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

ElijahAhianyo commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ElijahAhianyo commented Apr 2, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

m4tx left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ElijahAhianyo commented Mar 20, 2026 •

edited

Loading

github-actions Bot commented Mar 20, 2026 •

edited

Loading

codecov Bot commented Mar 20, 2026 •

edited

Loading

ElijahAhianyo commented Mar 31, 2026 •

edited

Loading