Jwbshaw: more tables

2026-06-26T07:28:24Z

more tables

@@ Line 896: / Line 896: @@
 |-
 | AllowEnviromentOverride || 1 = parcels can override environment
 |}

Jwbshaw: added opensim

2026-06-24T14:01:31Z

added opensim

Show changes

Jwbshaw: first

2026-06-24T07:26:13Z

first

New page

= OpenSimulator Internals/Databases =

== Overview ==

OpenSimulator uses two categories of database:

* The grid database (osimdev_robust) -- owned by ROBUST, holds grid-wide data: user accounts, inventory, assets, presence, region registration, friends, avatar appearance
* Region databases (osimdev_t1, osimdev_t2, ...) -- owned by the simulator, one per region, holds in-world object and terrain data

Both databases run on the same MariaDB instance. ROBUST never touches region databases. Simulators connect to ROBUST services over HTTP for grid data, and directly to their own region database for local data.

See [[OpenSimulator Internals/GridService]], [[OpenSimulator Internals/Asset Connector]], and [[OpenSimulator Internals/ROBUST Services]] for the service layer above these tables.

----

== Grid Database (osimdev_robust) ==

=== Table List ===

{| class="wikitable"
! Table !! Purpose
|-
| regions || Region registration -- one row per online or recently-seen region
|-
| UserAccounts || User accounts including the internal GRID SERVICES account
|-
| Avatars || Avatar appearance: worn items, attachment points, visual params (key-value store)
|-
| GridUser || Home region, last region, last position, login/logout timestamps
|-
| Presence || Active sessions -- who is online right now and in which region
|-
| auth || Password hashes and authentication tokens
|-
| tokens || Session tokens for region-to-region and HyperGrid authentication
|-
| inventoryfolders || Inventory folder hierarchy
|-
| inventoryitems || Inventory item records
|-
| assets || Asset metadata and binary data
|-
| Friends || Friend relationships and permissions, including HyperGrid friends
|-
| AgentPrefs || Per-user preferences (hover height, language, default permissions)
|-
| hg_traveling_data || HyperGrid travel state for avatars currently visiting foreign grids
|-
| MuteList || Per-user mute lists
|-
| im_offline || Stored offline instant messages
|-
| migrations || Schema version tracking for each service
|}

----

=== regions ===

One row per registered region. Written on simulator startup (RegisterRegion), updated on shutdown (DeregisterRegion).

{| class="wikitable"
! Field !! Type !! Notes
|-
| uuid || varchar(36) || Primary key -- region UUID
|-
| regionHandle || bigint unsigned || Encoded X,Y handle: (locX << 32) | locY
|-
| regionName || varchar(128) || Display name, max 128 chars
|-
| serverURI || varchar(255) || HTTP endpoint of the simulator e.g. http://osimdev.org:9000/
|-
| locX || int unsigned || Region origin X in metres (region coord * 256)
|-
| locY || int unsigned || Region origin Y in metres (region coord * 256)
|-
| sizeX || int || Region width in metres (512 for a 2x2 varregion)
|-
| sizeY || int || Region height in metres
|-
| flags || int || Bitmask of RegionFlags (4 = RegionOnline)
|-
| last_seen || int || Unix timestamp of last registration or deregistration
|-
| owner_uuid || varchar(36) || Estate owner UUID
|-
| ScopeID || char(36) || Grid scope -- zero UUID for default scope
|-
| access || int unsigned || Parcel access level (1 = PG)
|-
| regionMapTexture || varchar(36) || UUID of map tile image asset
|-
| PrincipalID || char(36) || Used for reservation authentication
|-
| Token || varchar(255) || Authentication token for reserved regions
|}

Legacy fields present but unused in current code: regionRecvKey, regionSendKey, regionSecret, regionDataURI, regionAssetURI, regionAssetRecvKey, regionAssetSendKey, regionUserURI, regionUserRecvKey, regionUserSendKey, serverRemotingPort, eastOverrideHandle, westOverrideHandle, southOverrideHandle, northOverrideHandle.

Sample row (T1 on osimdev):

{| class="wikitable"
! Field !! Value
|-
| uuid || 6f0a42d1-3053-422d-9c26-13205c9c7723
|-
| regionName || T1
|-
| locX / locY || 256000 (= region coordinate 1000)
|-
| sizeX / sizeY || 512
|-
| flags || 4 (RegionOnline)
|-
| serverURI || http://osimdev.org:9000/
|-
| last_seen || Unix timestamp
|}

----

=== UserAccounts ===

{| class="wikitable"
! Field !! Type !! Notes
|-
| PrincipalID || char(36) || UUID primary key
|-
| FirstName || varchar(64) ||
|-
| LastName || varchar(64) ||
|-
| Email || varchar(64) || Login email
|-
| UserLevel || int || 0 = normal user, 240 = god-level
|-
| UserFlags || int || Reserved
|-
| Created || int || Unix timestamp
|}

Two rows on a fresh grid: the admin avatar (UserLevel 0) and the internal GRID SERVICES account (UserLevel 240). The GRID SERVICES account has no auth record and never logs in -- it is used internally by OpenSim services.

----

=== Avatars ===

Key-value store. One row per attribute per avatar. PrincipalID + Name form the composite key.

{| class="wikitable"
! Name pattern !! Value format !! Notes
|-
| _ap_N || UUID or comma-separated UUIDs || Attachment point N -- asset UUID of worn item. Comma-separated for multi-attach points.
|-
| Wearable N:0 || inventoryUUID:assetUUID || Worn wearable layer N. 0=shape, 1=skin, 2=shirt, 3=pants, 13=physics, etc.
|-
| AvatarHeight || float || Avatar height in metres
|-
| AvatarType || int || 0 = classic system avatar, 1 = mesh avatar
|-
| VisualParams || comma-separated bytes || 253-element appearance slider array -- body shape, skin tone, hair color etc.
|-
| Serial || int || Appearance version serial number
|}

Attachment point numbers follow the SL/OpenSim standard: 2=chest, 5=left hand, 12=hair, 40=left foot, etc. Multi-attach points store comma-separated UUIDs.

Sample data (Jagga Meredith, 13 rows):
* AvatarType = 1 (mesh)
* AvatarHeight = 1.6885326
* 4 attachment points: chest, left hand (3 items), hair, left foot
* 5 wearable layers: shape, skin, shirt, pants, physics

----

=== GridUser ===

One row per user. Written on first login, updated on every login, logout, and teleport.

{| class="wikitable"
! Field !! Type !! Notes
|-
| UserID || varchar(255) || UUID or HyperGrid URI -- primary key
|-
| HomeRegionID || char(36) || UUID of home region
|-
| HomePosition || varchar(64) || Vector3 in region-local metres e.g. <254.87, 255.54, 27.12>
|-
| HomeLookAt || varchar(64) || Vector3 look direction
|-
| LastRegionID || char(36) || UUID of last visited region
|-
| LastPosition || varchar(64) || Vector3 in region-local metres
|-
| LastLookAt || varchar(64) || Vector3 look direction
|-
| Online || tinyint || 1 only while session is active
|-
| Login || int || Unix timestamp of last login
|-
| Logout || int || Unix timestamp of last logout
|}

UserID is varchar(255) not char(36) -- accommodates HyperGrid user URIs from foreign grids.

----

=== Presence ===

One row per active session. Empty when no users are logged in. Rows are created on login and deleted on logout.

{| class="wikitable"
! Field !! Type !! Notes
|-
| SessionID || char(36) || Primary key -- unique per login session
|-
| UserID || varchar(255) || UUID or HyperGrid URI
|-
| RegionID || char(36) || Current region UUID -- zero UUID if not yet in a region
|-
| SecureSessionID || char(36) || Secondary session token for viewer authentication
|-
| LastSeen || timestamp || Auto-updated on change -- used to detect stale sessions
|}

----

=== auth ===

One row per user account. Stores password credentials.

{| class="wikitable"
! Field !! Type !! Notes
|-
| UUID || char(36) || Primary key -- matches UserAccounts.PrincipalID
|-
| passwordHash || char(32) || MD5 hash of password
|-
| passwordSalt || char(32) || MD5 salt
|-
| webLoginKey || varchar(255) || UUID for web-based login -- zero UUID if not configured
|-
| accountType || varchar(32) || Default: UserAccount
|}

GRID SERVICES account has no auth row -- it cannot log in. Only user accounts that can authenticate have rows here.

----

=== tokens ===

Short-lived session tokens used for region-to-region and HyperGrid authentication.

{| class="wikitable"
! Field !! Type !! Notes
|-
| UUID || char(36) || User UUID -- composite primary key with token
|-
| token || varchar(255) || UUID-format token
|-
| validity || datetime || Expiry datetime -- expired tokens remain until cleaned up
|}

Multiple tokens per user are normal -- one per teleport attempt. Expired tokens are not automatically deleted; they accumulate until a cleanup job runs.

----

=== assets ===

Stores all asset data. One row per asset.

{| class="wikitable"
! Field !! Type !! Notes
|-
| id || char(36) || Primary key -- asset UUID
|-
| name || varchar(64) || Display name
|-
| description || varchar(64) || Description
|-
| assetType || tinyint || Asset type number (see below)
|-
| data || longblob || Raw binary asset data
|-
| local || tinyint(1) || 1 = local-only, not transferred to other grids
|-
| temporary || tinyint(1) || 1 = temporary, may be discarded
|-
| asset_flags || int || Bitmask of asset flags
|-
| CreatorID || varchar(128) || Creator UUID or HyperGrid URI
|-
| create_time || int || Unix timestamp of creation
|-
| access_time || int || Unix timestamp of last access
|}

Asset types observed on osimdev:

{| class="wikitable"
! assetType !! Name !! Notes
|-
| 0 || Texture || Image data
|-
| 3 || Landmark || HyperGrid landmarks store grid URI in description field
|-
| 6 || Object || Serialized prim/linkset XML
|-
| 7 || Notecard || Text notecard
|-
| 10 || Script || LSL script source
|-
| 20 || Animation || BVH animation data
|}

Library/system assets loaded at startup use non-random UUID patterns (e.g. 00000000-0000-1111-9999-000000000001) and CreatorID 11111111-1111-0000-0000-000100bba000. User-created assets use standard random UUIDs.

On osimdev after initial setup and one user session: 2602 total assets, 85 created by Jagga Meredith (1 texture, 4 landmarks, 79 objects, 1 notecard).

----

=== inventoryfolders ===

{| class="wikitable"
! Field !! Type !! Notes
|-
| folderID || char(36) || Primary key
|-
| folderName || varchar(64) || Display name
|-
| type || smallint || Folder type (see below)
|-
| version || int || Incremented on folder contents change
|-
| agentID || char(36) || Owner UUID
|-
| parentFolderID || char(36) || Parent folder UUID -- zero UUID for root
|}

System folder types:

{| class="wikitable"
! type !! Name
|-
| -1 || User-created folder
|-
| 0 || Textures
|-
| 1 || Sounds
|-
| 2 || Calling Cards
|-
| 3 || Landmarks
|-
| 5 || Clothing
|-
| 6 || Objects
|-
| 7 || Notecards
|-
| 8 || My Inventory (root)
|-
| 10 || Scripts
|-
| 13 || Body Parts
|-
| 14 || Trash
|-
| 15 || Photo Album
|-
| 16 || Lost And Found
|-
| 20 || Animations
|-
| 21 || Gestures
|-
| 23 || Favorites
|-
| 46 || Current Outfit
|-
| 47 || Outfit
|-
| 48 || My Outfits
|-
| 50 || Received Items
|-
| 56 || Settings
|-
| 57 || Materials
|-
| 100 || My Suitcase (HyperGrid)
|}

My Suitcase (type 100) is the HyperGrid suitcase -- items here travel with the avatar to foreign grids. Its subtree mirrors the main inventory structure. Firestorm creates system folders: #Firestorm (containing #AO, #LSL Bridge, #Wearable Favorites).

----

=== inventoryitems ===

One row per inventory item.

{| class="wikitable"
! Field !! Type !! Notes
|-
| inventoryID || char(36) || Primary key
|-
| assetID || varchar(36) || Foreign key to assets.id
|-
| assetType || int || Asset type
|-
| invType || int || Inventory type (can differ from assetType)
|-
| inventoryName || varchar(64) || Display name
|-
| inventoryDescription || varchar(128) ||
|-
| avatarID || char(36) || Owner UUID
|-
| parentFolderID || char(36) || Containing folder UUID
|-
| creatorID || varchar(255) || Creator UUID or HyperGrid URI (varchar for HG compatibility)
|-
| inventoryBasePermissions || int unsigned || Base permission bitmask
|-
| inventoryCurrentPermissions || int unsigned || Current permission bitmask
|-
| inventoryNextPermissions || int unsigned || Next owner permission bitmask
|-
| inventoryEveryOnePermissions || int unsigned || Everyone permission bitmask
|-
| inventoryGroupPermissions || int unsigned || Group permission bitmask
|-
| groupID || varchar(36) || Associated group UUID
|-
| groupOwned || tinyint || 1 if group-owned
|-
| salePrice || int || Sale price in grid currency
|-
| saleType || tinyint || 0=not for sale, 1=original, 2=copy, 3=contents
|-
| creationDate || int || Unix timestamp
|-
| flags || int unsigned || Item flags
|}

creatorID is varchar(255) to accommodate HyperGrid creator URIs (e.g. UUID;http://foreigngrid.com:8002/).

Item count on osimdev after initial session and AviWorlds visit: 380 items. Breakdown by assetType: 171 objects, 75 animations, 34 links, 28 textures, 24 body parts, 21 clothing, 15 landmarks, 6 notecards, 3 scripts, 2 sounds, 1 mesh.

----

=== Friends ===

One row per directional friendship. Friendships are stored as two rows (A->B and B->A).

{| class="wikitable"
! Field !! Type !! Notes
|-
| PrincipalID || varchar(255) || Owner UUID or HyperGrid URI -- composite primary key
|-
| Friend || varchar(255) || Friend UUID or HyperGrid compound string
|-
| Flags || varchar(16) || Permission flags (1 = accepted)
|-
| Offered || varchar(32) || Pending offer token
|}

For HyperGrid friends, Friend field format is: UUID;GridURI;DisplayName;token

Example: 5a365446-ad4f-4f7f-a843-563494b0e78b;http://login.aviworlds.com:8002/;Jagga Meredith;23cba5bc

PrincipalID and Friend are varchar(255) to accommodate HyperGrid URIs.

----

=== AgentPrefs ===

One row per user. Written when user explicitly sets preferences in-world. Defaults apply if no row exists.

{| class="wikitable"
! Field !! Type !! Default !! Notes
|-
| PrincipalID || char(36) || -- || Primary key
|-
| AccessPrefs || char(2) || M || Content rating: G, M, or A
|-
| HoverHeight || double || 0.0 || Avatar hover offset in metres
|-
| Language || char(5) || en-us || Viewer language preference
|-
| LanguageIsPublic || tinyint || 1 || Whether language preference is visible to others
|-
| PermEveryone || int || 0 || Default everyone permissions for new objects
|-
| PermGroup || int || 0 || Default group permissions for new objects
|-
| PermNextOwner || int || 532480 || Default next owner permissions for new objects
|}

----

=== hg_traveling_data ===

Tracks avatars currently traveling between grids via HyperGrid. One row per active HG session. Rows are deleted when the avatar returns home or logs out.

{| class="wikitable"
! Field !! Type !! Notes
|-
| SessionID || varchar(36) || Primary key -- login session UUID
|-
| UserID || varchar(36) || Avatar UUID
|-
| GridExternalName || varchar(255) || URI of the grid the avatar is currently visiting
|-
| ServiceToken || varchar(255) || Auth token for the foreign grid session
|-
| ClientIPAddress || varchar(16) || Avatar's client IP on the foreign grid
|-
| MyIPAddress || varchar(16) || This grid's external IP as seen by the foreign grid
|-
| TMStamp || timestamp || Auto-updated -- used to detect stale travel records
|}

Empty when no avatars are traveling. Populated during active HyperGrid teleport and cleared on return or logout.

----

== Region Database (osimdev_t1) ==

-- to be documented with live data --

=== Table List ===

{| class="wikitable"
! Table !! Purpose
|-
| prims || Every prim/object in the region
|-
| primshapes || Shape and texture data for each prim
|-
| primitems || Inventory items inside prim object contents
|-
| terrain || Region heightmap
|-
| bakedterrain || Baked terrain data
|-
| land || Parcel definitions
|-
| landaccesslist || Per-parcel access lists
|-
| regionsettings || Region-wide settings (gravity, water level, etc.)
|-
| regionenvironment || Environment/windlight settings
|-
| regionwindlight || Legacy windlight settings
|-
| regionextra || Extra region key-value data
|-
| estate_settings || Estate configuration (name, owner, access flags)
|-
| estate_map || Maps regions to estates
|-
| estate_managers || Estate manager UUID list
|-
| estate_groups || Estate group access list
|-
| estate_users || Estate user access list
|-
| estateban || Estate ban list
|-
| regionban || Region-level ban list
|-
| spawn_points || Avatar spawn point locations
|-
| migrations || Schema version tracking
|}

----

=== prims ===

-- to be documented --

----

=== primshapes ===

-- to be documented --

----

=== terrain ===

-- to be documented --

----

=== regionsettings ===

-- to be documented --

----

=== estate_settings ===

-- to be documented --

----

=== land ===

-- to be documented --

----

== See Also ==

* [[OpenSimulator Internals/ROBUST Services]]
* [[OpenSimulator Internals/GridService]]
* [[OpenSimulator Internals/Asset Connector]]
* [[OpenSimulator Internals/Data Dictionaries]]

OpenSimulator Internals/Databases - Revision history

Jwbshaw: more tables

Jwbshaw: added opensim

Jwbshaw: first