a6cde07af0
See [Linear issue 2-1627](https://linear.app/unleash/issue/2-1627/db-permissions-update-docs-and-migration-guides). Since we now use functions, we need more permissions than just GRANT ALL PERMISSIONS ON DATBASE. In addition we need to be allowed to create functions in the schema that's actually being used. This PR takes the easy way out and say that we need OWNER privileges on the database. That guarantees that we can do all we do in our migration scripts. ### Discussion points We might encounter some pushback on this, if so, we'll need to say that we need `GRANT ALL PRIVILEGES ON ALL FUNCTIONS IN <schema>` in addition to GRANT ALL PRIVILEGES ON DATABASE, where <schema> is the schema selected in their configuration.
3.5 KiB
| title |
|---|
| Back end |
The backend is written in nodejs/typescript. It's written as a REST API following a CSR (controller, service, repository/store) pattern. The following ADRs are defined for the backend:
ADRs
We have created a set of ADRs to help guide the development of the backend:
Requirements
Before developing on this project you will need two things:
- PostgreSQL 14.x or newer
- Node.js 14.x or newer
yarn install
yarn dev
PostgreSQL
To run and develop unleash, you need to have PostgreSQL database (PostgreSQL v14.x or newer) locally.
Unleash currently also work with PostgreSQL v14+, but this might change in a future feature release, and we have stopped running automatic integration tests below PostgreSQL v12. The current recommendation is to use a role with Owner privileges since Unleash uses Postgres functions to simplify our database usage.
Create a local unleash databases in postgres
$ psql postgres <<SQL
CREATE USER unleash_user WITH PASSWORD 'password';
CREATE DATABASE unleash WITH OWNER unleash_user;
CREATE DATABASE unleash_test WITH OWNER unleash_user;
ALTER DATABASE unleash_test SET timezone TO 'UTC';
SQL
Then set env vars:
(Optional as unleash will assume these as default values).
export DATABASE_URL=postgres://unleash_user:password@localhost:5432/unleash
export TEST_DATABASE_URL=postgres://unleash_user:password@localhost:5432/unleash_test
PostgreSQL with docker
If you don't want to install PostgreSQL locally, you can spin up an Docker instance. We have created a script to ease this process: scripts/docker-postgres.sh
Start the application
In order to start the application you will need Node.js v14.x or newer installed locally.
// Install dependencies
yarn install
// Start Unleash in development
yarn dev
// Unleash UI
http://localhost:3000
// API:
http://localhost:3000/api/
// Execute tests in all packages:
yarn test
Database changes
We use database migrations to track database changes. Never change a migration that has been merged to main. If you need to change a migration, create a new migration that reverts the old one and then creates the new one.
Making a schema change
To run migrations, you will set the environment variable for DATABASE_URL
export DATABASE_URL=postgres://unleash_user:password@localhost:5432/unleash
Use db-migrate to create new migrations file.
> yarn run db-migrate create YOUR-MIGRATION-NAME
All migrations require one up and one down method. There are some migrations that will maintain the database integrity, but not the data integrity and may not be safe to run on a production database.
Example of a typical migration:
/* eslint camelcase: "off" */
'use strict';
exports.up = function(db, cb) {
db.createTable(
'examples',
{
id: { type: 'int', primaryKey: true, notNull: true },
created_at: { type: 'timestamp', defaultValue: 'now()' },
},
cb,
);
};
exports.down = function(db, cb) {
return db.dropTable('examples', cb);
};
Test your migrations:
> yarn run db-migrate up
> yarn run db-migrate down
Publishing / Releasing new packages
Please run yarn test checks before publishing.
Run npm run publish to start the publishing process.
npm run publish:dry