This package uses Sequelize to provide a simple framework for working with PostgreSQL databases.
pnpm add @ttoss/postgresdb
pnpm add -D @ttoss/postgresdb-cli
This package is ESM only. Make sure to use it in an ESM environment.
{
"type": "module"
}
If you already have a database, you can skip this step. If you don't, you can use the following Docker command to create a new PostgreSQL database on port 5432 using Docker:
docker run --name postgres-test -e POSTGRES_PASSWORD=mysecretpassword -d -p 5432:5432 postgres
Create a folder called models
and add a new file called User.ts
with the following content:
import { Table, Column, Model } from '@ttoss/postgresdb';
@Table
export class User extends Model<User> {
@Column
declare name: string;
@Column
declare email: string;
}
_This packages exports all decorators from [sequelize-typescript](https://github.com/sequelize/sequelize-typescript), so you can use them to define your models._
Export the model in the models/index.ts
file:
export { User } from './User';
Create a new file called src/db.ts
with the following content:
import { initialize } from '@ttoss/postgresdb';
import * as models from './models';
export const db = initialize({ models });
You can set the database connection parameters in two ways:
-
Defining them in the
src/db.ts
file using theinitialize
function.export const db = initialize({ database: '', // database name username: '', // database username password: '', // database password host: '', // database host port: 5432, // database port. Default: 5432 models, });
-
Using environment variables:
-
DB_NAME
: database name -
DB_USERNAME
: database username -
DB_PASSWORD
: database password -
DB_HOST
: database host -
DB_PORT
: database port. Default: 5432
@ttoss/postgresdb
will use them automatically if they are defined. -
To sync the database schema with the models, use the sync
command:
pnpm dlx @ttoss/postgresdb-cli sync
By now, you should have a working database with a User
table.
You can now use the db
object to interact with the database. Check the Sequelize documentation for more information.
import { db } from './db';
const user = await db.User.create({
name: 'John Doe',
email: 'johndoe@email.com',
});
All models are available in the db
object.
If you want to use in a monorepo by sharing the models between packages, you need to create some configurations to make it work.
-
Create your
postgresdb
package following the steps above. -
Exports your main file in the
package.json
file:{ "type": "module", "exports": "./src/index.ts" }
-
Create a new file called
src/index.ts
with the following content to exports themodels
you've created:export * as models from './models';
We recommend to not export the
db
object in this file because you may want to use different configurations in different packages.
-
Install
@ttoss/postgresdb
package:pnpm add @ttoss/postgresdb
-
Add your
postgresdb
package as a dependency. In the case you're using PNPM, you can use the workspace protocol:{ "dependencies": { "@yourproject/postgresdb": "workspace:^" } }
-
Include the
postgresdb
package in theinclude
field of thetsconfig.json
file:{ "include": ["src", "../postgresdb/src"] }
This way, you can import the models using the
@yourproject/postgresdb
package. -
Create a new file called
src/db.ts
with the following content:import { initialize } from '@ttoss/postgresdb'; import { models } from '@yourproject/postgresdb'; export const db = initialize({ models, // other configurations });
-
Use the
db
object to interact with the database.
Initialize the database connection and load the models.
All Sequelize options are available, expect models
.
-
models
: An object with all models to be loaded. The keys are the model names, and the values are the model classes. This way, you can access the models using thedb
object.
This package exports all decorators from sequelize-typescript, i.e., @Table
, @Column
, @ForeignKey
, etc.
A type that represents the columns of a model.
import { Column, Model, type ModelColumns, Table } from '@ttoss/postgresdb';
@Table
class User extends Model<User> {
@Column
declare name?: string;
@Column
declare email: string;
}
/**
* UserColumns = {
* name?: string;
* email: string;
* }
*/
type UserColumns = ModelColumns<User>;