pgsql-client is a PostgreSQL client utility specifically designed as a core component of the constructive-io ecosystem. It provides robust query helpers, integrated Row-Level Security (RLS) context management, and tools for database administration, emphasizing a database-first approach to application development. This library ships with comprehensive TypeScript types, enabling developers to build type-safe, modular PostgreSQL applications by treating the database as a version-controlled system. Its current stable version, 3.9.3, reflects ongoing development within the constructive-io framework. The project's release cadence is tied to the broader constructive-io ecosystem, which maintains active development. Key differentiators include its deep integration with RLS for fine-grained access control, support for modular database design via tools like `pgpm`, and rich developer tooling to streamline secure and scalable PostgreSQL backend development. It is important to distinguish this package from the `postgresql-client` NPM package, which was renamed to `postgrejs`.
npm install pgsql-clientVerified import paths — ran on the pinned version, not inferred.
Demonstrates connecting to a PostgreSQL database, setting Row-Level Security (RLS) context, and executing a query that is automatically filtered by the server-side RLS policies based on the session context.
Ensure you are installing from the correct scope or repository if consuming directly, or use it as intended within the `constructive-io` framework.
Consult the `pgsql-client` and PostgreSQL server release notes before performing major database upgrades. Update `pgsql-client` if necessary.
Thoroughly test RLS policies and ensure `client.setContext` is called with appropriate and verified claims/variables for every session or transaction where RLS applies. Follow PostgreSQL RLS best practices.
Refer to `pgsql-client` documentation for recommended connection pooling strategies. If not explicitly managed by the library, consider using a dedicated connection pooler alongside `pgsql-client` or ensuring clients are reused.
Review your RLS policies on the PostgreSQL server. Ensure `client.setContext` is correctly populating the session variables that your RLS policies rely on (e.g., `current_setting('jwt.claims.user_id', true)`).Verify your `DATABASE_URL` environment variable or connection string. Check PostgreSQL server logs for connection attempts and ensure the database server is running and accessible from your application's host.
Ensure proper error handling around `new Client()` and `await client.connect()`. Always check if the `client` object is defined and connected before performing database operations.