c77_secure_db/INSTALLATION.md

Installation Guide for c77_secure_db

This guide provides detailed instructions for installing and configuring the c77_secure_db PostgreSQL extension.

Prerequisites

• PostgreSQL 11 or higher
• Database superuser access (for installation)
• pgcrypto extension

Standard Installation (using PGXS)

Step 1: Obtain the Extension

Either download the extension from the repository or create the files manually:

1. c77_secure_db.control - Extension control file
2. c77_secure_db--1.0.0.sql - SQL for extension version 1.0.0
3. Makefile - For installation with PGXS

Step 2: Build and Install

Use the PostgreSQL build infrastructure (PGXS) to build and install the extension:

make
sudo make install

This will copy the files to the appropriate PostgreSQL extension directories.

Step 3: Create the Extension in Your Database

Connect to your database and create the extension:

-- First, ensure pgcrypto is installed
CREATE EXTENSION IF NOT EXISTS pgcrypto;

-- Then create the c77_secure_db extension
CREATE EXTENSION c77_secure_db;

Manual Installation

If you don't have development tools or prefer a manual installation:

Step 1: Locate PostgreSQL Extension Directory

Find your PostgreSQL extension directory:

pg_config --sharedir

The extension directory is usually [pg_sharedir]/extension/.

Step 2: Copy Files

Copy the extension files:

# Replace [pg_sharedir] with the output from pg_config --sharedir
cp c77_secure_db.control [pg_sharedir]/extension/
cp c77_secure_db--1.0.0.sql [pg_sharedir]/extension/

Step 3: Create the Extension

Connect to your database and create the extension:

-- First, ensure pgcrypto is installed
CREATE EXTENSION IF NOT EXISTS pgcrypto;

-- Then create the c77_secure_db extension
CREATE EXTENSION c77_secure_db;

Post-Installation Configuration

Step 1: Create a Secure Schema

Create a schema for your secure tables:

CREATE SCHEMA secure_data;

Step 2: Register the Schema

Register the schema with the secure database system:

SELECT c77_manage_secure_schemas('add', 'secure_data');

Step 3: Verify the Installation

Verify that the functions are installed correctly:

SELECT pg_proc.proname
FROM pg_proc
JOIN pg_namespace ON pg_proc.pronamespace = pg_namespace.oid
WHERE pg_namespace.nspname = 'public'
AND pg_proc.proname LIKE 'c77_%';

This should return a list of all the c77_ functions.

Testing

Create a test table and verify that direct modifications are blocked:

-- Create a test table
CREATE TABLE secure_data.test_table (
    id SERIAL PRIMARY KEY,
    name TEXT NOT NULL,
    content_hash TEXT,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW(),
    deleted_at TIMESTAMPTZ DEFAULT NULL
);

-- Attempt a direct insertion (this should fail)
INSERT INTO secure_data.test_table (name) VALUES ('Test');

-- Use the secure operation function (this should succeed)
SELECT c77_secure_db_operation(
    jsonb_build_object(
        'schema_name', 'secure_data',
        'table_name', 'test_table',
        'operation', 'insert',
        'data', jsonb_build_object(
            'name', 'Secure Test'
        )
    )
);

-- Verify the record was inserted with content_hash
SELECT * FROM secure_data.test_table;

Troubleshooting

Common Issues

1. Extension files not found

   If you see an error like "could not open extension control file", ensure the .control file is in the correct location.

   Solution: Verify the location with pg_config --sharedir and check that the file is in the extension subdirectory.

2. pgcrypto not installed

   The extension requires pgcrypto to be installed first.

   Solution: Run CREATE EXTENSION pgcrypto; before trying to create the c77_secure_db extension.

3. Permission denied for schema public

   If you get a permission error when creating the extension, you may not have sufficient privileges.

   Solution: Connect as a database superuser to create the extension.

4. Event trigger creation fails

   If the event trigger fails to create, it might already exist or you might not have permission.

   Solution: Check if the trigger exists with SELECT * FROM pg_event_trigger; and drop it if needed.

Getting Help

If you encounter issues not covered in this guide, please:

1. Check the PostgreSQL logs for detailed error messages
2. Verify that all prerequisite steps have been completed
3. Contact the extension maintainer for support

Upgrading

To upgrade the extension in the future:

ALTER EXTENSION c77_secure_db UPDATE;

Uninstalling

If needed, you can remove the extension:

DROP EXTENSION c77_secure_db CASCADE;

Note: This will not drop any secured tables, but the security triggers will be removed.