[Quest API] Add Native Database Querying Interface (#4531)

* Add database quest API

API functions are named to be similar to LuaSQL and perl DBI

New connections are made for Database objects. These can either use
credentials from the server eqemu_config or manual connections.

* Add option to use zone db connections

zone/CMakeLists.txt

@@ -54,6 +54,7 @@ SET(zone_sources
     lua_buff.cpp
     lua_corpse.cpp
     lua_client.cpp
+    lua_database.cpp
     lua_door.cpp
     lua_encounter.cpp
     lua_entity.cpp
@@ -110,6 +111,7 @@ SET(zone_sources
     perl_bot.cpp
     perl_buff.cpp
     perl_client.cpp
+    perl_database.cpp
     perl_doors.cpp
     perl_entity.cpp
     perl_expedition.cpp
@@ -135,6 +137,7 @@ SET(zone_sources
     qglobals.cpp
     queryserv.cpp
     questmgr.cpp
+    quest_db.cpp
     quest_parser_collection.cpp
     raids.cpp
     raycast_mesh.cpp
@@ -215,6 +218,7 @@ SET(zone_headers
     lua_buff.h
     lua_client.h
     lua_corpse.h
+    lua_database.h
     lua_door.h
     lua_encounter.h
     lua_entity.h
@@ -251,6 +255,7 @@ SET(zone_headers
     pathfinder_interface.h
     pathfinder_nav_mesh.h
     pathfinder_null.h
+    perl_database.h
     perlpacket.h
     petitions.h
     pets.h
@@ -260,6 +265,7 @@ SET(zone_headers
     queryserv.h
     quest_interface.h
     questmgr.h
+    quest_db.h
     quest_parser_collection.h
     raids.h
     raycast_mesh.h

zone/embparser.cpp

@@ -58,6 +58,7 @@ void perl_register_expedition_lock_messages();
 void perl_register_bot();
 void perl_register_buff();
 void perl_register_merc();
+void perl_register_database();
 #endif // EMBPERL_XS_CLASSES
 #endif // EMBPERL_XS
 
@@ -1185,6 +1186,7 @@ void PerlembParser::MapFunctions()
 	perl_register_bot();
 	perl_register_buff();
 	perl_register_merc();
+	perl_register_database();
 #endif // EMBPERL_XS_CLASSES
 }
 

zone/embperl.h

@@ -21,6 +21,8 @@ Eglin
 #include <perlbind/perlbind.h>
 namespace perl = perlbind;
 
+#undef connect
+#undef bind
 #undef Null
 
 #ifdef WIN32

zone/lua_database.cpp

@@ -0,0 +1,214 @@
+#ifdef LUA_EQEMU
+
+#include "lua_database.h"
+#include "zonedb.h"
+#include <luabind/luabind.hpp>
+#include <luabind/adopt_policy.hpp>
+
+// Luabind adopts the PreparedStmt wrapper object allocated with new and deletes it via GC
+// Lua GC is non-deterministic so handles should be closed explicitly to free db resources
+// Script errors/exceptions will hold resources until GC deletes the wrapper object
+
+Lua_MySQLPreparedStmt* Lua_Database::Prepare(lua_State* L, std::string query)
+{
+	return m_db ? new Lua_MySQLPreparedStmt(L, m_db->Prepare(std::move(query))) : nullptr;
+}
+
+void Lua_Database::Close()
+{
+	m_db.reset();
+}
+
+// ---------------------------------------------------------------------------
+
+void Lua_MySQLPreparedStmt::Close()
+{
+	m_stmt.reset();
+}
+
+void Lua_MySQLPreparedStmt::Execute(lua_State* L)
+{
+	if (m_stmt)
+	{
+		m_res = m_stmt->Execute();
+	}
+}
+
+void Lua_MySQLPreparedStmt::Execute(lua_State* L, luabind::object args)
+{
+	if (m_stmt)
+	{
+		std::vector<mysql::PreparedStmt::param_t> inputs;
+
+		// iterate table until nil like ipairs to guarantee traversal order
+		for (int i = 1, type; (type = luabind::type(args[i])) != LUA_TNIL; ++i)
+		{
+			switch (type)
+			{
+			case LUA_TBOOLEAN:
+				inputs.emplace_back(luabind::object_cast<bool>(args[i]));
+				break;
+			case LUA_TNUMBER: // all numbers are doubles in lua before 5.3
+				inputs.emplace_back(luabind::object_cast<lua_Number>(args[i]));
+				break;
+			case LUA_TSTRING:
+				inputs.emplace_back(luabind::object_cast<const char*>(args[i]));
+				break;
+			case LUA_TTABLE: // let tables substitute for null since nils can't exist
+				inputs.emplace_back(nullptr);
+				break;
+			default:
+				break;
+			}
+		}
+
+		m_res = m_stmt->Execute(inputs);
+	}
+}
+
+void Lua_MySQLPreparedStmt::SetOptions(luabind::object table)
+{
+	if (m_stmt)
+	{
+		mysql::StmtOptions opts = m_stmt->GetOptions();
+		if (luabind::type(table["buffer_results"]) == LUA_TBOOLEAN)
+		{
+			opts.buffer_results = luabind::object_cast<bool>(table["buffer_results"]);
+		}
+		if (luabind::type(table["use_max_length"]) == LUA_TBOOLEAN)
+		{
+			opts.use_max_length = luabind::object_cast<bool>(table["use_max_length"]);
+		}
+		m_stmt->SetOptions(opts);
+	}
+}
+
+static void PushValue(lua_State* L, const mysql::StmtColumn& col)
+{
+	if (col.IsNull())
+	{
+		lua_pushnil(L); // clear entry in cache from any previous row
+		return;
+	}
+
+	// 64-bit ints are pushed as strings since lua 5.1 only has 53-bit precision
+	switch (col.Type())
+	{
+	case MYSQL_TYPE_TINY:
+	case MYSQL_TYPE_SHORT:
+	case MYSQL_TYPE_INT24:
+	case MYSQL_TYPE_LONG:
+	case MYSQL_TYPE_FLOAT:
+	case MYSQL_TYPE_DOUBLE:
+		lua_pushnumber(L, col.Get<lua_Number>().value());
+		break;
+	case MYSQL_TYPE_LONGLONG:
+	case MYSQL_TYPE_BIT:
+	case MYSQL_TYPE_TIME:
+	case MYSQL_TYPE_DATE:
+	case MYSQL_TYPE_DATETIME:
+	case MYSQL_TYPE_TIMESTAMP:
+		{
+			std::string str = col.GetStr().value();
+			lua_pushlstring(L, str.data(), str.size());
+		}
+		break;
+	default: // string types, push raw buffer to avoid copy
+		{
+			std::string_view str = col.GetStrView().value();
+			lua_pushlstring(L, str.data(), str.size());
+		}
+		break;
+	}
+}
+
+luabind::object Lua_MySQLPreparedStmt::FetchArray(lua_State* L)
+{
+	auto row = m_stmt ? m_stmt->Fetch() : mysql::StmtRow();
+	if (!row)
+	{
+		return luabind::object();
+	}
+
+	// perf: bypass luabind operator[]
+	m_row_array.push(L);
+	for (const mysql::StmtColumn& col : row)
+	{
+		PushValue(L, col);
+		lua_rawseti(L, -2, col.Index() + 1);
+	}
+	lua_pop(L, 1);
+
+	return m_row_array;
+}
+
+luabind::object Lua_MySQLPreparedStmt::FetchHash(lua_State* L)
+{
+	auto row = m_stmt ? m_stmt->Fetch() : mysql::StmtRow();
+	if (!row)
+	{
+		return luabind::object();
+	}
+
+	// perf: bypass luabind operator[]
+	m_row_hash.push(L);
+	for (const mysql::StmtColumn& col : row)
+	{
+		PushValue(L, col);
+		lua_setfield(L, -2, col.Name().c_str());
+	}
+	lua_pop(L, 1);
+
+	return m_row_hash;
+}
+
+int Lua_MySQLPreparedStmt::ColumnCount()
+{
+	return m_res.ColumnCount();
+}
+
+uint64_t Lua_MySQLPreparedStmt::LastInsertID()
+{
+	return m_res.LastInsertID();
+}
+
+uint64_t Lua_MySQLPreparedStmt::RowCount()
+{
+	return m_res.RowCount();
+}
+
+uint64_t Lua_MySQLPreparedStmt::RowsAffected()
+{
+	return m_res.RowsAffected();
+}
+
+luabind::scope lua_register_database()
+{
+	return luabind::class_<Lua_Database>("Database")
+		.enum_("constants")
+		[(
+			luabind::value("Default", static_cast<int>(QuestDB::Connection::Default)),
+			luabind::value("Content", static_cast<int>(QuestDB::Connection::Content))
+		)]
+		.def(luabind::constructor<>())
+		.def(luabind::constructor<QuestDB::Connection>())
+		.def(luabind::constructor<QuestDB::Connection, bool>())
+		.def(luabind::constructor<const char*, const char*, const char*, const char*, uint32_t>())
+		.def("close", &Lua_Database::Close)
+		.def("prepare", &Lua_Database::Prepare, luabind::adopt(luabind::result)),
+
+	luabind::class_<Lua_MySQLPreparedStmt>("MySQLPreparedStmt")
+		.def("close", &Lua_MySQLPreparedStmt::Close)
+		.def("execute", static_cast<void(Lua_MySQLPreparedStmt::*)(lua_State*)>(&Lua_MySQLPreparedStmt::Execute))
+		.def("execute", static_cast<void(Lua_MySQLPreparedStmt::*)(lua_State*, luabind::object)>(&Lua_MySQLPreparedStmt::Execute))
+		.def("fetch", &Lua_MySQLPreparedStmt::FetchArray)
+		.def("fetch_array", &Lua_MySQLPreparedStmt::FetchArray)
+		.def("fetch_hash", &Lua_MySQLPreparedStmt::FetchHash)
+		.def("insert_id", &Lua_MySQLPreparedStmt::LastInsertID)
+		.def("num_fields", &Lua_MySQLPreparedStmt::ColumnCount)
+		.def("num_rows", &Lua_MySQLPreparedStmt::RowCount)
+		.def("rows_affected", &Lua_MySQLPreparedStmt::RowsAffected)
+		.def("set_options", &Lua_MySQLPreparedStmt::SetOptions);
+}
+
+#endif // LUA_EQEMU

zone/lua_database.h

@@ -0,0 +1,51 @@
+#pragma once
+
+#ifdef LUA_EQEMU
+
+#include "quest_db.h"
+#include "../common/mysql_stmt.h"
+#include <luabind/object.hpp>
+
+namespace luabind { struct scope; }
+luabind::scope lua_register_database();
+
+class Lua_MySQLPreparedStmt;
+
+class Lua_Database : public QuestDB
+{
+public:
+	using QuestDB::QuestDB;
+
+	void Close();
+	Lua_MySQLPreparedStmt* Prepare(lua_State*, std::string query);
+};
+
+class Lua_MySQLPreparedStmt
+{
+public:
+	Lua_MySQLPreparedStmt(lua_State* L, mysql::PreparedStmt&& stmt)
+		: m_stmt(std::make_unique<mysql::PreparedStmt>(std::move(stmt)))
+		, m_row_array(luabind::newtable(L))
+		, m_row_hash(luabind::newtable(L)) {}
+
+	void Close();
+	void Execute(lua_State*);
+	void Execute(lua_State*, luabind::object args);
+	void SetOptions(luabind::object table_opts);
+	luabind::object FetchArray(lua_State*);
+	luabind::object FetchHash(lua_State*);
+
+	// StmtResult functions accessible through this class to simplify api
+	int ColumnCount();
+	uint64_t LastInsertID();
+	uint64_t RowCount();
+	uint64_t RowsAffected();
+
+private:
+	std::unique_ptr<mysql::PreparedStmt> m_stmt;
+	mysql::StmtResult m_res = {};
+	luabind::object m_row_array; // perf: table cache for fetches
+	luabind::object m_row_hash;
+};
+
+#endif // LUA_EQEMU

zone/lua_parser.cpp

@@ -42,6 +42,7 @@
 #include "lua_spawn.h"
 #include "lua_spell.h"
 #include "lua_stat_bonuses.h"
+#include "lua_database.h"
 
 const char *LuaEvents[_LargestEventID] = {
 	"event_say",
@@ -1318,7 +1319,8 @@ void LuaParser::MapFunctions(lua_State *L) {
 			lua_register_expedition(),
 			lua_register_expedition_lock_messages(),
 			lua_register_buff(),
-			lua_register_exp_source()
+			lua_register_exp_source(),
+			lua_register_database()
 		)];
 
 	} catch(std::exception &ex) {