clj-postgresql
A Clojure library providing PostgreSQL helpers with automatic type conversions and connection management.
What is clj-postgresql?
clj-postgresql is a Clojure library that extends clojure.java.jdbc to simplify using advanced PostgreSQL features. It provides seamless type coercion for Clojure data structures like maps and vectors into PostgreSQL types such as JSON, arrays, and timestamps, and leverages PostgreSQL environment variables for connection management. The library reduces boilerplate by automating connections and type conversions, making it easier to integrate PostgreSQL's native capabilities into Clojure applications.
Clojure developers building applications that rely on PostgreSQL's advanced features, such as JSON storage, geometric types, PostGIS spatial data, or array columns. It is particularly useful for teams that want to minimize configuration overhead and leverage PostgreSQL's environment-based connection standards.
Developers choose clj-postgresql for its automatic integration with PostgreSQL's environment variables and ~/.pgpass, eliminating manual connection setup. Its extensible type conversion system allows seamless use of Clojure-native data structures with PostgreSQL's specialized types, reducing boilerplate and improving developer productivity compared to raw JDBC usage.
Overview
PostgreSQL helpers for Clojure projects
Use Cases
Best For
- Building Clojure applications that require seamless conversion between Clojure maps/vectors and PostgreSQL JSON/array types.
- Leveraging PostgreSQL environment variables (PGHOST, PGUSER, etc.) and ~/.pgpass for simplified, secure database connections in Clojure.
- Working with PostGIS spatial data types like points, linestrings, and polygons in Clojure, with automatic Geometry object handling.
- Using PostgreSQL geometric types (e.g., points, boxes, circles) directly in Clojure code with helper functions for creation and manipulation.
- Implementing connection pooling with HikariCP in Clojure PostgreSQL applications for improved performance.
- Extending type conversions for custom PostgreSQL database types via multimethods for maps, vectors, and numbers.
Not Ideal For
- Projects using databases other than PostgreSQL, as the library's features are specific to PostgreSQL's type system and environment variables.
- Teams requiring asynchronous or reactive database access, since clj-postgresql is built on synchronous clojure.java.jdbc with no built-in async support.
- Applications in dynamic environments where database connections are managed via service discovery or orchestration tools, rather than static environment variables.
Pros & Cons
Pros
Automatically uses PGHOST, PGUSER, and other PostgreSQL environment variables along with ~/.pgpass for connections, reducing manual setup as shown in the `pg/spec` and `pg/pool` examples.
Extends clojure.java.jdbc to convert Clojure maps, vectors, and sequences directly to PostgreSQL types like JSON, arrays, and timestamps, demonstrated in parameterized queries.
Includes built-in helpers for PostGIS spatial types (e.g., points, polygons) and PostgreSQL geometric types (e.g., boxes, circles), with functions like `st/point` and `pg/circle` for easy manipulation.
Allows custom type conversions via multimethods for maps, vectors, and numbers, enabling support for user-defined PostgreSQL types as documented in the extensibility section.
Cons
Built on clojure.java.jdbc, which is older and less performant than modern alternatives like next.jdbc, potentially hindering adoption in new Clojure projects focused on performance.
Lacks support for asynchronous database calls, making it unsuitable for high-concurrency applications that require non-blocking I/O, a common need in modern web development.
Exclusively tailored for PostgreSQL, so projects needing multi-database support or potential migration to other systems cannot use this library without significant rework.
The README provides basic examples but lacks tutorials on complex use cases, error handling, or best practices, which may increase the learning curve for production deployments.
Frequently Asked Questions
Related Projects
PostgreSQLPostgreSQL client for node.js.
pqGo PostgreSQL driver for database/sql
rust-postgresqlNative PostgreSQL driver for the Rust programming language
npgsqlNpgsql is the .NET data provider for PostgreSQL.
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.