@totuna/cli

☶ Totuna | @totuna/cli

Manage Your PostgreSQL RLS and Privileges as Code

Overview

Totuna makes PostgreSQL database management seamless by allowing you to handle Row Level Security (RLS) and privileges through code. Inspired by principles of Infrastructure as Code (IaC), Totuna introduces a more intuitive and efficient way to manage database states, akin to systems like Kubernetes.

• Define and track database objects and permissions using code nspired by Kubernetes' "kind" system.
• Seamlessly apply, plan, preview, and synchronize your local state with your remote database.

How does it work?

The Totuna CLI uses straightforward commands to manage your PostgreSQL databases, enabling operations such as applying changes, planning migrations, previewing pending changes, and updating your database with the latest remote state.

Installation

Install with npm, Yarn, or pnpm:

npm install -g @totuna/cli
yarn global add @totuna/cli
pnpm add -g @totuna/cli

Usage

Begin by initializing Totuna CLI and manage your PostgreSQL databases seamlessly:

# Initialize your environment
$ totuna init

# Pull the latest state from the remote database
$ totuna pull

# Preview changes to your database after modifying a file
$ totuna preview

# Generate the planned migration files to update remote state
$ totuna plan

# Run migrations applying the plan
$ totuna apply

Contributing

We encourage contributions of all forms! Feel free to submit pull requests, fix bugs, add features, or improve documentation.

Help / Discord

If you encounter any issues or need guidance, don't hesitate to join our Discord Server.

Documentation

Kind Types

Manage the following types of database objects with Totuna:

• Privileges

  • Database Privileges
  • Schema Privileges
  • Table Privileges
  • Column Privileges
  • View Privileges
  • Function Privileges
  • Sequence Privileges

• Row Level Security Policies

  • Table RLS Status & Policies

Kind Files

Manage your database objects using:

• TypeScript Files (.ts)
• YAML Files (.yaml)

Set your preferred format with the objectParser property in your totuna.config.{ts|js|json|yaml} file.

Kind Schemas Documentation

The following documentation outlines the structure for each type of Kind configuration file supported by Totuna. These schemas define how you can manage different aspects of PostgreSQL privileges and security settings through YAML or TypeScript files.

Example Files

TablePrivileges.ts

import type {TablePrivileges} from '@totuna/cli/@Objects/@Object_TablePrivileges.js'

export default {
  kind: 'TablePrivileges',
  metadata: {
    name: 'mydatabase.myschema.Employee',
  },
  spec: {
    database: 'mydatabase',
    schema: 'myschema',
    table: 'Employee',
    privileges: [
      {
        role: 'PUBLIC',
        privileges: ['SELECT'],
      },
    ],
  },
} satisfies TablePrivileges

TablePrivileges.yaml

kind: TablePrivileges
metadata:
  name: totuna.private_tables.Employee
spec:
  database: totuna
  schema: private_tables
  table: Employee
  privileges:
    - role: PUBLIC
      privileges:
        - SELECT

TableColumnsPrivileges

• Kind: TableColumnsPrivileges
• Properties:
  • metadata.name: Unique name for the column privilege setting.
  • spec.database: Name of the database.
  • spec.schema: Schema containing the table.
  • spec.table: Table containing the columns.
  • spec.privileges: Array of objects specifying column-level privileges.
    • column: Column name.
    • privileges: Array of privileges (SELECT, INSERT, UPDATE, DELETE, TRUNCATE, REFERENCES, TRIGGER) assigned to different roles.

DatabasePrivileges

• Kind: DatabasePrivileges
• Properties:
  • metadata.name: Unique name for the database privilege setting.
  • spec.database: Name of the database.
  • spec.privileges: Array of objects specifying database-level privileges.
    • role: Database role.
    • privileges: Array of privileges (CREATE, CONNECT, TEMPORARY).

FunctionPrivileges

• Kind: FunctionPrivileges
• Properties:
  • metadata.name: Unique name for the function privilege setting.
  • spec.database: Name of the database.
  • spec.schema: Schema containing the function.
  • spec.function: Function name.
  • spec.privileges: Array of objects specifying function-level privileges (EXECUTE).

SchemaPrivileges

• Kind: SchemaPrivileges
• Properties:
  • metadata.name: Unique name for the schema privilege setting.
  • spec.database: Name of the database.
  • spec.schema: Schema name.
  • spec.privileges: Array of objects specifying schema-level privileges (USAGE, CREATE).

SequencePrivileges

• Kind: SequencePrivileges
• Properties:
  • metadata.name: Unique name for the sequence privilege setting.
  • spec.database: Name of the database.
  • spec.schema: Schema containing the sequence.
  • spec.sequence: Sequence name.
  • spec.privileges: Array of privileges (USAGE, SELECT, UPDATE) assigned to different roles.

TablePrivileges

• Kind: TablePrivileges
• Properties:
  • metadata.name: Unique name for the table privilege setting.
  • spec.database: Name of the database.
  • spec.schema: Schema containing the table.
  • spec.table: Table name.
  • spec.privileges: Array of privileges (SELECT, INSERT, UPDATE, DELETE, TRUNCATE, REFERENCES, TRIGGER) assigned to different roles.

ViewPrivileges

• Kind: ViewPrivileges
• Properties:
  • metadata.name: Unique name for the view privilege setting.
  • spec.database: Name of the database.
  • spec.schema: Schema containing the view.
  • spec.view: View name.
  • spec.privileges: Array of privileges (SELECT, INSERT, UPDATE, DELETE, TRUNCATE, REFERENCES, TRIGGER) assigned to different roles.

TablePolicies

• Kind: TablePolicies
• Properties:
  • metadata.name: Unique name for the Table policy setting.
  • spec.database: Name of the database.
  • spec.schema: Schema containing the table.
  • spec.table: Table name.
  • spec.rlsEnabled: Boolean indicating if row-level security is enabled.
  • spec.policies: Array of policy objects.
    • name: Policy name.
    • as: Policy type (RESTRICTIVE, PERMISSIVE).
    • command: Commands the policy applies to (SELECT, INSERT, UPDATE, DELETE, ALL).
    • roles: Array of roles the policy applies to, with restrictions on using 'PUBLIC'.
    • using: Condition under which the policy is valid (optional).
    • withCheck: Condition to check post-operation (optional).