diff --git a/docs/06-concepts/02-models/03-vector-fields.md b/docs/06-concepts/02-models/03-vector-fields.md index 5858c8ed..6edf7c89 100644 --- a/docs/06-concepts/02-models/03-vector-fields.md +++ b/docs/06-concepts/02-models/03-vector-fields.md @@ -13,7 +13,7 @@ All vector types support specialized distance operations for similarity search a To ensure optimal performance with vector similarity searches, consider creating specialized vector indexes on your vector fields. See the [Vector indexes](../database/indexing#vector-indexes) section for more details. :::info -The usage of Vector fields requires the pgvector PostgreSQL extension to be installed, which comes by default on new Serverpod projects. To upgrade an existing project, see the [Upgrading to pgvector support](../../upgrading/upgrade-to-pgvector) guide. +The usage of Vector fields requires the PostgreSQL database with the `pgvector` extension installed - which comes by default on new Serverpod projects. To upgrade an existing project, see the [Upgrading to pgvector support](../../upgrading/upgrade-to-pgvector) guide. ::: ## Vector diff --git a/docs/06-concepts/06-database/01-connection.md b/docs/06-concepts/06-database/01-connection.md index 0c9ce97a..d9dca357 100644 --- a/docs/06-concepts/06-database/01-connection.md +++ b/docs/06-concepts/06-database/01-connection.md @@ -1,15 +1,15 @@ # Connection -In Serverpod the connection details and password for the database are stored inside the `config` directory in your server package. Serverpod automatically establishes a connection to the Postgres instance by using these configuration details when you start the server. +In Serverpod the connection details and password for the database are stored inside the `config` directory in your server package. Serverpod automatically establishes a connection to the database instance by using these configuration details when you start the server. -The easiest way to get started is to use a Docker container to run your local Postgres server, and this is how Serverpod is set up out of the box. This page contains more detailed information if you want to connect to another database instance or run Postgres locally yourself. +If using PostgreSQL, the easiest way to get started is to use a Docker container to run your local PostgreSQL server, and this is how Serverpod is set up out of the box. This page contains more detailed information if you want to connect to another database instance or run PostgreSQL locally yourself. ### Connection details Each environment configuration contains a `database` keyword that specifies the connection details. For your development build you can find the connection details in the `config/development.yaml` file. -This is an example: +Below is an example for PostgreSQL: ```yaml ... @@ -24,14 +24,23 @@ database: The `name` refers to the database name, `host` is the domain name or IP address pointing to your Postgres instance, `port` is the port that Postgres is listening to, and `user` is the username that is used to connect to the database. :::caution - By default, Postgres is listening for connections on port 5432. However, the Docker container shipped with Serverpod uses port 8090 to avoid conflicts. If you host your own instance, double-check that the correct port is specified in your configuration files. - ::: +Serverpod also supports SQLite as a database backend: + +```yaml +... +database: + filePath: server.db +... +``` + +Note that the same database backend must be used for all run modes. For more information, see the [configuration documentation](../configuration#database-backends). + #### Configure search paths -You can customize the search paths for your database connection—helpful if you're working with multiple schemas. By default, Postgres uses the `public` schema unless otherwise specified. +If using PostgreSQL, you can customize the search paths for your database connection—helpful if you're working with multiple schemas. By default, Postgres uses the `public` schema unless otherwise specified. To override this, use the optional `searchPaths` setting in your configuration: @@ -46,7 +55,7 @@ database: ... ``` -In this example, Postgres will look for tables in the `custom` schema first, and then fall back to `public` if needed. This gives you more control over where your data lives and how it’s accessed. +In this example, Postgres will look for tables in the `custom` schema first, and then fall back to `public` if needed. This gives you more control over where your data lives and how it's accessed. :::tip It is also possible to set the search paths using [runtime parameters](runtime-parameters) directly on the server startup (or on a specific transaction). If the paths are set on both the configuration file and as runtime parameters, the runtime parameters will take precedence. @@ -82,6 +91,8 @@ database: You can also configure this setting via the environment variable `SERVERPOD_DATABASE_MAX_CONNECTION_COUNT`. +On SQLite, this configuration will set the number of read-only transactions that can be executed concurrently - only one write transaction can be executed at a time. + ### Database password The database password is stored in a separate file called `passwords.yaml` in the same `config` directory. The password for each environment is stored under the `database` keyword in the file. @@ -95,9 +106,11 @@ development: ... ``` +No database password is required when using SQLite. + ## Development database -A newly created Serverpod project has a preconfigured Docker instance with a Postgres database set up. Run the following command from the root of the `server` package to start the database: +A newly created Serverpod project has a preconfigured Docker instance with a PostgreSQL database set up. Run the following command from the root of the `server` package to start the database: ```bash $ docker compose up --build --detach @@ -144,9 +157,7 @@ You can connect to a Google Cloud SQL Postgres instance in two ways: The next step is to update the database password in `passwords.yaml` and the connection details for the desired environment in the `config` folder. :::info - If you are using the `isUnixSocket` don't forget to add __"/.s.PGSQL.5432"__ to the end of the `host` IP address. Otherwise, your Google Cloud Run instance will not be able to connect to the database. - ::: ### Connecting to AWS RDS diff --git a/docs/06-concepts/06-database/02-models.md b/docs/06-concepts/06-database/02-models.md index 4283cf84..2f0836e6 100644 --- a/docs/06-concepts/06-database/02-models.md +++ b/docs/06-concepts/06-database/02-models.md @@ -56,7 +56,7 @@ For a complete guide on how to work with relations see the [relation section](re ### Storing serializable fields as JSONB -By default, complex types are stored as `json` in PostgreSQL. You can opt into `jsonb` storage instead using the `serializationDataType` keyword. JSONB is a binary format that supports efficient querying and [GIN indexing](indexing#gin-indexes). +By default, complex types are stored as `json` in the database. You can opt into `jsonb` storage instead using the `serializationDataType` keyword. JSONB is a binary format that supports efficient querying and [GIN indexing](indexing#gin-indexes) for PostgreSQL. :::info The `serializationDataType` keyword is only valid on serializable field types (models, Lists, Maps). Primitive types like `String` and `int` have their own native database column types and are not affected by this setting. diff --git a/docs/06-concepts/06-database/03-relations/05-referential-actions.md b/docs/06-concepts/06-database/03-relations/05-referential-actions.md index 49c639d4..16bcc493 100644 --- a/docs/06-concepts/06-database/03-relations/05-referential-actions.md +++ b/docs/06-concepts/06-database/03-relations/05-referential-actions.md @@ -1,6 +1,6 @@ # Referential actions -In Serverpod, the behavior of update and delete for relations can be precisely defined using the onUpdate and onDelete properties. These properties map directly to the corresponding referential actions in PostgreSQL. +In Serverpod, the behavior of update and delete for relations can be precisely defined using the onUpdate and onDelete properties. These properties map directly to the corresponding referential actions in the database. ## Available referential actions diff --git a/docs/06-concepts/06-database/04-indexing.md b/docs/06-concepts/06-database/04-indexing.md index 9b2fe594..5937d031 100644 --- a/docs/06-concepts/06-database/04-indexing.md +++ b/docs/06-concepts/06-database/04-indexing.md @@ -63,6 +63,10 @@ indexes: If no type is specified the default is `btree`. All [PostgreSQL index types](https://www.postgresql.org/docs/current/indexes-types.html) are supported, `btree`, `hash`, `gist`, `spgist`, `gin`, `brin`. +:::info +Index types are only supported for PostgreSQL. On SQLite3, only `btree` indexes are supported. Indexes declared with different types on the models will be skipped when creating a migration and a warning will be logged. +::: + ## GIN indexes GIN (Generalized Inverted Index) indexes are designed for efficiently querying composite values such as JSONB data. When all fields in an index are stored as `jsonb`, Serverpod automatically defaults the index type to `gin`: @@ -110,10 +114,6 @@ indexes: If you only need containment queries (`@>`), use `jsonbPathOps` — it produces a smaller and faster index than the default `jsonbOps`. ::: -:::info -GIN indexes are a PostgreSQL feature. On SQLite, GIN index definitions are silently skipped during migration generation. -::: - For details on configuring JSONB storage on your model fields, see [Storing serializable fields as JSONB](models#storing-serializable-fields-as-jsonb). ## Vector indexes diff --git a/docs/06-concepts/06-database/05-crud.md b/docs/06-concepts/06-database/05-crud.md index 1edd9f0d..8281931a 100644 --- a/docs/06-concepts/06-database/05-crud.md +++ b/docs/06-concepts/06-database/05-crud.md @@ -57,7 +57,7 @@ The method returns only the rows that were successfully inserted. If all rows co This is useful for idempotent operations where you want to insert data without failing on duplicates. :::note -Under the hood, this uses PostgreSQL's `ON CONFLICT DO NOTHING`. Only unique and exclusion constraint violations are ignored — other errors such as `NOT NULL`, `CHECK`, or foreign key violations will still throw an exception. +Under the hood, this uses a `ON CONFLICT DO NOTHING` SQL clause. Only unique and exclusion constraint violations are ignored — other errors such as `NOT NULL`, `CHECK`, or foreign key violations will still throw an exception. ::: :::warning diff --git a/docs/06-concepts/06-database/08-transactions.md b/docs/06-concepts/06-database/08-transactions.md index d0f6e8b6..9fd0829c 100644 --- a/docs/06-concepts/06-database/08-transactions.md +++ b/docs/06-concepts/06-database/08-transactions.md @@ -26,9 +26,11 @@ In the example we insert a company and an employee in the same transaction. If a The transaction isolation level can be configured when initiating a transaction. The isolation level determines how the transaction interacts with concurrent database operations. If no isolation level is supplied, the level is determined by the database engine. :::info - At the time of writing, the default isolation level for the PostgreSQL database engine is `IsolationLevel.readCommitted`. +::: +:::info +Transaction isolation is only supported for PostgreSQL. SQLite3 uses `serializable` by default and currently does not support changing the transaction level to `readUncommitted`. ::: To set the isolation level, configure the `isolationLevel` property of the `TransactionSettings` object: @@ -85,12 +87,12 @@ Once a savepoint is created, you can roll back to it by calling the `rollback` m await session.db.transaction((transaction) async { // Changes preserved in the database await Company.db.insertRow(session, company, transaction: transaction); - + // Create savepoint var savepoint = await transaction.createSavepoint(); await Employee.db.insertRow(session, employee, transaction: transaction); - // Changes rolled back + // Changes rolled back await savepoint.rollback(); }); ``` diff --git a/docs/06-concepts/06-database/12-runtime-parameters.md b/docs/06-concepts/06-database/12-runtime-parameters.md index 989e7324..34d2bc02 100644 --- a/docs/06-concepts/06-database/12-runtime-parameters.md +++ b/docs/06-concepts/06-database/12-runtime-parameters.md @@ -6,6 +6,10 @@ Runtime parameters in Serverpod allow you to fine-tune the behavior of the datab Setting runtime parameters affects PostgreSQL's query planning and execution. Always test different parameter combinations with your specific dataset and query patterns to find the optimal configuration. ::: +:::info +Runtime parameters are only supported for PostgreSQL. Setting runtime parameters on SQLite is a no-op. +::: + ## Parameter scopes Runtime parameters can be applied with different scopes: diff --git a/docs/06-concepts/06-database/13-row-locking.md b/docs/06-concepts/06-database/13-row-locking.md index 9a932921..d50bdf52 100644 --- a/docs/06-concepts/06-database/13-row-locking.md +++ b/docs/06-concepts/06-database/13-row-locking.md @@ -84,7 +84,7 @@ The `lockMode` parameter determines the type of lock acquired. Different lock mo | For share | `LockMode.forShare` | Shared lock that blocks exclusive locks but allows other shared locks. Use when you need to ensure rows don't change while reading. | | For key share | `LockMode.forKeyShare` | Weakest lock that only blocks changes to key columns. | -For a detailed explanation of how lock modes interact, see the [PostgreSQL documentation](https://www.postgresql.org/docs/current/explicit-locking.html#LOCKING-ROWS). +For a detailed explanation of how lock modes interact, see the [PostgreSQL documentation](https://www.postgresql.org/docs/current/explicit-locking.html#LOCKING-ROWS). On SQLite, row locking is a no-op operation, since it only supports one write-transaction at a time. ## Lock behavior diff --git a/docs/06-concepts/07-configuration.md b/docs/06-concepts/07-configuration.md index f4999c87..fe8d34d7 100644 --- a/docs/06-concepts/07-configuration.md +++ b/docs/06-concepts/07-configuration.md @@ -57,6 +57,7 @@ These can be separately declared for each run mode in the corresponding yaml fil | SERVERPOD_DATABASE_REQUIRE_SSL | database.requireSsl | false | Indicates if SSL is required for the database | | SERVERPOD_DATABASE_IS_UNIX_SOCKET | database.isUnixSocket | false | Specifies if the database connection is a Unix socket | | SERVERPOD_DATABASE_MAX_CONNECTION_COUNT | database.maxConnectionCount | 10 | The maximum number of connections in the database pool. Set to 0 or a negative value for unlimited connections. | +| SERVERPOD_DATABASE_FILE_PATH | database.filePath | - | The SQLite database file path. Set this instead of host/port/name/user when using SQLite. | | SERVERPOD_REDIS_HOST | redis.host | - | The host address of the Redis server | | SERVERPOD_REDIS_PORT | redis.port | - | The port number for the Redis server | | SERVERPOD_REDIS_USER | redis.user | - | The user name for Redis authentication | @@ -214,6 +215,36 @@ futureCall: scanInterval: 2000 ``` +#### Database backends + +Serverpod supports both PostgreSQL and SQLite as database backends. + +:::warning +The same database backend must be used for all run modes. Otherwise, an error will be thrown when generating migrations. This practice is recommended to ensure that the development environment is consistent with the production environment. +::: + +##### PostgreSQL + +```yaml +database: + host: localhost + port: 8090 + name: database_name + user: postgres + maxConnectionCount: 10 +``` + +Set the database password in `passwords.yaml` (`database`) or through `SERVERPOD_PASSWORD_database`. + +##### SQLite + +```yaml +database: + filePath: server.db +``` + +No database password is required when using SQLite. + ### Passwords file example The password file contains the secrets used by the server to connect to different services but you can also supply your secrets if you want. This file is structured with a common `shared` section, any secret put here will be used in all run modes. The other sections are the names of the run modes followed by respective key/value pairs. @@ -235,6 +266,10 @@ production: twilioApiKey: 'prod_twilio_key' ``` +:::info +The `database` keyword is only needed for PostgreSQL. SQLite does not use a password. +::: + ### Dart config object example To configure Serverpod in Dart you simply pass an instance of the `ServerpodConfig` class to the `Serverpod` constructor. This config will override any environment variables or config files present. The `Serverpod` constructor is normally used inside the `run` function in your `server.dart` file. At a minimum, the `apiServer` has to be provided. diff --git a/docs/06-concepts/13-health-checks.md b/docs/06-concepts/13-health-checks.md index 8ec19221..001b47fb 100644 --- a/docs/06-concepts/13-health-checks.md +++ b/docs/06-concepts/13-health-checks.md @@ -99,7 +99,7 @@ The format of the response is as follows: Serverpod automatically registers health indicators based on your configuration: - **ServerpodStartupIndicator** - Tracks server initialization completion. -- **DatabaseHealthIndicator** - Checks PostgreSQL connectivity (if database is configured). +- **DatabaseHealthIndicator** - Checks database connectivity (if database is configured). - **RedisHealthIndicator** - Checks Redis connectivity (if Redis is enabled). ## Custom health indicators diff --git a/docs/06-concepts/19-testing/01-get-started.md b/docs/06-concepts/19-testing/01-get-started.md index a05d7cbe..44a95a19 100644 --- a/docs/06-concepts/19-testing/01-get-started.md +++ b/docs/06-concepts/19-testing/01-get-started.md @@ -3,14 +3,12 @@ Serverpod provides simple but feature rich test tools to make testing your backend a breeze. :::info - For Serverpod Mini projects, everything related to the database in this guide can be ignored. - :::
- Have an existing project? Follow these steps first! + Have an existing project from before Serverpod 3.0? Follow these steps first!

For existing non-Mini projects, a few extra things need to be done: 1. Add the `server_test_tools_path` key with the value `test/integration/test_tools` to `config/generator.yaml`: @@ -21,12 +19,12 @@ server_test_tools_path: test/integration/test_tools Without this key, the test tools file is not generated. With the above config the location of the test tools file is `test/integration/test_tools/serverpod_test_tools.dart`, but this can be set to any folder (though should be outside of `lib` as per Dart's test conventions). -2. New projects now come with a test postgres and redis instance in `docker-compose.yaml`. This is not strictly mandatory, but is recommended to ensure that the testing state is never polluted. Add the snippet below to the `docker-compose.yaml` file in the server directory: +2. New projects come with a test PostgreSQL and Redis instance in `docker-compose.yaml`. This is not strictly mandatory, but is recommended to ensure that the testing state is never polluted. Add the snippet below to the `docker-compose.yaml` file in the server directory: ```yaml # Add to the existing services postgres_test: - image: postgres:16.3 + image: pgvector/pgvector:pg16 ports: - '9090:5432' environment: @@ -55,7 +53,7 @@ volumes: services: # Development services postgres: - image: postgres:16.3 + image: pgvector/pgvector:pg16 ports: - '8090:5432' environment: @@ -74,7 +72,7 @@ services: # Test services postgres_test: - image: postgres:16.3 + image: pgvector/pgvector:pg16 ports: - '9090:5432' environment: @@ -210,7 +208,7 @@ The location of the test tools can be changed by changing the `server_test_tool ::: -Before the test can be run the Postgres and Redis also have to be started: +If using PostgreSQL, before the test can be run the PostgreSQL and Redis also have to be started: ```bash docker compose up --build --detach diff --git a/docs/08-deployments/05-general.md b/docs/08-deployments/05-general.md index 981bb8d9..c2c21867 100644 --- a/docs/08-deployments/05-general.md +++ b/docs/08-deployments/05-general.md @@ -4,7 +4,7 @@ You can host Serverpod anywhere, running Dart directly or through a Docker conta ## Required services -Serverpod will not run without a link to a Postgres database with the correct tables added (unless you're running Serverpod mini). Serverpod can also optionally use Redis. You enable Redis in your configuration files. +Serverpod will not run without a link to a database with the correct tables added (unless you're running Serverpod mini). Serverpod can also optionally use Redis. You enable Redis in your configuration files. ## Configuration files diff --git a/docs/11-serverpod-mini.md b/docs/11-serverpod-mini.md index d9a254ca..416dd72c 100644 --- a/docs/11-serverpod-mini.md +++ b/docs/11-serverpod-mini.md @@ -7,7 +7,7 @@ sidebar_class_name: sidebar-icon-serverpod-mini ## Serverpod or Serverpod Mini? -Serverpod Mini is a lightweight version of Serverpod that is perfect for small projects or when you want to try out Serverpod without setting up a Postgres database. If you start with Mini, you can upgrade to the full version of Serverpod anytime. +Serverpod Mini is a lightweight version of Serverpod that is perfect for small projects or when you want to try out Serverpod without setting up a database. If you start with Mini, you can upgrade to the full version of Serverpod anytime.

__Serverpod vs Serverpod Mini comparison__ @@ -20,7 +20,7 @@ Serverpod Mini is a lightweight version of Serverpod that is perfect for small p | Streaming data | ✅ | ✅ | | Custom auth | ✅ | ✅ | | Pre-built auth | ✅ | | -| Postgres database ORM | ✅ | | +| Database ORM | ✅ | | | Task scheduling | ✅ | | | Basic logging | ✅ | ✅ | | Serverpod Insights | ✅ | |