PersistenceConfig class

Persistence / Storage Configuration

The PersistenceConfig group controls how the SDK stores, orders, and purges records in its on-device SQLite database. The database acts as a durable buffer between data producers (locations, geofences) and consumers (your app code and the HTTP service).

BackgroundGeolocation.ready(Config(
  persistence: PersistenceConfig(
    maxDaysToPersist: 3,
    maxRecordsToPersist: 1000,
    extras: {
      'user_id': 123,
      'appVersion': '1.2.3'
    },
    persistMode: PersistMode.all
 ))

The SDK prefers an empty database. Each new Location (and geofence event) is written to SQLite immediately, then consumed (and typically deleted) by downstream services such as the HTTP uploader. When a record is successfully processed (e.g., posted to your server), it is removed to keep the buffer small and responsive.

Configure PersistenceConfig via Config.persistence.

What gets stored?

• Locations recorded by the tracker
• Geofence events (enter / exit / dwell)
• Extras you attach via PersistenceConfig.extras (merged into each record at write time)

When are records deleted?

A record is deleted when any of the following occur:

• Your server returns a 20x for the HTTP upload (see HttpConfig)
• You call BackgroundGeolocation.destroyLocations
• PersistenceConfig.maxDaysToPersist elapses (rolling TTL purge)
• PersistenceConfig.maxRecordsToPersist would be exceeded (oldest records are dropped to admit the newest)

You can inspect how many pending records remain with BackgroundGeolocation.count, and fetch them with BackgroundGeolocation.locations.

Ordering

The HTTP service and other consumers select records in the order defined by PersistenceConfig.locationsOrderDirection:

• "ASC" → oldest first (default)
• "DESC" → newest first

JSON templating

The default JSON schemas posted to your server can be customized:

• PersistenceConfig.locationTemplate for Location uploads
• PersistenceConfig.geofenceTemplate for geofence uploads

Templates receive the full record as context, letting you reshape or rename fields to match your backend (see also HttpConfig.rootProperty).

Extras

PersistenceConfig.extras is a free-form map merged into each record at write time (before persistence and upload). This is ideal for static or slowly-changing context like user_id, route_id, or appVersion.

Persist mode

Control what kinds of records are persisted using PersistMode:

• PersistMode.all (default): persist locations and geofences
• PersistMode.location: persist locations only
• PersistMode.geofence: persist geofences only
• PersistMode.none: do not persist (still delivers live callbacks)

Even with PersistMode.none, HTTP uploads can still occur if your configuration requests them immediately; the distinction is whether records are saved to the long-lived SQLite buffer.

Example

Even when persistence is disabled, you can still trigger an HTTP upload directly using BackgroundGeolocation.getCurrentPosition:

bg.Location location = await bg.BackgroundGeolocation.getCurrentPosition(
  persist: true,
  extras: {"get_current_position": true},
  samples: 3,
);

In this case, the fetched location is first persisted to the SDK’s SQLite database (because persist: true, overriding PersistenceConfig.persistMode), then transmitted immediately (if HttpConfig.autoSync is enabled).

Provider change records

If you don’t need diagnostic records when the device’s provider changes (e.g., GPS toggled / settings altered), disable them with PersistenceConfig.disableProviderChangeRecord to keep the database lean.

Examples

Configure persistence behavior

import 'package:flutter_background_geolocation/flutter_background_geolocation.dart' as bg;

final config = bg.Config(
  persistence: bg.PersistenceConfig(
    // Keep up to 14 days of data
    maxDaysToPersist: 14,
    // Enforce an upper bound on queued records
    maxRecordsToPersist: 5000,
    // Oldest-first consumption (good for chronological replay)
    locationsOrderDirection: 'ASC',
    // Persist both locations and geofences
    persistMode: bg.PersistMode.all,
    // Stamp each record with useful context
    extras: {'user_id': 123, 'appVersion': '1.2.3'},
  ),
  http: bg.HttpConfig(
    url: 'https://example.com/locations',
    autoSync: true,
  ),
);

await bg.BackgroundGeolocation.ready(config);

Inspect and purge the database

final pending = await bg.BackgroundGeolocation.count;
print('Pending records: $pending');

// Remove everything (useful during logout or testing)
final ok = await bg.BackgroundGeolocation.destroyLocations();
print('Destroyed all records? $ok');

Custom JSON templates

final config = bg.Config(
  persistence: bg.PersistenceConfig(
    locationTemplate: '''
    {
      "lat": <%= latitude %>,
      "lng": <%= longitude %>,
      "ts": "<%= timestamp %>",
      "meta": <%= JSON.stringify(extras) %>
    }
    ''',
    geofenceTemplate: '''
    {
      "id": "<%= identifier %>",
      "action": "<%= action %>",
      "ts": "<%= timestamp %>"
    }
    ''',
  ),
);

Migration from legacy flat Config

Previously, persistence options lived directly on Config:

// Legacy
Config(
  maxDaysToPersist: 14,
  maxRecordsToPersist: 5000,
  locationsOrderDirection: 'ASC',
  locationTemplate: '{...}',
  geofenceTemplate: '{...}',
  persistMode: Config.PERSIST_MODE_ALL,
  extras: {'user_id': 123},
  disableProviderChangeRecord: true,
);

They are now grouped under PersistenceConfig via Config.persistence:

// New
Config(
  persistence: PersistenceConfig(
    maxDaysToPersist: 14,
    maxRecordsToPersist: 5000,
    locationsOrderDirection: 'ASC',
    locationTemplate: '{...}',
    geofenceTemplate: '{...}',
    persistMode: PersistMode.all,
    extras: {'user_id': 123},
    disableProviderChangeRecord: true,
  ),
);

Legacy keys remain available but are marked @Deprecated; prefer the compound form going forward.