Expose a public Golang API

api_doc.md

@@ -0,0 +1,105 @@
+# pgschema Public API
+
+This package provides a programmatic API for pgschema's PostgreSQL schema management functionality. It offers Terraform-style declarative schema migration workflows with dump/plan/apply operations that can be used directly from Go code.
+
+## Quick Start
+
+```go
+package main
+
+import (
+    "context"
+    "log"
+
+    "github.com/pgschema/pgschema/pgschema"
+)
+
+func main() {
+    ctx := context.Background()
+
+    dbConfig := pgschema.DatabaseConfig{
+        Host:     "localhost",
+        Port:     5432,
+        Database: "myapp",
+        User:     "postgres",
+        Password: "password",
+        Schema:   "public",
+    }
+
+    // Dump current schema
+    schema, err := pgschema.DumpSchema(ctx, dbConfig)
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    // Generate migration plan
+    plan, err := pgschema.GeneratePlan(ctx, dbConfig, "desired_schema.sql")
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    // Apply migration
+    err = pgschema.ApplyPlan(ctx, dbConfig, plan, true)
+    if err != nil {
+        log.Fatal(err)
+    }
+}
+```
+
+## Core Operations
+
+### Dump
+
+Extract current database schema as SQL:
+
+```go
+// Simple dump to string
+schema, err := pgschema.DumpSchema(ctx, dbConfig)
+
+// Dump to file
+err := pgschema.DumpSchemaToFile(ctx, dbConfig, "schema.sql")
+
+// Dump to multiple files organized by object type
+err := pgschema.DumpSchemaMultiFile(ctx, dbConfig, "schemas/")
+```
+
+### Plan
+
+Generate migration plans by comparing current and desired states:
+
+```go
+// Generate plan from desired state file
+plan, err := pgschema.GeneratePlan(ctx, dbConfig, "desired_schema.sql")
+
+// Generate plan with custom options
+client := pgschema.NewClient(dbConfig)
+plan, err := client.Plan(ctx, pgschema.PlanOptions{
+    File:            "desired_schema.sql",
+    ApplicationName: "my-migration-tool",
+})
+```
+
+### Apply
+
+Apply migration plans to update database schema:
+
+```go
+// Apply schema file directly
+err := pgschema.ApplySchemaFile(ctx, dbConfig, "desired_schema.sql", false)
+
+// Apply with auto-approval (no prompts)
+err := pgschema.ApplySchemaFile(ctx, dbConfig, "desired_schema.sql", true)
+
+// Apply silently (no output)
+err := pgschema.QuietApplySchemaFile(ctx, dbConfig, "desired_schema.sql")
+```
+
+## Relationship to CLI
+
+This API provides programmatic access to the same functionality available through the pgschema CLI commands:
+
+- `pgschema dump` → `pgschema.DumpSchema()` / `Client.Dump()`
+- `pgschema plan` → `pgschema.GeneratePlan()` / `Client.Plan()`
+- `pgschema apply` → `pgschema.ApplySchemaFile()` / `Client.Apply()`
+
+The CLI commands and public API are independent - using the API doesn't affect CLI behavior.

convenience.go

@@ -0,0 +1,79 @@
+package pgschema
+
+import (
+	"context"
+
+	"github.com/pgschema/pgschema/internal/plan"
+)
+
+// DumpSchema is a convenience function to dump a database schema as a single SQL string.
+func DumpSchema(ctx context.Context, dbConfig DatabaseConfig) (string, error) {
+	client := NewClient(dbConfig)
+	return client.Dump(ctx, DumpOptions{})
+}
+
+// DumpSchemaToFile is a convenience function to dump a database schema to a single file.
+func DumpSchemaToFile(ctx context.Context, dbConfig DatabaseConfig, filePath string) error {
+	client := NewClient(dbConfig)
+	_, err := client.Dump(ctx, DumpOptions{
+		File: filePath,
+	})
+	return err
+}
+
+// DumpSchemaMultiFile is a convenience function to dump a database schema to multiple files.
+func DumpSchemaMultiFile(ctx context.Context, dbConfig DatabaseConfig, basePath string) error {
+	client := NewClient(dbConfig)
+	_, err := client.Dump(ctx, DumpOptions{
+		MultiFile: true,
+		File:      basePath,
+	})
+	return err
+}
+
+// GeneratePlan is a convenience function to generate a migration plan from a desired state file.
+func GeneratePlan(ctx context.Context, dbConfig DatabaseConfig, desiredStateFile string) (*plan.Plan, error) {
+	client := NewClient(dbConfig)
+	return client.Plan(ctx, PlanOptions{
+		File: desiredStateFile,
+	})
+}
+
+// ApplySchemaFile is a convenience function to apply a desired state schema file directly.
+// This generates a plan and applies it in one operation.
+func ApplySchemaFile(ctx context.Context, dbConfig DatabaseConfig, desiredStateFile string, autoApprove bool) error {
+	client := NewClient(dbConfig)
+	return client.Apply(ctx, ApplyOptions{
+		File:        desiredStateFile,
+		AutoApprove: autoApprove,
+	})
+}
+
+// ApplyPlan is a convenience function to apply a pre-generated migration plan.
+func ApplyPlan(ctx context.Context, dbConfig DatabaseConfig, migrationPlan *plan.Plan, autoApprove bool) error {
+	client := NewClient(dbConfig)
+	return client.Apply(ctx, ApplyOptions{
+		Plan:        migrationPlan,
+		AutoApprove: autoApprove,
+	})
+}
+
+// QuietApplySchemaFile is like ApplySchemaFile but suppresses all output except errors.
+func QuietApplySchemaFile(ctx context.Context, dbConfig DatabaseConfig, desiredStateFile string) error {
+	client := NewClient(dbConfig)
+	return client.Apply(ctx, ApplyOptions{
+		File:        desiredStateFile,
+		AutoApprove: true,
+		Quiet:       true,
+	})
+}
+
+// QuietApplyPlan is like ApplyPlan but suppresses all output except errors.
+func QuietApplyPlan(ctx context.Context, dbConfig DatabaseConfig, migrationPlan *plan.Plan) error {
+	client := NewClient(dbConfig)
+	return client.Apply(ctx, ApplyOptions{
+		Plan:        migrationPlan,
+		AutoApprove: true,
+		Quiet:       true,
+	})
+}