Project Structure

User Project Structure

my-project/
├── db/                       # User's database code (git tracked)
│   ├── infra/                # DB-level: roles, extensions, CREATE SCHEMA
│   │   ├── 001_roles.sql
│   │   ├── 002_extensions.sql
│   │   └── 003_schemas.sql
│   └── schema/               # Per-schema SQL files
│       ├── public/           # Schema: "public"
│       │   ├── tables/
│       │   │   ├── 001_users.sql
│       │   │   └── ...
│       │   ├── views/
│       │   ├── functions/
│       │   ├── triggers/
│       │   ├── types/
│       │   ├── enums/
│       │   ├── grants/
│       │   └── seeds/
│       └── app/              # Schema: "app" (optional)
│           ├── tables/
│           └── seeds/
├── .postkit/                 # PostKit runtime (gitignored)
│   ├── db/                   # All DB runtime files
│   │   ├── session.json      # Session state
│   │   ├── committed.json    # Committed migrations tracking
│   │   ├── plan_public.sql   # Generated plan per schema
│   │   ├── plan_app.sql
│   │   ├── schema_public.sql # Generated schema artifact per schema
│   │   ├── schema_app.sql
│   │   ├── session/          # Session migrations (temporary)
│   │   └── migrations/       # Committed migrations (for deploy)
│   └── auth/                 # Auth module runtime files
│       ├── raw/              # Raw exports from source Keycloak
│       │   └── {realm}.json
│       └── realm/            # Cleaned configs for import
│           └── {realm}.json
├── postkit.config.json       # Project configuration
├── .env                      # Environment variables (gitignored)
└── package.json

Schema Directory

The db/ directory is organized into infrastructure and per-schema sections:

Infrastructure (Handled Separately)

Directory	Description	Processed By
db/infra/	DB-level: roles, extensions, CREATE SCHEMA	Applied separately (excluded from pgschema)

Schema Objects (Processed by postkit db plan)

Each schema has its own subdirectory under db/schema/<name>/:

Directory	Description	Supported by pgschema
db/schema/<name>/types/	Custom types	✅ Yes
db/schema/<name>/enums/	ENUM types	✅ Yes
db/schema/<name>/tables/	Table definitions	✅ Yes
db/schema/<name>/views/	View definitions	✅ Yes
db/schema/<name>/functions/	Function definitions	✅ Yes
db/schema/<name>/triggers/	Trigger definitions	✅ Yes
db/schema/<name>/indexes/	Index definitions	✅ Yes

Post-Migration (Handled Separately)

Directory	Description	Processed By
db/schema/<name>/grants/	Grant statements	Managed by pgschema
db/schema/<name>/seeds/	Seed data	Applied separately

Note: Cluster and database level commands (CREATE DATABASE, CREATE ROLE, CREATE EXTENSION, etc.) are not supported by pgschema. Use db/infra/ or manual migrations instead.

PostKit Runtime Directory

The .postkit/ directory contains runtime files that are not tracked by git:

Database Module (db/)

File/Directory	Description
session.json	Current session state
committed.json	Committed migrations tracking
plan_<name>.sql	Generated migration plan per schema (e.g. plan_public.sql, plan_app.sql)
schema_<name>.sql	Generated schema artifact per schema (e.g. schema_public.sql)
session/	Session migrations (temporary, cleared on commit)
migrations/	Committed migrations (for deployment)

Auth Module (auth/)

File/Directory	Description
raw/{realm}.json	Raw export from source Keycloak (includes IDs, secrets)
realm/{realm}.json	Cleaned config ready for import (IDs, secrets stripped)

Config File

postkit.config.json in your project root (committed, non-sensitive settings only):

{
  "db": {
    "infraPath": "db/infra",
    "schemaPath": "db/schema",
    "schemas": ["public"]
  }
}

Credentials and remote configurations belong in postkit.secrets.json (gitignored). See Configuration for the full reference.

Run postkit init to create the .postkit/ directory structure.