# Getting Started
This section will help you generate example files from the ground up. If you already have an existing project and would like to keep documentation inside the project, start from Step 3.
# Steps
Step 1: Create a new directory and change into it.
$ mkdir my-project && cd my-project
Step 2: Create a
.env
file and add your credentials or use environment variables for database authorization. (You can also use parameters.)$ touch .env
Add and edit the following data to the
.env
file you just created.DB_DATABASE=example DB_HOST=localhost DB_USER=user DB_PASSWORD=password
Step 3: Install pg-generator locally or globally with your preferred package manager. If you install globally
pgen
command is available anywhere.$ npm install -g pg-generator`
Step 4: Install a generator that contains templates. If you installed the pg-generator globally, install the generator globally too. For a start, you may install
pg-generator-example
to see how pg-generator works.pg-generator-example
provides some example generators.$ npm install -g pg-generator-example
Step 5: Run generator for your database.
CLI
$ pgen example --out-dir models --clear
or add a sub-generator name after the semicolon ":" to execute a sub-generator
$ pgen example:report --out-dir reports --clear
API
import { generate } from "pg-generator"; await generate("example", { outDir: "models", clear: true });
or add sub-generator as a second parameter to use one a sub-generator
import { generate } from "pg-generator"; await generate("example", "report", { outDir: "reports", clear: true });
See pg-generator-example docs (opens new window) for the available sub-generators.
If you have complex relationships (e.g. multiple relations between the same tables etc.) in your database, you may get a naming collision error. You can try
--relation-name-functions optimal
and--relation-name-functions descriptive
. They produce longer relation names to prevent a collision.
TIP
See available options using pgen --help
or have a look at generate function documentation.
# Examples
See pg-generator-example (opens new window) plugin for an example. It provides examples of:
- Sub-generators for popular ORMs, markdown with mermaid support, and a report.
- Custom filters
- Custom context
- Shared partial usage
← Introduction Advanced →