DbConnect: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
No edit summary
No edit summary
Line 12: Line 12:


===Required Arguments===
===Required Arguments===
*'''databaseType:''' The type of database. There is currently only one supported type: 'sqlite'
*'''databaseType:''' The type of database. This can be either ''sqlite'' or ''mysql''
*'''host:''' The target to connect to. The format of this depends on the database type. 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.
*'''host:''' The target to connect to. The format of this depends on the database type.
** 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.
** For MySQL it is a list of key=value pairs separated by semicolons. Supported keys are:
*** '''dbname''': Name of the database to use e.g. ''dbname=test''
*** '''host''': Host address e.g. ''host=127.0.0.1''
*** '''port''': Host port e.g. ''port=1234'' (optional, defaults to standard MySQL port if not used)
*** '''unix_socket''': Unix socket or named pipe to use (optional, thankgoodness)


===Optional Arguments===
===Optional Arguments===
*'''username:''' Not required for sqlite
*'''username:''' Usually required for MySQL, ignored by SQLite
*'''password:''' Not required for sqlite
*'''password:''' Usually required for MySQL, ignored by SQLite
*'''options :''' List of key=value pairs separated by semicolons
*'''options :''' List of key=value pairs separated by semicolons. Supported keys are:
**'''share''' which can be set to 0 or 1. 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. Default value for SQLite is "share=1". Default value for MySQL is "share=0"


===Returns===
===Returns===
Line 24: Line 31:


==Example==
==Example==
This example opens a connection to a sqlite database file in the current resource
This example opens a connection to a SQLite database file in the current resource
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
local test_db = dbConnect( "sqlite", "file.db" )
local test_db = dbConnect( "sqlite", "file.db" )
</syntaxhighlight>
</syntaxhighlight>


This example opens a connection to a sqlite database file in another resource
This example opens a connection to a SQLite database file in another resource
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
local test_db = dbConnect( "sqlite", ":resname/file.db" )
local test_db = dbConnect( "sqlite", ":resname/file.db" )
</syntaxhighlight>
</syntaxhighlight>


This example opens a connection to a sqlite database file in the global databases directory
This example opens a connection to a SQLite database file in the global databases directory
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
local test_db = dbConnect( "sqlite", ":/file.db" )
local test_db = dbConnect( "sqlite", ":/file.db" )
</syntaxhighlight>
</syntaxhighlight>


This example opens a connection to a sqlite database file in a sub directory of the global databases directory
This example opens a connection to a SQLite database file in a sub directory of the global databases directory
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
local test_db = dbConnect( "sqlite", ":/example/sub/dir/file.db" )
local test_db = dbConnect( "sqlite", ":/example/sub/dir/file.db" )
</syntaxhighlight>
This example opens a connection to a MySQL database called 'frank' at server ip 1.2.3.4 and allows the connection to be shared. Note that changing the database or other connection dependent settings affect all connections that are shared.
<syntaxhighlight lang="lua">
local test_db = dbConnect( "mysql", "dbname=frank;host=1.2.3.4", "username", "password", "share=1" )
</syntaxhighlight>
This example opens a connection to a SQLite database is disallows sharing of the connection
<syntaxhighlight lang="lua">
local test_db = dbConnect( "sqlite", ":file.db", "", "", "share=0" )
</syntaxhighlight>
</syntaxhighlight>



Revision as of 04:04, 28 October 2011

Available only in MTA SA 1.1.1 r3328 and onwards This function opens a connection to a database and returns an element that can be used with dbQuery

Syntax

element dbConnect ( string databaseType, string host [, string username, string password, string options ] )

Required Arguments

  • databaseType: The type of database. This can be either sqlite or mysql
  • host: The target to connect to. The format of this depends on the database type.
    • 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.
    • For MySQL it is a list of key=value pairs separated by semicolons. Supported keys are:
      • dbname: Name of the database to use e.g. dbname=test
      • host: Host address e.g. host=127.0.0.1
      • port: Host port e.g. port=1234 (optional, defaults to standard MySQL port if not used)
      • unix_socket: Unix socket or named pipe to use (optional, thankgoodness)

Optional Arguments

  • username: Usually required for MySQL, ignored by SQLite
  • password: Usually required for MySQL, ignored by SQLite
  • options : List of key=value pairs separated by semicolons. Supported keys are:
    • share which can be set to 0 or 1. 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. Default value for SQLite is "share=1". Default value for MySQL is "share=0"

Returns

Returns a database connection element unless there are problems, in which case it return false.

Example

This example opens a connection to a SQLite database file in the current resource

local test_db = dbConnect( "sqlite", "file.db" )

This example opens a connection to a SQLite database file in another resource

local test_db = dbConnect( "sqlite", ":resname/file.db" )

This example opens a connection to a SQLite database file in the global databases directory

local test_db = dbConnect( "sqlite", ":/file.db" )

This example opens a connection to a SQLite database file in a sub directory of the global databases directory

local test_db = dbConnect( "sqlite", ":/example/sub/dir/file.db" )

This example opens a connection to a MySQL database called 'frank' at server ip 1.2.3.4 and allows the connection to be shared. Note that changing the database or other connection dependent settings affect all connections that are shared.

local test_db = dbConnect( "mysql", "dbname=frank;host=1.2.3.4", "username", "password", "share=1" )

This example opens a connection to a SQLite database is disallows sharing of the connection

local test_db = dbConnect( "sqlite", ":file.db", "", "", "share=0" )

Requirements

Minimum server version 1.1.1-9.03328
Minimum client version n/a

Note: Using this feature requires the resource to have the above minimum version declared in the meta.xml <min_mta_version> section. e.g. <min_mta_version server="1.1.1-9.03328" />

See Also