:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
pub mod error;
pub mod postgres;
pub mod types;
use std::collections::HashMap;
use async_trait::async_trait;
pub use error::{StorageError, StorageResult};
pub use types::{AttachOutcome, DistinctIdMapping, Person, PersonStub, StubOutcome};
pub const DB_QUERY_DURATION: &str = "personhog_identity_db_query_duration_ms";
/// Storage operations for the identity service. All queries run on the
/// Postgres primary: identity resolution must never be stale, and stub
/// creation is a sync-plane write.
#[async_trait]
pub trait IdentityStorage: Send + Sync {
/// Batch-resolve (team_id, distinct_id) keys to persons on the primary.
/// Returns a map keyed by (team_id, distinct_id); unresolved keys are absent.
/// Persons carry identity only (no properties): the leader owns those.
async fn resolve_distinct_ids(
&self,
keys: &[(i64, String)],
) -> StorageResult<HashMap<(i64, String), Person>>;
/// Person ids from live distinct id rows, without reading the person table.
async fn resolve_person_ids(
&self,
keys: &[(i64, String)],
) -> StorageResult<HashMap<(i64, String), i64>>;
/// Expand person ids to their live distinct id rows on the primary.
/// With a per-person limit, identified ids survive the cut and the
/// scan is capped for pathological persons — the same ordering
/// contract as the replica's expansion.
async fn get_distinct_ids_for_persons(
&self,
team_id: i64,
person_ids: &[i64],
limit_per_person: Option<i64>,
) -> StorageResult<Vec<DistinctIdMapping>>;
/// Create person stubs (uuidv5 from team_id:distinct_id, version 0, empty
/// properties) plus their distinct id rows in one multi-row transaction.
/// Safe to race: unique conflicts resolve per row to the winner instead of
/// erroring, so one key's race never fails the rest of the batch.
///
/// Callers must dedupe stubs by (team_id, distinct_id); duplicate keys in
/// one call have unspecified per-row outcomes. Outcomes are in stub order.
async fn create_person_stubs(&self, stubs: &[PersonStub]) -> StorageResult<Vec<StubOutcome>>;
/// Attach personless distinct ids to a live person with plain mapping
/// inserts. Live mappings are never repointed (`AlreadyMapped`); an id
/// absent from the result attached nothing. Callers dedupe.
async fn attach_distinct_ids(
&self,
team_id: i64,
person_id: i64,
distinct_ids: &[String],
) -> StorageResult<HashMap<String, AttachOutcome>>;
}