{"library":"pgsql-client","title":"PostgreSQL Client for Constructive.io (pgsql-client)","description":"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`.","language":"javascript","status":"active","last_verified":"Wed Apr 22","install":{"commands":["npm install pgsql-client"],"cli":null},"imports":["import { Client } from 'pgsql-client'","import { ConnectionOptions } from 'pgsql-client'","await client.setContext({...})"],"auth":{"required":false,"env_vars":[]},"quickstart":{"code":"import { Client } from 'pgsql-client';\n\nasync function runPgsqlClientExample() {\n  // Ensure DATABASE_URL is set in your environment or provide a default\n  const connectionString = process.env.DATABASE_URL ?? 'postgresql://user:password@localhost:5432/mydb';\n\n  let client: Client | undefined;\n  try {\n    // Initialize and connect the PostgreSQL client\n    client = new Client(connectionString);\n    await client.connect();\n    console.log('Successfully connected to PostgreSQL database.');\n\n    // Set RLS context for the current session, crucial for secure data access\n    // In a real application, this context comes from an authenticated user's JWT claims or session data.\n    const currentUser = {\n      id: 'usr_abc123',\n      role: 'authenticated',\n      tenant_id: 'org_xyz'\n    };\n    await client.setContext({\n      role: currentUser.role,\n      'jwt.claims.user_id': currentUser.id,\n      'app.tenant_id': currentUser.tenant_id // Custom context variable for multi-tenancy\n    });\n    console.log(`RLS context set for user '${currentUser.id}' in tenant '${currentUser.tenant_id}'.`);\n\n    // Execute a query; RLS policies on the server will automatically filter results\n    // based on the 'app.tenant_id' set in the context.\n    const result = await client.query('SELECT id, name, description FROM products WHERE tenant_id = current_setting(\\'app.tenant_id\\', true)::text ORDER BY name LIMIT 3');\n    console.log('Query executed. Products (filtered by RLS):', result.rows);\n\n  } catch (error: any) {\n    console.error('Database operation failed:', error.message);\n  } finally {\n    if (client) {\n      // Always ensure the client connection is closed\n      await client.close();\n      console.log('PostgreSQL connection closed.');\n    }\n  }\n}\n\nrunPgsqlClientExample();","lang":"typescript","description":"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.","tag":null,"tag_description":null,"last_tested":null,"results":[]},"compatibility":null}