TypeORM
FoalTS components using TypeORM officially support the following databases: PostgreSQL, MySQL, MariaDB and SQLite.
A simple model:
#
The ORMFoalTS uses TypeORM as default Object-Relational Mapping. This allows you to create classes to interact with your database tables (or collections). TypeORM is written in TypeScript and supports both Active Record and Data Mapper patterns.
Here is a non-exhaustive list of its features:
- migrations and automatic migrations generation
- uni-directional, bi-directional and self-referenced relations
- eager and lazy relations
- TypeScript support
- connection configuration in json / xml / yml / env formats
- transactions
- etc
TypeORM supports many SQL databases (MySQL / MariaDB / Postgres / SQLite / Microsoft SQL Server / Oracle / sql.js) as well as the MongoDB NoSQL database.
Although this documentation presents the basic features of TypeORM, you may be interested in reading the official documentation to learn more advanced features.
#
Use with FoalTSTypeORM is integrated by default in each new FoalTS project. This allows you to quickly create models, run migrations and use the authentication system without wasting time on configuration. However, if you do not wish to use it, you can refer to the page Using another ORM.
#
Initial ConfigurationWhen creating a new project, an SQLite
database is used by default as it does not require any additional installation (the data is saved in a file). The connection configuration is stored in ormconfig.js
and default.json
located respectively at the root of your project and in the config/
directory.
ormconfig.js
default.json (example)
#
PackagesTwo packages are required to use TypeORM with FoalTS:
- The package typeorm which is the official one of the ORM. It includes everything you need to create models and make database requests.
- The package @foal/typeorm (maintained by FoalTS) which contains additional components. These are particularly useful when using FoalTS authentication and authorization system.
#
Database Configuration ExamplesThis section shows how to configure MySQL or PostgreSQL with Foal.
ormconfig.js
With this configuration, database credentials can be provided in a YAML, a JSON or a .env
configuration file or in environment variables.
{% code-tabs %} {% code-tabs-item title="config/default.yml" %}
{% endcode-tabs-item %} {% code-tabs-item title="config/default.json" %}
{% endcode-tabs-item %} {% code-tabs-item title=".env or environment variables" %}
{% endcode-tabs-item %} {% endcode-tabs %}
#
MySQL / MariaDBInstall mysql
or mysql3
drivers.
#
PostgreSQLInstall pg
driver.
#
Configuration and TestingWhen running the command npm run test
with the above configuration, FoalTS will try to retrieve the database configuration in this order:
- Environment variables.
.env
file.config/test.yml
andconfig/test.json
.config/default.yml
andconfig/default.json
.
For example, if the environment variable DATABASE_PASSWORD
is defined, Foal will use its value. Otherwise, it will look at the .env
file to see if it is defined here. If it is not, it will go through the YAML and JSON config/
files.
In this way, you can define a default configuration in the config/default.{yml|json}
file to use both during development and testing and override some settings in config/test.{yml|json}
during testing.
You learn more on how configuration works in Foal here
In the example below, we add two new options:
dropSchema
clears the database each time we callcreateConnection
- and
synchronize
synchronizes the database tables with your entities so your do not have to generate and run migrations during testing.
config/test.yml
Example of a test