diff --git a/docs/docs/css/syntax_highlight.css b/docs/docs/css/syntax_highlight.css index ba9cee32f..90a10cde1 100644 --- a/docs/docs/css/syntax_highlight.css +++ b/docs/docs/css/syntax_highlight.css @@ -45,3 +45,13 @@ .SyntaxHighlight-16 { color: #000088; } @media (prefers-color-scheme: dark) { .SyntaxHighlight-16 { color: #b9eeff; } } + + + + +.md-typeset__table table:not([class]) { + font-size: .74rem; +} + + + diff --git a/docs/docs/schema.md b/docs/docs/schema.md index b3508074d..bdb274603 100644 --- a/docs/docs/schema.md +++ b/docs/docs/schema.md @@ -9,18 +9,16 @@ description: Define the schema of your database. ## Overview -Drift supports defining your database schema using either Dart or SQL. This guide focuses on the Dart approach, which allows you to define your schema using Dart classes and annotations. +You can define your schema using Dart or SQL(1). Use whichever method you're most comfortable with. +{ .annotate } -#### Dart vs SQL Schema Definition +1. The SQL is type-checked at compile time and the generated code is also type-safe. + You aren't sacrificing type safety or performance if you choose to use SQL. -Whether you use Dart or SQL, Drift will generate type-safe code for database interactions. Choose whichever method you're most comfortable with. - -If you're interested in using SQL, see the [SQL Schema](./sql_schema.md) guide. +This page focuses on Dart. For the SQL approach, see the [SQL Schema](./sql_schema.md) documentation. #### Basic Example -Let's start with a simple example to illustrate how to define a table using Dart : - {{ load_snippet('superhero_schema_with_db','lib/snippets/schema.dart.excerpt.json',title="schema.dart") }} This example defines a `Superheros` table with columns for id, name, secret name, age, and height. The `AppDatabase` class ties it all together, creating a database with the `Superheros` table. @@ -33,6 +31,8 @@ In the following sections, we'll dive deeper into the various aspects of schema --- +## Tables + In Drift, a table is represented by any class which extends the `Table` class. @@ -47,7 +47,7 @@ class Categories extends Table { ``` !!! tip "Table Naming" - Table classes should be named in plural form (e.g., `Superheros`, `Categories`). This convention typically results in better-named generated classes. For more details, refer to the [Naming](#naming) section. + Table classes should be named in plural form (e.g., `Superheros`, `Categories`). This convention generally leads to more appropriately named generated classes. For more information, see the [Naming](#naming) section. ## Columns @@ -56,8 +56,6 @@ Each column in your table should be defined as a `late final` field that uses on The following table lists the built-in column types: - - | Dart Type | Drift Column | | -------------------------------- | --------------------------------------------- | | `int` | `late final id = integer()()` | @@ -68,32 +66,38 @@ The following table lists the built-in column types: | `Uint8List` | `late final image = blob()()` | | [`DateTime`](#datetime-columns) | `late final createdAt = dateTime()()` | | [`enum`](#enums) | `late final category = intEnum()()` | -| Anything Else | See [Custom Types](#custom-types) | - -By default, all columns are required (non-nullable). To make a column nullable, use the `nullable()` method. - -{{ load_snippet('optional_columns','lib/snippets/schema.dart.excerpt.json') }} - !!! note "Extra Parentheses" - Each column must end with an extra pair of parentheses. Drift will warn you if you forget them. + Each column must end with an extra pair of parentheses. + Drift will warn you if you forget them. ```dart - late final id = integer(); // Missing extra parentheses - late final id = integer()(); // Looks good + late final id = integer(); // Bad + late final id = integer()(); // ``` - + +In addition to these built-in types, you can also store custom types by converting them to one of these built-in types. See the [Custom Types](#custom-types) section for more information. + +## Required + +By default, all columns are required. To make a column optional, use the `nullable()` method. + +Example: + +{{ load_snippet('optional_columns','lib/snippets/schema.dart.excerpt.json') }} + +Now the `age` column is optional. If you try to insert a record without an `age`, it will be set to `null`. ## Defaults -To set default values for your database fields, use the `clientDefault` method. +To set default values for your database fields, use the `clientDefault()` method. {{ load_snippet('client_default','lib/snippets/schema.dart.excerpt.json') }} In the above example, the `isAdmin` field will default to `false` if no value is provided. -??? question "What's `withDefault()`" +??? question "`withDefault()`" `withDefault()` is similar to `clientDefault()`, but the default value is set in the database. @@ -116,9 +120,9 @@ In the above example, the `isAdmin` field will default to `false` if no value is ## Primary Keys -Every table in a relational database needs a primary key - a column or set of columns that uniquely identifies each row. +Every table in a relational database needs a primary key - a column (or set of columns) that uniquely identifies each row. -By default, Drift will use a single auto-incrementing integer column as the primary key. You can override this behavior by setting a custom primary key. +This is the recommended way to define a primary key for a table: ```dart class Superheros extends Table { @@ -209,11 +213,7 @@ Drift provides support for storing Dart enums in your database. Enums can be sto -## `int` & `BigInt` Columns - -For most cases, use the standard `int` type for storing integers. It's efficient and works well for typical integer values. -Only use `BigInt` if you need to store extremely large numbers, and will be compiling your app to JavaScript. `BigInt` ensures accurate representation of these large numbers in JavaScript environments, but comes with a slight performance overhead. See the dart-lang [documentation](https://dart.dev/guides/language/numbers#what-should-you-do) for more information. ## `DateTime` Columns @@ -352,4 +352,8 @@ Here is a small example showing how to use a custom check to enforce that the `a If any record is inserted with an `age` less than 0, an exception will be thrown. -Keep in mind that this check is run in the database, so if you change this check you will need to migrate the database. \ No newline at end of file +Keep in mind that this check is run in the database, so if you change this check you will need to migrate the database. + +### `BigInt` Columns + +Use the standard `int` type for storing integers as it is efficient for typical values. Only use `BigInt` for extremely large numbers when compiling to JavaScript, as it ensures accuracy but has a performance cost. For more details, refer to the dart-lang [documentation](https://dart.dev/guides/language/numbers#what-should-you-do).