FreeScript
fivem_postgresql
by JoeSzymkowiczFiveM · version 2026.05.08 · updated 2 days ago
No reviews yet
- Downloads
- 0
- Reviews
- 0
- Size
- 16 KB
- Code check
- Clean
- Licence
- LGPL-3.0
- Released
- Nov 2026
PostreSQL wrapper for FiveM
fivem_postgresql
A FiveM resource to communicate with a PostgreSQL database using pg and pg-format. A server-side only wrapper that exposes a clean, awaitable Lua API for full CRUD access, transactions, upserts, and safe identifier formatting.
✨ Features
All settings are convars set in
Convar, Required, Default, Description
👀 Usage
Add this to the
All functions are synchronous from Lua's perspective (powered by
Waiting for the database to be ready
Before running any queries at startup, wait for the connection:
**
Run any SQL query. Best suited for
Field, Type, Description
Returns: array of row tables, or
**
Run an
Field, Type, Description
Returns: array of inserted row tables, or
**
Run an
Field, Type, Description
Returns: array of updated row tables, or
**
Run a
Field, Type, Description
Returns: array of deleted row tables, or
**
Run an
Field, Type, Description
Returns: array of row tables (inserted or updated), or
**
Execute multiple queries inside a single
Each entry in the array is a table with the same
Returns: array of row-arrays (one per query in order), or
…
A FiveM resource to communicate with a PostgreSQL database using pg and pg-format. A server-side only wrapper that exposes a clean, awaitable Lua API for full CRUD access, transactions, upserts, and safe identifier formatting.
✨ Features
- Full CRUD:
query,insert,update,delete transaction— multi-statementBEGIN/COMMIT/ROLLBACKupsert—INSERT ... ON CONFLICT DO UPDATEscalar— return a single value (e.g.COUNT,MAX)format— safe SQL identifier and literal escaping viapg-formatgetPoolStats— live connection pool diagnostics- Configurable connection pool size
- Optional slow-query logging
- Clone this repository into your FiveM
resourcesfolder asfivem_postgresql. - Run
npm installinsideresources/fivem_postgresql. - Copy
database.cfgto your server root directory. - Add the following to your
server.cfg:
exec "database.cfg"
start fivem_postgresql
- Edit
database.cfgwith your connection details (see Configuration below).
All settings are convars set in
database.cfg.Convar, Required, Default, Description
postgresql_host, ✅, —, Database server hostname or IPpostgresql_port, 5432, Database server portpostgresql_username, ✅, —, Database userpostgresql_password, ✅, —, Database passwordpostgresql_database, ✅, —, Database namepostgresql_schema, —, Schema to set as search_path (optional)postgresql_pool_max, 10, Maximum connections in the poolpostgresql_slow_query_ms, 0, Log queries slower than this (ms). 0 disables.
set postgresql_host 'localhost'
set postgresql_port '5432'
set postgresql_username 'postgres'
set postgresql_password 'yourpassword'
set postgresql_database 'fivem'
set postgresql_schema 'fivem'
set postgresql_pool_max '10'
set postgresql_slow_query_ms '500'👀 Usage
Add this to the
fxmanifest.lua of any resource that needs database access. It must come before your own server script:
server_scripts {
'@fivem_postgresql/lib/PostgreSQL.lua',
'server.lua',
}All functions are synchronous from Lua's perspective (powered by
Citizen.Await) and must be called from inside a CreateThread or an event handler — not at the top level of the file.Waiting for the database to be ready
Before running any queries at startup, wait for the connection:
-- Callback style
PostgreSQL.ready(function()
print('Database is ready!')
end)
-- Awaitable style (inside CreateThread)
CreateThread(function()
PostgreSQL.ready()
print('Database is ready!')
end)**
PostgreSQL.query(params)**Run any SQL query. Best suited for
SELECT statements.Field, Type, Description
query, string, SQL query text. Use $1, $2, … placeholders for values.values, table, (optional) Array of parameter values.Returns: array of row tables, or
nil on error.
local rows = PostgreSQL.query({
query = 'SELECT * FROM players WHERE active = $1',
values = { true },
})
for _, row in ipairs(rows) do
print(row.name, row.identifier)
end**
PostgreSQL.insert(params)**Run an
INSERT statement.Field, Type, Description
query, string, Must start with INSERT.values, table, (optional) Parameter values.returning, table, (optional) Columns to return. Defaults to *.Returns: array of inserted row tables, or
nil on error.
local rows = PostgreSQL.insert({
query = 'INSERT INTO players (identifier, name) VALUES ($1, $2)',
values = { 'steam:110000112345678', 'Joe' },
-- returning = { 'id', 'name' } -- optionally limit returned columns
})
print('New player ID:', rows[1].id)**
PostgreSQL.update(params)**Run an
UPDATE statement.Field, Type, Description
query, string, Must start with UPDATE.values, table, (optional) Parameter values.returning, table, (optional) Columns to return. Defaults to *.Returns: array of updated row tables, or
nil on error.
local rows = PostgreSQL.update({
query = 'UPDATE players SET name = $1 WHERE identifier = $2',
values = { 'NewName', 'steam:110000112345678' },
})
print('Updated:', rows[1].name)**
PostgreSQL.delete(params)**Run a
DELETE statement.Field, Type, Description
query, string, Must start with DELETE.values, table, (optional) Parameter values.returning, table, (optional) Columns to return. Defaults to *.Returns: array of deleted row tables, or
nil on error.
local rows = PostgreSQL.delete({
query = 'DELETE FROM players WHERE identifier = $1',
values = { 'steam:110000112345678' },
})
print('Deleted player:', rows[1].name)**
PostgreSQL.upsert(params)**Run an
INSERT ... ON CONFLICT ... DO UPDATE statement. The query must start with INSERT and contain an ON CONFLICT clause.Field, Type, Description
query, string, Must start with INSERT and contain ON CONFLICT.values, table, (optional) Parameter values.returning, table, (optional) Columns to return. Defaults to *.Returns: array of row tables (inserted or updated), or
nil on error.
-- Insert the player if they don't exist, otherwise update their name.
local rows = PostgreSQL.upsert({
query = [[
INSERT INTO players (identifier, name) VALUES ($1, $2)
ON CONFLICT (identifier) DO UPDATE SET name = EXCLUDED.name
]],
values = { 'steam:110000112345678', 'Joe' },
})
print('Upserted player ID:', rows[1].id)**
PostgreSQL.transaction(queries)**Execute multiple queries inside a single
BEGIN/COMMIT transaction. If any query fails, the entire transaction is automatically rolled back.Each entry in the array is a table with the same
query and values fields as the other functions.Returns: array of row-arrays (one per query in order), or
nil if the transaction was r…