# 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:

```bash
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:

```sql
-- 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:

```bash
pg_config --sharedir
```

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

### Step 2: Copy Files

Copy the extension files:

```bash
# 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:

```sql
-- 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:

```sql
CREATE SCHEMA secure_data;
```

### Step 2: Register the Schema

Register the schema with the secure database system:

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

### Step 3: Verify the Installation

Verify that the functions are installed correctly:

```sql
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:

```sql
-- 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:

```sql
ALTER EXTENSION c77_secure_db UPDATE;
```

## Uninstalling

If needed, you can remove the extension:

```sql
DROP EXTENSION c77_secure_db CASCADE;
```

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