monolayer-pg

Appearance

Databases ​

monolayer-pg will be aware of all your databases through exported database defintions from a single databases file.

You can think of the databases file as the entrypoint for all the databases and schemas you want to manage with monolayer-pg.

As a starting point, you are given a default folder/file structure for the db folder and a databases.ts file it.

text
🗂️ <project-root>
└ 📁 <chosen-db-location>
  └ 📁 db
    ├ 📄 client.ts
    ├ 📄 databases.ts
    ├ 📄 schema.ts
    ├ 📄 seeds.ts

However, you can move and rename files as you see fit and modularize your code to your own conventions.

WARNING

Don't forget to update the configuration in monolayer.config.ts, when the change your databases file name or its location.

Define a single database ​

After importing defineDatabase from @monolayer/pg/schema, you export a default database definition.

ts
import { defineDatabase } from "@monolayer/pg/schema";
import { dbSchema } from "./schema";

export default defineDatabase({
  schemas: [dbSchema], // Schemas in the database
  // Other configuration options
});

See the list of config options in the PgDatabaseConfig Reference.

Define multiple databases ​

To define multiple databases, you export more than one database definition from the databases file.

ts
import { defineDatabase } from "@monolayer/pg/schema";

export default defineDatabase({
  // Database configuration options
});

export const stats = defineDatabase({
  id: "stats",
  // Other database configuration options
});

WARNING

When you define multiple databases, make sure each database definition has a unique identifier. Otherwise, you will have multiple databases with the same default identifier.

You can also re-export databases from other files.

ts
import { defineDatabase } from "@monolayer/pg/schema";
export { statsDb } from "./stats";

export default defineDatabase({
  // Database configuration options
});
ts
import { defineDatabase } from "@monolayer/pg/schema";
import { statsSchema } from "./stats-schema";

export const stats = defineDatabase({
  id: "stats",
  schemas: [statsSchema],
  // Other database configuration options
});

Database identifiers ​

Each database has a configurable unique identifier (id), and the default id is default.

The unique identifier is used internally by monolayer-pg to resolve:

  1. The current database context when running CLI commands.
  2. The environment variable name that will contain the database connection URL.

Database connection URL ​

Based on the defined database id, monolayer-pg will be able to connect to the database by fetching the database connection URL from an environment variable in the format: MONO_PG_${DATABASE_ID_TO_SNAKE_CASE_AND_UPPER_CASE}_DATABASE_URL.

EXAMPLE

For a database with the unique identifier user_stats, the expected environment variable containing the database connection URL is: MONO_PG_USER_STATS_DATABASE_URL.

TIP

monolayer-pg will also try to fetch environment variable from the .env file in your project root, if present.

Read more about database connection URLs in the PostgreSQL Documentation