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

PostKit v1.2.0 Custom Schema Compatibility Release

Release Notes — v1.2.0

Highlights

Custom Schema Support

PostKit now supports non-public schemas. Import and migrate databases using custom schemas like myapp with postkit db import --schema myapp. Migration tracking is stored in a dedicated postkit schema to avoid polluting your application schema.

Grants Command Removed

The standalone postkit db grants command has been removed. pgschema now manages database grants internally, simplifying the migration workflow to three steps: infra -> migration -> seeds.

Portable Migration Paths

Migration file paths in session.json and committed.json are now stored as project-relative paths. This makes state files portable across machines and team members.

AI-Powered Developer Workflows

PostKit now ships with Claude Code skills and agents for automated development:

• 7 skills: /create-pr, /write-test-e2e, /write-test-unit, /bugfix, /create-feature, /architecture, /update-docs
• 10 agents: reviewer, bugfixer, tester, validator, feature-planner, senior-engineer, architect, docs-agent, e2e-test-agent, unit-test-agent

What's New

• postkit db import --schema <name> — import databases with custom schemas
• Migration tracking in postkit.schema_migrations instead of public.schema_migrations
• Claude Code skills and agents for AI-assisted development
• GitHub Actions release workflow
• Centralized SQL query module

Breaking Changes

• postkit db grants removed — pgschema handles grants internally
• grantsApplied removed from session state — existing sessions are backward compatible

Bug Fixes

• Fix schema import leaving temporary schema.sql artifacts
• Fix deployment step sequence numbering for local clone cleanup
• Fix pgschema plan search_path handling for non-public schemas

Full Changelog

See commits since v1.0.9

PostKit v1.0.9 Bugfix Release

Release Notes — v1.0.9

Bug Fixes

Schema directory no longer cleared on db start

Previously, running postkit db start deleted all files in the schema directory before cloning the remote database. This caused loss of any existing schema changes. The schema directory is now preserved when starting a new session.

committed.json state consistency on import

When postkit db import cleared migration .sql files, the committed.json tracking file was not reset, causing stale references to deleted files. The committed state is now properly reset to {migrations: []} during import.

Infra file ordering on import

Imported infra SQL files are now generated with numeric prefixes (001_roles.sql, 002_schemas.sql) to guarantee execution order. Roles must be created before schemas since schemas reference roles via AUTHORIZATION.

---

Breaking Changes

Deployment tracking moved to remote database

The deployed and deployedAt fields have been removed from CommittedMigration. Deployment status is now determined by querying the remote database's schema_migrations table directly — the source of truth.

Impact:

• Existing committed.json files with deployed fields will continue to work — the field is silently ignored
• Multiple remotes are now properly supported — each remote's deployment status is checked independently
• No migration step required

Removed API:

• markMigrationDeployed() — no longer needed
• deployed / deployedAt fields on CommittedMigration type

New API:

• getAllCommittedMigrations() — lists all committed migrations without checking remote
• getPendingCommittedMigrations(remoteUrl) — now requires a remote URL, checks schema_migrations table

---

Documentation

• New guide: Migrating an Existing Database
• Homepage features updated with linkable routing
• Removed default Docusaurus blog posts
• Cleaned up navbar configuration

---

Full Changelog

949d27e...1f447a4 (10 commits)

• 934d7b1 — Remove automatic schema directory cleanup during start command execution
• 0a01e4b — Derive deployment status from remote schema_migrations table instead of local state
• 9d030da — Reset committed state when clearing migration directory during database import
• cd214c0 — Prefix infra SQL files with numeric ordering for consistent deployment sequence
• 0014eb5 — Add guide for migrating existing databases and update homepage illustration
• 3dc3674 — Remove default Docusaurus blog posts and update documentation site configuration
• eccba36 — Remove navbar title and add linkable routing to homepage features
• 52fd441 — Update committed migration state to verify deployment status against remote database
• d163ce5 — Remove redundant schema fixture installation and update path/execution logic in existing db import workflow
• 1f447a4 — Bump package version to 1.0.9