Merge branch 'serverpod:main' into allow-set-query-options

Author: marcelomendoncasoares

docs/01-get-started/01-creating-endpoints.md

@@ -20,7 +20,6 @@ serverpod create magic_recipe
 
 :::tip
 Always open the root directory of the project in your IDE. This will make it easier to navigate between the server and app packages. It will also prevent your analyzer from going out of sync when you generate code.
-
 :::
 
 ### Add the Gemini API to your project
@@ -197,7 +196,7 @@ class MyHomePageState extends State<MyHomePage> {
 ## Run the app
 
 :::tip
-Before you start your server, ensure no other Serverpod server is running. Also, ensure that Docker for another project isn't running. You can see and stop containers in the Docker Desktop app.
+Before you start your server, ensure no other Serverpod server is running. Also, ensure that Docker containers from other Serverpod projects aren't running to avoid port conflicts. You can see and stop containers in the Docker Desktop app.
 :::
 
 Let's try our new recipe app! First, start the server:

docs/01-get-started/02-models-and-data.md

@@ -41,7 +41,7 @@ This will generate the code for the model and create a new file called `recipe.d
 
 ## Use the model in the server
 
-Now that you have created the model, you can use it in your server code. Let's update the `lib/src/recipies/recipe_endpoint.dart` file to make the `generateRecipe` method to return a `Recipe` object instead of a string.
+Now that you have created the model, you can use it in your server code. Let's update the `lib/src/recipes/recipe_endpoint.dart` file to make the `generateRecipe` method return a `Recipe` object instead of a string.
 
 <!--SNIPSTART 02-typed-endpoint  {"selectedLines": ["4", "10-12", "39-48"]}-->
 ```dart

docs/01-get-started/03-working-with-the-database.md

@@ -4,11 +4,11 @@ sidebar_label: 3. Working with the database
 
 # Working with the database
 
-In this section, we will build upon the models we created in the previous section and add a database to store our favorite recipes that we create in the app.
+In this section, we will build upon the models we created in the previous section and add a database to store the recipes that users create in the app. This will allow our application to persist data between sessions.
 
 ## Object relation mapping
 
-Any Serverpod model can be mapped to the database through Serverpod's object relation mapping (ORM). Simply add the `table` keyword to the `Recipe` model in our `recipe.spy.yaml` file. This will map the model to a new table in the database called `recipes`.
+Any Serverpod model can be mapped to the database through Serverpod's object relation mapping (ORM). To enable database storage for our recipe model, simply add the `table` keyword to the `Recipe` model in our `recipe.spy.yaml` file. This will map the model to a new table in the database called `recipes`.
 
 <!--SNIPSTART 03-table-model-->
 ```yaml
@@ -33,19 +33,24 @@ Check out the reference for [database models](../06-concepts/02-models.md#keywor
 
 ## Migrations
 
-With database migrations, Serverpod makes it easy to evolve your database schema. When you make changes to your project that should be reflected in your database, you need to create a migration. A migration is a set of SQL queries that are run to update the database. To create a migration, run `serverpod create-migration` in the home directory of the server. Since we modified one of our models, make sure to also run `serverpod generate`, to update the generated code in our server.
+Database migrations in Serverpod provide a way to safely evolve your database schema over time. When you make changes to your models that affect the database structure, you need to create a migration. A migration consists of SQL queries that update the database schema to match your model changes.
+
+To create a migration, follow these two steps in order:
+
+1. Run `serverpod generate` to update the generated code based on your model changes.
+2. Run `serverpod create-migration` to create the necessary database migration.
 
 ```bash
 $ cd magic_recipe/magic_recipe_server
 $ serverpod generate
 $ serverpod create-migration
 ```
 
-You will notice that there will be a new entry in your _migrations_ folder - serverpod creates these migrations "step by step" - each time you have changes which are relevant to the database and run `serverpod create-migrations` a new migration file will be created. This is a good way to keep track of the changes you make to the database and to be able to roll back changes if needed.
+Each time you run `serverpod create-migration`, a new migration file will be created in your _migrations_ folder. These step-by-step migrations provide a history of your database changes and allow you to roll back changes if needed.
 
 ## Writing to the database
 
-Let's save all the recipes we create to the database. Because the `Recipe` now has a `table` key, it is not just a serializable model but also a `TableRow`. This means that Serverpod has generated bindings for us to the database. You can access the bindings through the static `db` field of the `Recipe`. Here, you will find the `insertRow` method, which is used to create a new entry in the database.
+Now that we've added the `table` keyword to our `Recipe` model, it becomes a `TableRow` type, giving us access to database operations. Serverpod automatically generates database bindings that we can access through the static `db` field of the `Recipe` class. Let's use the `insertRow` method to save new recipes to the database:
 
 <!--SNIPSTART 03-persisted-endpoint {"selectedLines": ["10-12", "39-51"]}-->
 ```dart
@@ -418,18 +423,21 @@ class ResultDisplay extends StatelessWidget {
 
 ## Run the app
 
-First, we need to start the server and apply the migrations by adding the `--apply-migrations` flag:
+To run the application with database support, follow these steps in order:
+
+First, start the database and apply migrations:
 
 ```bash
 $ cd magic_recipe/magic_recipe_server
-$ docker compose up -d
-$ dart bin/main.dart --apply-migrations
+$ docker compose up -d                   # Start the database container
+$ dart bin/main.dart --apply-migrations  # Apply any pending migrations
 ```
 
 :::tip
-When developing your server, it's always safe to pass the `--apply-migrations` flag. If no migration needs to be applied, the flag is simply ignored. In a production environment, you may want to have a bit more control.
+The `--apply-migrations` flag is safe to use during development - if no migrations are pending, it will simply be ignored. For production environments, you may want more controlled migration management.
 :::
-Now, start the Flutter app:
+
+Next, launch the Flutter app:
 
 ```bash
 $ cd magic_recipe/magic_recipe_flutter
@@ -438,12 +446,14 @@ $ flutter run -d chrome
 
 ## Summary
 
-You now know the fundamentals of Serverpod - how to create and use endpoints with custom data models and how to store the data in a database. You have also learned how to use the generated client code to call the endpoints from your Flutter app. We cannot wait to see what you will build with Flutter and Serverpod.
+You've now learned the fundamentals of Serverpod:
 
-If you get stuck, never be afraid to ask questions in our [community on Github](https://github.com/serverpod/serverpod/discussions). The Serverpod team is very active there, and many questions are also answered by other developers.
+- Creating and using endpoints with custom data models.
+- Storing data persistently in a database.
+- Using the generated client code in your Flutter app.
 
-:::tip
-
-Working with a database is an extensive subject, and Serverpod's ORM is very powerful. Learn more in the [Database](../06-concepts/06-database/01-connection.md) section.
+We're excited to see what you'll build with Flutter and Serverpod! If you need help, don't hesitate to ask questions in our [community on Github](https://github.com/serverpod/serverpod/discussions). Both the Serverpod team and community members are active and ready to help.
 
+:::tip
+Database operations are a broad topic, and Serverpod's ORM offers many powerful features. To learn more about advanced database operations, check out the [Database](../06-concepts/06-database/01-connection.md) section.
 :::

docs/01-get-started/04-deployment.md

@@ -6,11 +6,11 @@ sidebar_label: 4. Deploying Serverpod
 
 ## Server requirements
 
-Since Serverpod is written in Dart, it can be compiled into native code and runs on any platform that is supported by the [Dart tooling](https://dart.dev/get-dart#system-requirements).
+Serverpod is written in Dart and compiles to native code, allowing it to run on any platform supported by the [Dart tooling](https://dart.dev/get-dart#system-requirements).
 
-Many users will want to deploy Serverpod using Docker. There is a basic Dockerfile included in the project that can be used to build a Docker image. This image can then be run on any platform that supports Docker.
+Many users prefer to deploy Serverpod using Docker. The project includes a basic Dockerfile that you can use to build a Docker image, which can then be run on any Docker-compatible platform.
 
-If you don't use Docker, you will need [compile the Dart code](https://dart.dev/tools/dart-compile) and copy any assets and configuration files to the server since [asset bundling is not yet supported by Dart](https://github.com/dart-lang/sdk/issues/55195).
+For non-Docker deployments, you'll need to [compile the Dart code](https://dart.dev/tools/dart-compile) and manually copy your assets and configuration files to the server. This manual step is necessary since [asset bundling is not yet supported by Dart](https://github.com/dart-lang/sdk/issues/55195).
 
 ## Server configuration
 
@@ -22,9 +22,9 @@ By default Serverpod is active on three ports:
 
 You will also need to configure the database connection in the `config/production.yaml` file and **securely** provide the `config/passwords.yaml` file to the server.
 
-## Health check from load balancer
+## Health checks
 
-The **8080** port returns a basic health check response. You can use this to check if the server is running and is healthy.
+The server exposes a health check on the root endpoint `/` on port **8080**. Load balancers and monitoring systems can use this endpoint to verify that your server is running and healthy. The endpoint returns a basic health status response.
 
 ## Deploying with Serverpod Cloud
 
@@ -34,4 +34,4 @@ Serverpod Cloud is currently in private beta. Request access by [filling out thi
 
 ## Other deployment options
 
-Checkout [choosing a deployment strategy](../07-deployments/01-deployment-strategy.md) for more information on how to deploy your Serverpod application to other platforms.
+Check out [choosing a deployment strategy](../07-deployments/01-deployment-strategy.md) for more information on how to deploy your Serverpod application to other platforms.

docs/01-get-started/_category_.json

@@ -1,4 +1,4 @@
 {
-  "label": "Getting Started",
+  "label": "🚀 Getting started",
   "collapsed": false
 }