pgterra 0.1.2 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Terra Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,69 +1,93 @@
-# pgterra
-
-Declarative schema management for Postgres. Define your desired schema, pgterra handles the migrations.
-
-## Quick Start
+<div align="center">
+  <img src="assets/readme-hero.png" alt="Terra - Declarative PostgreSQL schema management" />
+  <br />
+  <br />
+  <a href="https://github.com/elitan/terra/blob/main/LICENSE">
+    <img alt="MIT License" src="https://img.shields.io/github/license/elitan/terra" />
+  </a>
+  <a href="https://github.com/elitan/terra/stargazers">
+    <img alt="GitHub Stars" src="https://img.shields.io/github/stars/elitan/terra?style=social" />
+  </a>
+  <br />
+  <a href="https://x.com/elitasson">
+    <img alt="Twitter Follow" src="https://img.shields.io/twitter/follow/elitasson?style=social" />
+  </a>
+</div>
+
+<br />
+
+Declarative PostgreSQL schema management. Write CREATE statements, Terra generates the migrations.
+
+## Install
 
 ```bash
 npm install -g pgterra
 ```
 
-## How it works
+## Usage
 
-**1. Start with a schema:**
+**1. Create schema.sql:**
 
 ```sql
--- schema.sql
 CREATE TABLE users (
   id SERIAL PRIMARY KEY,
-  email VARCHAR(255) NOT NULL UNIQUE,
-  created_at TIMESTAMP DEFAULT NOW()
+  email VARCHAR(255) NOT NULL UNIQUE
 );
 ```
 
+**2. Preview changes:**
+
+```bash
+terra plan
+```
+
+**3. Apply:**
+
 ```bash
-pgterra apply  # Creates the table
+terra apply
 ```
 
-**2. Update your schema declaratively:**
+**4. Update schema.sql:**
 
 ```sql
--- schema.sql
 CREATE TABLE users (
   id SERIAL PRIMARY KEY,
   email VARCHAR(255) NOT NULL UNIQUE,
-  full_name VARCHAR(200) NOT NULL,  -- new column
-  is_active BOOLEAN DEFAULT true,   -- another new column
-  created_at TIMESTAMP DEFAULT NOW()
+  name VARCHAR(100) NOT NULL,        -- added
+  active BOOLEAN DEFAULT true        -- added
 );
 
-CREATE TABLE posts (                 -- new table
+CREATE TABLE posts (                 -- added
   id SERIAL PRIMARY KEY,
   title VARCHAR(255) NOT NULL,
-  user_id INTEGER REFERENCES users(id),
-  created_at TIMESTAMP DEFAULT NOW()
+  user_id INTEGER NOT NULL,
+  CONSTRAINT fk_user FOREIGN KEY (user_id) REFERENCES users(id)
 );
+
+CREATE INDEX idx_user_email ON users (LOWER(email));  -- added
 ```
 
-**3. pgterra calculates the migration:**
+**5. Terra generates the ALTER statements:**
 
 ```bash
-$ pgterra plan
-📋 Analyzing schema changes...
+$ terra plan
+ALTER TABLE users ADD COLUMN name VARCHAR(100) NOT NULL
+ALTER TABLE users ADD COLUMN active BOOLEAN DEFAULT true
+CREATE TABLE posts (...)
+CREATE INDEX idx_user_email ON users (LOWER(email))
 
-Planned changes:
-  1. ALTER TABLE users ADD COLUMN full_name VARCHAR(200) NOT NULL
-  2. ALTER TABLE users ADD COLUMN is_active BOOLEAN DEFAULT true  
-  3. CREATE TABLE posts (id SERIAL PRIMARY KEY, title VARCHAR(255) NOT NULL, user_id INTEGER REFERENCES users(id), created_at TIMESTAMP DEFAULT NOW())
-
-$ pgterra apply  # Applies the changes safely
+$ terra apply
 ```
 
-**That's it.** No migration files, no manual ALTER statements, no dependency ordering. Just define what you want.
-
 ## Configuration
 
-Set your database connection:
+Database connection via `DATABASE_URL` or individual variables:
+
+```bash
+export DATABASE_URL="postgres://user:password@localhost:5432/mydb"
+```
+
+Or:
 
 ```bash
 export DB_HOST=localhost
@@ -73,37 +97,142 @@ export DB_USER=postgres
 export DB_PASSWORD=password
 ```
 
-## Features
+## What's supported
+
+**Tables & Columns:**
+All PostgreSQL column types, default values, NOT NULL constraints
+
+**Functions & Procedures:**
+User-defined functions and procedures with full PostgreSQL feature support
+
+**Triggers:**
+Table triggers with BEFORE/AFTER/INSTEAD OF timing
+
+**Sequences:**
+Custom sequences with configurable properties
+
+**Constraints:**
+```sql
+-- Primary keys
+id SERIAL PRIMARY KEY
+
+-- Foreign keys with actions
+CONSTRAINT fk_user FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+
+-- Check constraints
+CONSTRAINT check_positive CHECK (quantity > 0)
+
+-- Unique constraints
+email VARCHAR(255) UNIQUE
+CONSTRAINT unique_email UNIQUE (email, domain)
+```
+
+**Indexes:**
+```sql
+-- Basic
+CREATE INDEX idx_email ON users (email);
+
+-- Partial
+CREATE INDEX idx_active_users ON users (email) WHERE active = true;
+
+-- Expression
+CREATE INDEX idx_lower_email ON users (LOWER(email));
+
+-- Concurrent (built automatically when safe)
+```
+
+**ENUM types:**
+```sql
+CREATE TYPE status AS ENUM ('pending', 'active', 'inactive');
+
+CREATE TABLE users (
+  id SERIAL PRIMARY KEY,
+  status status NOT NULL
+);
+```
+
+**Views:**
+```sql
+CREATE VIEW active_users AS
+SELECT id, email FROM users WHERE active = true;
+
+CREATE MATERIALIZED VIEW user_stats AS
+SELECT COUNT(*) as total FROM users;
+```
+
+**Functions:**
+```sql
+CREATE FUNCTION calculate_total(quantity INT, price DECIMAL)
+RETURNS DECIMAL
+AS $$
+  SELECT quantity * price
+$$
+LANGUAGE SQL IMMUTABLE;
+```
 
-- ✅ Tables, columns, and data types
-- ✅ Primary keys, foreign keys, check constraints, unique constraints  
-- ✅ Indexes (btree, gin, gist, partial, expression-based)
-- ✅ ENUM types
-- ✅ Dependency resolution for complex schemas
-- ✅ Data-safe migrations with validation
-- ✅ Destructive operation protection
+**Procedures:**
+```sql
+CREATE PROCEDURE archive_old_posts(days_old INT)
+LANGUAGE SQL
+AS $$
+  DELETE FROM posts WHERE created_at < NOW() - INTERVAL '1 day' * days_old;
+$$;
+```
+
+**Triggers:**
+```sql
+-- First create a trigger function
+CREATE FUNCTION update_modified_timestamp()
+RETURNS TRIGGER
+AS $$
+  BEGIN
+    NEW.modified_at = NOW();
+    RETURN NEW;
+  END;
+$$
+LANGUAGE plpgsql;
+
+-- Then create the trigger
+CREATE TRIGGER set_modified_timestamp
+BEFORE UPDATE ON users
+FOR EACH ROW
+EXECUTE FUNCTION update_modified_timestamp();
+```
 
-## Why declarative?
+**Sequences:**
+```sql
+CREATE SEQUENCE custom_id_seq
+START 1000
+INCREMENT 1
+CACHE 20;
+```
 
-Like Terraform for infrastructure, pgterra lets you define *what* you want, not *how* to get there:
+## Commands
 
-- **Version control your complete schema** - not scattered migration files
-- **No migration ordering issues** - pgterra handles dependencies
-- **Easier code reviews** - see the full schema state, not just changes
-- **Safe schema changes** - preview before applying, with rollback support
+```bash
+terra plan                    # Preview changes
+terra plan -f custom.sql      # Use custom schema file
+terra apply                   # Apply changes
+terra apply -f custom.sql     # Apply from custom file
+```
 
 ## Development
 
+Requires [Bun](https://bun.sh):
+
 ```bash
-git clone https://github.com/elitan/pgterra.git
-cd pgterra
+git clone https://github.com/elitan/terra.git
+cd terra
 bun install
 
-# Set up test database connection
-export DATABASE_URL="postgres://user:password@localhost:5432/test_db"
+# Start test database
+docker compose up -d
 
 # Run tests
+export DATABASE_URL="postgres://test_user:test_password@localhost:5487/sql_terraform_test"
 bun test
 ```
 
-**Note:** Tests require a `DATABASE_URL` environment variable pointing to a PostgreSQL database. The tests will create and drop tables as needed, so use a dedicated test database.
+## License
+
+MIT