paper_trail
Track and record all changes in your Elixir/Ecto database, allowing you to revert to any point in history.
What is paper_trail?
PaperTrail is an Elixir library that adds versioning to Ecto database models. It tracks every change (insert, update, delete) in a separate `versions` table, allowing developers to audit changes and revert to any historical state. It solves the problem of losing data history and provides a reliable audit trail for applications.
Elixir developers building applications with Ecto that require audit trails, data recovery, or compliance with data history regulations.
Developers choose PaperTrail for its transaction-safe design, minimal data duplication, and strong focus on data integrity. It offers features like strict mode for relational consistency, multi-tenancy support, and flexible metadata storage, making it a robust alternative to the Ruby paper_trail gem in the Elixir ecosystem.
Overview
Track and record all the changes in your database with Ecto. Revert back to anytime in history.
Use Cases
Best For
- Adding audit trails to Elixir Phoenix applications
- Implementing undo/redo functionality for database records
- Meeting compliance requirements for data change tracking
- Debugging data issues by reviewing historical changes
- Building multi-tenant applications with versioned data
- Ensuring data integrity in large-scale Elixir projects
Not Ideal For
- High-throughput applications where the additional transaction and table writes could become a performance bottleneck
- Projects relying heavily on database triggers or built-in versioning features instead of application-level tracking
- Systems using non-Ecto ORMs or raw SQL queries exclusively for data access
- Teams needing zero-downtime migrations without altering existing table schemas for strict mode
Pros & Cons
Pros
Wraps Ecto's insert, update, and delete operations to automatically generate version records within database transactions, ensuring data consistency as shown in the example code.
Offers strict mode with foreign key constraints between models and versions, enhancing reliability for larger applications by preventing orphaned version records.
Supports configurable origin tracking and a meta field for storing additional context, such as user IDs or slugs, enabling detailed audit trails as demonstrated in the README.
Integrates with Ecto's query prefixes to version data across different schemas or databases, making it suitable for multi-tenant applications without extra setup.
Library is assailed with hundreds of test assertions per release, emphasizing reliability and data integrity as noted in the documentation.
Cons
Requires generating and running a migration for the versions table, plus additional configuration for non-standard primary keys like UUIDs, which adds initial complexity.
Each versioned operation doubles the database writes by inserting into the versions table, potentially slowing down write-heavy applications.
Enabling strict mode necessitates adding and maintaining first_version_id and current_version_id columns in all tracked models, increasing database schema management effort.
Tied exclusively to Ecto, so it cannot version data from other sources or ORMs, limiting flexibility in mixed-stack applications.
Frequently Asked Questions
Related Projects
ectoA toolkit for data mapping and language integrated query.
postgrexPostgreSQL driver for Elixir
eventstoreEvent store using PostgreSQL for persistence
redixFast, pipelined, resilient Redis driver for Elixir. 🛍
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.