# Pure Hylang Migration Tool
A **100% pure Hylang v1.1.0** schema migration tool for SQLite with SQLObject integration. No Python code - everything is written in idiomatic Hylang using modern features like `hyrule` macros.
## Features
- ✨ **Pure Hylang** - Entire codebase in Hylang v1.1.0, no Python files
- 🎯 **Modern Hylang idioms** - Uses `hyrule` macros, `let` bindings, and functional patterns
- 📦 **Pip installable** - Works as a standard Python package despite being pure Hylang
- 🔄 **Full migration lifecycle** - Create, apply, rollback, validate migrations
- 🗃️ **SQLObject integration** - Seamless ORM support
- 🎨 **Colored CLI output** - Beautiful terminal interface using colorama
- 🛡️ **Transaction safety** - All migrations run in transactions
- ✅ **Validation & checksums** - Ensure migration integrity
- 🔍 **Dry-run mode** - Preview changes before applying
## Installation
### Using UV (Recommended)
[UV](https://github.com/astral-sh/uv) is a fast Python package manager that provides excellent environment handling:
```bash
# Clone the repository
git clone https://github.com/yourusername/hylang-migrations.git
cd hylang-migrations
# Create virtual environment and install
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv pip install -e .
# The tool is now available
hylang-migrate --help
```
### Using pip
```bash
# Clone the repository
git clone https://github.com/yourusername/hylang-migrations.git
cd hylang-migrations
# Install in development mode
pip install -e .
# Or build and install
pip install build
python -m build
pip install dist/hylang_migrations-*.whl
```
### From PyPI (when published)
```bash
pip install hylang-migrations
```
## Quick Start
### 1. Initialize Your Project
```bash
cd your-project
hylang-migrate init
```
This creates:
- `migrations/` directory for migration files
- `.migrations` configuration file (in Hylang format)
- Initial project structure
### 2. Create a Migration
```bash
hylang-migrate create create_users_table
```
This generates a timestamped Hylang migration file:
```hylang
;;; Migration: create_users_table
;;; Version: 20240101120000
(defclass CreateUsersTable []
(defn up [self connection]
"Apply migration"
(connection.execute
"CREATE TABLE users (
id INTEGER PRIMARY KEY,
username VARCHAR(255) UNIQUE NOT NULL,
email VARCHAR(255) UNIQUE NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
)"))
(defn down [self connection]
"Rollback migration"
(connection.execute "DROP TABLE IF EXISTS users")))
(setv migration (CreateUsersTable))
```
### 3. Run Migrations
```bash
# Apply all pending migrations
hylang-migrate migrate
# Preview changes (dry run)
hylang-migrate migrate --dry-run
# Migrate to specific version
hylang-migrate migrate --target 20240101120000
```
### 4. Check Status
```bash
hylang-migrate status
```
Output:
```
📊 Migration Status
Database: database.db
Migrations: migrations/
✅ Applied Migrations:
Version Name Applied At
20240101120000 create_users_table 2024-01-01 12:00:00
⏳ Pending Migrations:
Version Name
20240101130000 add_user_profiles
```
### 5. Rollback
```bash
# Rollback last migration
hylang-migrate rollback
# Rollback multiple migrations
hylang-migrate rollback --steps 3
# Rollback to specific version
hylang-migrate rollback --to 20240101120000
```
## Command Reference
### Global Options
- `--config PATH` - Configuration file path (default: `.migrations`)
- `--db PATH` - Database file path (default: `database.db`)
- `--migrations-dir PATH` - Migrations directory (default: `migrations`)
- `--verbose` - Verbose output
### Commands
| Command | Description | Options |
|---------|-------------|---------|
| `init` | Initialize migration system | - |
| `create NAME` | Create new migration | - |
| `migrate` | Run pending migrations | `--target VERSION`, `--dry-run` |
| `rollback` | Rollback migrations | `--steps N`, `--to VERSION`, `--dry-run` |
| `status` | Show migration status | - |
| `list` | List all migrations | `--pending`, `--applied` |
| `show VERSION` | Show migration details | - |
| `validate` | Validate migration files | - |
## Configuration
### Hylang Format (`.migrations`)
```hylang
{
:database {
:path "database.db"
:type "sqlite"
}
:migrations {
:directory "migrations"
:table-name "migration_history"
:auto-transaction true
:verify-checksums true
}
:sqlobject {
:debug false
:cache true
:lazy-update true
}
:logging {
:level "INFO"
:file "migrations.log"
}
}
```
### Environment Variables
```bash
export DB_PATH=production.db
export MIGRATIONS_DIR=db/migrations
export SQLOBJECT_DEBUG=true
```
## Writing Migrations
### Basic Migration Structure
```hylang
(require hyrule [-> ->> as->])
(import sqlite3)
(defclass MigrationName []
(defn __init__ [self]
(setv self.version "20240101120000")
(setv self.name "migration_name"))
(defn up [self connection]
"Apply migration"
;; Your forward migration logic
)
(defn down [self connection]
"Rollback migration"
;; Your rollback logic
)
(defn validate [self connection]
"Optional validation"
True)
(defn get-checksum [self]
"Calculate checksum"
(import hashlib)
(-> (hashlib.sha256)
(.update (.encode (+ self.version self.name) "utf-8"))
(.hexdigest))))
(setv migration (MigrationName))
```
### Using SQLObject Models
```hylang
(import sqlobject [SQLObject StringCol IntCol DateTimeCol BoolCol])
(import datetime [datetime])
(defclass User [SQLObject]
(setv _table "users")
(setv username (StringCol :unique True :notNone True))
(setv email (StringCol :unique True :notNone True))
(setv is-active (BoolCol :default True))
(setv created-at (DateTimeCol :default datetime.now)))
```
## Pure Hylang Implementation
This tool is written entirely in Hylang v1.1.0 with modern idioms:
### Key Files (all `.hy`):
- `cli.hy` - Command-line interface with argparse and colorama
- `migrations.hy` - Core migration engine
- `config.hy` - Configuration management
- `utils.hy` - Utility functions
- `templates.hy` - Migration and model generators
### Hylang v1.1.0 Features Used:
- `require hyrule` for modern macros
- `let` bindings for local scope
- `lfor` list comprehensions
- `#**` for keyword arguments
- f-strings for formatting
- Pattern matching with `cond`
## Development
### Setup Development Environment
```bash
# Clone repo
git clone https://github.com/yourusername/hylang-migrations.git
cd hylang-migrations
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install in development mode
pip install -e ".[dev]"
```
### Running Tests
```bash
# Run all tests
pytest tests/
# Run specific test
pytest tests/test_migrations.hy
# With coverage
pytest --cov=hylang_migrations tests/
```
### Building Package
```bash
# Build distribution
python -m build
# Upload to TestPyPI
python -m twine upload --repository testpypi dist/*
# Upload to PyPI
python -m twine upload dist/*
```
## Project Structure
```
hylang-migrations/
├── src/
│ └── hylang_migrations/
│ ├── __init__.hy # Package initialization
│ ├── __main__.hy # Module entry point
│ ├── cli.hy # CLI implementation
│ ├── migrations.hy # Core engine
│ ├── config.hy # Configuration
│ ├── utils.hy # Utilities
│ └── templates.hy # Generators
├── migrations/ # User migrations directory
│ └── *.hy # Migration files
├── tests/ # Test suite
│ └── test_*.hy # Test files
├── pyproject.toml # Package configuration
├── setup.hy # Hylang setup script
├── README.md # This file
└── LICENSE # MIT License
```
## Why Pure Hylang?
This project demonstrates that complex tools can be written entirely in Hylang without any Python code:
1. **Language Purity** - Shows Hylang's completeness as a language
2. **Lisp Power** - Leverages macros and functional programming
3. **Python Ecosystem** - Still integrates seamlessly with pip/PyPI
4. **Modern Hylang** - Uses latest v1.1.0 features and idioms
5. **Real-World Tool** - Not just a toy, but a production-ready tool
## Claude Code Integration
This package includes Claude Code subagents to help you work with Hylang migrations more effectively!
### Installing Claude Agents
```bash
# Install the Hylang migrations assistant
hylang-migrate install-claude-agent
# The agents are now available in Claude Code!
```
### Available Agents
1. **hylang-migrate-assistant** - Expert help with:
- Creating and managing migrations
- Debugging migration issues
- Schema design best practices
- Hylang v1.1.0 migration syntax
2. **hyrule-expert** - Hylang/Hyrule language expert for:
- Conditionals (`if`, `when`, `cond`)
- Loops and comprehensions
- String formatting (`.format` vs f-strings)
- Hyrule macros and utilities
To use these agents in Claude Code, type `/agents` and select the appropriate assistant.
## Contributing
Contributions must be in pure Hylang! We welcome:
- Bug fixes
- New features
- Documentation improvements
- Test coverage
- Performance optimizations
Please ensure all code follows Hylang v1.1.0 idioms and includes tests.
## License
MIT License - See LICENSE file for details.
## Acknowledgments
- Hylang community for the amazing Lisp-on-Python language
- SQLObject for the ORM functionality
- All contributors to the Python ecosystem
---
**Remember**: This entire tool is written in pure Hylang - no Python files! 🎉
Raw data
{
"_id": null,
"home_page": null,
"name": "hylang-migrations",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "James <james@example.com>",
"keywords": "database, hylang, lisp, migrations, schema, sqlite, sqlobject",
"author": null,
"author_email": "James <james@example.com>",
"download_url": "https://files.pythonhosted.org/packages/5b/94/6e4ce7f268cafc44990def486801a1d07ce8e5f3c57fac705d0625c41669/hylang_migrations-0.1.0.tar.gz",
"platform": null,
"description": "# Pure Hylang Migration Tool\n\nA **100% pure Hylang v1.1.0** schema migration tool for SQLite with SQLObject integration. No Python code - everything is written in idiomatic Hylang using modern features like `hyrule` macros.\n\n## Features\n\n- \u2728 **Pure Hylang** - Entire codebase in Hylang v1.1.0, no Python files\n- \ud83c\udfaf **Modern Hylang idioms** - Uses `hyrule` macros, `let` bindings, and functional patterns\n- \ud83d\udce6 **Pip installable** - Works as a standard Python package despite being pure Hylang\n- \ud83d\udd04 **Full migration lifecycle** - Create, apply, rollback, validate migrations\n- \ud83d\uddc3\ufe0f **SQLObject integration** - Seamless ORM support\n- \ud83c\udfa8 **Colored CLI output** - Beautiful terminal interface using colorama\n- \ud83d\udee1\ufe0f **Transaction safety** - All migrations run in transactions\n- \u2705 **Validation & checksums** - Ensure migration integrity\n- \ud83d\udd0d **Dry-run mode** - Preview changes before applying\n\n## Installation\n\n### Using UV (Recommended)\n\n[UV](https://github.com/astral-sh/uv) is a fast Python package manager that provides excellent environment handling:\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/hylang-migrations.git\ncd hylang-migrations\n\n# Create virtual environment and install\nuv venv\nsource .venv/bin/activate # On Windows: .venv\\Scripts\\activate\nuv pip install -e .\n\n# The tool is now available\nhylang-migrate --help\n```\n\n### Using pip\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/hylang-migrations.git\ncd hylang-migrations\n\n# Install in development mode\npip install -e .\n\n# Or build and install\npip install build\npython -m build\npip install dist/hylang_migrations-*.whl\n```\n\n### From PyPI (when published)\n\n```bash\npip install hylang-migrations\n```\n\n## Quick Start\n\n### 1. Initialize Your Project\n\n```bash\ncd your-project\nhylang-migrate init\n```\n\nThis creates:\n- `migrations/` directory for migration files\n- `.migrations` configuration file (in Hylang format)\n- Initial project structure\n\n### 2. Create a Migration\n\n```bash\nhylang-migrate create create_users_table\n```\n\nThis generates a timestamped Hylang migration file:\n\n```hylang\n;;; Migration: create_users_table\n;;; Version: 20240101120000\n\n(defclass CreateUsersTable []\n (defn up [self connection]\n \"Apply migration\"\n (connection.execute\n \"CREATE TABLE users (\n id INTEGER PRIMARY KEY,\n username VARCHAR(255) UNIQUE NOT NULL,\n email VARCHAR(255) UNIQUE NOT NULL,\n created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP\n )\"))\n \n (defn down [self connection]\n \"Rollback migration\"\n (connection.execute \"DROP TABLE IF EXISTS users\")))\n\n(setv migration (CreateUsersTable))\n```\n\n### 3. Run Migrations\n\n```bash\n# Apply all pending migrations\nhylang-migrate migrate\n\n# Preview changes (dry run)\nhylang-migrate migrate --dry-run\n\n# Migrate to specific version\nhylang-migrate migrate --target 20240101120000\n```\n\n### 4. Check Status\n\n```bash\nhylang-migrate status\n```\n\nOutput:\n```\n\ud83d\udcca Migration Status\n Database: database.db\n Migrations: migrations/\n\n\u2705 Applied Migrations:\nVersion Name Applied At\n20240101120000 create_users_table 2024-01-01 12:00:00\n\n\u23f3 Pending Migrations:\nVersion Name\n20240101130000 add_user_profiles\n```\n\n### 5. Rollback\n\n```bash\n# Rollback last migration\nhylang-migrate rollback\n\n# Rollback multiple migrations\nhylang-migrate rollback --steps 3\n\n# Rollback to specific version\nhylang-migrate rollback --to 20240101120000\n```\n\n## Command Reference\n\n### Global Options\n\n- `--config PATH` - Configuration file path (default: `.migrations`)\n- `--db PATH` - Database file path (default: `database.db`)\n- `--migrations-dir PATH` - Migrations directory (default: `migrations`)\n- `--verbose` - Verbose output\n\n### Commands\n\n| Command | Description | Options |\n|---------|-------------|---------|\n| `init` | Initialize migration system | - |\n| `create NAME` | Create new migration | - |\n| `migrate` | Run pending migrations | `--target VERSION`, `--dry-run` |\n| `rollback` | Rollback migrations | `--steps N`, `--to VERSION`, `--dry-run` |\n| `status` | Show migration status | - |\n| `list` | List all migrations | `--pending`, `--applied` |\n| `show VERSION` | Show migration details | - |\n| `validate` | Validate migration files | - |\n\n## Configuration\n\n### Hylang Format (`.migrations`)\n\n```hylang\n{\n :database {\n :path \"database.db\"\n :type \"sqlite\"\n }\n :migrations {\n :directory \"migrations\"\n :table-name \"migration_history\"\n :auto-transaction true\n :verify-checksums true\n }\n :sqlobject {\n :debug false\n :cache true\n :lazy-update true\n }\n :logging {\n :level \"INFO\"\n :file \"migrations.log\"\n }\n}\n```\n\n### Environment Variables\n\n```bash\nexport DB_PATH=production.db\nexport MIGRATIONS_DIR=db/migrations\nexport SQLOBJECT_DEBUG=true\n```\n\n## Writing Migrations\n\n### Basic Migration Structure\n\n```hylang\n(require hyrule [-> ->> as->])\n(import sqlite3)\n\n(defclass MigrationName []\n (defn __init__ [self]\n (setv self.version \"20240101120000\")\n (setv self.name \"migration_name\"))\n \n (defn up [self connection]\n \"Apply migration\"\n ;; Your forward migration logic\n )\n \n (defn down [self connection]\n \"Rollback migration\"\n ;; Your rollback logic\n )\n \n (defn validate [self connection]\n \"Optional validation\"\n True)\n \n (defn get-checksum [self]\n \"Calculate checksum\"\n (import hashlib)\n (-> (hashlib.sha256)\n (.update (.encode (+ self.version self.name) \"utf-8\"))\n (.hexdigest))))\n\n(setv migration (MigrationName))\n```\n\n### Using SQLObject Models\n\n```hylang\n(import sqlobject [SQLObject StringCol IntCol DateTimeCol BoolCol])\n(import datetime [datetime])\n\n(defclass User [SQLObject]\n (setv _table \"users\")\n (setv username (StringCol :unique True :notNone True))\n (setv email (StringCol :unique True :notNone True))\n (setv is-active (BoolCol :default True))\n (setv created-at (DateTimeCol :default datetime.now)))\n```\n\n## Pure Hylang Implementation\n\nThis tool is written entirely in Hylang v1.1.0 with modern idioms:\n\n### Key Files (all `.hy`):\n\n- `cli.hy` - Command-line interface with argparse and colorama\n- `migrations.hy` - Core migration engine\n- `config.hy` - Configuration management\n- `utils.hy` - Utility functions\n- `templates.hy` - Migration and model generators\n\n### Hylang v1.1.0 Features Used:\n\n- `require hyrule` for modern macros\n- `let` bindings for local scope\n- `lfor` list comprehensions\n- `#**` for keyword arguments\n- f-strings for formatting\n- Pattern matching with `cond`\n\n## Development\n\n### Setup Development Environment\n\n```bash\n# Clone repo\ngit clone https://github.com/yourusername/hylang-migrations.git\ncd hylang-migrations\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Install in development mode\npip install -e \".[dev]\"\n```\n\n### Running Tests\n\n```bash\n# Run all tests\npytest tests/\n\n# Run specific test\npytest tests/test_migrations.hy\n\n# With coverage\npytest --cov=hylang_migrations tests/\n```\n\n### Building Package\n\n```bash\n# Build distribution\npython -m build\n\n# Upload to TestPyPI\npython -m twine upload --repository testpypi dist/*\n\n# Upload to PyPI\npython -m twine upload dist/*\n```\n\n## Project Structure\n\n```\nhylang-migrations/\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 hylang_migrations/\n\u2502 \u251c\u2500\u2500 __init__.hy # Package initialization\n\u2502 \u251c\u2500\u2500 __main__.hy # Module entry point\n\u2502 \u251c\u2500\u2500 cli.hy # CLI implementation\n\u2502 \u251c\u2500\u2500 migrations.hy # Core engine\n\u2502 \u251c\u2500\u2500 config.hy # Configuration\n\u2502 \u251c\u2500\u2500 utils.hy # Utilities\n\u2502 \u2514\u2500\u2500 templates.hy # Generators\n\u251c\u2500\u2500 migrations/ # User migrations directory\n\u2502 \u2514\u2500\u2500 *.hy # Migration files\n\u251c\u2500\u2500 tests/ # Test suite\n\u2502 \u2514\u2500\u2500 test_*.hy # Test files\n\u251c\u2500\u2500 pyproject.toml # Package configuration\n\u251c\u2500\u2500 setup.hy # Hylang setup script\n\u251c\u2500\u2500 README.md # This file\n\u2514\u2500\u2500 LICENSE # MIT License\n```\n\n## Why Pure Hylang?\n\nThis project demonstrates that complex tools can be written entirely in Hylang without any Python code:\n\n1. **Language Purity** - Shows Hylang's completeness as a language\n2. **Lisp Power** - Leverages macros and functional programming\n3. **Python Ecosystem** - Still integrates seamlessly with pip/PyPI\n4. **Modern Hylang** - Uses latest v1.1.0 features and idioms\n5. **Real-World Tool** - Not just a toy, but a production-ready tool\n\n## Claude Code Integration\n\nThis package includes Claude Code subagents to help you work with Hylang migrations more effectively!\n\n### Installing Claude Agents\n\n```bash\n# Install the Hylang migrations assistant\nhylang-migrate install-claude-agent\n\n# The agents are now available in Claude Code!\n```\n\n### Available Agents\n\n1. **hylang-migrate-assistant** - Expert help with:\n - Creating and managing migrations\n - Debugging migration issues \n - Schema design best practices\n - Hylang v1.1.0 migration syntax\n\n2. **hyrule-expert** - Hylang/Hyrule language expert for:\n - Conditionals (`if`, `when`, `cond`)\n - Loops and comprehensions\n - String formatting (`.format` vs f-strings)\n - Hyrule macros and utilities\n\nTo use these agents in Claude Code, type `/agents` and select the appropriate assistant.\n\n## Contributing\n\nContributions must be in pure Hylang! We welcome:\n\n- Bug fixes\n- New features\n- Documentation improvements\n- Test coverage\n- Performance optimizations\n\nPlease ensure all code follows Hylang v1.1.0 idioms and includes tests.\n\n## License\n\nMIT License - See LICENSE file for details.\n\n## Acknowledgments\n\n- Hylang community for the amazing Lisp-on-Python language\n- SQLObject for the ORM functionality\n- All contributors to the Python ecosystem\n\n---\n\n**Remember**: This entire tool is written in pure Hylang - no Python files! \ud83c\udf89\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Pure Hylang database migration tool for SQLite - schema versioning and management in Lisp",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/yourusername/hylang-migrations/issues",
"Documentation": "https://github.com/yourusername/hylang-migrations#readme",
"Homepage": "https://github.com/yourusername/hylang-migrations",
"Repository": "https://github.com/yourusername/hylang-migrations.git"
},
"split_keywords": [
"database",
" hylang",
" lisp",
" migrations",
" schema",
" sqlite",
" sqlobject"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "640053717d614f8ed14c8e51728d49e3ba27b0cda1535a0c31a93aeb6b62417e",
"md5": "c47d7954045d7d190f87c7a8f362a23a",
"sha256": "e546520a3f3adadea0c4600049b1c9d2629233066616f667f86d843c273e045c"
},
"downloads": -1,
"filename": "hylang_migrations-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c47d7954045d7d190f87c7a8f362a23a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 6218,
"upload_time": "2025-08-31T21:11:03",
"upload_time_iso_8601": "2025-08-31T21:11:03.712642Z",
"url": "https://files.pythonhosted.org/packages/64/00/53717d614f8ed14c8e51728d49e3ba27b0cda1535a0c31a93aeb6b62417e/hylang_migrations-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5b946e4ce7f268cafc44990def486801a1d07ce8e5f3c57fac705d0625c41669",
"md5": "b351af794bbbf033b3f3fc222e90d628",
"sha256": "fa7f402a40d32339f9c08ecace6e9604cb9dfc2db6c2ad42204c08ca814d1e9a"
},
"downloads": -1,
"filename": "hylang_migrations-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "b351af794bbbf033b3f3fc222e90d628",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 38538,
"upload_time": "2025-08-31T21:11:04",
"upload_time_iso_8601": "2025-08-31T21:11:04.916050Z",
"url": "https://files.pythonhosted.org/packages/5b/94/6e4ce7f268cafc44990def486801a1d07ce8e5f3c57fac705d0625c41669/hylang_migrations-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-31 21:11:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "hylang-migrations",
"github_not_found": true,
"lcname": "hylang-migrations"
}
JSON
