97 online 3 members  + Join RP Base  +
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
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
  • Full CRUD: query, insert, update, delete
  • transaction — multi-statement BEGIN/COMMIT/ROLLBACK
  • upsert — INSERT ... ON CONFLICT DO UPDATE
  • scalar — return a single value (e.g. COUNT, MAX)
  • format — safe SQL identifier and literal escaping via pg-format
  • getPoolStats — live connection pool diagnostics
  • Configurable connection pool size
  • Optional slow-query logging
📚 Installation
  1. Clone this repository into your FiveM resources folder as fivem_postgresql.
  2. Run npm install inside resources/fivem_postgresql.
  3. Copy database.cfg to your server root directory.
  4. Add the following to your server.cfg:
exec "database.cfg"
start fivem_postgresql
  1. Edit database.cfg with your connection details (see Configuration below).
⚙️ Configuration
All settings are convars set in database.cfg.

Convar, Required, Default, Description

postgresql_host, ✅, —, Database server hostname or IP
postgresql_port, 5432, Database server port
postgresql_username, ✅, —, Database user
postgresql_password, ✅, —, Database password
postgresql_database, ✅, —, Database name
postgresql_schema, —, Schema to set as search_path (optional)
postgresql_pool_max, 10, Maximum connections in the pool
postgresql_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

…