|
1 | | -# replace this |
| 1 | +# @libreworks/db-provision-pgsql |
| 2 | + |
| 3 | +[](https://github.com/libreworks/db-provision-pgsql/blob/main/LICENSE) |
| 4 | +[](https://www.npmjs.com/package/@libreworks/db-provision-pgsql) |
| 5 | +[](https://github.com/libreworks/db-provision-pgsql/actions/workflows/release.yml) |
| 6 | +[](https://github.com/libreworks/db-provision-pgsql/releases) |
| 7 | +[](https://codecov.io/gh/libreworks/db-provision-pgsql) |
| 8 | + |
| 9 | +Provision databases and schemas in PostgreSQL along with roles, logins, and grants. |
| 10 | + |
| 11 | +## Installation |
| 12 | + |
| 13 | +```shell |
| 14 | +npm install @libreworks/db-provision-pgsql |
| 15 | +``` |
| 16 | + |
| 17 | +This library conforms to ECMAScript Modules (ESM). You can import this module using ESM or TypeScript syntax. |
| 18 | + |
| 19 | +```TypeScript |
| 20 | +import { Catalog } from "@libreworks/db-provision-pgsql"; |
| 21 | +``` |
| 22 | + |
| 23 | +If you're using CommonJS, you must use [dynamic imports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) instead. |
| 24 | + |
| 25 | +## Usage |
| 26 | + |
| 27 | +You can use this library to perform initialization of a PostgreSQL database server (version 11 and later). For example, creating databases, schemas, roles, users, and grants. |
| 28 | + |
| 29 | +Here is an example to provision several database objects. |
| 30 | + |
| 31 | +```typescript |
| 32 | +import { Login, Role, Catalog } from "@libreworks/db-provision-pgsql"; |
| 33 | + |
| 34 | +const username = "example_user"; |
| 35 | +const password = "🙈"; |
| 36 | +const owner = new Login(username, password); |
| 37 | +const admin = new Role("admin"); |
| 38 | +const grants = []; |
| 39 | +grants.push(admin.assignTo(owner)); |
| 40 | +const readers = new Role("readers"); |
| 41 | +const catalog = new Catalog("my_database"); |
| 42 | +const schema = catalog.createSchema(username, owner); |
| 43 | +grants.push( |
| 44 | + catalog.grant(owner, "CONNECT", "TEMP"), |
| 45 | + catalog.grant(readers, "CONNECT", "TEMP"), |
| 46 | + schema.grant(readers, "USAGE"), |
| 47 | + schema.allTables().grant(readers, "SELECT"), |
| 48 | + schema.allSequences().grant(readers, "SELECT"), |
| 49 | + schema.setDefaultTablePrivileges(readers, "SELECT").forCreator(owner), |
| 50 | + schema.setDefaultSequencePrivileges(readers, "SELECT").forCreator(owner) |
| 51 | +); |
| 52 | + |
| 53 | +// Display the SQL |
| 54 | +const statements = [ |
| 55 | + owner, |
| 56 | + admin, |
| 57 | + readers, |
| 58 | + catalog, |
| 59 | + schema, |
| 60 | + ...grants, |
| 61 | +].map((v) => v.toSql()); |
| 62 | +console.log(statements.join(";\n") + ";\n"); |
| 63 | +``` |
| 64 | + |
| 65 | +The above example outputs the following SQL statements: |
| 66 | + |
| 67 | +```sql |
| 68 | +CREATE USER example_user WITH PASSWORD '🙈'; |
| 69 | +CREATE ROLE admin; |
| 70 | +CREATE ROLE readers; |
| 71 | +CREATE DATABASE my_database ENCODING 'UTF8'; |
| 72 | +CREATE SCHEMA IF NOT EXISTS example_user AUTHORIZATION example_user; |
| 73 | +GRANT admin TO example_user; |
| 74 | +GRANT CONNECT, TEMP ON DATABASE my_database TO example_user; |
| 75 | +GRANT CONNECT, TEMP ON DATABASE my_database TO readers; |
| 76 | +GRANT USAGE ON SCHEMA example_user TO readers; |
| 77 | +GRANT SELECT ON ALL TABLES IN SCHEMA example_user TO readers; |
| 78 | +GRANT SELECT ON ALL SEQUENCES IN SCHEMA example_user TO readers; |
| 79 | +ALTER DEFAULT PRIVILEGES FOR USER example_user IN SCHEMA example_user GRANT SELECT ON TABLES TO readers; |
| 80 | +ALTER DEFAULT PRIVILEGES FOR USER example_user IN SCHEMA example_user GRANT SELECT ON SEQUENCES TO readers; |
| 81 | +``` |
0 commit comments