Sequelize

​

Why

​

Setup

1. In development.ts, production.ts, and test.ts, set tools.rds:
   rds: {
     client: RDSClientType.SEQUELIZE,
     dialect: SequelizeDialectType.POSTGRES,
     host: process.env.POSTGRES_HOST,
     port: Number(process.env.POSTGRES_PORT),
     username: process.env.POSTGRES_USER,
     password: process.env.POSTGRES_PASSWORD,
     database: process.env.POSTGRES_DB,
   }
   
2. In compose.yml, the rds service provides PostgreSQL:
   rds:
     image: postgres:18
     environment:
       POSTGRES_USER: ${POSTGRES_USER}
       POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
       POSTGRES_DB: ${POSTGRES_DB}
     ports:
       - 5432:5432
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d postgres"]
       interval: 2s
       timeout: 5s
       retries: 10
   
3. In .env.development, set:
   POSTGRES_HOST=rds
   POSTGRES_PORT=5432
   POSTGRES_USER=postgres
   POSTGRES_PASSWORD=postgres
   POSTGRES_DB=refract_dev
   
4. Run migrations: make migrate.
5. Run make test module=backend.

​

Adding a new model

1. Create apps/backend/src/tools/rds/sequelize/models/<ModelName>/index.ts (or a flat file for simple models). Extend Model from Sequelize, define attributes, and call ModelName.init(...) with the table name in snake_case plural.
2. Register associations in the model file’s associate static method, called automatically by the model loader.
3. Generate a migration: copy the closest existing migration in apps/backend/src/tools/rds/sequelize/migrations/ and name it <timestamp>-<describe-change>.ts.
4. Export the model from apps/backend/src/tools/rds/sequelize/models/index.ts.
5. Run make migrate to apply.
6. Run make test module=backend.

​

Migrations

make migrate         # apply all pending migrations
make migrate-down    # roll back the last migration

​

Soft deletes (paranoid models)

// Returns only active members (default behaviour):
await tools.rds.models.OrganizationMember.findAll({ where: { organization_id } });

// Returns ALL members including revoked (only when you need it):
await tools.rds.models.OrganizationMember.findAll({
  where: { organization_id },
  paranoid: false,
});

​

Gotchas

• Always pass the active transaction to every ORM call inside a transaction block. Omitting it causes dirty reads and partial writes.
• Never run sequelize.sync() in production — use migrations.
• The verbose: true config flag logs every SQL query. Useful for debugging, but leave it off in production.
• POSTGRES_PORT must be a number. The config parses it with Number(process.env.POSTGRES_PORT) — ensure your .env has no quotes around it.

​

What’s next?

• Configuration — environment-level database vars.
• Tooling system — how the tools object is assembled.
• Architecture overview — where this tool sits in the full system.