DOCSEARCHbyAlgolia
Submit Docs

Serverpod Documentation

website·Indexed 34 days ago

https://docs.serverpod.dev

An open-source full-stack framework for Flutter. Serverpod provides tools for building scalable backends with Dart, featuring automatic client-server communication, database ORM with support for PostgreSQL, migrations, endpoint middleware, and integration for AI and RAG.

Tokens
165.6K
Snippets
777
Records
1.1K
Agent score
63%

What's inside Serverpod

  1. Overview of Serverpod Cloud hosting

    Serverpod Cloud is a fully managed hosting platform designed specifically for Serverpod applications. It eliminates the need for manual VM setup, container configuration, or infrastructure orchestration. Key managed features include:

    • Production-grade Postgres databases with automatic migration application on deployment.
    • Networking, load balancing, and custom domains with TLS certificates.
    • Server instances (podlets) with predictable pricing.
    • A secure key manager for application secrets.

  2. Overview of Serverpod full-stack framework

    Serverpod is an open-source full-stack framework for Flutter that allows developers to write their entire stack in Dart. It uses YAML for data model definitions and provides generated, type-safe Dart code to call server endpoints from a Flutter app, eliminating the need for manual REST contracts or boilerplate code.

  3. Overview of Serverpod Database Migrations

    Serverpod uses a migration system to keep the database schema up to date as a project evolves. A migration consists of a set of database operations (e.g., creating tables or adding columns) that initialize a new database or roll an existing one forward. If the live database schema gets out of sync with the migration system, 'repair migrations' can be used to align them.

  4. Overview of JwtTokenManager for stateless authentication

    The JwtTokenManager provides stateless authentication using JSON Web Tokens (JWT). It utilizes two types of tokens: a short-lived access token sent with every request and a long-lived refresh token used to obtain new access tokens. Key features include automatic token rotation and the elimination of database queries for access token validation.

  5. Overview of Serverpod Database Relations

    Relations link rows in one table to rows in another via foreign keys, preventing data duplication and allowing related data to be queried independently. Serverpod provides two ways to declare relations in model files using the relation keyword:

    1. Object Relation: Types the field as the related model (e.g., address: Address?, relation). This allows the related object to be fetched together with the row using relation queries.
    2. ID Relation: Stores only the foreign key (e.g., addressId: int, relation(parent=address)). The developer manually reads and sets the ID.

  6. Overview of File Uploads architecture

    Serverpod handles file uploads by sending files directly to storage rather than through endpoint methods, preventing large files from bloating API calls.

    • Default Storage: Files are stored in the database (suitable for development).
    • Production Storage: Supports Google Cloud Storage, AWS S3, and Cloudflare R2.
    • Custom Storage: Local disk or NAS storage requires a custom cloud storage implementation.
    • Default Storages: public and private storages are configured by default, but additional storages can be added.

  7. Overview of ServerSideSessionsTokenManager

    The ServerSideSessionsTokenManager provides stateful authentication by validating tokens against server-side session records in the database. Unlike stateless JWTs, this manager allows for immediate session revocation and supports session expiration and inactivity timeouts. It stores only a hash of the session key in the database, while the token remains on the client device. Note that these auth sessions are distinct from the Session object used in endpoint methods.

  8. Overview of Serverpod Web Server

    Serverpod includes a built-in web server that runs alongside the API server. While Endpoints are used for typed communication between a Serverpod client and server, Web Server Routes are used for plain HTTP communication, such as REST APIs, webhooks, static files, and server-rendered HTML. The web server is built on the Relic framework and provides access to the same Session object as endpoint methods, allowing full access to the database and business logic.

  9. Overview of Serverpod Future Calls

    A future call is a piece of server work scheduled to run at a later time. Unlike in-memory timers, future calls are stored in the database, meaning they survive server restarts and are shared across all server instances.

    Execution Guarantees:

    • At-least-once delivery: A call is guaranteed to run at least once. If a server instance crashes during execution, another instance will pick up the call. Methods should be idempotent (safe to repeat).
    • Error Handling: If a method throws an exception, Serverpod logs the error and does not retry. You must manually schedule a new call for retries, except for recurring calls which schedule their next run regardless of success.
    • Timeouts: There is no default execution timeout; calls run until the method returns. Use Future.timeout within the method if a limit is needed.

  10. Use Serverpod Insights for monitoring and logs

    Serverpod Insights is a companion desktop application (available for macOS and Windows) used to view server logs and health metrics. It is critical to use a version of the Insights app that matches the version of Serverpod used in your project to ensure all features function correctly.

  11. Understand the Serverpod project structure

    A Serverpod project is a Dart pub workspace containing three primary packages. The developer writes code in the server and the Flutter app, while Serverpod automatically generates the client package to provide typed communication between them.

    • Server (myproject_server/): Contains endpoints, data models, configuration, and database migrations.
    • Client (myproject_client/): A generated package that the Flutter app uses to call server endpoints via typed Dart methods.
    • Flutter App (myproject_flutter/): The frontend application that depends on the client package.
    myproject/
├── myproject_server/    # Your server: endpoints, models, config, migrations
├── myproject_client/    # Generated client: how your app calls the server
└── myproject_flutter/   # Your Flutter app

  12. Use Serverpod health probes for orchestration

    Serverpod provides three built-in HTTP health probe endpoints used by hosts (like Kubernetes) to determine if a server should receive traffic or be restarted. These endpoints are available by default on all server instances (API server port 8080, Insights server port 8081, and web server port 8082). These paths are reserved and cannot be overridden by custom web server routes.