0
# Server Management
1

2
Direct server lifecycle management for advanced use cases requiring custom control over the milvus-lite server process. This provides low-level access to server initialization, configuration, and process management.
3

4
## Capabilities
5

6
### Server Class
7

8
Core server management class for controlling individual milvus-lite server instances.
9

10
```python { .api }
11
class Server:
12
    """
13
    The milvus-lite server implementation.
14
    
15
    Manages a single milvus-lite server process with database file storage
16
    and network configuration options.
17
    """
18
    
19
    def __init__(self, db_file: str, address: Optional[str] = None):
20
        """
21
        Initialize server with database file and optional network address.
22
        
23
        Parameters:
24
        - db_file (str): Path to local database file for data storage
25
        - address (Optional[str]): Network address (host:port) or None for UDS
26
        
27
        Raises:
28
        - RuntimeError: If db_file name is invalid or too long
29
        """
30
    
31
    def init(self) -> bool:
32
        """
33
        Initialize server by validating paths and dependencies.
34
        
35
        Returns:
36
        - bool: True if initialization successful, False otherwise
37
        """
38
    
39
    def start(self) -> bool:
40
        """
41
        Start the milvus-lite server process.
42
        
43
        Creates file lock, configures environment, and spawns server process.
44
        Uses Unix Domain Socket for local communication by default.
45
        
46
        Returns:
47
        - bool: True if server started successfully, False otherwise
48
        
49
        Raises:
50
        - BlockingIOError: If database file is locked by another process
51
        """
52
    
53
    def stop(self) -> None:
54
        """
55
        Stop the server process and cleanup resources.
56
        
57
        Releases file locks, terminates server process, and removes
58
        temporary socket and lock files.
59
        """
60
    
61
    def __del__(self) -> None:
62
        """Destructor ensures server is stopped when object is destroyed."""
63
```
64

65
**Usage Example:**
66

67
```python
68
from milvus_lite.server import Server
69

70
# Create server instance
71
server = Server("./my_database.db")
72

73
try:
74
    # Initialize and start server
75
    if not server.init():
76
        raise RuntimeError("Server initialization failed")
77
        
78
    if not server.start():
79
        raise RuntimeError("Server startup failed")
80
    
81
    # Server is now running and ready for connections
82
    print(f"Server started with UDS path: {server.uds_path}")
83
    
84
    # Use server (connect with pymilvus client using UDS path)
85
    # ... your application logic ...
86

87
finally:
88
    # Always cleanup server resources
89
    server.stop()
90
```
91

92
### Server Properties
93

94
Read-only properties providing server configuration and status information.
95

96
```python { .api }
97
@property
98
def milvus_bin(self) -> str:
99
    """Path to the milvus binary executable."""
100

101
@property  
102
def log_level(self) -> str:
103
    """Log level from LOG_LEVEL environment variable (default: 'ERROR')."""
104

105
@property
106
def uds_path(self) -> str:
107
    """Unix Domain Socket path with 'unix:' prefix for client connections."""
108

109
@property
110
def args(self) -> List[str]:
111
    """Command line arguments for starting the milvus server process."""
112
```
113

114
**Usage Example:**
115

116
```python
117
server = Server("./test.db")
118

119
# Check server configuration before starting
120
print(f"Binary path: {server.milvus_bin}")
121
print(f"Log level: {server.log_level}")
122
print(f"UDS path: {server.uds_path}")
123
print(f"Server args: {server.args}")
124

125
# Server properties are available before calling start()
126
```
127

128
### Network Configuration
129

130
Configure the server for TCP network access instead of Unix Domain Sockets.
131

132
```python { .api }
133
# TCP network server
134
server = Server(
135
    db_file="./network_db.db",
136
    address="localhost:19530"  # TCP address instead of UDS
137
)
138
```
139

140
**Usage Example:**
141

142
```python
143
# Create server with network access
144
server = Server("./shared_db.db", address="0.0.0.0:19530")
145

146
if server.init() and server.start():
147
    print("Server available at localhost:19530")
148
    
149
    # Connect with pymilvus using network address
150
    from pymilvus import MilvusClient
151
    client = MilvusClient(uri="http://localhost:19530")
152
    
153
    # Use client normally...
154
    client.create_collection("test", dimension=128)
155
```
156

157
### Error Handling
158

159
Server operations can raise various exceptions depending on the failure mode.
160

161
```python { .api }
162
# Exceptions that may be raised:
163
# - RuntimeError: Invalid database names, missing binaries, startup failures
164
# - BlockingIOError: Database file locked by another process  
165
# - subprocess.TimeoutExpired: Process management timeouts
166
# - FileNotFoundError: Missing required files or directories
167
```
168

169
**Usage Example:**
170

171
```python
172
from milvus_lite.server import Server
173
import logging
174

175
def start_server_safely(db_path: str) -> Optional[Server]:
176
    """Start server with comprehensive error handling."""
177
    server = Server(db_path)
178
    
179
    try:
180
        if not server.init():
181
            logging.error("Server initialization failed - check binary paths")
182
            return None
183
            
184
        if not server.start():
185
            logging.error("Server startup failed - check logs and ports")
186
            return None
187
            
188
        logging.info(f"Server started successfully at {server.uds_path}")
189
        return server
190
        
191
    except BlockingIOError:
192
        logging.error(f"Database {db_path} is already in use by another process")
193
        return None
194
    except RuntimeError as e:
195
        logging.error(f"Runtime error starting server: {e}")
196
        return None
197
    except Exception as e:
198
        logging.error(f"Unexpected error: {e}")
199
        return None
200
```
201

202
## Database File Requirements
203

204
Database files must meet specific naming and path requirements for security and compatibility.
205

206
```python { .api }
207
# Valid database file names (examples):
208
# - "data.db"
209
# - "vectors_2024.db" 
210
# - "user-embeddings.db"
211
# - "test_collection.db"
212

213
# Invalid database file names:
214
# - "data base.db" (spaces not allowed)
215
# - "data@base.db" (special characters not allowed)
216
# - "very_long_database_name_that_exceeds_limits.db" (too long)
217
```
218

219
**File Name Rules:**
220
- Must match regex: `^[a-zA-Z0-9.\-_]+$`
221
- Maximum length: 36 characters
222
- Only alphanumeric characters, dots, hyphens, and underscores allowed
223
- Parent directory must exist and be writable
224

225
## Process Management
226

227
The Server class manages the underlying milvus binary process with proper environment setup and resource cleanup.
228

229
**Environment Variables:**
230
- `BIN_PATH`: Override default binary path location
231
- `LOG_LEVEL`: Set server log level (ERROR, WARN, INFO, DEBUG)
232
- `LD_LIBRARY_PATH`: Managed automatically for Linux
233
- `DYLD_LIBRARY_PATH`: Managed automatically for macOS
234

235
**Process Lifecycle:**
236
1. Initialize paths and validate configuration
237
2. Create file lock to prevent concurrent access
238
3. Configure environment variables for native libraries
239
4. Spawn milvus binary with appropriate arguments  
240
5. Monitor process startup and health
241
6. Cleanup resources on shutdown (locks, sockets, processes)
242

243
**Resource Cleanup:**
244
- Automatic cleanup on object destruction (`__del__`)
245
- Explicit cleanup via `stop()` method
246
- File lock release terminates server automatically
247
- Temporary socket files are removed
248
- Server process is terminated gracefully (SIGTERM then SIGKILL)