New schema docs #3290

dickermoshe · 2024-10-16T19:06:48Z

This PR:

Restructures the layout of the site. This does not affect urls.
Remove Type Converter and Custom row class docs. Move into table and dataclass docs respectively
Add redirect for removed ages
rewrite table docs
Move a whole bunch of stuff into guides
Add missing CSS style

github-actions · 2024-10-16T20:09:15Z

🚀 Deployed on https://deploy-preview-3290--moor.netlify.app

simolus3

LGTM apart from the remaining comments on other pages. I can take care of them too.

simolus3 · 2024-10-27T21:03:48Z

docs/docs/_redirects

+https://drift.simonbinder.eu/custom_row_classes/ /dart_api/dataclass/
+https://drift.simonbinder.eu/type_converters/ /dart_api/tables/#custom-types


Shouldn't these be without the domain like the others above?

Yes. Remove the leading url

simolus3 · 2024-10-27T21:05:23Z

docs/docs/dart_api/dataclass.md

+
+{{ load_snippet('data-class-name','lib/snippets/dart_api/dataclass.dart.excerpt.json') }}
+
+## Json serialization


I think this should not be this far up - and there should be a little warning saying that using custom row classes is the preferred approach for JSON serialization.

Drift is a relational persistence library, and ideally shouldn't have to do anything to do with serialization. It's a historical artifact that I regret, but it's too late to fix this now.

Our serialization capabilities are incredibly restricted compared to packages that actually intend to do serialziation, which is why I recommend using custom row classes to combine drift with other libraries where necessary.

simolus3 · 2024-10-27T21:06:03Z

docs/docs/dart_api/dataclass.md

@@ -1,23 +1,112 @@
 ---

-title: Custom row classes
-description: Use your own classes as data classes for drift tables
+title: Dataclass


I'm still not too happy with the generic Dataclass name, does "Generated classes" with a description like "Overview of classes generated by drift for reading and writing to the database" work?

docs/docs/dart_api/dataclass.md

simolus3 · 2024-10-27T21:09:33Z

docs/docs/dart_api/dataclass.md

+
+<div class="annotate" markdown>
+
+{{ load_snippet('generated-companion','lib/snippets/dart_api/dataclass.dart.excerpt.json') }}


I think we should use a tabbed view here with Manager vs. the Core query builder instead of having it in a single snippet.

simolus3 · 2024-10-27T21:14:39Z

docs/docs/dart_api/dataclass.md

+### Value object
+When using the companion object to update a row, optional fields must be wrapped in a `Value` object. This is used by Drift to distinguish between `null` and not present values.
+
+{{ load_snippet('generated-value','lib/snippets/dart_api/dataclass.dart.excerpt.json') }}


This example really isn't too helpful. Values were also used in the example above for updates, perhaps we could reference that here.

This is used by Drift to distinguish between null and not present values.

A better explanation would be to mention what drift actually does with that: For updates, there's a distinction between setting the value of a column to null vs. not touching it at all. We can't represent without introducing some kind of optional structure, which is what Value is.

simolus3 · 2024-10-27T21:15:43Z

docs/docs/dart_api/expressions.md

+
+[^1]: Like bigger than 4,503,599,627,370,496!
+
+Using `dartCast<BigInt>()` will ensure that the result is interpreted as a `BigInt` by drift.


We should also note that this doesn't change the behavior in SQL at all.

simolus3 · 2024-10-27T21:16:09Z

docs/docs/dart_api/expressions.md

@@ -76,6 +76,20 @@ bitwise operations:

 {{ load_snippet('bitwise','lib/snippets/dart_api/expressions.dart.excerpt.json') }}

+### BigInt
+
+You may want to cast an expression to a `BigInt` if:


Suggested change

You may want to cast an expression to a `BigInt` if:

You may want to cast an expression to a `BigInt` if both of these apply to your app:

simolus3 · 2024-10-27T21:17:00Z

docs/docs/dart_api/expressions.md

+
+You may want to cast an expression to a `BigInt` if:
+
+- The result of an arithmetic operation will be extremely large[^1].


What's the point of being imprecise here? We can just write

Suggested change

- The result of an arithmetic operation will be extremely large[^1].

- The result of an arithmetic operation is not representable by a `double` (i.e., it is larger than `2^52`).

simolus3 · 2024-10-27T21:18:37Z

docs/docs/dart_api/manager.md

@@ -1,17 +1,11 @@
 ---

-title: Manager
+title: Queries


IMO we should leave this as-is before the restructuring is more complete. At the moment we'd then effectively have multiple pages on queries which is more confusing than before.

We can name it "Queries with Manager" or something and also point out in the introduction/getting started guide that there are two ways to write these queries (like we already do on the new table page).

Co-authored-by: Simon Binder <[email protected]>

dickermoshe added 7 commits October 15, 2024 00:03

update highlight css

523a418

temp

18e6ce3

keep olf reference docs

86c68e4

ok, great

e7488f9

lint

1f81dab

fix format

9d8e69b

fix analyze

209ae69

github-actions bot temporarily deployed to pull request October 16, 2024 20:09 Inactive

github-actions bot temporarily deployed to commit October 16, 2024 20:09 Inactive

simolus3 and others added 2 commits October 22, 2024 00:13

Rework table docs, fix broken links

7a42d73

Update tables.dart

debafa1

github-actions bot temporarily deployed to commit October 23, 2024 11:54 Inactive

github-actions bot temporarily deployed to pull request October 23, 2024 11:54 Inactive

Document new sqliteAny type

fad3b90

github-actions bot temporarily deployed to pull request October 23, 2024 19:43 Inactive

github-actions bot temporarily deployed to commit October 23, 2024 19:43 Inactive

simolus3 added 3 commits October 26, 2024 23:51

Start restructuring table docs

c46bf3a

Merge branch 'develop' into new-schema-docs

79e20f2

Highlight type converters more

bd67794

github-actions bot temporarily deployed to pull request October 26, 2024 22:05 Inactive

github-actions bot temporarily deployed to commit October 26, 2024 22:05 Inactive

small nits

eabd194

github-actions bot temporarily deployed to commit October 27, 2024 02:19 Inactive

github-actions bot temporarily deployed to pull request October 27, 2024 02:19 Inactive

simolus3 reviewed Oct 27, 2024

View reviewed changes

Update docs/docs/dart_api/dataclass.md

d94b243

Co-authored-by: Simon Binder <[email protected]>

github-actions bot temporarily deployed to commit October 28, 2024 01:23 Inactive

github-actions bot temporarily deployed to pull request October 28, 2024 01:26 Inactive

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

New schema docs #3290

New schema docs #3290

dickermoshe commented Oct 16, 2024

github-actions bot commented Oct 16, 2024 •

edited

Loading

simolus3 left a comment

simolus3 Oct 27, 2024

dickermoshe Oct 28, 2024

simolus3 Oct 27, 2024

dickermoshe Oct 28, 2024

simolus3 Oct 28, 2024

simolus3 Oct 27, 2024

simolus3 Oct 27, 2024

simolus3 Oct 27, 2024

simolus3 Oct 27, 2024

simolus3 Oct 27, 2024

simolus3 Oct 27, 2024

simolus3 Oct 27, 2024

		https://drift.simonbinder.eu/custom_row_classes/ /dart_api/dataclass/
		https://drift.simonbinder.eu/type_converters/ /dart_api/tables/#custom-types


		{{ load_snippet('data-class-name','lib/snippets/dart_api/dataclass.dart.excerpt.json') }}

		## Json serialization


		<div class="annotate" markdown>

		{{ load_snippet('generated-companion','lib/snippets/dart_api/dataclass.dart.excerpt.json') }}


		[^1]: Like bigger than 4,503,599,627,370,496!

		Using `dartCast<BigInt>()` will ensure that the result is interpreted as a `BigInt` by drift.

	You may want to cast an expression to a `BigInt` if:
	You may want to cast an expression to a `BigInt` if both of these apply to your app:


		You may want to cast an expression to a `BigInt` if:

		- The result of an arithmetic operation will be extremely large[^1].

New schema docs #3290

Are you sure you want to change the base?

New schema docs #3290

Conversation

dickermoshe commented Oct 16, 2024

github-actions bot commented Oct 16, 2024 • edited Loading

simolus3 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Oct 16, 2024 •

edited

Loading