You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+16-9Lines changed: 16 additions & 9 deletions
Original file line number
Diff line number
Diff line change
@@ -61,7 +61,7 @@ Additionally, a video tutorial by [Mitch McCollum (finepointcgi)](https://github
61
61
62
62
Default extension that is automatically appended to the `path`-variable whenever **no** extension is detected/given.
63
63
64
-
***NOTE:** If database files without extension are desired, this variable has to be set to "" (= an empty string) as to skip this automatic procedure entirely.*
64
+
***NOTE**: If database files without extension are desired, this variable has to be set to "" (= an empty string) as to skip this automatic procedure entirely.*
65
65
66
66
-**foreign_keys** (Boolean, default=false)
67
67
@@ -71,8 +71,6 @@ Additionally, a video tutorial by [Mitch McCollum (finepointcgi)](https://github
71
71
72
72
Enabling this property opens the database in read-only modus & allows databases to be packaged inside of the PCK. To make this possible, a custom [VFS](https://www.sqlite.org/vfs.html) is employed which internally takes care of all the file handling using the Godot API.
73
73
74
-
***NOTE:** Godot opens files in a mode that is not shareable i.e. the database file cannot be open in any other program. Attempting to open a read-only database that is locked by another program fails and returns `ERR_FILE_CANT_OPEN` (`12`). However, multiple simultaneous read-only database connections are allowed.*
75
-
76
74
-**query_result** (Array, default=[])
77
75
78
76
Contains the results from the latest query **by value**; meaning that this property is safe to use when looping successive queries as it does not get overwritten by any future queries.
@@ -97,16 +95,22 @@ Additionally, a video tutorial by [Mitch McCollum (finepointcgi)](https://github
97
95
| VERBOSE (2) | Print additional information to the console |
98
96
| VERY_VERBOSE (3) | Same as VERBOSE |
99
97
100
-
***NOTE:** VERBOSE and higher levels might considerably slow down your queries due to excessive logging.*
98
+
***NOTE**: VERBOSE and higher levels might considerably slow down your queries due to excessive logging.*
101
99
102
-
## Functions
100
+
## Methods
103
101
104
102
- Boolean success = **open_db()**
105
103
104
+
Open a new database connection. Multiple concurrently open connections to the same database are possible.
Binds the parameters contained in the `param_bindings`-variable to the query. Using this function stops any possible attempts at SQL data injection as the parameters are sanitized. More information regarding parameter bindings can be found [here](https://www.sqlite.org/c3ref/bind_blob.html).
@@ -169,16 +173,21 @@ Additionally, a video tutorial by [Mitch McCollum (finepointcgi)](https://github
169
173
# Add the row "id" to the table, which is an auto-incremented primary key.
170
174
# When adding additional rows, this value can either by explicitely given or be unfilled.
171
175
table_dictionary["id"] = {
172
-
"data_type":"int",
176
+
"data_type":"int",
173
177
"primary_key": true,
174
-
"auto_increment":true
178
+
"auto_increment":true
175
179
}
176
180
```
177
181
178
182
For more concrete usage examples see the `database.gd`-file as found in this repository's demo project.
Each key/value pair of the `row_dictionary`-variable defines the column values of a single row.
@@ -362,8 +371,6 @@ To enable this behaviour following conditions need to be met:
362
371
363
372
You can also open databases in read-only mode that are not packaged, albeit under some restrictions such as the fact that the database files have to copied manually to `user://`-folder on mobile platforms (Android & iOS) and for web builds.
364
373
365
-
One important additional constraint for read-only databases is that Godot's implementation of file handling does not allow files to opened in a shareable manner. Basically this means that opening a database connection fails whenever other programs have a read lock on the database file e.g. having the file open in [SQLiteStudio](https://sqlitestudio.pl/) for editing purposes. However, multiple simultaneous read-only database connections are allowed.
366
-
367
374
***NOTE**: The contents of your PCK file can be verified by using externally available tools as found [here](https://github.com/hhyyrylainen/GodotPckTool).*
Open a new database connection. Multiple concurrently open connections to the same database are possible.
54
+
</description>
55
+
</method>
56
+
<methodname="close_db">
57
+
<returntype="bool" />
58
+
<description>
59
+
Close the current database connection.
60
+
</description>
61
+
</method>
62
+
<methodname="query">
63
+
<returntype="bool" />
64
+
<description>
65
+
Query the database using the raw SQL statement defined in [code]query_string[/code].
66
+
</description>
67
+
</method>
68
+
<methodname="query_with_bindings">
69
+
<returntype="bool" />
70
+
<description>
71
+
Binds the parameters contained in the [code]param_bindings[/code]-variable to the query. Using this function stops any possible attempts at SQL data injection as the parameters are sanitized. More information regarding parameter bindings can be found [url=https://www.sqlite.org/c3ref/bind_blob.html]here[/url].
72
+
[b]Example usage[/b]:
73
+
[codeblock]
74
+
var query_string : String = "SELECT ? FROM company WHERE age < ?;"
75
+
var param_bindings : Array = ["name", 24]
76
+
var success = db.query_with_bindings(query_string, param_bindings)
77
+
# Executes following query:
78
+
# SELECT name FROM company WHERE age < 24;
79
+
[/codeblock]
80
+
Using bindings is optional, except for PackedByteArray (= raw binary data) which has to binded to allow the insertion and selection of BLOB data in the database.
81
+
[i][b]NOTE:[/b] Binding column names is not possible due to SQLite restrictions. If dynamic column names are required, insert the column name directly into the [code]query_string[/code]-variable itself (see [url=https://github.com/2shady4u/godot-sqlite/issues/41]https://github.com/2shady4u/godot-sqlite/issues/41[/url]).[/i]
82
+
</description>
83
+
</method>
84
+
<methodname="create_table">
85
+
<returntype="bool" />
86
+
<description>
87
+
Each key/value pair of the [code]table_dictionary[/code]-variable defines a column of the table. Each key defines the name of a column in the database, while the value is a dictionary that contains further column specifications.
88
+
[b]Required fields[/b]:
89
+
- [b]"data_type"[/b]: type of the column variable, following values are valid*:
* [i]Data types not found in this list throw an error and end up finalizing the current SQLite statement.[/i][br] ** [i]with the question mark being replaced by the maximum amount of characters[/i]
92
+
[b]Optional fields[/b]:
93
+
- [b]"not_null"[/b] [i](default = false)[/i]: Is the NULL value an invalid value for this column?[br]- [b]"unique"[/b] [i](default = false)[/i]: Does the column have a unique constraint?[br]- [b]"default"[/b]: The default value of the column if not explicitly given.[br]- [b]"primary_key"[/b] [i](default = false)[/i]: Is this the primary key of this table?
94
+
Evidently, only a single column can be set as the primary key.
95
+
- [b]"auto_increment"[/b] [i](default = false)[/i]: Automatically increment this column when no explicit value is given. This auto-generated value will be one more (+1) than the largest value currently in use.
96
+
[i][b]NOTE[/b]: Auto-incrementing a column only works when this column is the primary key![/i]
97
+
- [b]"foreign_key"[/b]: Enforce an "exist" relationship between tables by setting this variable to [code]foreign_table.foreign_column[/code]. In other words, when adding an additional row, the column value should be an existing value as found in the column with name [code]foreign_column[/code] of the table with name [code]foreign_table[/code].
98
+
[i][b]NOTE[/b]: Availability of foreign keys has to be enabled by setting the [code]foreign_keys[/code]-variable to true BEFORE opening the database.[/i]
99
+
[b]Example usage[/b]:
100
+
[codeblock]
101
+
# Add the row "id" to the table, which is an auto-incremented primary key.
102
+
# When adding additional rows, this value can either by explicitely given or be unfilled.
103
+
table_dictionary["id"] = {
104
+
"data_type": "int",
105
+
"primary_key": true,
106
+
"auto_increment": true
107
+
}
108
+
[/codeblock]
109
+
For more concrete usage examples see the [code]database.gd[/code]-file as found [url=https://github.com/2shady4u/godot-sqlite/blob/master/demo/database.gd]here[url].
110
+
</description>
111
+
</method>
112
+
<methodname="drop_table">
113
+
<returntype="bool" />
114
+
<description>
115
+
Drop the table with name [code]table_name[/code]. This method is equivalent to the following query:
116
+
[codeblock]
117
+
db.query("DROP TABLE "+ table_name + ";")
118
+
[/codeblock]
119
+
</description>
120
+
</method>
121
+
<methodname="insert_row">
122
+
<returntype="bool" />
123
+
<description>
124
+
Each key/value pair of the [code]row_dictionary[/code]-variable defines the column values of a single row.
125
+
Columns should adhere to the table schema as instantiated using the [code]table_dictionary[/code]-variable and are required if their corresponding [b]"not_null"[/b]-column value is set to [code]True[/code].
126
+
</description>
127
+
</method>
128
+
<methodname="insert_rows">
129
+
<returntype="bool" />
130
+
<description>
131
+
Insert multiple rows into the given table. The [code]row_array[/code] input argument should be an array of dictionaries where each element is defined as in [method insert_row].
132
+
</description>
133
+
</method>
134
+
<methodname="select_rows">
135
+
<returntype="Array" />
136
+
<description>
137
+
Returns the results from the latest query [b]by value[/b]; meaning that this property does not get overwritten by any successive queries.
138
+
</description>
139
+
</method>
140
+
<methodname="update_rows">
141
+
<returntype="bool" />
142
+
<description>
143
+
With the [code]updated_row_dictionary[/code]-variable adhering to the same table schema & conditions as the [code]row_dictionary[/code]-variable defined previously.
144
+
</description>
145
+
</method>
146
+
<methodname="delete_rows">
147
+
<returntype="bool" />
148
+
<description>
149
+
Delete all rows of the table that match the given conditions.
150
+
</description>
151
+
</method>
152
+
<methodname="import_from_json">
153
+
<returntype="bool" />
154
+
<description>
155
+
Drops all database tables and imports the database structure and content present inside of [code]import_path.json[/code].
156
+
</description>
157
+
</method>
158
+
<methodname="export_to_json">
159
+
<returntype="bool" />
160
+
<description>
161
+
Exports the database structure and content to [code]export_path.json[/code] as a backup or for ease of editing.
162
+
</description>
163
+
</method>
164
+
<methodname="create_function">
165
+
<returntype="bool" />
166
+
<description>
167
+
Bind a [url=https://www.sqlite.org/appfunc.html]scalar SQL function[/url] to the database that can then be used in subsequent queries.
168
+
</description>
169
+
</method>
170
+
<methodname="get_autocommit">
171
+
<returntype="int" />
172
+
<description>
173
+
Check if the given database connection is or is not in autocommit mode, see [url=https://sqlite.org/c3ref/get_autocommit.html]here[/url].
174
+
</description>
175
+
</method>
176
+
<methodname="backup_to">
177
+
<returntype="bool" />
178
+
<description>
179
+
Backup the current database to a path, see [url=https://www.sqlite.org/backup.html]here[/url]. This feature is useful if you are using a database as your save file and you want to easily implement a saving mechanic.
180
+
</description>
181
+
</method>
182
+
<methodname="restore_from">
183
+
<returntype="bool" />
184
+
<description>
185
+
Restore the current database from a path, see [url=https://www.sqlite.org/backup.html]here[/url]. This feature is useful if you are using a database as your save file and you want to easily implement a loading mechanic. Be warned that the original database will be overwritten entirely when restoring.
186
+
</description>
187
+
</method>
188
+
<methodname="compileoption_used">
189
+
<returntype="bool" />
190
+
<description>
191
+
Check if the binary was compiled using the specified option, see [url=https://sqlite.org/c3ref/compileoption_get.html]here[/url].
192
+
Mostly relevant for checking if the [url=https://sqlite.org/fts5.html]SQLite FTS5 Extension[/url] is enabled, in which case the following lines can be used:
193
+
[codeblock]
194
+
db.compileoption_used("SQLITE_ENABLE_FTS5") # Returns '1' if enabled or '0' if disabled
195
+
db.compileoption_used("ENABLE_FTS5") # The "SQLITE_"-prefix may be omitted.
196
+
[/codeblock]
197
+
</description>
198
+
</method>
199
+
</methods>
200
+
<members>
201
+
<membername="path"type="String"default="default">
202
+
Path to the database, should be set before opening the database with [code]open_db()[/code]. If no database with this name exists, a new one at the supplied path will be created. Both [code]res://[/code] and [code]user://[/code] keywords can be used to define the path.
Contains the zErrMsg returned by the SQLite query in human-readable form. An empty string corresponds with the case in which the query executed succesfully.
Default extension that is automatically appended to the [code]path[/code]-variable whenever [b]no[/b] extension is detected/given.
209
+
[i][b]NOTE:[/b] If database files without extension are desired, this variable has to be set to "" (= an empty string) as to skip this automatic procedure entirely.[/i]
Enabling this property opens the database in read-only modus & allows databases to be packaged inside of the PCK. To make this possible, a custom [url=https://www.sqlite.org/vfs.html]VFS[/url] is employed which internally takes care of all the file handling using the Godot API.
Contains the results from the latest query [b]by value[/b]; meaning that this property is safe to use when looping successive queries as it does not get overwritten by any future queries.
0 commit comments