Connection

Connection Options

Configure advanced connection options

Connection Options

Use MongoDB.ClientWithOptions() for advanced connection configuration.

Basic Usage

local client = MongoDB.ClientWithOptions("mongodb://localhost:27017", {
    app_name = "MyGModServer",
    max_pool_size = 50,
    retry_writes = true
})

Available Options

app_name

Application name for server monitoring and logging.

local client = MongoDB.ClientWithOptions("mongodb://localhost:27017", {
    app_name = "MyGameServer"
})

Type: string
Default: "gmsv_mongo_v2"
Purpose: Appears in MongoDB server logs and monitoring tools

max_pool_size

Maximum number of connections in the connection pool.

local client = MongoDB.ClientWithOptions("mongodb://localhost:27017", {
    max_pool_size = 100
})

Type: number
Default: 100
Purpose: Controls concurrent connection capacity

retry_writes

Automatically retry failed write operations.

local client = MongoDB.ClientWithOptions("mongodb://localhost:27017", {
    retry_writes = true
})

Type: boolean
Default: true
Purpose: Handles transient network failures gracefully

Complete Options Example

local client = MongoDB.ClientWithOptions("mongodb://localhost:27017", {
    -- Application identification
    app_name = "MyGModServer",

    -- Connection pool configuration
    max_pool_size = 50,

    -- Retry behavior
    retry_writes = true
})

if client then
    print("✓ Connected with custom options!")
end

Internal Configuration

The library uses these internal defaults (from Rust configuration):

Setting	Default Value	Description
`min_pool_size`	10	Minimum connections maintained
`max_pool_size`	100	Maximum connections allowed
`server_selection_timeout`	30s	Time to select a server
`connect_timeout`	10s	Connection establishment timeout
`max_idle_time`	600s	Close idle connections after
`retry_writes`	true	Retry failed writes
`retry_reads`	true	Retry failed reads

Connection Pool Behavior

How Pooling Works

Initial Connection: First operation creates connection(s)
Reuse: Subsequent operations reuse existing connections
Scaling: Pool grows based on demand (up to max_pool_size)
Cleanup: Idle connections are closed after max_idle_time

Pool Size Guidelines

-- Development/Testing
local client = MongoDB.ClientWithOptions("mongodb://localhost:27017", {
    max_pool_size = 10
})

-- Small server (< 32 players)
local client = MongoDB.ClientWithOptions("mongodb://localhost:27017", {
    max_pool_size = 25
})

-- Medium server (32-64 players)
local client = MongoDB.ClientWithOptions("mongodb://localhost:27017", {
    max_pool_size = 50
})

-- Large server (64+ players)
local client = MongoDB.ClientWithOptions("mongodb://localhost:27017", {
    max_pool_size = 100
})

Environment-Specific Examples

Development

local client = MongoDB.ClientWithOptions("mongodb://localhost:27017", {
    app_name = "GModDev",
    max_pool_size = 10
})

Production

local client = MongoDB.ClientWithOptions("mongodb://prod-user:secure-pass@mongo.example.com:27017", {
    app_name = "GModProd_Server1",
    max_pool_size = 75,
    retry_writes = true
})

Docker Environment

-- When MongoDB is in the same Docker network
local client = MongoDB.ClientWithOptions("mongodb://mongo:27017", {
    app_name = "GModDocker",
    max_pool_size = 50
})

Monitoring Connections

Check Connection Health

local function checkConnection(client)
    if not client then
        return false, "No client"
    end

    local databases = client:ListDatabases()
    if databases then
        return true, "Connected (" .. #databases .. " databases)"
    else
        return false, "Connection test failed"
    end
end

-- Usage
local ok, message = checkConnection(client)
print(ok and "✓" or "✗", message)

Connection in Server Logs

With app_name set, you'll see entries in MongoDB logs:

{"t":{"$date":"2024-01-15T10:30:00.000+00:00"},"s":"I",
 "c":"NETWORK","msg":"Connection accepted",
 "attr":{"appName":"MyGModServer"}}

Best Practices

Set app_name: Helps identify connections in MongoDB logs
Size pool appropriately: Match to expected concurrent operations
Enable retry_writes: Handles transient network issues
Use single client: Reuse the same client instance
Test on startup: Verify connection before starting server

Next Steps

Database Operations - Working with databases
CRUD Operations - Data manipulation

Basic Connection

Create simple MongoDB connections

Database Operations

Working with MongoDB databases