Skip to main content
pgw keeps its state in one SQLite database, pgw.db, in data_dir. Use this reference to read the database during an investigation, or to know what a backup holds.
Don’t change pgw.db by hand. Use the admin API or the CLI. To back it up, follow Back up, move, or restore pgw.

Entity relationship diagram

Solid lines are foreign keys that the database enforces. Dashed lines are references that pgw keeps in its own code.

Tables

All times are Unix timestamps in seconds.

Data lifetime

  • pgw deletes a binding when:
    • The app unregisters, or its registration expires.
    • The account has max_bindings_per_aor devices, and another device registers. pgw deletes the binding that registered least recently.
    • You delete or turn off the managed user that the binding registers as, or revoke the user with pgw user revoke.
    • The managed device didn’t register for credential_silence_purge.
    • The push service reports the binding’s push token invalid. In managed mode, pgw also unregisters it at the PBX.
    • The managed device has no push, and its connection to pgw closed or its registration expired.
    • The device registers its Contact again under another binding, as a browser page without +sip.instance does when it reloads. pgw keeps the binding that holds the push token. Two devices that send the same Contact with different +sip.instance values, as two phones behind NATs can, keep a binding each.
    • You delete the binding with pgw binding delete.
  • A binding keeps dead_reason only when pgw couldn’t delete it. pgw sends it no pushes, and deletes it at the next renewal scan in managed mode, or when its registration expires in passthrough mode.
  • An iPhone binding whose remote token is invalid stays, without the remote token, because calls still reach it through its VoIP token.
  • pgw deletes push events older than push_event_retention_days.
  • You can’t delete an upstream while bindings use it. The API returns 409. With force=true, pgw deletes the upstream and its bindings together. Deleting an upstream always deletes its users and domains through the foreign keys.

Sensitive columns

Next steps

Back up, move, or restore pgw

Copy pgw.db and the master key to a backup or another host.

Security

See how pgw protects the master key and the secrets in pgw.db.