Sync facts

• Running an initial sync from your DB to Oso Cloud.
• Keeping facts up-to-date in production with Oso Sync.
• Configuration for PostgreSQL, MongoDB, and CSV.
• Limitations and best practices.

​

Sync facts in production

1. Decide how to represent authorization data as facts.
2. Run a one-time initial sync to populate Oso Cloud.
3. Keep facts in sync using dual writes and periodic reconciliation.

​

Initial sync with Oso Sync

oso-cloud reconcile --perform-updates reconcile.yaml

​

Configure Oso Sync

​

PostgreSQL

version: 1
source: postgres
facts:
  has_relation(Repository:_, String:parent, Organization:_):
    db: app_db
    query: |-
      select repository.public_id, organization.public_id
      from repository
      join organization
        on organization.id = repository.organization_id
dbs:
  app_db:
    connection_string: postgresql://oso:oso@host:5432/dbname
    ssl:
      ca_file: /path/to/ca.pem
      use_system_certs: true
      ssl_mode: [require|prefer]

• version: optional, defaults to 1.
• source: optional, defaults to postgres.
• facts:
  • Fact type uses positional variables (_) that map to query columns in order.
  • db matches an entry in dbs.
  • query returns all facts of that type.
  • Example: has_relation(Repository:_, String:parent, Organization:_) has variables in the first and third arguments. repository.public_id fills the first argument (Repository), and organization.public_id fills the third argument (Organization).
• dbs:
  • Maps unique names to database connection details.
  • connection_string is a PostgreSQL connection URI or an environment variable: connection_string: $ENV_VAR_NAME.
  • ssl: optional block to configure SSL/TLS settings.
    • ca_file: optional, path to a custom CA certificate file.
    • use_system_certs: optional, opt-in to using the system’s certificate store; defaults to false.
    • ssl_mode: optional, if you have specified a ca_file, defaults to require; otherwise, defaults to prefer.
      • require: fail the connection if the server does not support SSL.
      • prefer: use SSL if the server supports it, but fall back to no SSL otherwise.

​

MongoDB

version: 1
source: mongodb
facts:
  has_relation(Repository:_, String:parent, Organization:_):
    db: app_db
    collection: has_relation
    fields:
      - name: repository
      - name: organization
        is_array: true
    query:
      find: {}
dbs:
  app_db:
    connection_string: mongodb://oso:oso@somemongo.instance.aws.com:27017/dbname

• version: must be 1.
• source: must be mongodb.
• facts:
  • Fact type uses positional variables (_) that map to query columns in order.
  • collection: name containing fact data.
  • fields: maps to positional arguments in fact type.
    • At most one field can have is_array: true (automatically unwound).
  • query can be either:
  • find: standard find query.
  • aggregate: aggregation pipeline (cannot use $out).
  • Example: has_relation(Repository:_, String:parent, Organization:_) has variables in the first and third arguments.
• dbs:
  • connection_string must be a valid MongoDB connection URI or an environment variable: connection_string: $ENV_VAR_NAME.

​

Comma-separated Values (CSV)

version: 1
source: csv
facts:
  has_relation(Repository:_, String:parent, Organization:_):
    fields:
      - name: repository
      - name: organization
    path: /path/to/has_relation.csv

• version: must be 1.
• source: must be csv.
• facts:
  • Fact type uses positional variables (_) that map to query columns in order.
  • fields: must match the CSV header exactly.
    • Order must match positional arguments in the fact type.
  • path: local path to CSV file.
  • Example: has_relation(Repository:_, String:parent, Organization:_) has variables in the first and third arguments.

​

Oso Sync limitations

​

Docker

FROM public.ecr.aws/osohq/reconcile:latest
ARG CONFIG_PATH
RUN test -n "$CONFIG_PATH" || (echo "CONFIG_PATH argument must be set to path of your reconcile.yaml" && false)
WORKDIR /app
COPY $CONFIG_PATH /app/config.yaml
ENTRYPOINT ["/app/reconcile", "reconcile", "/app/config.yaml"]