199 lines
4.8 KiB
Markdown
199 lines
4.8 KiB
Markdown
# 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.
|