@@ -5,7 +5,10 @@ than one, add `_env = 'production'` or join on `_env`.
55
66There are two conventions throughout:
77
8- - Filter ` _deleted_at is null ` for live rows.
8+ - Read the ` _live ` views (` workos.users_live ` , ` workos.organizations_live ` ,
9+ ...) for live rows. Each is its table minus the tombstoned rows, so no
10+ ` _deleted_at is null ` filter is needed. Read the base table when you want
11+ deleted rows too; see [ Live views] ( schema.md#live-views ) .
912- Join on ` _env ` as well as the id.
1013
1114## Seats and adoption
@@ -17,10 +20,10 @@ SELECT o.name AS organization,
1720 COUNT (* ) AS seats,
1821 COUNT (* ) FILTER (WHERE u .last_sign_in_at IS NULL
1922 OR u .last_sign_in_at < NOW() - INTERVAL ' 30 days' ) AS dormant
20- FROM workos .organization_memberships m
21- JOIN workos .users u ON u .id = m .user_id AND u ._env = m ._env
22- JOIN workos .organizations o ON o .id = m .organization_id AND o ._env = m ._env
23- WHERE u . _deleted_at IS NULL AND m . _deleted_at IS NULL AND m .status = ' active'
23+ FROM workos .organization_memberships_live m
24+ JOIN workos .users_live u ON u .id = m .user_id AND u ._env = m ._env
25+ JOIN workos .organizations_live o ON o .id = m .organization_id AND o ._env = m ._env
26+ WHERE m .status = ' active'
2427 GROUP BY o .name
2528 HAVING COUNT (* ) FILTER (WHERE u .last_sign_in_at IS NULL
2629 OR u .last_sign_in_at < NOW() - INTERVAL ' 30 days' ) > 0
@@ -36,27 +39,30 @@ seats counted either way.
3639
3740``` sql
3841SELECT u .email , u .created_at , NOW() - u .created_at AS age
39- FROM workos .users u
40- LEFT JOIN workos .organization_memberships m
41- ON m .user_id = u .id AND m ._env = u ._env AND m ._deleted_at IS NULL
42- WHERE u ._deleted_at IS NULL
43- AND m .id IS NULL
42+ FROM workos .users_live u
43+ LEFT JOIN workos .organization_memberships_live m
44+ ON m .user_id = u .id AND m ._env = u ._env
45+ WHERE m .id IS NULL
4446 AND u .created_at < NOW() - INTERVAL ' 7 days'
4547 ORDER BY u .created_at ;
4648```
4749
50+ Note that the ` _live ` view on the outer side of the ` LEFT JOIN ` does the work
51+ that ` m._deleted_at IS NULL ` in the ` ON ` clause would otherwise have to: a user
52+ whose only membership was revoked still shows up here.
53+
4854## Enterprise readiness
4955
5056** Organizations with a verified domain but no directory.**
5157
5258``` sql
5359SELECT o .name AS organization, d .domain , o .created_at
54- FROM workos .organizations o
55- JOIN workos .organization_domains d
60+ FROM workos .organizations_live o
61+ JOIN workos .organization_domains_live d
5662 ON d .organization_id = o .id AND d ._env = o ._env AND d .state = ' verified'
57- LEFT JOIN workos .directories dir
58- ON dir .organization_id = o .id AND dir ._env = o ._env AND dir . _deleted_at IS NULL
59- WHERE o . _deleted_at IS NULL AND dir .id IS NULL
63+ LEFT JOIN workos .directories_live dir
64+ ON dir .organization_id = o .id AND dir ._env = o ._env
65+ WHERE dir .id IS NULL
6066 ORDER BY o .created_at ;
6167```
6268
@@ -66,26 +72,26 @@ mirror kept fresh by `reconcile` — is how you find them.
6672
6773``` sql
6874SELECT o .name AS organization, d .name AS directory, d .type , d .state , d .updated_at
69- FROM workos .directories d
70- JOIN workos .organizations o ON o .id = d .organization_id AND o ._env = d ._env
71- WHERE d ._deleted_at IS NULL AND d . state <> ' linked'
75+ FROM workos .directories_live d
76+ JOIN workos .organizations_live o ON o .id = d .organization_id AND o ._env = d ._env
77+ WHERE d .state <> ' linked'
7278 ORDER BY d .updated_at ;
7379```
7480
7581** SSO adoption by connection type.**
7682
7783``` sql
7884SELECT connection_type, state, COUNT (* ) AS connections
79- FROM workos .connections
80- WHERE _deleted_at IS NULL
85+ FROM workos .connections_live
8186 GROUP BY connection_type, state
8287 ORDER BY connections DESC ;
8388```
8489
8590## Authentication
8691
8792These read ` auth_attempts ` , which exists only because the mirror captured it —
88- there is no endpoint to ask for this history.
93+ there is no endpoint to ask for this history. It is append-only, so it has no
94+ ` _live ` view and nothing to filter.
8995
9096** Failed sign-ins by user, last hour.**
9197
@@ -102,6 +108,10 @@ SELECT COALESCE(u.email, a.email) AS email,
102108 ORDER BY failures DESC ;
103109```
104110
111+ This one joins the base ` workos.users ` table on purpose: an attempt against an
112+ account that has since been deleted should still be reported under its email,
113+ and the tombstone is where that email lives.
114+
105115** Sign-in success rate by method.** The ` type ` column is the method
106116(` password ` , ` sso ` , ` oauth ` , ` magic_auth ` , ...); ` status ` is derived from
107117whether the event name ended in ` _succeeded ` or ` _failed ` .
@@ -147,10 +157,9 @@ SELECT u.email,
147157 u .metadata - >> ' plan' AS plan,
148158 COUNT (s .id ) AS sessions_30d,
149159 MAX (s .created_at ) AS last_active
150- FROM workos .users u
160+ FROM workos .users_live u
151161 JOIN app .accounts a ON a .id = u .external_id
152162 LEFT JOIN app .sessions s ON s .account_id = a .id AND s .created_at > NOW() - INTERVAL ' 30 days'
153- WHERE u ._deleted_at IS NULL
154163 GROUP BY u .email , u .metadata - >> ' plan'
155164 ORDER BY sessions_30d DESC ;
156165```
@@ -160,11 +169,10 @@ already on the organization object:
160169
161170``` sql
162171SELECT o .name , s .status AS subscription, COUNT (m .id ) AS seats
163- FROM workos .organizations o
172+ FROM workos .organizations_live o
164173 JOIN billing .subscriptions s ON s .customer = o .stripe_customer_id
165- LEFT JOIN workos .organization_memberships m
166- ON m .organization_id = o .id AND m ._env = o ._env AND m ._deleted_at IS NULL
167- WHERE o ._deleted_at IS NULL
174+ LEFT JOIN workos .organization_memberships_live m
175+ ON m .organization_id = o .id AND m ._env = o ._env
168176 GROUP BY o .name , s .status ;
169177```
170178
@@ -194,7 +202,8 @@ SELECT DATE_TRUNC('day', created_at) AS day,
194202
195203## Deleted objects
196204
197- Tombstones mean you can still ask who left.
205+ Tombstones mean you can still ask who left. This is the one kind of question
206+ the ` _live ` views cannot answer, so these read the base table.
198207
199208``` sql
200209SELECT email, _deleted_at AS deleted_at, last_sign_in_at
@@ -203,24 +212,29 @@ SELECT email, _deleted_at AS deleted_at, last_sign_in_at
203212 ORDER BY _deleted_at DESC ;
204213```
205214
215+ The base table is also the only place that tells "deleted" apart from "never
216+ synced": a row with ` _deleted_at ` set was seen and then removed upstream; no row
217+ at all means the mirror never saw it.
218+
206219## Convenience views
207220
208- If filtering tombstones on every query is tedious, create views once:
221+ The ` _live ` views are generated for you, one per mirror table, and re-created
222+ every time the schema is applied, so they always carry the table's current
223+ columns. If you want them under different names or in a separate schema, build
224+ your own views on top of them rather than editing them: the engine never drops
225+ a view it did not create.
209226
210227``` sql
211228CREATE SCHEMA IF NOT EXISTS workos_live;
212229
213- CREATE VIEW workos_live .users AS
214- SELECT * FROM workos .users WHERE _deleted_at IS NULL ;
215-
216- CREATE VIEW workos_live .organizations AS
217- SELECT * FROM workos .organizations WHERE _deleted_at IS NULL ;
230+ CREATE VIEW workos_live .users AS SELECT * FROM workos .users_live ;
218231```
219232
220233## Giving an agent read access
221234
222235A read-only role over the mirror is a far better-scoped grant than an API key,
223- and one SQL tool replaces a pile of per-endpoint tools:
236+ and one SQL tool replaces a pile of per-endpoint tools. ` ALL TABLES ` covers the
237+ ` _live ` views as well:
224238
225239``` sql
226240CREATE ROLE analytics_reader LOGIN PASSWORD ' ...' ;
@@ -238,11 +252,10 @@ CREATE SCHEMA IF NOT EXISTS workos_safe;
238252
239253CREATE VIEW workos_safe .users AS
240254 SELECT u .id , u ._env , u .created_at , u .last_sign_in_at ,
241- COUNT (m .id ) FILTER ( WHERE m . _deleted_at IS NULL ) AS organizations
242- FROM workos .users u
243- LEFT JOIN workos .organization_memberships m
255+ COUNT (m .id ) AS organizations
256+ FROM workos .users_live u
257+ LEFT JOIN workos .organization_memberships_live m
244258 ON m .user_id = u .id AND m ._env = u ._env
245- WHERE u ._deleted_at IS NULL
246259 GROUP BY u .id , u ._env , u .created_at , u .last_sign_in_at ;
247260
248261GRANT USAGE ON SCHEMA workos_safe TO analytics_reader;
0 commit comments