# Getting Started

This section will help you generate a basic generator from the ground up. We will create a markdown file for each table. Created files will contain the list of all columns of the corresponding table.

If you are not using TypeScript or Babel, please put files into the lib folder instead of the src folder.

There are two methods for creating a generator: Using a scaffold or creating manually.

# Method 1: Using Scaffold

The first method is by creating a skeleton project using the pgen-scaffold command. The created project uses the nunjucks template engine by default, but you can change it after the project is created. Don't forget to change tsconfig.json and package.json according to your needs and to update packages to the latest versions.

$ pgen-scaffold nunjucks --outDir pg-generator-awesome

# Method 2: Creating Manually

Alternatively You can create your generator manually using the following steps.

Step 1: Create a new directory starting with "pg-generator" and change into it.
```
$ mkdir pg-generator-awesome && cd pg-generator-awesome
```

Step 2: Setup Node.js module.

Create a package.json file and copy the following entries:

{
  "name": "pg-generator-awesome",
  "version": "1.0.0",
  "description": "pg-generator for my favorite ORM models.",
  "files": ["dist", "lib"],
  "keywords": ["pg-generator"]
}

Step 3: Install the latest version of the pg-generator and nunjucks templating engine we use in the examples. You can use any template engine.
```
$ npm install pg-generator nunjucks
```
Step 4: Create the default sub-generator app.
```
$ mkdir -p src/app/templates
```

Step 5: Add the following generator and template file.

src/app/index.ts

import { PgGenerator, Context } from "pg-generator";
import { join } from "path";
import { filterFunctions } from "pg-generator";
import nunjucks, { Environment } from "nunjucks";

const nunjucksLoader = new nunjucks.FileSystemLoader(join(__dirname, "templates"));
const nunjucksEnvironment = new nunjucks.Environment(nunjucksLoader, { autoescape: false });
Object.entries(...filterFunctions).forEach(([name, filter]) => nunjucksEnvironment.addFilter(name, filter));

export default class App extends PgGenerator {
  /**
   * Render content using context. Returned content is written to the disk by pg-generator.
   * @param templatePath is the path of the template file.
   * @param context is the data passed by pg-generator to the template file.
   * @returns rendered content.
   */
  protected async render(templatePath: string, context: Context): Promise<string> {
    return nunjucksEnvironment.render(templatePath, context);
  }
}

src/app/templates/[table]{schema.name # dash-case}{name # dash-case}.md.njk

|PK|FK|Name|Type|NN|Index|
|:-:|:-:|---|---|:-:|:-:|
{%- for column in table.columns %}
|{{ "🔑" if column.isPrimaryKey }}|{{ "FK" if column.isForeignKey }}|{{column.name}}|{{column.type.name}}{{ column | dboColumnTypeModifier }}|{{ "●" if column.notNull else "○" }}|{{ column.indexes.length if column.indexes.length > 0 }}|
{%- endfor %}

Step 6: Symlink your generator as if installed globally. Execute the following command from the root of your module, where package.json is located.
```
$ npm link
```
Step 7: Use your generator and see if it works.

If you get collision errors try --relationNameFunctions optimal or --relationNameFunctions optimal options. Also prefer to use .env file instead of passing credentials via CLI options.
```
$ pgen awesome --outDir db-docs --clear --host localhost --database db --user user --password password
```

Congratulations! You created your first generator. Please see Getting Started Section of the guide to see how to use it in your projects.

# Examples

For advanced examples, check pg-generator-example (opens new window) plugin. It provides examples that you may use as a basis for your generators including:

Sub-generators for popular ORMs, markdown with mermaid support, and a report.
Custom filters
Custom context
Shared partial usage

← Introduction Templates →