Getting Started

First Steps

Write your first MongoDB operations with gmsv_mongo

First Steps

This guide walks you through your first MongoDB operations with gmsv_mongo.

Loading the Module

-- Load the MongoDB module
require("mongo")

-- Verify it loaded
print("MongoDB Module Version:", MongoDB.Version())

Creating a Connection

-- Connect to MongoDB
local client = MongoDB.Client("mongodb://localhost:27017")

if not client then
    print("Failed to connect to MongoDB!")
    return
end

print("✓ Connected to MongoDB!")

Working with Databases

-- Get a database reference
local db = client:Database("gameserver")

-- List all databases on the server
local databases = client:ListDatabases()
print("Available databases:")
for i, name in ipairs(databases) do
    print("  " .. i .. ". " .. name)
end

Working with Collections

-- Get a collection reference
local players = db:Collection("players")

-- List all collections in the database
local collections = db:ListCollections()
print("Collections in database:")
for i, name in ipairs(collections) do
    print("  " .. i .. ". " .. name)
end

Your First Insert

-- Insert a single document
local playerId = players:InsertOne({
    steamid = "STEAM_0:1:12345678",
    username = "TestPlayer",
    level = 1,
    credits = 1000,
    joined_at = os.time(),
    inventory = {}
})

print("Inserted player with ID:", playerId)

Your First Query

-- Find the player we just inserted
local player = players:FindOne({
    steamid = "STEAM_0:1:12345678"
})

if player then
    print("Found player:", player.username)
    print("  Level:", player.level)
    print("  Credits:", player.credits)
else
    print("Player not found")
end

Your First Update

-- Update the player's level
local modified = players:UpdateOne(
    { steamid = "STEAM_0:1:12345678" },  -- Filter
    { ["$set"] = { level = 2 } }         -- Update
)

print("Modified", modified, "document(s)")

Your First Delete

-- Delete the test player
local deleted = players:DeleteOne({
    steamid = "STEAM_0:1:12345678"
})

print("Deleted", deleted, "document(s)")

Complete Example

Here's a complete example putting it all together:

require("mongo")

-- Connect
local client = MongoDB.Client("mongodb://localhost:27017")
if not client then
    print("Connection failed!")
    return
end

-- Setup
local db = client:Database("gameserver")
local players = db:Collection("players")

-- Create
local id = players:InsertOne({
    steamid = "STEAM_0:1:99999999",
    username = "NewPlayer",
    level = 1,
    credits = 500
})
print("Created player:", id)

-- Read
local player = players:FindOne({ steamid = "STEAM_0:1:99999999" })
print("Player level:", player.level)

-- Update
players:UpdateOne(
    { steamid = "STEAM_0:1:99999999" },
    { ["$inc"] = { level = 1, credits = 100 } }
)

-- Verify update
player = players:FindOne({ steamid = "STEAM_0:1:99999999" })
print("New level:", player.level)      -- 2
print("New credits:", player.credits)  -- 600

-- Delete
players:DeleteOne({ steamid = "STEAM_0:1:99999999" })
print("Player deleted")

Error Handling

Always handle potential errors:

-- Check connection
local client = MongoDB.Client("mongodb://localhost:27017")
if not client then
    print("ERROR: Could not connect to MongoDB")
    print("Please check that MongoDB is running")
    return
end

-- Check operations
local result = players:InsertOne({ name = "test" })
if not result then
    print("ERROR: Insert failed")
end

Next Steps

Now that you've completed the basics, explore:

CRUD Operations

Master all database operations

Async Operations

Non-blocking database calls

Examples

Real-world code examples

Configuration

Configure gmsv_mongo connection options and settings

Connection

Manage MongoDB connections with gmsv_mongo