# Database and Migrations

The bundled Postgres, writing a migration, and running it.

The database is Postgres, and Elements bundles it. There is nothing to install.
A per-machine `elements-machine` daemon runs a single Postgres cluster shared by
all your projects; it is created automatically, kept healthy, and listens on
loopback port `5433` (not the usual `5432`, so it never collides with a Postgres
you already run). Data lives under `~/elements/db` in development.

On the first build, the project connects to the daemon, the cluster is ensured
ready, and your project's app database and test database are created
automatically. The names derive from the project directory (`MyApp` →
`my_app` and `my_app_test`), or from `database.name` in `config.jsoc`.

Migrations are SQL files under `app/migrations/`, and applying them is part of
the build loop. Save a migration and Elements applies it, to the test database
first, then the app database. In development you can edit an applied migration
and Elements rolls it back and replays it. On a deploy machine a migration runs
exactly once and is frozen thereafter.

To point at a remote or hosted Postgres instead of the bundled cluster, set
`DB_HOST` (and the other `DB_*` values) in the active environment. Full topics:
`elements man database`, `elements man migrations`.