ORM Reference

datafaker keeps information about the structure of the database in a YAML file, which is passed to several commands with the --orm-file option. By default this is called orm.yaml and that is how we shall refer to it here.

This file generated by the make-tables command and used by almost every other command. make-tables looks at the source database and writes the structure of the database into orm.yaml. create-tables takes orm.yaml and writes the structure described there into the destination database. Most of the other commands will use orm.yaml to determine how they interact with the source or destination database (rather than using the database as it actually is); in this way you can edit the orm.yaml file if you need certain effects.

Here’s a short example of a hypothetical orm.yaml file:

dsn: postgresql://tim:***@localhost:5432/pagila
schema: public
tables:
  person:
    columns:
      person_id:
        nullable: false
        primary: true
        type: INTEGER
      birth_date:
        nullable: false
        primary: false
        type: TIMESTAMP WITH TIME ZONE
      name:
        nullable: false
        primary: false
        type: TEXT
    unique: []
  death:
    columns:
      death_id:
        nullable: false
        primary: true
        type: INTEGER
      person_id:
        nullable: false
        primary: false
        type: INTEGER
        foreign_keys:
        - person.person_id
      reason:
        nullable: false
        primary: false
        type: TEXT
    unique: []

Here we can see how the primary keys in each table are marked with primary: true. We can also see how the person_id column in the death table is a foreign_keys, referring to the person_id in the person table.

Now, we can see these unique: [] lines. This is showing that neither of these tables have uniqueness constraints. If we configure column generators for this database and generate a database from this, we will find many people dying twice or more times. The original database does not have a uniqueness constraint requiring that each person can only appear once in the death database; there can be many reasons for this, but it is causing us problems. We can change orm.yaml like so:

dsn: postgresql://tim:***@localhost:5432/pagila
schema: public
tables:
  #...
  death:
    #...
    unique:
    - name: arbitrary_name_like_unique_death_person_id
      columns:
      - person_id

Now the create-tables command will create this uniqueness constraint in the destination table. Also, the create-data command will retry generators as many times as is required to satisfy this uniqueness constraint. If you like, you can run create-tables without adding this constraint to orm.yaml, then add it before running create-data; this will create a database without the uniqueness constraint (matching the source database) but create data as if the constraint were present.