feat(grants): support grant and revoke for roles, tables and schemas

docs/README.md

@@ -113,6 +113,7 @@ Want to know more? Read docs:
   - [Roles](roles.md)
   - [Policies](policies.md)
   - [Extensions](extensions.md)
+  - [Grants](grants.md)
   - [Miscellaneous](misc.md)
 - [Transpiling migrations](transpiling.md)
 - [Troubleshooting](troubleshooting.md)

docs/_sidebar.md

@@ -18,6 +18,7 @@
   - [Roles](roles.md)
   - [Policies](policies.md)
   - [Extensions](extensions.md)
+  - [Grants](grants.md)
   - [Miscellaneous](misc.md)
 - [Transpiling migrations](transpiling.md)
 - [Troubleshooting](troubleshooting.md)

docs/grants.md

@@ -0,0 +1,98 @@
+# Grant Operations
+
+### `pgm.grantRoles( roles_from, roles_to, grant_roles_options )`
+
+> Define access privileges - [postgres docs](https://www.postgresql.org/docs/current/sql-grant.html)
+
+**Arguments:**
+
+- `roles_from` _[[Name](migrations.md#type) or array of [Names](migrations.md#type)]_ - names of roles
+- `roles_to` _[[Name](migrations.md#type) or array of [Names](migrations.md#type)]_ - names of roles
+- `grant_roles_options` _[object]_ - options:
+  - `withAdminOption` _[boolean]_ - default false
+  - `onlyAdminOption` _[boolean]_ - default false
+  - `cascade` _[boolean]_ - default false
+
+**Reverse Operation:** `revokeRoles`
+
+---
+
+### `pgm.revokeRoles( roles, roles_from, drop_options )`
+
+> Remove access privileges - [postgres docs](https://www.postgresql.org/docs/current/sql-revoke.html)
+
+**Arguments:**
+
+- `roles` _[[Name](migrations.md#type) or array of [Names](migrations.md#type)]_ - names of roles
+- `roles_from` _[[Name](migrations.md#type) or array of [Names](migrations.md#type)]_ - names of roles
+- `drop_options` _[object]_ - options:
+  - `onlyAdminOption` _[boolean]_ - default false
+  - `cascade` _[boolean]_ - drops also dependent objects
+
+---
+
+### `pgm.grantOnTables( grant_options )`
+
+> Define access privileges - [postgres docs](https://www.postgresql.org/docs/current/sql-grant.html)
+
+**Arguments:**
+
+- `grant_options` _[object]_ - options:
+  - `tables` _[[Name](migrations.md#type) or array of [Names](migrations.md#type)] or [ALL]_ - names of tables
+  - `schema` _[string]_ - if tables ALL, then schema name is required
+  - `privileges` _[array of TablePrivileges] or [ALL]_ - list of privileges
+  - `roles` _[[Name](migrations.md#type) or array of [Names](migrations.md#type)]_ - names of roles
+  - `withGrantOption` _[boolean]_ - default false
+  - `cascade` _[boolean]_ - default false
+
+**Reverse Operation:** `revokeOnTables`
+
+---
+
+### `pgm.revokeOnTables( revoke_options )`
+
+> Remove access privileges - [postgres docs](https://www.postgresql.org/docs/current/sql-revoke.html)
+
+**Arguments:**
+
+- `revoke_options` _[object]_ - options:
+  - `tables` _[[Name](migrations.md#type) or array of [Names](migrations.md#type)] or [ALL]_ - names of tables
+  - `schema` _[string]_ - if tables ALL, then schema name is required
+  - `privileges` _[array of TablePrivileges] or [ALL]_ - list of privileges
+  - `roles` _[[Name](migrations.md#type) or array of [Names](migrations.md#type)]_ - names of roles
+  - `withGrantOption` _[boolean]_ - default false
+  - `cascade` _[boolean]_ - drops also dependent objects
+
+---
+
+### `pgm.grantOnSchemas( grant_options )`
+
+> Define access privileges - [postgres docs](https://www.postgresql.org/docs/current/sql-grant.html)
+
+**Arguments:**
+
+- `grant_options` _[object]_ - options:
+  - `schemas` _[[Name](migrations.md#type) or array of [Names](migrations.md#type)] or [ALL]_ - names of schemas
+  - `privileges` _[array of SchemaPrivileges] or [ALL]_ - list of privileges
+  - `roles` _[[Name](migrations.md#type) or array of [Names](migrations.md#type)]_ - names of roles
+  - `withGrantOption` _[boolean]_ - default false
+  - `onlyGrantOption` _[boolean]_ - default false
+  - `cascade` _[boolean]_ - default false
+
+**Reverse Operation:** `revokeOnSchemas`
+
+---
+
+### `pgm.revokeOnSchemas( revoke_options )`
+
+> Remove access privileges - [postgres docs](https://www.postgresql.org/docs/current/sql-revoke.html)
+
+**Arguments:**
+
+- `revoke_options` _[object]_ - options:
+  - `schemas` _[[Name](migrations.md#type) or array of [Names](migrations.md#type)] or [ALL]_ - names of schemas
+  - `privileges` _[array of SchemaPrivileges] or [ALL]_ - list of privileges
+  - `roles` _[[Name](migrations.md#type) or array of [Names](migrations.md#type)]_ - names of roles
+  - `withGrantOption` _[boolean]_ - default false
+  - `onlyGrantOption` _[boolean]_ - default false
+  - `cascade` _[boolean]_ - drops also dependent objects

src/index.ts

@@ -43,6 +43,37 @@ export type {
   Type,
   Value,
 } from './operations/generalTypes';
+export type {
+  AllTablesOptions,
+  CommonGrantOnTablesOptions,
+  CommonOnTablesOptions,
+  GrantOnAllTablesOptions,
+  GrantOnSchemas,
+  GrantOnSchemasFn,
+  GrantOnSchemasOptions,
+  GrantOnSomeTablesOptions,
+  GrantOnTables,
+  GrantOnTablesFn,
+  GrantOnTablesOptions,
+  GrantRoles,
+  GrantRolesFn,
+  GrantRolesOptions,
+  OnlyAdminOption,
+  OnlyGrantOnSchemasOptions,
+  OnlyGrantOption,
+  RevokeOnObjectsOptions,
+  RevokeOnSchemas,
+  RevokeOnSchemasOptions,
+  RevokeOnTables,
+  RevokeOnTablesOptions,
+  RevokeRoles,
+  RevokeRolesOptions,
+  SchemaPrivilege,
+  SomeTablesOptions,
+  TablePrivilege,
+  WithAdminOption,
+  WithGrantOption,
+} from './operations/grants';
 export type {
   CreateIndex,
   CreateIndexFn,

src/migrationBuilder.ts

@@ -13,6 +13,7 @@ import * as domains from './operations/domains';
 import * as extensions from './operations/extensions';
 import * as functions from './operations/functions';
 import type { Operation } from './operations/generalTypes';
+import * as grants from './operations/grants';
 import * as indexes from './operations/indexes';
 import * as mViews from './operations/materializedViews';
 import * as operators from './operations/operators';
@@ -292,6 +293,28 @@ export default class MigrationBuilderImpl implements MigrationBuilder {
     ...args: Parameters<mViews.RefreshMaterializedView>
   ) => void;
 
+  public readonly grantRoles: (...args: Parameters<grants.GrantRoles>) => void;
+
+  public readonly revokeRoles: (
+    ...args: Parameters<grants.RevokeRoles>
+  ) => void;
+
+  public readonly grantOnSchemas: (
+    ...args: Parameters<grants.GrantOnSchemas>
+  ) => void;
+
+  public readonly revokeOnSchemas: (
+    ...args: Parameters<grants.RevokeOnSchemas>
+  ) => void;
+
+  public readonly grantOnTables: (
+    ...args: Parameters<grants.GrantOnTables>
+  ) => void;
+
+  public readonly revokeOnTables: (
+    ...args: Parameters<grants.RevokeOnTables>
+  ) => void;
+
   public readonly sql: (...args: Parameters<sql.Sql>) => void;
 
   public readonly func: (sql: string) => PgLiteral;
@@ -442,6 +465,13 @@ export default class MigrationBuilderImpl implements MigrationBuilder {
       mViews.refreshMaterializedView(options)
     );
 
+    this.grantRoles = wrap(grants.grantRoles(options));
+    this.revokeRoles = wrap(grants.revokeRoles(options));
+    this.grantOnSchemas = wrap(grants.grantOnSchemas(options));
+    this.revokeOnSchemas = wrap(grants.revokeOnSchemas(options));
+    this.grantOnTables = wrap(grants.grantOnTables(options));
+    this.revokeOnTables = wrap(grants.revokeOnTables(options));
+
     this.sql = wrap(sql.sql(options));
 
     // Other utilities which may be useful

src/operations/grants/grantOnSchemas.ts

@@ -0,0 +1,45 @@
+import type { MigrationOptions } from '../../types';
+import type { Name, Reversible } from '../generalTypes';
+import { revokeOnSchemas } from './revokeOnSchemas';
+import type {
+  RevokeOnObjectsOptions,
+  SchemaPrivilege,
+  WithGrantOption,
+} from './shared';
+import { asArray, asRolesStr } from './shared';
+
+export interface OnlyGrantOnSchemasOptions {
+  privileges: SchemaPrivilege | SchemaPrivilege[] | 'ALL';
+  schemas: string[] | string;
+  roles: Name | Name[];
+}
+
+export type GrantOnSchemasOptions = OnlyGrantOnSchemasOptions &
+  WithGrantOption &
+  RevokeOnObjectsOptions;
+
+export type GrantOnSchemasFn = (
+  options: GrantOnSchemasOptions
+) => string | string[];
+
+export type GrantOnSchemas = Reversible<GrantOnSchemasFn>;
+
+export function grantOnSchemas(mOptions: MigrationOptions): GrantOnSchemas {
+  const _grantOnSchemas: GrantOnSchemas = ({
+    privileges,
+    schemas,
+    roles,
+    withGrantOption,
+  }) => {
+    const rolesStr = asRolesStr(roles, mOptions);
+    const schemasStr = asArray(schemas).map(mOptions.literal).join(', ');
+    const privilegesStr = asArray(privileges).map(String).join(', ');
+    const withGrantOptionStr = withGrantOption ? ' WITH GRANT OPTION' : '';
+
+    return `GRANT ${privilegesStr} ON SCHEMA ${schemasStr} TO ${rolesStr}${withGrantOptionStr};`;
+  };
+
+  _grantOnSchemas.reverse = revokeOnSchemas(mOptions);
+
+  return _grantOnSchemas;
+}

src/operations/grants/grantOnTables.ts

@@ -0,0 +1,42 @@
+import type { MigrationOptions } from '../../types';
+import type { Reversible } from '../generalTypes';
+import { revokeOnTables } from './revokeOnTables';
+import type {
+  AllTablesOptions,
+  CommonGrantOnTablesOptions,
+  RevokeOnObjectsOptions,
+  SomeTablesOptions,
+} from './shared';
+import { asArray, asRolesStr, asTablesStr } from './shared';
+
+export type GrantOnSomeTablesOptions = CommonGrantOnTablesOptions &
+  SomeTablesOptions;
+
+export type GrantOnAllTablesOptions = CommonGrantOnTablesOptions &
+  AllTablesOptions;
+
+export type GrantOnTablesOptions =
+  | GrantOnSomeTablesOptions
+  | GrantOnAllTablesOptions;
+
+export type GrantOnTablesFn = (
+  options: GrantOnTablesOptions & RevokeOnObjectsOptions
+) => string | string[];
+
+export type GrantOnTables = Reversible<GrantOnTablesFn>;
+
+export function grantOnTables(mOptions: MigrationOptions): GrantOnTables {
+  const _grantOnTables: GrantOnTables = (options) => {
+    const { privileges, roles, withGrantOption } = options;
+    const rolesStr = asRolesStr(roles, mOptions);
+    const privilegesStr = asArray(privileges).map(String).join(', ');
+    const tablesStr = asTablesStr(options, mOptions);
+    const withGrantOptionStr = withGrantOption ? ' WITH GRANT OPTION' : '';
+
+    return `GRANT ${privilegesStr} ON ${tablesStr} TO ${rolesStr}${withGrantOptionStr};`;
+  };
+
+  _grantOnTables.reverse = revokeOnTables(mOptions);
+
+  return _grantOnTables;
+}

src/operations/grants/grantRoles.ts

@@ -0,0 +1,31 @@
+import type { MigrationOptions } from '../../types';
+import type { Name } from '../generalTypes';
+import type { RevokeRolesOptions } from './revokeRoles';
+import { revokeRoles } from './revokeRoles';
+import type { WithAdminOption } from './shared';
+import { asArray } from './shared';
+
+export type GrantRolesOptions = WithAdminOption & RevokeRolesOptions;
+
+export type GrantRolesFn = (
+  rolesFrom: Name | Name[],
+  rolesTo: Name | Name[],
+  grantRolesOptions?: GrantRolesOptions
+) => string | string[];
+
+export type GrantRoles = GrantRolesFn & { reverse: GrantRolesFn };
+
+export function grantRoles(mOptions: MigrationOptions): GrantRoles {
+  const _grantRoles: GrantRoles = (rolesFrom, rolesTo, options) => {
+    const rolesFromStr = asArray(rolesFrom).map(mOptions.literal).join(', ');
+    const rolesToStr = asArray(rolesTo).map(mOptions.literal).join(', ');
+    const withAdminOptionStr =
+      options && options.withAdminOption ? ' WITH ADMIN OPTION' : '';
+
+    return `GRANT ${rolesFromStr} TO ${rolesToStr}${withAdminOptionStr};`;
+  };
+
+  _grantRoles.reverse = revokeRoles(mOptions);
+
+  return _grantRoles;
+}

src/operations/grants/index.ts

@@ -0,0 +1,7 @@
+export * from './grantOnSchemas';
+export * from './grantOnTables';
+export * from './grantRoles';
+export * from './revokeOnSchemas';
+export * from './revokeOnTables';
+export * from './revokeRoles';
+export * from './shared';

src/operations/grants/revokeOnSchemas.ts

@@ -0,0 +1,31 @@
+import type { MigrationOptions } from '../../types';
+import type { OnlyGrantOnSchemasOptions } from './grantOnSchemas';
+import type { RevokeOnObjectsOptions } from './shared';
+import { asArray, asRolesStr } from './shared';
+
+export type RevokeOnSchemasOptions = OnlyGrantOnSchemasOptions &
+  RevokeOnObjectsOptions;
+
+export type RevokeOnSchemas = (
+  options: RevokeOnSchemasOptions
+) => string | string[];
+
+export function revokeOnSchemas(mOptions: MigrationOptions): RevokeOnSchemas {
+  const _revokeOnSchemas: RevokeOnSchemas = ({
+    privileges,
+    schemas,
+    roles,
+    onlyGrantOption,
+    cascade,
+  }) => {
+    const rolesStr = asRolesStr(roles, mOptions);
+    const schemasStr = asArray(schemas).map(mOptions.literal).join(', ');
+    const privilegesStr = asArray(privileges).map(String).join(', ');
+    const onlyGrantOptionStr = onlyGrantOption ? ' GRANT OPTION FOR' : '';
+    const cascadeStr = cascade ? ' CASCADE' : '';
+
+    return `REVOKE${onlyGrantOptionStr} ${privilegesStr} ON SCHEMA ${schemasStr} FROM ${rolesStr}${cascadeStr};`;
+  };
+
+  return _revokeOnSchemas;
+}

src/operations/grants/revokeOnTables.ts

@@ -0,0 +1,31 @@
+import type { MigrationOptions } from '../../types';
+import type {
+  AllTablesOptions,
+  CommonOnTablesOptions,
+  RevokeOnObjectsOptions,
+  SomeTablesOptions,
+} from './shared';
+import { asArray, asRolesStr, asTablesStr } from './shared';
+
+export type RevokeOnTablesOptions = CommonOnTablesOptions &
+  (AllTablesOptions | SomeTablesOptions) &
+  RevokeOnObjectsOptions;
+
+export type RevokeOnTables = (
+  options: RevokeOnTablesOptions
+) => string | string[];
+
+export function revokeOnTables(mOptions: MigrationOptions): RevokeOnTables {
+  const _revokeOnTables: RevokeOnTables = (options) => {
+    const { privileges, roles, onlyGrantOption, cascade } = options;
+    const rolesStr = asRolesStr(roles, mOptions);
+    const privilegesStr = asArray(privileges).map(String).join(', ');
+    const tablesStr = asTablesStr(options, mOptions);
+    const onlyGrantOptionStr = onlyGrantOption ? ' GRANT OPTION FOR' : '';
+    const cascadeStr = cascade ? ' CASCADE' : '';
+
+    return `REVOKE${onlyGrantOptionStr} ${privilegesStr} ON ${tablesStr} FROM ${rolesStr}${cascadeStr};`;
+  };
+
+  return _revokeOnTables;
+}