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
description: The **db-query** represents a database query returned by the [[dbQuery]] function. It can be used to read the query result with [[dbPoll]], or freed using [[dbFree]].
description: This function opens a connection to a database and returns an element
5
-
that can be used with [dbQuery](/wiki/DbQuery "DbQuery"). To disconnect use [destroyElement](/wiki/DestroyElement
6
-
"DestroyElement").
4
+
that can be used with [[dbQuery]] and other db functions. To disconnect use [[destroyElement]].
7
5
parameters:
8
6
- name: databaseType
9
7
type: string
10
-
description: The type of database. This can be either sqlite or mysql
8
+
description: The type of database. This can be either **sqlite** or **mysql**.
11
9
- name: host
12
10
type: string
13
-
description: Host address e.g. host=127.0.0.1
11
+
description: |
12
+
The target to connect to. The format of this depends on the database type.
13
+
14
+
- For SQLite it is a [[filepath]] to a SQLite database file. If the filepath starts with ":/" then the server's global databases directory is used. The file will be created if it does not exist.
15
+
- For MySQL it is a list of key=value pairs separated by semicolons. Supported keys are:
16
+
- **dbname**: Name of the database to use e.g. dbname=test
17
+
- **host**: Host address e.g. host=127.0.0.1
18
+
- **port**: Host port e.g. port=3306 (optional, defaults to standard MySQL port if not used).
19
+
- **unix_socket**: Unix socket or named pipe to use (optional).
20
+
- **charset**: Communicate with the server using a character which is different from the default e.g. charset=utf8 (optional).
14
21
- name: username
15
22
type: string
16
23
description: Usually required for MySQL, ignored by SQLite
@@ -21,73 +28,97 @@ shared:
21
28
default: '""'
22
29
- name: options
23
30
type: string
24
-
description: MISSING_PARAM_DESC
31
+
description: |
32
+
List of key=value pairs separated by semicolons. Supported keys are:
33
+
34
+
- **share**: which can be set to 0 or 1. (Default value for SQLite is "share=1", for MySQL is "share=0"). When set to 1, the connection is shared and will be used by other calls to dbConnect with the same host string. This is usually a good thing for SQLite connections, but not so good for MySQL unless care is taken.
35
+
- **batch**: which can be set to 0 or 1. (Default is "batch=1"). When set to 1, queries called in the same frame are automatically batched together which can significantly speed up inserts/updates. The downside is you lose control of the feature that is used to achieve batching (For SQLite it is transactions, for MySQL it is autocommit mode). Therefore, if you use transactions, lock tables or control autocommit yourself, you may want to disable this feature.
36
+
- **autoreconnect**: which can be set to 0 or 1. (Default value "autoreconnect=1"). When set to 1, dropped connections will automatically be reconnected. Note that session variables (incl. SET NAMES), user variables, table locks and temporary tables will be reset because of the reconnection. So if you use these fancy features, you will need to turn autoreconnect off and cope with dropped connections some other way.
37
+
- **log**: which can be set to 0 or 1. (Default value "log=1"). When set to 0, activity from this connection will not be recorded in the [database debug log file](/articles/Server_Commands#debugdb).
38
+
- **tag**: (Default value "tag=script"). A string which helps identify activity from this connection in the [database debug log file](/articles/Server_Commands#debugdb).
39
+
- **suppress**: A comma separated list of error codes to ignore. (eg. "suppress=1062,1169").
40
+
- **multi_statements**: Enable multiple statements (separated by a semi-colon) in one query. Use [[dbPrepareString]] when building a multiple statement query to reduce SQL injection risks.
41
+
- **queue**: Name of the queue to use. (Default value for SQLite is "sqlite", for MySQL default is the host string from the host argument). Asynchronous database queries in the same queue are processed in order, one at a time. Any name can be used.
42
+
- **use_ssl**: which can be set to 0 or 1. (Default value is 0), ignored by SQLite.
43
+
- **get_server_public_key**: which can be set to 0 or 1. (Default value is 1), ignored by SQLite. When set to 1, this enables the client to request from the server the public key required for RSA key pair-based password exchange. This option applies to clients that authenticate with the `caching_sha2_password`` authentication plugin.
25
44
default: '""'
26
45
examples:
27
46
- path: examples/dbConnect-1.lua
28
-
description: This example opens a connection to a SQLite database file in the
29
-
current resource
30
-
side: server
47
+
description: This example opens a connection to a SQLite database file in the current resource.
48
+
title: SQLite
31
49
- path: examples/dbConnect-2.lua
32
-
description: This example opens a connection to a SQLite database file in another
33
-
resource
34
-
side: server
50
+
description: This example opens a connection to a SQLite database file in another resource.
51
+
title: SQLite
35
52
- path: examples/dbConnect-3.lua
36
-
description: This example opens a connection to a SQLite database file in the
37
-
global databases directory
38
-
side: server
53
+
description: This example opens a connection to a SQLite database file in the global databases directory.
54
+
title: SQLite
39
55
- path: examples/dbConnect-4.lua
40
-
description: This example opens a connection to a SQLite database file in a sub
41
-
directory of the global databases directory
42
-
side: server
56
+
description: This example opens a connection to a SQLite database file in a sub directory of the global databases directory.
57
+
title: SQLite
43
58
- path: examples/dbConnect-5.lua
44
59
description: This example opens a connection to a MySQL database called 'frank'
45
60
at server ip 1.2.3.4 using utf8 character set and allows the connection to be
46
61
shared. Note that changing the database or other connection dependent settings
47
62
affect all connections that are shared.
48
-
side: server
63
+
title: MySQL
49
64
- path: examples/dbConnect-6.lua
50
-
description: This example opens a connection to a SQLite database is disallows
51
-
sharing of the connection
52
-
side: server
65
+
description: This example opens a connection to a SQLite database is disallows sharing of the connection.
66
+
title: SQLite
53
67
- path: examples/dbConnect-7.lua
54
-
description: This example output debug message, if the connection with SQLite
55
-
database was established or not
56
-
side: server
68
+
description: This example output debug message, if the connection with SQLite database was established or not.
69
+
title: SQLite
57
70
- path: examples/dbConnect-8.lua
58
-
description: 'The folowing example shows how you could approach a common resource
59
-
for database operations with exported functions (queryandexecute):'
60
-
side: server
71
+
description: 'The folowing example shows how you could approach a common resource for database operations with exported functions.'
72
+
title: MySQL
73
+
- path: examples/dbConnect_OOP-1.lua
74
+
description: This example output debug message, if the connection with SQLite database was established or not.
75
+
title: SQLite
76
+
oop: true
61
77
returns:
62
78
values:
63
-
- type: element
64
-
name: value
65
-
description: Returns a database connection element unless there are problems,
66
-
in which case it return false.
79
+
- type: db-connection
80
+
name: db connection handle
81
+
description: Returns a [database connection](/reference/db-connection) element unless there are problems,
82
+
in which case it return **false**.
67
83
oop:
68
-
element: connection
84
+
element: db-connection
69
85
constructorclass: Connection
70
86
notes:
71
-
- type: info
87
+
- type: tip
72
88
content: Connecting and disconnecting many times can have a performance impact
73
-
on the server. For optimal performance it is recommended that you use dbConnect
89
+
on the server. For optimal performance it is recommended that you use [[dbConnect]]
74
90
only once when the resource starts, and share the connection element with the
75
91
whole script.
76
92
- type: info
77
-
content: 'In MySQL 8.0 and later, you can choose between `caching_sha2_password`
78
-
, `sha256_password` , or `mysql_native_password` for password management. If
79
-
you opt for `caching_sha2_password` or `sha256_password` , SSL is not mandatory
80
-
but recommended for secure authentication. If you choose `mysql_native_password`
81
-
, you can set it as the default authentication plugin: In the `mysqld.cnf` configuration
82
-
file, by adding or modifying the following line: default-authentication-plugin=mysql_native_password
83
-
Using SQL queries (e.g., ALTER USER). In PHPMyAdmin (via the user settings page).
84
-
Please note that starting with MySQL 9.0, `mysql_native_password` will no longer
85
-
be available, and only `caching_sha2_password` and `sha256_password` will be
86
-
supported.'
93
+
content: |
94
+
In MySQL 8.0 and later, you can choose between `caching_sha2_password`, `sha256_password`, or `mysql_native_password` for password management.
95
+
96
+
- If you opt for `caching_sha2_password` or `sha256_password`, SSL is not mandatory but recommended for secure authentication.
97
+
- If you choose `mysql_native_password`, you can set it as the default authentication plugin:
98
+
- In the `mysqld.cnf` configuration file, by adding or modifying the following line: `default-authentication-plugin=mysql_native_password`.
99
+
- Using SQL queries (e.g., ALTER USER).
100
+
- In PHPMyAdmin (via the user settings page).
101
+
102
+
Please note that starting with MySQL 9.0, `mysql_native_password` will no longer be available, and only `caching_sha2_password` and `sha256_password` will be supported.
87
103
- type: info
88
104
content: Under certain platforms, for example on Unix-based OSes like Linux, using
89
-
this function could fail with a debug warning containing "[Could not connect]"
105
+
this function could fail with a debug warning containing `[Could not connect]`
90
106
accompanied by a prior debug error explaining the problem. In that case you
91
-
should check the Server Manual to see if you have missed any recommended (best-effort)
107
+
should check the [Server Manual](/articles/Server_Manual) to see if you have missed any recommended (best-effort)
92
108
steps for server set-up.
93
-
requires_review: true
109
+
meta:
110
+
- changelog:
111
+
- version: 1.3.1-9.04817
112
+
description: Added options **log**, **tag** and **suppress**.
description: This function executes a database query using the supplied connection.
5
-
No query result is returned.
3
+
description: This function executes a database query using the supplied connection. No query result is returned.
6
4
parameters:
7
5
- name: databaseConnection
8
-
type: element
9
-
description: A database connection element previously returned from dbConnect
6
+
type: db-connection
7
+
description: A database connection element previously returned from [[dbConnect]].
10
8
- name: query
11
9
type: string
12
-
description: An SQL query. Positions where parameter values will be inserted are
13
-
marked with a ?
10
+
description: An SQL query. Positions where parameter values will be inserted are marked with a `?`.
14
11
- name: param1 [, var param2 ...]
15
12
type: var
16
-
description: MISSING_PARAM_DESC
13
+
description: |
14
+
A variable number of parameters. These must be strings or numbers - it is important to make sure they are of the correct type. Also, the number of parameters passed must be equal to the number of `?` characters in the query string.
15
+
16
+
String parameters are automatically quoted and escaped as required. (If you do not want a string quoted, use `??`). Make sure that numbers are in number format as a string number is treated differently.
17
17
examples:
18
18
- path: examples/dbExec-1.lua
19
19
description: 'This example executes an INSERT query:'
20
-
side: server
21
20
- path: examples/dbExec-2.lua
22
-
description: 'This example shows how to use??for parts of the query that are not
21
+
description: 'This example shows how to use `??` for parts of the query that are not
23
22
column values:'
24
-
side: server
25
23
- path: examples/dbExec-3.lua
26
-
description: 'This example shows how to use backticks and??for parts of the query
24
+
description: 'This example shows how to use backticks and `??` for parts of the query
27
25
that are not column values:'
28
-
side: server
26
+
- path: examples/dbExec_OOP-1.lua
27
+
description: 'This example shows how to use backticks and `??` for parts of the query
28
+
that are not column values:'
29
+
oop: true
29
30
returns:
30
31
values:
31
32
- type: bool
32
33
name: value
33
-
description: Returns true unless the connection is incorrect, in which case it
34
-
returns false .
34
+
description: Returns **true** unless the connection is incorrect, in which case it returns **false**.
35
35
oop:
36
36
element: connection
37
37
method: exec
38
38
static: false
39
39
notes:
40
40
- type: tip
41
-
content: The server command debugdb 2 will output verbose information on each
42
-
query to a logging file (usually logs/db.log )
43
-
requires_review: true
41
+
content: The server command [debugdb 2](/articles/Server_Commands#debugdb) will output verbose information on each query to a logging file (usually `logs/db.log`).
42
+
- type: tip
43
+
content: It is usually good practice to surround table and column names with backticks (`) in case they contain spaces or SQL keywords (and therefore cause syntax errors). This is especially true when using variables for table and column names, as potential problems may not be apparent when the script is first written.
0 commit comments