KahWee - Web Development, AI Tools & Tech Trends

Expert takes on AI tools like Claude and Sora, modern web development with React and Vite, and tech trends. By KahWee.

Reading and Writing Tripsy's SQLite Database on macOS

Tripsy stores all your trip data in a local SQLite file that iCloud syncs to your Mac. The file is already on your disk — no export needed.

Give this to an agent

The intended workflow is to give this post to Claude Code, Cursor, or any agentic coding tool at the start of a session:

"Read this post: [URL]. Then help me add my missing flights from this KAYAK itinerary."

The agent reads the schema, timestamp format, field rules, and pre-write checklist, then generates and runs the correct SQL. You review the output and open Tripsy — done in minutes instead of working through the CoreData format by hand.


The database is at a fixed path. Three files travel together:

DB="$HOME/Library/Group Containers/group.app.tripsy.ios/Tripsy.sqlite"
sqlite3 "$DB"
File Purpose
Tripsy.sqlite Main database
Tripsy.sqlite-wal Write-ahead log (active journal)
Tripsy.sqlite-shm Shared memory index

sqlite3 reads the WAL automatically. You only interact with it explicitly when writing — see Pre-write checklist.


Schema overview

Tripsy uses Apple's CoreData. Every table is prefixed Z_ and every column starts with Z. ZGENERALACTIVITY is the hub of the itinerary — one row per timeline item, each pointing to exactly one content table.

Core tables:

Table Purpose
ZTRIP One row per trip
ZGENERALACTIVITY Itinerary timeline — links each item to a trip
ZACTIVITY Places: restaurants, cafes, parks, museums, events
ZHOSTING Hotels and accommodations
ZTRANSPORTATION Flights, trains, car rentals, road trips

Supporting tables:

Table Purpose
ZGEOCODEDLOCATION Cached geocoding results
ZEMAIL Forwarded booking confirmation emails
ZTRIPGUEST Travel companions
ZTRIPEXPENSE Trip expenses
ZDOCUMENT Attached documents
ZCUSTOMCATEGORY User-defined categories

Junction tables (Z_1EMAILS, Z_4HOSTINGS, Z_3TRANSPORTATIONS) handle many-to-many relationships between emails and itinerary items.

ZGENERALACTIVITY foreign keys:

ZGENERALACTIVITY
  ZTRIP           → ZTRIP.Z_PK
  ZACTIVITY       → ZACTIVITY.Z_PK       (null if not an activity)
  ZHOSTING        → ZHOSTING.Z_PK        (null if not a hotel)
  ZTRANSPORTATION → ZTRANSPORTATION.Z_PK (null if not transport)
  ZDATE           → timeline sort key (CoreData timestamp)

Exactly one of ZACTIVITY, ZHOSTING, ZTRANSPORTATION is non-null per row.


Timestamps

CoreData stores timestamps as seconds since January 1, 2001 — not the Unix epoch (January 1, 1970). The offset is 978,307,200 seconds.

Reading:

datetime(ZSTARTS + 978307200, 'unixepoch')           -- UTC
datetime(ZSTARTS + 978307200, 'unixepoch', '+8 hours') -- MYT / SGT
datetime(ZSTARTS + 978307200, 'unixepoch', '+9 hours') -- JST

Writing — convert local time to CoreData:

import datetime

apple_epoch = datetime.datetime(2001, 1, 1, tzinfo=datetime.timezone.utc)

def to_coredata(year, month, day, hour, minute=0, utc_offset=8):
    """Pass local time. utc_offset = hours ahead of UTC (8 for MYT/SGT, 9 for JST)."""
    dt = (datetime.datetime(year, month, day, hour, minute,
                            tzinfo=datetime.timezone.utc)
          - datetime.timedelta(hours=utc_offset))
    return int((dt - apple_epoch).total_seconds())

to_coredata(2026, 3, 18, 10, 0, utc_offset=8)  # 10:00 AM MYT → 795492000
to_coredata(2026, 3, 18, 10, 0, utc_offset=9)  # 10:00 AM JST → 795488400

Always verify before inserting:

SELECT datetime(795492000 + 978307200, 'unixepoch', '+8 hours');
-- → 2026-03-18 10:00:00

Off-by-one-year errors produce valid-looking dates in the wrong year and are easy to miss. Always confirm both the date and the year. Cross-check against a nearby existing row's ZSTARTS — if a known event is March 16 and your new event is March 18, their CoreData values should differ by roughly 2 × 86400 = 172800.


Reading data

All trips

SELECT
  ZNAME,
  date(ZSTARTS + 978307200, 'unixepoch') AS start_date,
  date(ZENDS   + 978307200, 'unixepoch') AS end_date,
  ZPLANNEDNUMBEROFDAYS AS planned_days
FROM ZTRIP
ORDER BY ZSTARTS DESC;

Full itinerary for a trip

SELECT
  date(ga.ZDATE + 978307200, 'unixepoch') AS date,
  time(ga.ZDATE + 978307200, 'unixepoch') AS time,
  CASE
    WHEN ga.ZACTIVITY       IS NOT NULL THEN a.ZINTERNALTYPE
    WHEN ga.ZTRANSPORTATION IS NOT NULL THEN tr.ZINTERNALTYPE
    ELSE 'hotel'
  END AS type,
  COALESCE(a.ZNAME, h.ZNAME, tr.ZNAME) AS name,
  COALESCE(
    a.ZADDRESS,
    h.ZADDRESS,
    tr.ZDEPARTUREDESCRIPTION || ' → ' || tr.ZARRIVALDESCRIPTION
  ) AS detail
FROM ZGENERALACTIVITY ga
LEFT JOIN ZACTIVITY       a  ON ga.ZACTIVITY       = a.Z_PK
LEFT JOIN ZHOSTING        h  ON ga.ZHOSTING        = h.Z_PK
LEFT JOIN ZTRANSPORTATION tr ON ga.ZTRANSPORTATION = tr.Z_PK
WHERE ga.ZTRIP = (SELECT Z_PK FROM ZTRIP WHERE ZNAME LIKE '%Japan%')
ORDER BY ga.ZDATE;

Flights

SELECT
  t.ZNAME AS trip,
  datetime(tr.ZDEPARTURE + 978307200, 'unixepoch') AS departs,
  tr.ZDEPARTUREDESCRIPTION AS from_airport,
  tr.ZARRIVALDESCRIPTION   AS to_airport,
  tr.ZTRANSPORTNUMBER      AS flight_number,
  tr.ZSEATCLASS AS cabin,
  tr.ZSEATNUMBER AS seat
FROM ZGENERALACTIVITY ga
JOIN ZTRANSPORTATION tr ON ga.ZTRANSPORTATION = tr.Z_PK
JOIN ZTRIP t            ON ga.ZTRIP = t.Z_PK
WHERE tr.ZINTERNALTYPE = 'airplane'
ORDER BY tr.ZDEPARTURE DESC;

ZDEPARTUREDESCRIPTION and ZARRIVALDESCRIPTION hold IATA airport codes for flights (SFO, LHR) and station names for trains. ZACTUALTRANSPORTNUMBER holds the operated-by carrier when different from the scheduled number.

Hotels

SELECT
  t.ZNAME AS trip,
  h.ZNAME AS hotel,
  date(h.ZSTARTS + 978307200, 'unixepoch') AS check_in,
  date(h.ZENDS   + 978307200, 'unixepoch') AS check_out,
  h.ZRESERVATIONCODE AS confirmation,
  h.ZROOMTYPE AS room_type
FROM ZGENERALACTIVITY ga
JOIN ZHOSTING h ON ga.ZHOSTING = h.Z_PK
JOIN ZTRIP    t ON ga.ZTRIP    = t.Z_PK
ORDER BY h.ZSTARTS DESC;

ZHOSTING.ZNOTES stores the full booking text — room details, cancellation policy — as parsed from the confirmation email. ZROOMNUMBER and ZROOMTYPE are populated only when entered manually in the app.

Parsed booking emails

Emails forwarded to Tripsy are stored in ZEMAIL. Junction tables link each email to its itinerary item:

Junction table Links ZEMAIL to
Z_1EMAILS ZACTIVITY
Z_4HOSTINGS ZHOSTING
Z_3TRANSPORTATIONS ZTRANSPORTATION
-- Emails linked to hotel bookings for a trip
SELECT e.ZSUBJECT, datetime(e.ZDATE + 978307200, 'unixepoch') AS received
FROM ZEMAIL e
JOIN Z_4HOSTINGS jeh ON jeh.Z_4EMAILS2 = e.Z_PK
WHERE jeh.Z_8HOSTINGS1 IN (
  SELECT ga.ZHOSTING FROM ZGENERALACTIVITY ga
  WHERE ga.ZTRIP = (SELECT Z_PK FROM ZTRIP WHERE ZNAME LIKE '%Japan%')
    AND ga.ZHOSTING IS NOT NULL
);

Multi-currency

Each item stores its own price and currency independently. No conversion happens at query time.

SELECT
  COALESCE(a.ZINTERNALTYPE, tr.ZINTERNALTYPE, 'hotel') AS type,
  COALESCE(a.ZNAME, h.ZNAME,
    tr.ZDEPARTUREDESCRIPTION || '→' || tr.ZARRIVALDESCRIPTION) AS name,
  COALESCE(a.ZPRICE,    h.ZPRICE,    tr.ZPRICE)    AS price,
  COALESCE(a.ZCURRENCY, h.ZCURRENCY, tr.ZCURRENCY) AS currency
FROM ZGENERALACTIVITY ga
LEFT JOIN ZACTIVITY       a  ON ga.ZACTIVITY       = a.Z_PK
LEFT JOIN ZHOSTING        h  ON ga.ZHOSTING        = h.Z_PK
LEFT JOIN ZTRANSPORTATION tr ON ga.ZTRANSPORTATION = tr.Z_PK
WHERE ga.ZTRIP = (SELECT Z_PK FROM ZTRIP WHERE ZNAME LIKE '%Japan%')
  AND COALESCE(a.ZPRICE, h.ZPRICE, tr.ZPRICE) > 0;

Travel companions

SELECT ZNAME, ZEMAIL FROM ZTRIPGUEST;

ZGUESTSIDS on activities, hostings, and transportation stores which guests are included, as a comma-separated string of integer IDs matching ZTRIPGUEST.ZID.

Geocoded locations

SELECT ZCOUNTRYNAME, ZCOUNTRYCODE, COUNT(*) AS lookups
FROM ZGEOCODEDLOCATION
GROUP BY ZCOUNTRYCODE
ORDER BY lookups DESC;

ZLATITUDE and ZLONGITUDE are also stored directly on ZACTIVITY and ZHOSTING rows — every place with coordinates is queryable for GeoJSON export without touching ZGEOCODEDLOCATION.


Writing to the database

Direct SQLite inserts appear in Tripsy when you next launch it — CoreData reads the local store on startup. New rows survive CloudKit sync. Updates to existing rows do not.

Tripsy's CloudKit sync doesn't follow the standard NSPersistentCloudKitContainer pattern — there are no CoreData history tracking tables in the store. Conflict resolution uses CloudKit's server-side modifiedAt, not the local SQLite ZUPDATEDAT field. Once a row has been pushed to CloudKit, Tripsy treats the cloud copy as authoritative and overwrites any direct UPDATE on the next open.

Operation Survives CloudKit sync?
INSERT new row Yes — CloudKit has never seen it
UPDATE existing row No — CloudKit's copy wins
UPDATE ZTRIP SET ZNAME No — rename trips in the Tripsy UI

Warning

Always quit Tripsy before writing. Writes while Tripsy is running corrupt the WAL sync state and may be silently discarded.

Pre-write checklist

# 1. Quit Tripsy
osascript -e 'tell application "Tripsy" to quit'

# 2. Confirm it's closed (must return no output)
pgrep -x "Tripsy"

# 3. Back up the database directory
cp -r ~/Library/Group\ Containers/group.app.tripsy.ios \
      ~/Desktop/Tripsy_backup_$(date +%Y-%m-%d)

# 4. After all inserts, merge the WAL
sqlite3 "$DB" "PRAGMA wal_checkpoint(TRUNCATE);"
# → 0|0|0  means clean (busy_writers | log_frames | checkpointed_frames)

Fixing data in existing rows

UPDATE gets reverted on any row that CloudKit has already seen. The fix is to delete the row and re-insert it with a fresh ZINTERNALIDENTIFIER.

BEGIN;

-- 1. Delete the GA entry
DELETE FROM ZGENERALACTIVITY WHERE ZTRANSPORTATION = <old_pk>;

-- 2. Delete the content row
DELETE FROM ZTRANSPORTATION WHERE Z_PK = <old_pk>;

-- 3. Re-insert with a new PK, new ZINTERNALIDENTIFIER, and correct data
INSERT INTO ZTRANSPORTATION (...) VALUES (<new_pk>, ..., 'NewIdentifierv2', ...);
INSERT INTO ZGENERALACTIVITY (...) VALUES (<new_ga_pk>, ..., <new_pk>, ...);

-- 4. Advance Z_PRIMARYKEY
UPDATE Z_PRIMARYKEY SET Z_MAX = <new_pk>    WHERE Z_NAME = 'Transportation';
UPDATE Z_PRIMARYKEY SET Z_MAX = <new_ga_pk> WHERE Z_NAME = 'GeneralActivity';

COMMIT;

When Tripsy next opens, it sends a deletion tombstone for the old identifier and registers the new row as a record CloudKit has never seen. Appending v2 to the identifier is enough: MU546SINPVGSep2023kTv2.

CoreData field reference

Every inserted row needs these fields set correctly. A wrong Z_ENT or missing ZOWNERID causes the row to be ignored or misclassified without any error.

Z_ENT — entity type number, required on every row:

Table Z_ENT
ZACTIVITY 1
ZCUSTOMCATEGORY 2
ZDOCUMENT 3
ZEMAIL 4
ZEMAILATTACHMENT 5
ZGENERALACTIVITY 6
ZGEOCODEDLOCATION 7
ZHOSTING 8
ZTRANSPORTATION 9
ZTRIP 10

Z_OPT — optimistic locking counter. Set to 1 on new rows. Tripsy increments it on each save through the UI. Setting it higher than 1 on a new row has no effect on whether CloudKit accepts or reverts the record — CloudKit uses its own server-side version, not Z_OPT.

ZID — internal integer, purpose unclear. Set to 0 for all manual inserts. Sequential values risk collisions with Tripsy's own counter.

ZOWNERID — must match the owner of the trip. Query it from any existing row in the same trip rather than guessing:

SELECT DISTINCT ZOWNERID FROM ZACTIVITY a
JOIN ZGENERALACTIVITY ga ON ga.ZACTIVITY = a.Z_PK
WHERE ga.ZTRIP = <your_trip_z_pk>;

ZTIMEZONE — must be a valid IANA timezone name matching the physical location of the activity. Both Malaysia and Singapore are UTC+8, but they use different identifiers:

Location ZTIMEZONE
Malaysia (KL, PJ, etc.) Asia/Kuala_Lumpur
Singapore Asia/Singapore
Japan Asia/Tokyo
US West Coast America/Los_Angeles
UK Europe/London

ZINTERNALIDENTIFIER — unique identifier, ~20 alphanumeric characters, no hyphens, underscores, or spaces. Existing values look like z2wxvvERr5khQPOfUMnQ. Derive it from the item name, location, and a few random characters — one per row.

Primary key management

Z_PRIMARYKEY tracks the current maximum PK per entity. Query it immediately before inserting and update it after.

Z_MAX can jump by large amounts between sessions. Tripsy creates rows internally during CloudKit sync and then immediately deletes many of them, but Z_MAX still advances for each one — a jump of 20–50 in a single open/close cycle is normal. Never reuse a value you read earlier. Re-query every time.

-- Read current max before inserting
SELECT Z_NAME, Z_MAX FROM Z_PRIMARYKEY
WHERE Z_NAME IN ('Activity', 'Transportation', 'GeneralActivity', 'Hosting');

-- Update after inserting
UPDATE Z_PRIMARYKEY SET Z_MAX = <new_max> WHERE Z_NAME = 'Activity';

CloudKit tombstones

When Tripsy deletes a row — either internally or via CloudKit sync — it stores a tombstone for that ZINTERNALIDENTIFIER. Reinserting any row with a tombstoned identifier causes Tripsy to silently delete it again on next sync.

Caution

This is the most confusing failure mode. The row appears in Tripsy on first launch, then disappears after a second open/close. No error is shown. The fix: always generate a brand-new identifier when reinserting a previously deleted row. Never reuse one.

Sequence to diagnose a tombstoned insert:

  1. You insert a row, verify it in SQLite, checkpoint the WAL
  2. Open Tripsy — row appears ✓
  3. Close and reopen Tripsy — row is gone
  4. Z_MAX has advanced past your PK, but no row exists there

Activity types

ZINTERNALTYPE controls how Tripsy displays and categorizes each item.

ZACTIVITY types:

Value Tripsy label
restaurant Restaurant
cafe Café
bakery Bakery
foodMarket Food market
park Park
museum Museum
concert Concert
tour Tour
shopping Shopping
general Activity

ZTRANSPORTATION types:

Value Tripsy label
airplane Flight
train Train
car Car rental
roadtrip Road trip

Insert activities with ZINTERNALTYPE = 'general' and change the type in the Tripsy UI afterward. It's faster than looking up the exact string, and the UI type change also triggers a CloudKit push.

Inserting an activity

Every insert needs two rows: one in the content table and one in ZGENERALACTIVITY linking it to the trip.

BEGIN TRANSACTION;

INSERT INTO ZACTIVITY (
  Z_PK, Z_ENT, Z_OPT,
  ZCHECKED, ZHIDDEN, ZID, ZOWNERID,
  ZCREATEDAT, ZUPDATEDAT,
  ZSTARTS, ZENDS,
  ZLATITUDE, ZLONGITUDE,
  ZINTERNALTYPE, ZNAME,
  ZADDRESS, ZTIMEZONE,
  ZINTERNALIDENTIFIER, ZOWNERNAME,
  ZISALLDAY
) VALUES (
  <next_pk>, 1, 1,
  0, 0, 0, <ZOWNERID>,
  <now_coredata>, <now_coredata>,
  <start_coredata>, <end_coredata>,
  48.8738, 2.3320,
  'general', 'Conference Day 1',
  '11 Rue Richer, 75009 Paris, France', 'Europe/Paris',
  'ConfDay1Paris2024xQm7Rk', 'Traveler Name',
  0
);

INSERT INTO ZGENERALACTIVITY (
  Z_PK, Z_ENT, Z_OPT,
  ZACTIVITY, ZHOSTING, ZTRANSPORTATION, ZTRIP,
  ZDATE, ZINTERNALTYPE
) VALUES (
  <next_ga_pk>, 6, 1,
  <activity_pk>, NULL, NULL, <trip_z_pk>,
  <start_coredata>, 'general'
);

UPDATE Z_PRIMARYKEY SET Z_MAX = <next_pk>    WHERE Z_NAME = 'Activity';
UPDATE Z_PRIMARYKEY SET Z_MAX = <next_ga_pk> WHERE Z_NAME = 'GeneralActivity';

COMMIT;

ZGENERALACTIVITY.ZDATE is the sort key for the itinerary timeline — set it to the activity's start time. Two activities can share the same ZDATE; Tripsy allows overlapping events.

Inserting a flight

BEGIN TRANSACTION;

INSERT INTO ZTRANSPORTATION (
  Z_PK, Z_ENT, Z_OPT,
  ZHIDDEN, ZID, ZOWNERID, ZRECEIVEUPDATES,
  ZDEPARTURE, ZARRIVAL,
  ZCREATEDAT, ZUPDATEDAT,
  ZDEPARTURELATITUDE, ZDEPARTURELONGITUDE,
  ZARRIVALLATITUDE,   ZARRIVALLONGITUDE,
  ZDISTANCEINMETERS,
  ZDEPARTUREDESCRIPTION, ZARRIVALDESCRIPTION,
  ZDEPARTURETIMEZONE,    ZARRIVALTIMEZONE,
  ZINTERNALTYPE,
  ZTRANSPORTNUMBER, ZCOMPANY, ZCURRENCY,
  ZRESERVATIONCODE, ZOWNERNAME,
  ZINTERNALIDENTIFIER
) VALUES (
  <next_pk>, 9, 1,
  0, 0, <ZOWNERID>, 0,
  <departure_coredata>, <arrival_coredata>,
  <now_coredata>, <now_coredata>,
  37.6189, -122.3748,     -- departure airport lat/lng (SFO)
  51.4775, -0.4613,       -- arrival airport lat/lng (LHR)
  8767000,                -- distance in meters
  'JFK', 'LHR',
  'America/New_York', 'Europe/London',
  'airplane',
  'BA178', 'British Airways', 'USD',
  'ABC123', 'Traveler Name',
  'JFKLHRba178xMp7Qr2024'
);

INSERT INTO ZGENERALACTIVITY (
  Z_PK, Z_ENT, Z_OPT,
  ZACTIVITY, ZHOSTING, ZTRANSPORTATION, ZTRIP,
  ZDATE, ZINTERNALTYPE
) VALUES (
  <next_ga_pk>, 6, 1,
  NULL, NULL, <transport_pk>, <trip_z_pk>,
  <departure_coredata>, 'general'
);

UPDATE Z_PRIMARYKEY SET Z_MAX = <next_pk>    WHERE Z_NAME = 'Transportation';
UPDATE Z_PRIMARYKEY SET Z_MAX = <next_ga_pk> WHERE Z_NAME = 'GeneralActivity';

COMMIT;

ZGENERALACTIVITY.ZDATE should match the departure timestamp. ZDEPARTURETIMEZONE and ZARRIVALTIMEZONE take IANA timezone names — use the physical timezone at each airport, not UTC.

Caution

Both ZDEPARTURELATITUDE/ZDEPARTURELONGITUDE and ZARRIVALLATITUDE/ZARRIVALLONGITUDE must be set to real coordinates. If either pair is 0.0 or NULL, Tripsy reverse-geocodes the coordinates and displays whatever city happens to be nearest — the flight shows as "Anacortes to Anacortes" or some other wrong city entirely unrelated to the route. Airport lat/lng is easy to copy from any other flight in the same database that stops at that airport — query SELECT ZDEPARTURELATITUDE, ZDEPARTURELONGITUDE FROM ZTRANSPORTATION WHERE ZDEPARTUREDESCRIPTION = 'SIN' LIMIT 1.

Inserting a hotel stay

BEGIN TRANSACTION;

INSERT INTO ZHOSTING (
  Z_PK, Z_ENT, Z_OPT,
  ZHIDDEN, ZID, ZOWNERID,
  ZCREATEDAT, ZUPDATEDAT,
  ZSTARTS, ZENDS,
  ZLATITUDE, ZLONGITUDE,
  ZNAME, ZADDRESS,
  ZTIMEZONE, ZINTERNALIDENTIFIER, ZOWNERNAME
) VALUES (
  <next_pk>, 8, 1,
  0, 0, <ZOWNERID>,
  <now_coredata>, <now_coredata>,
  <checkin_coredata>, <checkout_coredata>,
  35.6762, 139.6503,
  'Shinjuku Hotel', '1-2-3 Shinjuku, Tokyo 160-0022, Japan',
  'Asia/Tokyo', 'ShinjukuHotelTky8xQ25', 'Traveler Name'
);

INSERT INTO ZGENERALACTIVITY (
  Z_PK, Z_ENT, Z_OPT,
  ZACTIVITY, ZHOSTING, ZTRANSPORTATION, ZTRIP,
  ZDATE, ZINTERNALTYPE
) VALUES (
  <next_ga_pk>, 6, 1,
  NULL, <hosting_pk>, NULL, <trip_z_pk>,
  <checkin_coredata>, 'general'
);

UPDATE Z_PRIMARYKEY SET Z_MAX = <next_pk>    WHERE Z_NAME = 'Hosting';
UPDATE Z_PRIMARYKEY SET Z_MAX = <next_ga_pk> WHERE Z_NAME = 'GeneralActivity';

COMMIT;

After inserting

Checkpoint the WAL:

PRAGMA wal_checkpoint(TRUNCATE);
-- → 0|0|0 means the WAL was fully merged into the main file
-- → 0|N|N means N frames were checkpointed (also fine)
-- → 1|N|M means a writer is still active — Tripsy may still be running

If ZGENERALACTIVITY.ZDATE falls outside the trip's ZSTARTS/ZENDS range, Tripsy shows a banner when you next open the trip: "Activities beyond trip dates — Do you want to update the trip dates?" Tap "Update Trip Dates." That banner also confirms the insert was read by CoreData.

Syncing to iOS

Inserted rows appear in Tripsy on Mac immediately. They don't reach iPhone until Tripsy pushes them to CloudKit.

Open each inserted item in Tripsy on Mac and save it. Any UI save registers the row as a local change, pushes it to CloudKit, and syncs to iPhone. It also locks in the data — once Tripsy has pushed the record, the cloud copy matches and nothing reverts it.

Caution

Rows that are never touched through the Tripsy UI are never pushed to CloudKit. They stay Mac-only indefinitely. More importantly: if you insert a row with wrong data and Tripsy pushes that incorrect record to CloudKit before you can fix it, a subsequent UPDATE in SQLite will be reverted. Delete and re-insert with a new identifier instead.


Worked example: San Francisco to Grand Canyon, December 2019

This trip (Z_PK = 20, ZOWNERID = 189780) was a 13-day December road trip down the California coast, through Death Valley, and into Nevada and Arizona. All times are America/Los_Angeles (PST = UTC−8, so utc_offset=-8 in to_coredata()).

What's already in the database

SELECT
  date(ga.ZDATE + 978307200, 'unixepoch', '-8 hours') AS local_date,
  time(ga.ZDATE + 978307200, 'unixepoch', '-8 hours') AS local_time,
  CASE
    WHEN ga.ZTRANSPORTATION IS NOT NULL THEN tr.ZINTERNALTYPE
    ELSE 'hotel'
  END AS type,
  COALESCE(h.ZNAME, tr.ZDEPARTUREDESCRIPTION || ' → ' || tr.ZARRIVALDESCRIPTION) AS name
FROM ZGENERALACTIVITY ga
LEFT JOIN ZHOSTING        h  ON ga.ZHOSTING        = h.Z_PK
LEFT JOIN ZTRANSPORTATION tr ON ga.ZTRANSPORTATION = tr.Z_PK
WHERE ga.ZTRIP = 20
ORDER BY ga.ZDATE;
local_date local_time type name
2019-12-16 15:00 hotel Lavender Inn by the Sea (Santa Barbara)
2019-12-17 16:00 hotel Venice Charm 3BR Home w/ Parking (Venice, LA)
2019-12-23 15:00 hotel SAHARA Las Vegas
2019-12-26 19:55 airplane LAS → SFO

Three stays were missing: Del Monte Forest (Pebble Beach, Dec 14–16), Searles Valley Trona House (Dec 21–22), and Sun Angel Retreat #3 (Pahrump, Dec 22–23).

Computing the timestamps

import datetime

apple_epoch = datetime.datetime(2001, 1, 1, tzinfo=datetime.timezone.utc)

def to_coredata(year, month, day, hour, minute=0, utc_offset=8):
    dt = (datetime.datetime(year, month, day, hour, minute,
                            tzinfo=datetime.timezone.utc)
          - datetime.timedelta(hours=utc_offset))
    return int((dt - apple_epoch).total_seconds())

# Del Monte Forest — check-in Dec 14 3pm PST, check-out Dec 16 noon PST
to_coredata(2019, 12, 14, 15, 0, utc_offset=-8)   # → 598057200
to_coredata(2019, 12, 16, 12, 0, utc_offset=-8)   # → 598219200

# Searles Valley Trona House — check-in Dec 21 3pm PST, check-out Dec 22 11am PST
to_coredata(2019, 12, 21, 15, 0, utc_offset=-8)   # → 598662000
to_coredata(2019, 12, 22, 11, 0, utc_offset=-8)   # → 598734000

# Sun Angel Retreat #3, Pahrump — check-in Dec 22 4pm PST, check-out Dec 23 11am PST
to_coredata(2019, 12, 22, 16, 0, utc_offset=-8)   # → 598752000
to_coredata(2019, 12, 23, 11, 0, utc_offset=-8)   # → 598820400

Verify before inserting:

SELECT datetime(598057200 + 978307200, 'unixepoch', '-8 hours');
-- → 2019-12-14 15:00:00  (Del Monte Forest check-in) ✓
SELECT datetime(598752000 + 978307200, 'unixepoch', '-8 hours');
-- → 2019-12-22 16:00:00  (Pahrump check-in) ✓

Inserting the three missing hotels

Re-query Z_PRIMARYKEY right before inserting — Z_MAX shifts every time Tripsy opens.

SELECT Z_NAME, Z_MAX FROM Z_PRIMARYKEY
WHERE Z_NAME IN ('Hosting', 'GeneralActivity');
-- Example: Hosting|4300  GeneralActivity|10661
-- Use 4301, 4302, 4303 for hostings; 10662, 10663, 10664 for GA rows
BEGIN TRANSACTION;

-- Del Monte Forest (Pebble Beach, CA)
INSERT INTO ZHOSTING (
  Z_PK, Z_ENT, Z_OPT, ZCHECKED, ZHIDDEN, ZID, ZOWNERID,
  ZCREATEDAT, ZUPDATEDAT, ZSTARTS, ZENDS,
  ZLATITUDE, ZLONGITUDE,
  ZNAME, ZADDRESS, ZTIMEZONE, ZINTERNALIDENTIFIER, ZOWNERNAME
) VALUES (
  4301, 8, 1, 0, 0, 0, 189780,
  598057200, 598057200, 598057200, 598219200,
  36.5890, -121.9490,
  'Del Monte Forest', '17 Mile Drive, Pebble Beach, CA 93953',
  'America/Los_Angeles', 'DelMonteForestPB2019xKw', 'Kah Wee'
);

INSERT INTO ZGENERALACTIVITY (
  Z_PK, Z_ENT, Z_OPT,
  ZACTIVITY, ZHOSTING, ZTRANSPORTATION, ZTRIP,
  ZDATE, ZINTERNALTYPE
) VALUES (
  10662, 6, 1,
  NULL, 4301, NULL, 20,
  598057200, 'general'
);

-- Searles Valley Trona House (Trona, CA)
INSERT INTO ZHOSTING (
  Z_PK, Z_ENT, Z_OPT, ZCHECKED, ZHIDDEN, ZID, ZOWNERID,
  ZCREATEDAT, ZUPDATEDAT, ZSTARTS, ZENDS,
  ZLATITUDE, ZLONGITUDE,
  ZNAME, ZADDRESS, ZTIMEZONE, ZINTERNALIDENTIFIER, ZOWNERNAME
) VALUES (
  4302, 8, 1, 0, 0, 0, 189780,
  598662000, 598662000, 598662000, 598734000,
  35.7580, -117.3710,
  'Searles Valley Trona House', 'Trona, CA 93562',
  'America/Los_Angeles', 'SearlesValleyTrona2019xRm', 'Kah Wee'
);

INSERT INTO ZGENERALACTIVITY (
  Z_PK, Z_ENT, Z_OPT,
  ZACTIVITY, ZHOSTING, ZTRANSPORTATION, ZTRIP,
  ZDATE, ZINTERNALTYPE
) VALUES (
  10663, 6, 1,
  NULL, 4302, NULL, 20,
  598662000, 'general'
);

-- Sun Angel Retreat #3, Pahrump, NV
INSERT INTO ZHOSTING (
  Z_PK, Z_ENT, Z_OPT, ZCHECKED, ZHIDDEN, ZID, ZOWNERID,
  ZCREATEDAT, ZUPDATEDAT, ZSTARTS, ZENDS,
  ZLATITUDE, ZLONGITUDE,
  ZNAME, ZADDRESS, ZTIMEZONE, ZINTERNALIDENTIFIER, ZOWNERNAME
) VALUES (
  4303, 8, 1, 0, 0, 0, 189780,
  598752000, 598752000, 598752000, 598820400,
  36.2000, -115.9800,
  'Sun Angel Retreat #3', 'Pahrump, NV 89048',
  'America/Los_Angeles', 'SunAngelRetreatPahrump2019xTn', 'Kah Wee'
);

INSERT INTO ZGENERALACTIVITY (
  Z_PK, Z_ENT, Z_OPT,
  ZACTIVITY, ZHOSTING, ZTRANSPORTATION, ZTRIP,
  ZDATE, ZINTERNALTYPE
) VALUES (
  10664, 6, 1,
  NULL, 4303, NULL, 20,
  598752000, 'general'
);

UPDATE Z_PRIMARYKEY SET Z_MAX = 4303  WHERE Z_NAME = 'Hosting';
UPDATE Z_PRIMARYKEY SET Z_MAX = 10664 WHERE Z_NAME = 'GeneralActivity';

COMMIT;

Checkpoint the WAL after inserting, then open each new item in Tripsy to push it to CloudKit:

PRAGMA wal_checkpoint(TRUNCATE);
-- → 0|0|0

The trip's ZSTARTS was 2019-12-16 — Tripsy will show an "Activities beyond trip dates" banner on first open. Tap "Update Trip Dates" to extend it back to Dec 14.


Diagnosing failed inserts

Symptom Cause Fix
Row never appears in Tripsy Tripsy was open during insert Quit Tripsy, reinsert, run wal_checkpoint(TRUNCATE)
Row appears, then vanishes on next open CloudKit tombstone on ZINTERNALIDENTIFIER Generate a new identifier and reinsert
Row is on Mac but not iPhone Never saved through Tripsy UI Open each item in Tripsy and save it
Z_MAX jumped far past your PK Normal — Tripsy creates/deletes rows during sync Re-query Z_PRIMARYKEY before the next insert
Date is correct but wrong year Off-by-one-year in timestamp Verify with datetime(value + 978307200, 'unixepoch') and check the year explicitly
Date and year correct, wrong time UTC vs local time in to_coredata() Confirm utc_offset matches the activity's timezone
Date is off by one day (PST) to_coredata() for PST uses utc_offset=-8, but the function subtracts the offset — a positive utc_offset=8 adds 8 hours instead of subtracting, shifting midnight PST into the next day Always verify with datetime(value + 978307200, 'unixepoch', '-8 hours') and check both date and time
Row visible but wrong timezone label Wrong ZTIMEZONE value Edit through Tripsy UI — direct SQLite update will be reverted if the row was already synced to CloudKit
Flight shows "Anacortes to Anacortes" Departure or arrival coordinates are 0.0 or NULL Delete and re-insert with correct lat/lng — UPDATE will be reverted by CloudKit
UPDATE to existing row reverts on next Tripsy open CloudKit's copy overwrites local changes Delete the row, re-insert as a new record with a fresh ZINTERNALIDENTIFIER (e.g. append v2)
Trip rename (ZNAME) reverts Same CloudKit conflict resolution as above Rename the trip in the Tripsy UI instead

Every row inserted this way has survived months of CloudKit sync untouched — as long as each one was opened through the Tripsy UI afterward. The ones I skipped are still Mac-only.