Using TripLibreLab
Importing a TripLibre export
TripLibreLab reads the SQLite database that TripLibre includes in every export. It opens a copy read-only, checks it, and turns it into days, trips and stops it can replay.
The importer is being built against TripLibre's real database. Exact table and field mappings, supported versions and error messages will be documented here once they have been verified against a real export; until then they are marked Pending.
Which file
Use travel.sqlite from a TripLibre export folder (hht-export-YYYYMMDD-HHMMSS/). It is a complete
snapshot of TripLibre's database. TripLibreLab does not read the export's CSV, JSON or GeoJSON files.
A few facts about this file come from TripLibre's own documentation and do not depend on TripLibreLab:
- Timestamps ending in
_tsare UTC Unix seconds. - The schema version is stored in SQLite's
PRAGMA user_version, and TripLibre's migrations only ever add to the schema. - Deleted rows are kept with
deleted = 1rather than removed.
For every table and column, see TripLibre's Data dictionary.
How the file is opened
- You choose itThrough the iOS Files picker. TripLibreLab cannot see any file you have not picked.
- It is opened read-onlyThe original export is never modified.
- It is checked before it is readTripLibreLab checks that the file is a SQLite database, reads its schema version, and confirms the tables it needs are present before querying anything.
- It is normalisedRecords are converted into the app's own model: diary days, trips, stays and track points, with dates in the right time zone.
What TripLibreLab needs from the data Pending
| Need | Why | Status |
|---|---|---|
| Trip and stay start and end times | To order the day and drive the timeline. | Pending |
| Coordinates | To place stays and draw trips on the map. | Pending |
| Links between trips and stays | To know where each trip started and ended. | Pending |
| Recorded route geometry (optional) | To replay the actual path. Without it, trips are drawn as schematic lines. | Pending |
| Travel mode, place names (optional) | Labels on the timeline and map. | Pending |
The exact source tables and columns for each row will be listed in the data contract once it has been checked against a real export.
Missing and partial data
Real diaries have gaps. The intended behaviour is:
- A day with no travel records is not offered in the day picker.
- A trip without recorded points is drawn between its start and end as a schematic line, labelled as such.
- A trip or stay without a location stays on the timeline but is left off the map, and the app does not crash.
- An incomplete day is shown with what exists; nothing is filled in or guessed.
When a file can't be read
| Problem | What you'll see |
|---|---|
| Not a SQLite file, or damaged | A message that the file could not be opened as a TripLibre database. |
| Unsupported schema version | A message naming the version found and the versions TripLibreLab supports, with a suggestion to update TripLibre or TripLibreLab. |
| A database that isn't from TripLibre | A message that the tables TripLibreLab expects are missing. |
| An empty diary | A message that the file contains no recorded days. |
Exact wording will be added once the importer is finished.