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:

.. code-block:: yaml

  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:

.. code-block:: yaml

  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.