PostKit v1.3.0 – Docker Stack & Multi-Schema Release

PostKit v1.3.0 Release Notes

Released: 2026-07-02

---

Highlights

This release introduces the new Docker Stack module, allowing you to run a complete local backend—including PostgreSQL, Keycloak, PostgREST, and Traefik—with a single command. It also includes the previously introduced multi-schema PostgreSQL support, auto-container mode, improved CI/CD workflows, expanded documentation, and significant testing improvements.

---

New Features

Docker Stack

Manage your entire local backend using a single CLI command.

postkit stack up

The new Stack module includes:

• Docker Compose-based management for PostgreSQL, Keycloak, PostgREST, and Traefik
• Two-phase startup:
  • Start infrastructure services first
  • Apply infrastructure SQL, migrations, and seeds
  • Start Keycloak and PostgREST after database initialization
• Automatic Keycloak realm import
• Automatic PostgREST JWT key synchronization
• Built-in Keycloak provider support
• Project-specific Keycloak providers via auth/providers/<name>/target/
• is_initial database state to ensure one-time initialization
• Automatic reset of initialization state when running:

postkit stack down --volumes

Available commands:

postkit stack up
postkit stack down
postkit stack status
postkit stack logs
postkit stack restart
postkit stack keys
postkit stack realm

Improved postkit init

postkit init now:

• Requires a project name
• Generates a unique project identifier
• Creates the new db/infra/ structure
• Copies bundled Keycloak providers into the project
• Generates configuration compatible with Docker Stack and multi-schema projects

Multi-Schema Support

Manage multiple PostgreSQL schemas in a single PostKit project.

Config change (postkit.config.json):

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

Directory layout:

db/
├── infra/
└── schema/
    ├── public/
    └── app/

• postkit db plan runs pgschema per schema in configuration order
• Intermediate apply resolves cross-schema dependencies
• postkit db apply combines all schema plans into a single migration

postkit db schema add <name>

Create a fully scaffolded schema with a single command.

postkit db schema add app

The command:

• Creates the standard schema directory structure
• Registers the schema in postkit.config.json

Auto-Container Mode

Leave localDbUrl empty and PostKit automatically starts a matching PostgreSQL Docker container.

{
  "db": {
    "localDbUrl": ""
  }
}

The container lifecycle is managed automatically during development.

Dedicated db/infra/ Directory

Database infrastructure SQL now lives in:

db/infra/

This separates:

• Roles
• Extensions
• CREATE SCHEMA statements

from schema object definitions.

Configuration Split

Configuration is now divided into:

File	Git	Purpose
postkit.config.json	Committed	Project configuration
postkit.secrets.json	Gitignored	Secrets and database credentials

---

Improvements

• Added comprehensive Docker Stack documentation
• Added architecture documentation for the Stack module
• Added Stack command documentation
• Added multi-schema documentation
• Added cross-schema migration guide
• Added GitHub Actions PR validation workflow
• Release workflow now requires successful build, unit tests, and E2E tests
• postkit db import automatically updates configured schemas
• Infrastructure SQL is applied before planning to improve dependency resolution
• Updated all PostKit agent skills for the new project structure
• Improved documentation site with new pages and guides

---

Testing

This release includes significant test coverage improvements.

• ~130 unit tests
• 21 end-to-end tests
• Docker Stack lifecycle tests
• Stack initialization tests
• Multi-schema workflow tests
• Auto-container tests
• Restart and error handling tests

---

Bug Fixes

• Fixed TypeScript strict-mode issues across CLI test utilities
• Fixed Docker container cleanup during postkit db abort
• Improved Keycloak compatibility with newer versions
• Fixed PostgREST JWT synchronization during stack initialization
• Improved Docker networking for Keycloak configuration

---

Breaking Changes

Existing projects must migrate before upgrading to v1.3.0.

1 — Config key renamed

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

2 — Infra directory moved

Before:
db/schema/infra/

After:
db/infra/

3 — Schema SQL must be inside schema folders

Before:
db/schema/tables/

After:
db/schema/public/tables/

4 — Session state changed

Abort any active session before upgrading.

postkit db abort

5 — Generated file names changed

Before	After
.postkit/db/plan.sql	.postkit/db/plan_<schema>.sql
.postkit/db/schema.sql	.postkit/db/schema_<schema>.sql

Update your .gitignore or run:

postkit init

6 — Remotes moved to secrets file

Remote database configuration now belongs in:

postkit.secrets.json

---

Migration Guide

# Abort active session
postkit db abort

# Move infrastructure SQL
mkdir -p db/infra
mv db/schema/infra/* db/infra/

# Move schema SQL
mkdir -p db/schema/public
mv db/schema/tables \
   db/schema/functions \
   db/schema/views \
   db/schema/triggers \
   db/schema/grants \
   db/schema/rls \
   db/schema/seeds \
   db/schema/public/

# Update configuration
# schema -> schemas
# add infraPath

# Move remote configuration to postkit.secrets.json

# Re-run init
postkit init

---

Installation / Upgrade

npm install -g postkit@1.3.0

# or

npm update -g postkit