Zodgres is a TypeScript-first library designed to simplify database interactions by providing type-safe collections built on top of Postgres.js and Zod. It enables developers to define database schemas using familiar Zod syntax, which then powers automatic migrations to ensure the PostgreSQL database structure remains synchronized with the code. By leveraging static type inference, Zodgres provides full TypeScript support, ensuring that data objects created, retrieved, or updated through the library are validated and correctly typed at compile time. This approach significantly reduces runtime errors and boilerplate code associated with manual SQL string construction.

The functionality of Zodgres centers on its collection-based API, which wraps common CRUD operations in a fluent, type-safe interface. It supports advanced features such as JSON field storage, custom unique constraints, and complex SQL template literals for scenarios where raw querying power is required. Designed for scalability and developer productivity, the library handles the complexities of database connectivity and synchronization automatically, allowing teams to focus on application logic rather than schema management.

Some of the key features are:

• Type-safe: Offers full TypeScript support with Zod schema validation for robust data handling
• Simple API: Provides a collection-based interface that abstracts away complex database operations
• Flexible: Supports standard PostgreSQL connections as well as in-memory databases for testing
• SQL Templates: Uses ES6 tagged template literals to allow for complex, parameter-safe SQL queries
• Auto-migration: Automatically synchronizes PostgreSQL tables with your Zod schema definitions
• Raw SQL Execution: Allows for direct database access through specialized methods while maintaining parameter safety
• Performance Oriented: Supports batch operations and provides utilities for query optimization

The library is used by defining collection instances and then calling a central connection method to initialize the database and execute necessary migrations. Developers interact with these collections directly using methods like create, select, update, or delete. For more advanced requirements, the library provides hooks to execute custom raw SQL, which is especially useful for creating indexes, views, or performing specialized data transformations that fall outside the standard schema mapping capabilities.

Some common use cases include:

• Rapid Prototyping: Quickly setting up and iterating on database schemas with automatic migrations
• Type-Safe Backend Services: Building reliable Node.js backends where database data must strictly match TypeScript interfaces
• Automated Testing: Using in-memory database instances to run isolated, fast integration tests for data access layers
• Complex Querying: Executing highly customized, performance-tuned SQL queries while still utilizing type-safe collection references
• Database Evolution: Managing evolving project requirements through seamless automatic and manual migration workflows