{"id":28816805,"url":"https://github.com/finepointcgi/godot-4-postgre-plugin","last_synced_at":"2025-08-10T12:27:42.903Z","repository":{"id":298562800,"uuid":"1000401662","full_name":"finepointcgi/Godot-4-Postgre-Plugin","owner":"finepointcgi","description":"A PostgreSQL database adapter for Godot 4.","archived":false,"fork":false,"pushed_at":"2025-06-16T01:14:10.000Z","size":420,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-06-19T19:10:59.089Z","etag":null,"topics":["database","gdscript","godot","godot-addon","godot-engine","godot-modules","godot-plugin","postgres","postgres-backend","postgres-frontend","postgresql","postgresqlclient","sql","sql-commands"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/finepointcgi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-11T18:13:17.000Z","updated_at":"2025-06-16T01:14:13.000Z","dependencies_parsed_at":"2025-06-11T20:05:09.142Z","dependency_job_id":"b5b41230-7ec6-4b84-8688-c8ea52741b44","html_url":"https://github.com/finepointcgi/Godot-4-Postgre-Plugin","commit_stats":null,"previous_names":["finepointcgi/godot-4-postgre-plugin"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/finepointcgi/Godot-4-Postgre-Plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/finepointcgi%2FGodot-4-Postgre-Plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/finepointcgi%2FGodot-4-Postgre-Plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/finepointcgi%2FGodot-4-Postgre-Plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/finepointcgi%2FGodot-4-Postgre-Plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/finepointcgi","download_url":"https://codeload.github.com/finepointcgi/Godot-4-Postgre-Plugin/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/finepointcgi%2FGodot-4-Postgre-Plugin/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269723371,"owners_count":24464844,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","gdscript","godot","godot-addon","godot-engine","godot-modules","godot-plugin","postgres","postgres-backend","postgres-frontend","postgresql","postgresqlclient","sql","sql-commands"],"created_at":"2025-06-18T17:07:04.848Z","updated_at":"2025-08-10T12:27:42.894Z","avatar_url":"https://github.com/finepointcgi.png","language":"C++","readme":"# PostgreSQL GDExtension for Godot\n\n[![Build Status](https://github.com/finepointcgi/PostgrePlugin/workflows/Build%20PostgreSQL%20GDExtension/badge.svg)](https://github.com/finepointcgi/PostgrePlugin/actions/workflows/build.yml)\n\nA PostgreSQL database adapter for Godot 4, implemented as a native GDExtension using C++ and libpqxx. This plugin allows PostgreSQL database connections with features like connection pooling, transaction management, and asynchronous operations.\n\n## 📦 Pre-built Binaries\n\nDownload ready-to-use binaries for all platforms from the [Releases](https://github.com/finepointcgi/PostgrePlugin/releases) page:\n- **Linux**: x86_64 and ARM64\n- **Windows**: x86_64\n- **macOS**: Universal (Intel + Apple Silicon)\n\n## Features\n\n### Core Database Operations\n- **Parameterized Queries**: Safe SQL execution with parameter binding to prevent injection attacks\n- **Connection Pooling**: Efficient connection management with configurable pool size\n- **Automatic Reconnection**: Built-in retry logic for handling connection failures\n- **Modern libpqxx API**: Uses the latest non-deprecated PostgreSQL C++ library features\n\n### Advanced Features\n- **Transaction Management**: Full ACID transaction support with explicit control\n- **Asynchronous Operations**: Non-blocking query execution with signal-based results\n- **Enhanced Parameter Types**: Support for Godot-specific types (Vector2, Vector3) and NULL values\n- **Comprehensive Error Handling**: Detailed error reporting with automatic recovery\n\n### Godot Integration\n- **Signal-Based Architecture**: Event-driven programming with database operation signals\n- **Property System**: Easy configuration through Godot's inspector\n- **Resource Management**: Automatic cleanup and proper memory handling\n\n## Installation\n\n### Prerequisites\n- Godot 4.x\n- PostgreSQL client libraries (libpq, libpqxx)\n- C++ compiler with C++17 support\n- SCons build system\n\n### macOS Installation\n```bash\n# Install dependencies via Homebrew\nbrew install postgresql libpqxx\n\n# Clone the repository\ngit clone https://github.com/yourusername/PostgrePlugin.git\ncd PostgrePlugin\n\n# Build the extension\nscons\n\n# The built plugin will be available in demo/bin/\n```\n\n### Linux Installation\n```bash\n# Install dependencies (Ubuntu/Debian)\nsudo apt-get install libpqxx-dev libpq-dev\n\n# Or for Fedora/RHEL\nsudo dnf install libpqxx-devel libpq-devel\n\n# Build as above\nscons\n```\n\n## Quick Start\n\n### Basic Setup\n```gdscript\n# Add PostgreAdapter node to your scene\n@onready var db = $PostgreAdapter\n\nfunc _ready():\n    # Configure connection\n    db.connection_string = \"postgresql://username:password@localhost:5432/database\"\n    db.pool_size = 4\n    \n    # Connect to database\n    if db.connect_to_db():\n        print(\"Connected successfully!\")\n        \n        # Execute a simple query\n        var results = db.execute_query(\"SELECT * FROM users WHERE active = $1\", [true])\n        for row in results:\n            print(\"User: \", row[\"name\"])\n```\n\n### Transaction Example\n```gdscript\n# Start transaction\nif db.begin_transaction():\n    # Execute multiple operations\n    db.execute_non_query_in_transaction(\n        \"INSERT INTO users (name, email) VALUES ($1, $2)\",\n        [\"John Doe\", \"john@example.com\"]\n    )\n    \n    db.execute_non_query_in_transaction(\n        \"UPDATE user_stats SET login_count = login_count + 1 WHERE user_id = $1\",\n        [user_id]\n    )\n    \n    # Commit or rollback\n    if success_condition:\n        db.commit_transaction()\n    else:\n        db.rollback_transaction()\n```\n\n### Asynchronous Operations\n```gdscript\nfunc _ready():\n    # Connect signals\n    db.query_completed.connect(_on_query_completed)\n    db.async_query_failed.connect(_on_query_failed)\n    \n    # Execute async query\n    db.execute_query_async(\"SELECT * FROM large_table\")\n\nfunc _on_query_completed(results: Array):\n    print(\"Async query returned \", results.size(), \" rows\")\n    process_results(results)\n\nfunc _on_query_failed(query: String, error: String):\n    print(\"Query failed: \", error)\n```\n\n## API Reference\n\n### Core Methods\n- `connect_to_db() -\u003e bool`: Establish database connection\n- `disconnect_from_db()`: Close database connection\n- `execute_query(query: String, params: Array = []) -\u003e Array`: Execute SELECT queries\n- `execute_non_query(query: String, params: Array = []) -\u003e int`: Execute INSERT/UPDATE/DELETE\n\n### Transaction Methods\n- `begin_transaction() -\u003e bool`: Start a new transaction\n- `commit_transaction() -\u003e bool`: Commit current transaction\n- `rollback_transaction() -\u003e bool`: Rollback current transaction\n- `execute_query_in_transaction(query: String, params: Array = []) -\u003e Array`\n- `execute_non_query_in_transaction(query: String, params: Array = []) -\u003e int`\n\n### Asynchronous Methods\n- `execute_query_async(query: String, params: Array = [])`: Non-blocking query execution\n- `execute_non_query_async(query: String, params: Array = [])`: Non-blocking non-query execution\n\n### Properties\n- `connection_string: String`: PostgreSQL connection string\n- `pool_size: int`: Number of connections in the pool (default: 4)\n\n### Signals\n- `query_completed(results: Array)`: Emitted when async query completes\n- `non_query_completed(affected_rows: int)`: Emitted when async non-query completes\n- `async_query_failed(query: String, error: String)`: Emitted on async operation failure\n- `transaction_started()`: Emitted when transaction begins\n- `transaction_committed()`: Emitted when transaction commits\n- `transaction_rolled_back()`: Emitted when transaction rolls back\n- `transaction_failed(error: String)`: Emitted on transaction error\n\n## Supported Parameter Types\n\nThe adapter supports automatic conversion for the following Godot types:\n- `String`: Direct string values\n- `int`/`int64`: Numeric values\n- `float`/`double`: Floating-point values\n- `bool`: Boolean values (converted to PostgreSQL boolean)\n- `Vector2`: Converted to PostgreSQL POINT type\n- `Vector3`: Converted to text representation\n- `null`: Handled as PostgreSQL NULL\n\n## Connection String Format\n\n```\npostgresql://[username[:password]@][host][:port][/database][?param1=value1\u0026...]\n```\n\nExamples:\n- `postgresql://user:pass@localhost:5432/mydb`\n- `postgresql://localhost/mydb`\n- `postgresql://user@remote.host:5433/mydb?sslmode=require`\n\n## Error Handling\n\nThe adapter provides comprehensive error handling with automatic retry logic:\n\n- **Connection Failures**: Automatic reconnection attempts\n- **Query Errors**: Detailed error messages with context\n- **Transaction Errors**: Automatic rollback on failure\n- **Signal-Based Notifications**: Real-time error reporting\n\n## Performance Considerations\n\n- **Connection Pooling**: Reduces connection overhead for multiple operations\n- **Prepared Statements**: Automatic preparation for repeated queries\n- **Asynchronous Operations**: Prevents blocking the main thread\n- **Resource Management**: Efficient memory usage with automatic cleanup\n\n## Demo Project\n\nThe included demo project showcases all features:\n- Basic CRUD operations\n- Parameterized queries with various data types\n- Transaction management\n- Asynchronous operation handling\n- Error handling and recovery\n\nTo run the demo:\n1. Update the connection string in `Demo/db_test.gd`\n2. Run the demo scene in Godot\n3. Check the console output for detailed operation logs\n\n## Building from Source\n\n### Build Requirements\n- Godot 4.x headers (included via godot-cpp submodule)\n- PostgreSQL development libraries\n- C++17 compatible compiler\n\n### Build Process\n```bash\n# Initialize submodules\ngit submodule update --init --recursive\n\n# Build godot-cpp\ncd godot-cpp\nscons platform=\u003cplatform\u003e target=template_debug\ncd ..\n\n# Build the extension\nscons platform=\u003cplatform\u003e target=template_debug\n\n# For release builds\nscons platform=\u003cplatform\u003e target=template_release\n```\n\n### Platform-Specific Notes\n\n**macOS**: Requires PostgreSQL libraries from Homebrew\n**Linux**: Install development packages for libpqxx and libpq\n**Windows**: Requires PostgreSQL development libraries and Visual Studio\n\n## Contributing\n\nContributions are welcome! Please follow these guidelines:\n- Use consistent C++ coding style\n- Include tests for new features\n- Update documentation for API changes\n- Ensure cross-platform compatibility\n\n## License\n\nThis project is licensed under the MIT License. See LICENSE file for details.\n\n## Dependencies\n\n- **godot-cpp**: Godot C++ bindings (included as submodule)\n- **libpqxx**: C++ PostgreSQL library\n- **libpq**: PostgreSQL client library\n- **SCons**: Build system\n\n## Support\n\nFor issues, questions, or contributions:\n- GitHub Issues: Report bugs and request features\n- Documentation: Check the demo project for usage examples\n- PostgreSQL Documentation: For database-specific questions\n\n## Changelog\n\n### Latest Version\n- Modern libpqxx API support (no deprecated warnings)\n- Enhanced parameter type support (Vector2, Vector3, NULL)\n- Full transaction management\n- Asynchronous operation support\n- Improved error handling and recovery\n- Comprehensive signal system\n- Connection pooling with configurable size\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffinepointcgi%2Fgodot-4-postgre-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffinepointcgi%2Fgodot-4-postgre-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffinepointcgi%2Fgodot-4-postgre-plugin/lists"}