Release History
Help

YMatrix

Quick Start

Deployment

Data Usage

Manage Clusters

Security

Best Practice

Technical Principles

Advanced Features

Guide

SQL Reference

FAQ

Database Directories

This document describes the file directory structure used by a YMatrix database cluster during operation. From a functional perspective, the directories fall into the following categories:

  • Installation Directory
  • System Configuration Directory
  • Data Storage Directory
  • etcd Data Directory
  • Log Directories

Installation Directory

Directory Path

/opt/ymatrix/matrixdb6: The core installation directory for the cluster. It contains binary executables, libraries, configuration templates, and other essential runtime components.

Directory Structure

matrixdb6/
├── bin                     # Core executable commands
├── docs                    # Documentation and command help files
├── etc                     # Git metadata files
├── greenplum_path.sh       # Environment variable initialization script
├── include                 # Header files (interface declarations)
├── lib                     # Core library files (shared and static libraries)
├── libexec                 # Internal scripts and tools (used internally by the cluster)
├── sbin                    # Administrative utilities requiring elevated privileges
└── share                   # Shared resources (system catalog definitions, SQL scripts, etc.)

System Configuration Directory

Directory Path

/etc/matrixdb6: The global configuration directory for the cluster. It stores cluster topology, service configurations, and other system-wide settings.

Directory Structure

matrixdb6/
├── alert.yml                         # Alerting configuration
├── auth.conf                         # Stores mxadmin credentials for the MXUI web interface
├── cluster.conf                      # Core cluster configuration (nodes, ports, roles, etc.)
├── defaults.conf                     # Default port assignment parameters
├── mxui                              # MXUI web management interface configuration
├── physical_cluster.toml             # Physical cluster configuration (includes etcd ports)
├── postmaster.env                    # Environment variables for the postmaster process
├── recover_db_cluster.json           # Node configuration of the database instance cluster
├── recover_physical_cluster.json     # Configuration of the etcd cluster in YMatrix SOA architecture; used by `etcdrecover`
├── scripts                           # Monitoring and maintenance scripts
├── service                           # Service definitions for components (e.g., etcd, MXUI)
└── supervisor.conf                   # Supervisor configuration for managing database processes

Data Storage Directory

Directory Path

Run the following SQL query to identify the data directory paths for each segment:

SELECT * FROM gp_segment_configuration;

MASTER Node Directory Structure

├── base                    # User database data; each database has a subdirectory named by its OID
├── current_logfiles        # Mapping file for active log paths, supporting log rotation
├── fts_probe_file.bak      # Backup of FTS (Fault Tolerance Service) probe state
├── global                  # Global system catalogs (shared across databases: roles, tablespaces, etc.)
├── init_cluster.json       # Node initialization metadata (role, port, etc.)
├── internal.auto.conf      # Auto-generated database ID
├── log                     # Runtime logs for this node
├── pg_commit_ts            # Transaction commit timestamps (for point-in-time recovery)
├── pg_distributedlog       # Distributed transaction logs (for two-phase commit across nodes)
├── pg_dynshmem             # Dynamic shared memory for parallel query IPC
├── pg_hba.conf             # Client authentication and access control rules
├── pg_hba.conf.bak         # Backup of pg_hba.conf
├── pg_ident.conf           # OS user to database user mapping
├── pg_logical              # Logical replication data (slots, decoding plugins)
├── pg_multixact            # Multi-transaction concurrency control metadata
├── pg_notify               # Asynchronous LISTEN/NOTIFY messages
├── pg_replslot             # Replication slots (used by Domino streaming replication)
├── pg_serial               # Serializable isolation conflict detection data
├── pg_snapshots            # Exported transaction snapshots
├── pg_stat                 # Persistent statistics (table sizes, index usage, etc.)
├── pg_stat_tmp             # Temporary statistics (flushed periodically to pg_stat)
├── pg_subtrans             # Subtransaction status tracking
├── pg_tblspc               # Symbolic links to user-defined tablespaces
├── pg_twophase             # Prepared two-phase commit transactions
├── PG_VERSION              # Database major version identifier
├── pg_wal                  # Write-ahead log (WAL) files
├── pg_xact                 # Transaction commit/abort status (XID to WAL mapping)
├── postgresql.auto.conf    # Auto-generated configuration (do not edit)
├── postgresql.conf         # Main runtime configuration file
├── postgresql.conf.bak     # Backup of postgresql.conf
├── postmaster.opts         # Command-line arguments used to start postmaster
└── postmaster.pid          # PID and metadata of the running postmaster process

SEGMENT Node Directory Structure

The SEGMENT node directory structure is nearly identical to the MASTER, with the following contents:

├── base
├── current_logfiles
├── fts_probe_file.bak
├── global
├── internal.auto.conf
├── log
├── pg_commit_ts
├── pg_distributedlog
├── pg_dynshmem
├── pg_hba.conf
├── pg_hba.conf.bak
├── pg_ident.conf
├── pg_logical
├── pg_multixact
├── pg_notify
├── pg_replslot
├── pg_serial
├── pg_snapshots
├── pg_stat
├── pg_stat_tmp
├── pg_subtrans
├── pg_tblspc
├── pg_twophase
├── PG_VERSION
├── pg_wal
├── pg_xact
├── postgresql.auto.conf
├── postgresql.conf
├── postgresql.conf.bak
├── postmaster.opts
└── postmaster.pid

etcd Data Directory

Directory Path

The etcd data directory path is specified in /etc/matrixdb6/recover_physical_cluster.json.

Directory Structure

.
├── data  # Persistent etcd data (the coordination backbone of the YMatrix cluster)
└── log   # etcd runtime logs (essential for troubleshooting)

Log Directories

Utility Log Directory

Located at /home/mxadmin/gpAdminLogs/, this directory contains logs from YMatrix administrative tools:

/home/mxadmin/gpAdminLogs/
├── check-version_20251221.log    # Connectivity validation with etcd cluster
├── gpconfig_20251113.log         # gpconfig tool operations
├── mxdeletesystem_20251201.log   # Resource cleanup by mxdeletesystem
├── mxstart_20251221.log          # Cluster startup via mxstart
├── mxstate_20251203.log          # Cluster status checks by mxstate
└── mxstop_20251221.log           # Cluster shutdown via mxstop

Component Log Directory

Located at /var/log/matrixdb6/, this directory contains logs from YMatrix system components:

/var/log/matrixdb6/
├── cluster_fgd4USi2WTNdsv7dhbXzwu.log          # Logs from the cluster management process
├── replication-2_fgd4USi2WTNdsv7dhbXzwu.log    # Logs from replication worker #2
├── replication-4_fgd4USi2WTNdsv7dhbXzwu.log    # Logs from replication worker #4
├── shard_fgd4USi2WTNdsv7dhbXzwu.log            # Logs from shard management process
......
← Previous
Switching
Next →
Overview