Skip to content

Commit 6c76575

Browse files
t-bookt-book
committed
update readme
1 parent 45565d5 commit 6c76575

File tree

1 file changed

+58
-194
lines changed

1 file changed

+58
-194
lines changed

‎README.md‎

Lines changed: 58 additions & 194 deletions
Original file line numberDiff line numberDiff line change
@@ -1,164 +1,61 @@
1-
# KGR Toolbox
2-
3-
A QGIS plugin for managing PostgreSQL database templates and creating portable project archives.
4-
5-
## Features
6-
7-
### 🗄️ PostgreSQL Template Management
8-
- **Create Templates**: Generate database templates from existing PostgreSQL databases without data
9-
- **Deploy Templates**: Create new databases from existing templates
10-
- **Schema Preservation**: Maintain all database structure, constraints, and relationships
11-
12-
### 📦 Portable Project Archives
13-
- **PostgreSQL to Geopackage**: Convert all PostgreSQL layers to a single portable geopackage
14-
- **Complete Project Export**: Copy all project files including DCIM folders and media
15-
- **QField Compatible**: Create archives ready for mobile data collection with QField
16-
- **Progress Tracking**: Real-time progress feedback during export process
17-
18-
## Installation
19-
20-
### From QGIS Plugin Repository
21-
1. Open QGIS
22-
2. Go to `Plugins` → `Manage and Install Plugins`
23-
3. Search for "KGR Toolbox"
24-
4. Click `Install Plugin`
25-
26-
### Manual Installation
27-
1. Download the latest release from [GitHub Releases](https://github.com/csgis/postgresql-template-manager/releases)
28-
2. Extract the zip file to your QGIS plugins directory:
29-
- **Windows**: `C:\Users\[username]\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins\`
30-
- **macOS**: `~/Library/Application Support/QGIS/QGIS3/profiles/default/python/plugins/`
31-
- **Linux**: `~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/`
32-
3. Restart QGIS
33-
4. Enable the plugin in `Plugins` → `Manage and Install Plugins` → `Installed`
34-
35-
## Usage
36-
37-
### PostgreSQL Template Management
38-
39-
#### Creating a Template
40-
1. Open the KGR Toolbox plugin
41-
2. Go to the **Database Connection** tab
42-
3. Enter your PostgreSQL connection details
43-
4. Click **Test Connection**
44-
5. Switch to the **Create Template** tab
45-
6. Select source database and enter template name
46-
7. Click **Create Template**
47-
48-
#### Deploying from Template
49-
1. Ensure your connection is configured
50-
2. Go to the **Deploy Template** tab
51-
3. Select the template database
52-
4. Enter new database name
53-
5. Click **Deploy Database**
54-
55-
### Creating Portable Archives
56-
57-
#### Export Project Archive
58-
1. Open your QGIS project with PostgreSQL layers
59-
2. Open the KGR Toolbox plugin
60-
3. Go to the **Archive Project** tab
61-
4. Select output folder
62-
5. Click **Create Portable Archive**
63-
64-
The plugin will:
65-
- Copy all project files and folders (including DCIM)
66-
- Convert all PostgreSQL layers to a single geopackage
67-
- Update the project file to use geopackage sources
68-
- Create a portable `_portable.qgs` file
69-
70-
#### Warning
71-
The archive process copies ALL files from your project directory, including DCIM folders which may be quite large. Choose your output location carefully.
72-
73-
## Requirements
74-
75-
- QGIS 3.0 or higher
76-
- PostgreSQL database with appropriate permissions
77-
- Python 3.6+ (included with QGIS)
78-
79-
## Supported Formats
80-
81-
### Input
82-
- PostgreSQL databases
83-
- QGIS projects (.qgs files)
84-
- All standard QGIS vector layers
85-
86-
### Output
87-
- PostgreSQL templates
88-
- Geopackage (.gpkg)
89-
- Portable QGIS projects
90-
91-
## Technical Details
92-
931
### SQL Commands for Template Creation
942

953
When creating a clean template from a database, the plugin executes the following SQL commands in sequence:
964

975
#### 1. Disconnect Active Users
986
```sql
997
-- Terminate all active connections to the source database
100-
SELECT pg_terminate_backend(pg_stat_activity.pid)
101-
FROM pg_stat_activity
102-
WHERE pg_stat_activity.datname = 'source_database_name'
103-
AND pid <> pg_backend_pid();
8+
SELECT pg_terminate_backend(pid)
9+
FROM pg_stat_activity
10+
WHERE datname = 'source_database_name'
11+
AND pid != pg_backend_pid();
10412
```
10513

106-
#### 2. Create Template Database (Full Copy)
14+
#### 2. Create Template Database (Full Copy with Template Flag)
10715
```sql
16+
-- Drop existing template if it exists
17+
DROP DATABASE "template_database_name";
18+
10819
-- Create the new template database as a complete copy of the source
109-
CREATE DATABASE template_database_name
110-
WITH TEMPLATE source_database_name
111-
OWNER template_owner;
20+
-- and mark it as a template in the same command
21+
CREATE DATABASE "template_database_name"
22+
WITH TEMPLATE "source_database_name"
23+
IS_TEMPLATE = true;
11224
```
11325

11426
#### 3. Truncate All Data from Template
11527
```sql
116-
-- Connect to the template database and truncate all user tables
117-
-- This removes all data but preserves the complete schema structure
118-
119-
-- Get all user tables and truncate them
120-
DO $
121-
DECLARE
122-
table_name TEXT;
123-
BEGIN
124-
FOR table_name IN
125-
SELECT schemaname||'.'||tablename
126-
FROM pg_tables
127-
WHERE schemaname NOT IN ('information_schema', 'pg_catalog')
128-
LOOP
129-
EXECUTE 'TRUNCATE TABLE ' || table_name || ' CASCADE;';
130-
END LOOP;
131-
END $;
28+
-- Connect to the template database and get all user tables
29+
SELECT schemaname, tablename
30+
FROM pg_tables
31+
WHERE schemaname NOT IN ('information_schema', 'pg_catalog', 'pg_toast')
32+
ORDER BY schemaname, tablename;
33+
34+
-- Truncate each table individually with CASCADE
35+
TRUNCATE TABLE "schema_name"."table_name" CASCADE;
13236
```
13337

134-
#### 4. Set Template Properties
38+
#### 4. Template Deployment Commands
39+
When deploying a new database from a template:
13540
```sql
136-
-- Mark database as a template
137-
UPDATE pg_database
138-
SET datistemplate = true
139-
WHERE datname = 'template_database_name';
140-
141-
-- Prevent connections during final setup
142-
UPDATE pg_database
143-
SET datallowconn = false
144-
WHERE datname = 'template_database_name';
41+
-- Drop existing database if it exists
42+
DROP DATABASE "new_database_name";
14543

146-
-- Re-enable connections after setup is complete
147-
UPDATE pg_database
148-
SET datallowconn = true
149-
WHERE datname = 'template_database_name';
44+
-- Create new database from template
45+
CREATE DATABASE "new_database_name"
46+
WITH TEMPLATE "template_database_name";
15047
```
15148

152-
#### 5. Template Deployment Commands
153-
When deploying a new database from a template:
49+
#### 5. Template Deletion Commands
50+
When deleting a template:
15451
```sql
155-
-- Create new database from template
156-
CREATE DATABASE new_database_name
157-
WITH TEMPLATE template_database_name
158-
OWNER database_owner;
52+
-- Deactivate template status first
53+
UPDATE pg_database
54+
SET datistemplate = false
55+
WHERE datname = 'template_database_name';
15956

160-
-- Grant appropriate permissions
161-
GRANT ALL PRIVILEGES ON DATABASE new_database_name TO database_user;
57+
-- Drop the template database
58+
DROP DATABASE "template_database_name";
16259
```
16360

16461
### Manual Template Creation
@@ -169,59 +66,26 @@ If you prefer to create templates manually, you can use these commands directly
16966
# Connect to PostgreSQL
17067
psql -h hostname -U username -d postgres
17168

172-
# Execute the SQL commands above in sequence
173-
```
174-
175-
## Use Cases
176-
177-
### Template Management
178-
- **Development Workflows**: Create clean database templates for new projects
179-
- **Testing**: Deploy consistent test databases
180-
- **Team Collaboration**: Share database structures without sensitive data
181-
- **Backup & Recovery**: Maintain structural backups
182-
183-
### Portable Archives
184-
- **Project Sharing**: Share projects without database dependencies
185-
- **Offline Work**: Convert online projects for offline use
186-
- **Data Distribution**: Package projects for easy distribution
187-
188-
189-
## Troubleshooting
190-
191-
### Common Issues
192-
193-
**Connection Failed**
194-
- Verify PostgreSQL server is running
195-
- Check host, port, and credentials
196-
- Ensure user has appropriate permissions
197-
198-
**Template Creation Failed**
199-
- Ensure user has CREATEDB privileges
200-
- Check database name doesn't already exist
201-
- Verify sufficient disk space
202-
203-
**Archive Export Failed**
204-
- Check write permissions in output folder
205-
- Ensure sufficient disk space
206-
- Verify QGIS project is saved
207-
208-
### Getting Help
209-
- Check the [Issues](https://github.com/csgis/kgr_toolbox/issues) page
210-
- Create a new issue with detailed description
211-
- Include QGIS version, PostgreSQL version, and error messages
212-
213-
## License
214-
215-
This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](https://opensource.org/license/mit) file for details.
216-
217-
218-
## Changelog
219-
220-
### v1.0.0
221-
- Initial release
222-
- PostgreSQL template management
223-
- Portable project archive creation
224-
- QField compatibility
225-
- Progress tracking and user feedback
226-
227-
---
69+
# 1. Terminate active connections to source database
70+
SELECT pg_terminate_backend(pid)
71+
FROM pg_stat_activity
72+
WHERE datname = 'source_database_name'
73+
AND pid != pg_backend_pid();
74+
75+
# 2. Create template database
76+
CREATE DATABASE "template_database_name"
77+
WITH TEMPLATE "source_database_name"
78+
IS_TEMPLATE = true;
79+
80+
# 3. Connect to template database
81+
\c template_database_name
82+
83+
# 4. Get list of all user tables
84+
SELECT schemaname, tablename
85+
FROM pg_tables
86+
WHERE schemaname NOT IN ('information_schema', 'pg_catalog', 'pg_toast')
87+
ORDER BY schemaname, tablename;
88+
89+
# 5. Truncate each table (repeat for each table found)
90+
TRUNCATE TABLE "schema_name"."table_name" CASCADE;
91+
```

0 commit comments

Comments
 (0)