PostgreSQLClient for Godot Engine (GDscript)

<img src="./icon.svg"> Godot PostgreSQL Client is a GDscript script / class that allows you to connect to a Postgres backend and run SQL commands there. It is able to send data and receive it from the backend. Useful for managing player user data on a multiplayer game, by saving a large amount of data on a dedicated Postgres server from GDscript.

The class is written in pure GDScript which allows it not to depend on GDNative. This makes it ultra portable for many platforms. You can see a taste of using the Postgresql connector for Godot 3.0 in the "Helloworld.gd" file.

There are still some minor features to add but now the script is ready for production.

There is also a version for Godot 4 which fixes some nasty errors in postgreSQLClient. Next semester, I will no longer support Godot 3.x, instead I will support Godot 4 (alpha branch of the repository currently not finalized).

INSTALLATION PROCEDURE:

It is assumed that you have installed the latest version of PostgreSQL and that you have created a database. Access Godot's AssetLib catalog search for PostgreSQLClient. Include the PostgreSQLClient.gd file in your project (only this file is really needed).

Download the file "PostgreSQLClient.gd" then include it in your Godot project folders ("res: //").

The PostgreSQLClient class should now be accessible from any GDscript script. Otherwise, set the script to "Auto load" in your project settings.

HOW TO USE?:

Find an example of minimalist use in the <a href="./Helloworld.gd">Helloworld.gd</a> file. Other examples will be provided later.

You can also watch <a href="https://github.com/finepointcgi">Mitch McCollum (finepointcgi)</a> video tutorial here:

DONATION:

This project is maintained by an enthusiast who develops it in his spare time. If you feel like it, you can buy me a cup of coffee.

FREQUENTLY ASKED QUESTIONS

I get the error "The connection attempt failed. The backend does not want to establish a secure SSL/TLS connection", what does this mean?

---> please visit this link to understand: https://github.com/Marzin-bot/PostgreSQLClient/issues/29

PostgreSQLClient DOCUMENTATION (NOT FINALIZED):

This documentation concerns the version of the module intended for Godot 3. If you work with Godot 4 Look in the <a href="https://github.com/Marzin-bot/PostgreSQLClient/tree/alpha">alpha branch</a>!

PROPERTIES:

| Type | Properties | Default value | | --- | --- | --- | | float | PROTOCOL_VERSION const | 3.0 | | Dictionary | parameter_status reader alone | {} | | Dictionary | error_object reader alone | {} |

METHODS:

| Type | Method | | --- | --- | | Error | connect_to_host(url: String, ssl: bool = false, connect_timeout: int = 30) | | Status | get_status() | | Array | execute(sql: String) | | void | rollback(process_id: int, process_key: int) | | void | close(clean_closure: bool = true) | | void | poll() |

SIGNALS:

| Signal | | --- | | connection_closed(was_clean_close: bool) | | connection_error() | | authentication_error(error_object: Dictionnary) | | connection_established() |

ENUMARATIONS:

enum Status

STATUS_DISCONNECTED = 0 --- A status representing a PostgreSQLClient that is disconnected.
STATUS_CONNECTING = 1 --- A status representing a PostgreSQLClient that is connecting to a host.
STATUS_CONNECTED = 2 --- A status representing a PostgreSQLClient that is connected to a host.
STATUS_ERROR = 3 --- A status representing a PostgreSQLClient in error state.

enum DataTypePostgreSQL

BOOLEAN = 16 --- Postgresql data type of type boolean.
SMALLINT = 21 --- Postgresql data type of type smallint.
INTEGER = 23 --- Postgresql data type of type integer.
BIGINT = 20 --- Postgresql data type of type bigint.
REAL = 700 --- Postgresql data type of type real.
DOUBLE_PRECISION = 701 --- Postgresql data type of type double precision.
TEXT = 25 --- Postgresql data type of type text.
CHARACTER = 1042 --- Postgresql data type of type character alias char.
CHARACTER_VARYING = 3802 --- Postgresql data type of type character varying alias varchar.
JSON = 114 --- Postgresql data type of type json.
JSONB = 3802 --- Postgresql data type of type jsonb.
XML = 142 --- Postgresql data type of type xml.
BITEA = 17 --- Postgresql data type of type bitea.
CIDR = 650 --- Postgresql data type of type cidr.
INET = 869 --- Postgresql data type of type inet.
MACADDR = 829 --- Postgresql data type of type macaddr.
MACADDR8 = 774 --- Postgresql data type of type macaddr8.
BIT = 1560 --- Postgresql data type of type bit.
BIT_VARYING = 1562 --- Postgresql data type of type bit varying.
UUID = 2950 --- Postgresql data type of type uuid.
POINT = 600 --- Postgresql data type of type point.
BOX = 603 --- Postgresql data type of type box.
LSEG = 601 --- Postgresql data type of type lseg.
LINE = 628 --- Postgresql data type of type line.
CIRCLE = 718 --- Postgresql data type of type circle.
DATE = 1082 --- Postgresql data type of type date.
TIME = 1266 --- Postgresql data type of type time.

NOTE: Not all PostgreSQL data types are supported by PostgreSQLClient, but will be in a future release.

Property Descriptions

float PROTOCOL_VERSION const

Default value: 3.0

Version number (minor.major) of the PostgreSQL protocol used when connecting to the backend

Dictionary parameter_status reader alone

Default value: {}

A dictionary that contains various information about the execution state of the server. For security reasons the dictionary is always empty if the frontend is disconnected from the backend and updates once the connection is established.

Noted that the server is free to return whatever value it wants. Always remember to check the presence of the key before accessing the associated value.

Example of a typical value that a backend might return. Values may differ depending on the backend:

{"DateStyle":"ISO, DMY", "IntervalStyle":"postgres", "TimeZone":"Europe/Paris", "application_name":"", "client_encoding":"UTF8", "integer_datetimes":"on", "is_superuser":"off", "server_encoding":"UTF8", "server_version":"12.7 (Ubuntu 12.7-0ubuntu0.20.04.1)", "session_authorization":"samuel", "standard_conforming_strings":"on"}

Dictionary error_object reader alone

Default value: {}

A dictionary which contains various information on the execution errors of the last requests made on the backend (usually after using the execute() method). If the dictionary is empty, it means that the backend did not detect any error in the query. Should be used ideally after each use of the execute() method. For security reasons, the dictionary is empty when the frontend is not connected to the backend.

Method Descriptions

Error connect_to_host(url: String, ssl: bool = true, connect_timeout: int = 30)

Allows you to connect to a Postgresql backend at the specified url.

The url parameter is a PostgreSQL URL ideally in the form "postgresql://user:password@host:port/databasename". All other PostgreSQL URL syntaxes specified in this page [https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING] are not yet fully supported.

Noted that the default port for PostgreSQL is 5432.

If ssl is true, the frontend will try to establish a secure SSL/TLS connection with the backend. If the server is unfavorable, the connection will fail. Most of the time, all PostgreSQL backends are good at making an SSL/TLS connection. Old servers can be an exception. Passing the parameter to true is advisable for production use.

Array execute(sql: String)

Allows to send an SQL string to the backend that should run. The sql parameter can contain one or more valid SQL statements. Returns an Array of PostgreSQLQueryResult. There are as many PostgreSQLQueryResult elements in the array as there are SQL statements in sql (except in exceptional cases).

Status get_status()

Returns the status of the connection (see the Status enumeration).

void rollback(process_id : int, process_key : int)

Do not use because it is too unstable, will be subject to modification in future versions.

void close(clean_closure: bool = true)

Allows you to close the connection with the backend. If clean_closure is true, the frontend will notify the backend that it requests to close the connection. If false, the frontend forcibly closes the connection without notifying the backend (not recommended except in exceptional cases).

Has no effect if the frontend is not already connected to the backend.

void poll()

Poll the connection to check for incoming messages. Ideally, it should be called before PostgreSQLClient.execute() for it to work properly and called frequently in a loop.

Signal Descriptions

connection_closed(was_clean_close: bool)

Fires when the connection to the backend closes. was_clean_close is true if the connection was closed correctly otherwise false.

connection_error()

Do not listen to this signal, does not work. will be subject to change see removed in future versions.

authentication_error(error_object: Dictionnary)

Triggered when the authentication process failed during contact with the target backend. The error_object parameter is a dictionary that contains various

PostgreSQLClient

Install / Use

README