
# All properties

Every property `spring_boot_starter_data` reads, grouped by prefix. Each row gives the key, its type and allowed values, its default and what it does. The starter's metadata (`lib/spring_gen/spring_metadata.json`) lists the same keys, so editors with completion offer them: 58 keys for the primary database and the starter, and 44 more under `spring.datasources.*` for named databases.

## Why

The data layer is configured almost entirely with properties: which database, how many connections, which migrations, what to log. This page is the one place where all of them are listed, so you can check a key, its type and its default without reading every page.

## Example

A realistic configuration: PostgreSQL in production with TLS, a SQLite side database for statistics, migrations per database, slow statements logged, and paging limits for the API.

```yaml
# lib/resources/application.yml
spring:
  datasource:
    url: postgresql://db.example.com:5432/shop
    username: shop
    password: ${SHOP_DB_PASSWORD}
    pool:
      max-size: 20
      min-idle: 2
      connection-timeout: 10s
      idle-timeout: 10m
      max-lifetime: 30m
      validation: true
    postgresql:
      sslmode: verify-full
      ssl-root-cert: /etc/ssl/certs/db-ca.pem
      connect-timeout: 5s
      application-name: shop-api
      search-path: shop,public
  datasources:
    stats:
      url: sqlite:file:stats.db
      sqlite:
        busy-timeout: 2000
        isolate: true
      sql:
        migration:
          locations: resources:db/stats
  sql:
    migration:
      locations: resources:db/migration/{vendor}
      connect-retries: 5
      connect-retries-interval: 5s
      placeholders:
        recent-year: '2000'
  data:
    jdbc:
      schema: validate
      slow-query-threshold: 500ms
    web:
      pageable:
        default-page-size: 20
        max-page-size: 100
  jdbc:
    template:
      query-timeout: 30s
```

The same in `.properties`:

```properties
# lib/resources/application.properties
spring.datasource.url=postgresql://db.example.com:5432/shop
spring.datasource.username=shop
spring.datasource.password=${SHOP_DB_PASSWORD}
spring.datasource.pool.max-size=20
spring.datasource.pool.min-idle=2
spring.datasource.pool.connection-timeout=10s
spring.datasource.pool.idle-timeout=10m
spring.datasource.pool.max-lifetime=30m
spring.datasource.pool.validation=true
spring.datasource.postgresql.sslmode=verify-full
spring.datasource.postgresql.ssl-root-cert=/etc/ssl/certs/db-ca.pem
spring.datasource.postgresql.connect-timeout=5s
spring.datasource.postgresql.application-name=shop-api
spring.datasource.postgresql.search-path=shop,public
spring.datasources.stats.url=sqlite:file:stats.db
spring.datasources.stats.sqlite.busy-timeout=2000
spring.datasources.stats.sqlite.isolate=true
spring.datasources.stats.sql.migration.locations=resources:db/stats
spring.sql.migration.locations=resources:db/migration/{vendor}
spring.sql.migration.connect-retries=5
spring.sql.migration.connect-retries-interval=5s
spring.sql.migration.placeholders.recent-year=2000
spring.data.jdbc.schema=validate
spring.data.jdbc.slow-query-threshold=500ms
spring.data.web.pageable.default-page-size=20
spring.data.web.pageable.max-page-size=100
spring.jdbc.template.query-timeout=30s
```

## Writing values

- **Durations:** `500ms`, `30s`, `10m`, `1h`, ISO 8601 (`PT30S`), or a plain number of milliseconds. `spring.datasource.postgresql.connect-timeout` does not take `PT30S`. See [Durations](../spring-core-dart/conversion/durations.md).
- **Lists:** comma separated in `.properties` (`a,b`), a YAML list or comma separated in YAML.
- **Environment variables:** `SPRING_DATASOURCE_URL`, `SPRING_DATASOURCE_POSTGRESQL_SSLMODE`, `SPRING_DATASOURCES_STATS_SQLITE_BUSYTIMEOUT`. The names of `spring.datasources.<name>` are found only in property sources that list their keys (files, the command line): declare the URL in a file and override it with a variable.

## spring.datasource: the primary database

Set `spring.datasource.url` and the starter makes the primary `DataSource` and the beans over it. Without it, repositories keep their data in memory.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.datasource.url` | `String` | none | The database URL: `sqlite:file:books.db`, `sqlite::memory:` or `postgresql://user:password@host:5432/db`; a leading `jdbc:` is dropped. The scheme chooses the driver; a scheme no listed driver handles stops the start. |
| `spring.datasource.username` | `String` | none | The database user, when the URL does not carry it. |
| `spring.datasource.password` | `String` | none | The database password, when the URL does not carry it. Never logged. |
| `spring.datasource.driver` | `String` | none | The driver's name (`sqlite3`, `postgres`), when two drivers handle the scheme. |

## spring.datasource.pool

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.datasource.pool.max-size` | `int` | `10` | Most connections at once, at least 1. |
| `spring.datasource.pool.min-idle` | `int` | `0` | Connections kept open when idle, from 0 to `max-size`. |
| `spring.datasource.pool.connection-timeout` | `Duration` | `30s` | The longest wait for a connection, then `CannotGetJdbcConnectionException`. |
| `spring.datasource.pool.idle-timeout` | `Duration` | `10m` | An idle connection above `min-idle` older than this is closed; `0` keeps them forever. |
| `spring.datasource.pool.max-lifetime` | `Duration` | `30m` | A connection older than this is closed when it comes back to the pool; `0` for no limit. |
| `spring.datasource.pool.validation` | `bool` | `true` | Whether a connection that waited in the pool is checked with `isValid` before it is handed out. |

## spring.datasource.sqlite

Also readable as `spring.datasource.sqlite3.*` (the driver's name wins). See [SQLite](sqlite.md).

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.datasource.sqlite.busy-timeout` | `int` | `5000` | Milliseconds a connection waits for SQLite's lock. |
| `spring.datasource.sqlite.base-directory` | `String` | the working directory | Where relative `sqlite:file:` names are looked for. Beats `SqliteJdbcDriver.baseDirectory`. In a Flutter app the Flutter starter sets it. |
| `spring.datasource.sqlite.isolate` | `bool` | `false` | `true` opens each connection inside an isolate of its own, so a long query or a busy wait does not hold the caller's isolate. Beats `SqliteJdbcDriver(isolate:)`. In a Flutter app the Flutter starter sets it to `true`. |
| `spring.datasource.sqlite.location` | `support`, `cache`, `documents` | `support` | Read by `spring_boot_starter_flutter` only: the app directory it sets `base-directory` to. Any other value stops the start. Not in this starter's metadata. |

## spring.datasource.postgresql

Also readable as `spring.datasource.postgres.*` (the driver's name wins). The URL parameters `sslmode`, `sslrootcert`, `connect_timeout`, `application_name` and `currentSchema` set the same; the properties win. See [PostgreSQL](postgresql.md).

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.datasource.postgresql.sslmode` | `disable`, `allow`, `prefer`, `require`, `verify-ca`, `verify-full` | `prefer` | Whether and how the connection uses TLS (libpq's `sslmode`). `allow` tries TLS first, like `prefer`; `verify-ca` is as strict as `verify-full`. |
| `spring.datasource.postgresql.ssl-root-cert` | `String` | the system's roots | PEM file of the certificate authorities a `verify-*` mode checks the server against. |
| `spring.datasource.postgresql.connect-timeout` | `Duration` | `15s` | The longest wait for the connection and the TLS handshake (`500ms`, `30s`, `1m`, or milliseconds; not `PT30S`). |
| `spring.datasource.postgresql.application-name` | `String` | none | Shown in `pg_stat_activity`. |
| `spring.datasource.postgresql.search-path` | `String` | the server's | The schemas of `search_path`, comma separated (the URL's `currentSchema`). |

## spring.datasources: named databases

Each `spring.datasources.<name>.url` adds a database, with beans qualified `<name>` (`<name>DataSource`, `<name>TransactionManager`, `<name>JdbcTemplate`, `<name>NamedParameterJdbcTemplate`, `<name>JdbcClient`), used by `@UseDataSource('<name>')` and `@Transactional(transactionManager: '<name>')`. It takes every key of the primary database, and its own schema settings:

| Key | Same as |
|---|---|
| `spring.datasources.<name>.url`, `.username`, `.password`, `.driver` | `spring.datasource.*` |
| `spring.datasources.<name>.pool.*` (6 keys) | `spring.datasource.pool.*` |
| `spring.datasources.<name>.sqlite.busy-timeout`, `.base-directory`, `.isolate` | `spring.datasource.sqlite.*` |
| `spring.datasources.<name>.postgresql.*` (5 keys) | `spring.datasource.postgresql.*` |
| `spring.datasources.<name>.sql.init.*` (7 keys) | `spring.sql.init.*` |
| `spring.datasources.<name>.sql.migration.*` (18 keys) | `spring.sql.migration.*` |
| `spring.datasources.<name>.data.jdbc.schema` | `spring.data.jdbc.schema` |

The defaults are the same as for the primary database; a named database does not inherit the primary's values.

## spring.sql.migration: migrations

See [Schema and migrations](schema.md). Spring Boot's `spring.flyway.*` names stop the start, naming these.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.sql.migration.enabled` | `bool` | `true` | Whether migrations run: `V<version>__<name>.sql` and `R__<name>.sql`; with no files nothing runs anyway. |
| `spring.sql.migration.locations` | `List<String>` | `resources:db/migration` | Where the files are; `{vendor}` is replaced by the dialect's name (`sqlite`, `postgresql`). |
| `spring.sql.migration.table` | `String` | `schema_history` | The history table. |
| `spring.sql.migration.validate-on-migrate` | `bool` | `true` | Whether an applied migration whose checksum changed, or that is missing from the files, or a file older than the applied ones that was never applied, stops the start. |
| `spring.sql.migration.target` | `String` | `latest` | The version to migrate to, or `latest`. Repeatable migrations run only for `latest`. |
| `spring.sql.migration.out-of-order` | `bool` | `false` | Whether a file with a version below the latest applied one still runs. |
| `spring.sql.migration.ignore-migration-patterns` | `List<String>` | `*:future` | Which problems of the history are ignored, as `type:status`: type `versioned`, `repeatable` or `*`; status `missing` (applied, not in the files, below the latest file), `future` (applied, newer than every file), `ignored` (a file below the latest applied, never applied) or `*`. The default lets a database from a later version of the application start. |
| `spring.sql.migration.baseline-on-migrate` | `bool` | `false` | Whether a database with tables and no history is taken as being at `baseline-version` instead of stopping the start. |
| `spring.sql.migration.baseline-version` | `String` | `1` | The version of the baseline. |
| `spring.sql.migration.baseline-description` | `String` | `<< Baseline >>` | The description of the baseline. |
| `spring.sql.migration.placeholders.<name>` | `String` | none | The value of the placeholder `<name>` in the scripts. |
| `spring.sql.migration.placeholder-replacement` | `bool` | `true` | Whether the scripts have their placeholders replaced. |
| `spring.sql.migration.placeholder-prefix` | `String` | `${` | What a placeholder starts with; must not be empty. |
| `spring.sql.migration.placeholder-suffix` | `String` | `}` | What a placeholder ends with; must not be empty. |
| `spring.sql.migration.group` | `bool` | `false` | Whether all pending migrations run in one transaction instead of each in its own. |
| `spring.sql.migration.connect-retries` | `int` | `0` | How many times a failed connection is retried at startup. |
| `spring.sql.migration.connect-retries-interval` | `Duration` | `10s` | The wait between two of those attempts. |
| `spring.sql.migration.lock-timeout` | `Duration` | `1m` | How long the runner waits for the migration lock another process holds before it gives up. |

## spring.sql.init: SQL scripts

Used when there are no migrations. See [Schema and migrations](schema.md).

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.sql.init.mode` | `embedded`, `always`, `never` | `embedded` | When `schema.sql` and `data.sql` run: `embedded` only on an in-memory database (`sqlite::memory:`), as in Spring Boot; `always`; `never`. |
| `spring.sql.init.schema-locations` | `List<String>` | empty: `resources:schema.sql` and `resources:schema-<platform>.sql`, both optional | The schema scripts. A location you give must exist unless it starts with `optional:`; `@@platform@@` in it is replaced by the platform. |
| `spring.sql.init.data-locations` | `List<String>` | empty: `resources:data.sql` and `resources:data-<platform>.sql` | The data scripts. |
| `spring.sql.init.platform` | `String` | `all` | The platform in the names of the platform scripts. |
| `spring.sql.init.continue-on-error` | `bool` | `false` | Whether a failed statement is logged and skipped instead of stopping the start. |
| `spring.sql.init.separator` | `String` | `;` | The separator of the statements. |
| `spring.sql.init.encoding` | `String` | `utf-8` | The encoding of the script files. |

## spring.data.jdbc: schema mode and logging

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.data.jdbc.schema` | `none`, `validate`, `create`, `create-drop` | `validate` | What the starter does with the entities' schema: nothing; check that their tables and columns exist and fit; create the missing tables; create them and drop them when the context closes. `create` and `create-drop` are not for use with migrations or scripts. |
| `spring.data.jdbc.show-sql` | `bool` | `false` | Whether the statements are logged at info, so they show with the default level (Spring Boot's `spring.jpa.show-sql`). |
| `spring.data.jdbc.format-sql` | `bool` | `false` | Whether the SQL in the log is on several lines. |
| `spring.data.jdbc.show-parameters` | `bool` | `false` | Whether the bound values are logged at info too, instead of trace; those of secret-looking names stay masked. |
| `spring.data.jdbc.slow-query-threshold` | `Duration` | none | A slower statement is logged at warn, in every build. |
| `spring.main.startup-checks.enabled` | `bool` | not set: debug and profile builds | Read by the generator, not at run time: `true` keeps the startup checks `transactionValidator` and `dataFailureAnalyzer` in every build, `false` in none. Not set: in debug and profile builds only, so in a release build a wrong `@Transactional` method fails at its first call. |

`show-sql` is read by the generator too: `true` in the configuration without a profile keeps `show-sql`, `format-sql` and `show-parameters` in every build, `false` in none, not set in debug and profile builds only. `slow-query-threshold` stays in every build. See [Logging SQL](logging.md#in-a-release-build).

## spring.jdbc.template

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.jdbc.template.query-timeout` | `Duration` | none | Bounds each statement of the `JdbcTemplate` beans, such as `500ms` or `10s`; past it, a `QueryTimeoutException`. |

## spring.data.store: the default store

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.data.store` | `String` | `jdbc` with a primary data source, else `memory` | The store of the repositories without `@UseStore` and `@UseDataSource`: `memory`, `jdbc`, or the name of another package's store. A name no store has fails the repositories when they are created, with the stores there are. The build reads it too, from the file without a profile. See [Stores and their capabilities](stores.md). |

## spring.data.memory: the in-memory store

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.data.memory.lock-timeout` | `Duration` | `10s` | The in-memory store's wait for a row lock, such as `500ms`; zero fails at once, as `nowait` does. |

## spring.data.web: paging in controllers

Read only when `spring_boot_starter_web` is a dependency too. See [In a web application](web.md).

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.data.web.pageable.default-page-size` | `int` | `20` | The page size when the request has no `size`. |
| `spring.data.web.pageable.max-page-size` | `int` | `2000` | The largest page size; a larger `size` is cut to it. |
| `spring.data.web.pageable.one-indexed-parameters` | `bool` | `false` | Whether the `page` parameter starts at 1 instead of 0. |
| `spring.data.web.pageable.page-parameter` | `String` | `page` | The name of the page number parameter. |
| `spring.data.web.pageable.size-parameter` | `String` | `size` | The name of the page size parameter. |
| `spring.data.web.pageable.prefix` | `String` | `''` | A prefix put before the page and size parameter names. |
| `spring.data.web.pageable.qualifier-delimiter` | `String` | `_` | The delimiter between a `@Qualifier` and the parameter name (`x_page`). |
| `spring.data.web.sort.sort-parameter` | `String` | `sort` | The name of the sort parameter. |

## Read from other packages

| Key | Package | Default | Meaning |
|---|---|---|---|
| `management.health.db.enabled` | the actuator | `true` | Whether the `db` health contributor, one indicator per data source, is registered. |
| `logging.level.spring.jdbc.core.JdbcTemplate` | logging | | `debug` shows each statement. |
| `logging.level.spring.jdbc.core.StatementCreatorUtils` | logging | | `trace` shows the bound values. |
| `logging.level.spring.sql.migration` | logging | | The migration runner's lines. |

## In Spring (Java)

Most keys keep Spring Boot's names: `spring.datasource.url`, `username`, `password`, `spring.sql.init.*`, `spring.jdbc.template.query-timeout`, `spring.data.web.*`. The differences:

| Spring Boot | Here |
|---|---|
| `spring.datasource.hikari.maximum-pool-size` and the other Hikari keys | `spring.datasource.pool.*` |
| `spring.flyway.*` | `spring.sql.migration.*` (the Spring name stops the start) |
| `spring.jpa.hibernate.ddl-auto` | `spring.data.jdbc.schema` (no `update`) |
| `spring.jpa.show-sql` | `spring.data.jdbc.show-sql` |
| a second `DataSource` in code | `spring.datasources.<name>.*` |

## See also

- [Data sources](data-sources.md)
- [Schema and migrations](schema.md)
- [Logging SQL](logging.md)
- [Configuration properties](../spring-core-dart/config/configuration-properties.md)
