0
# Database Connection
1

2
Core database connection functionality with lazy connection management and enhanced connection methods.
3

4
## Capabilities
5

6
### Database Connection Function
7

8
Creates a database connection using a MongoDB connection string.
9

10
```javascript { .api }
11
/**
12
 * Create a database connection
13
 * @param {string} connectionString - MongoDB connection URI
14
 * @param {object} [options] - Connection options
15
 * @returns {SkinDb} Database instance with lazy connection
16
 */
17
function db(connectionString, options);
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
const mongoskin = require('mongoskin');
24

25
// Basic connection
26
const db = mongoskin.db('mongodb://localhost:27017/myapp');
27

28
// Connection with options
29
const db = mongoskin.db('mongodb://localhost:27017/myapp', {
30
  native_parser: true,
31
  auto_reconnect: true
32
});
33

34
// Connection with authentication
35
const db = mongoskin.db('mongodb://user:pass@localhost:27017/myapp');
36
```
37

38
### MongoClient Connection
39

40
Static method for creating database connections, compatible with the native MongoDB driver.
41

42
```javascript { .api }
43
/**
44
 * Connect to MongoDB using MongoClient
45
 * @param {string} connectionString - MongoDB connection URI
46
 * @param {object} [options] - Connection options
47
 * @param {function} [callback] - Optional callback function
48
 * @returns {SkinDb} Database instance
49
 */
50
MongoClient.connect(connectionString, options, callback);
51
```
52

53
**Usage Examples:**
54

55
```javascript
56
const mongoskin = require('mongoskin');
57

58
// Direct connection (returns immediately)
59
const db = mongoskin.MongoClient.connect('mongodb://localhost:27017/myapp');
60

61
// With callback (traditional style)
62
mongoskin.MongoClient.connect('mongodb://localhost:27017/myapp', (err, db) => {
63
  if (err) throw err;
64
  // db is ready to use
65
  db.close();
66
});
67
```
68

69
### Database Instance Methods
70

71
Core methods available on database instances for connection management and collection access.
72

73
```javascript { .api }
74
/**
75
 * Get or create a collection
76
 * @param {string} name - Collection name
77
 * @param {object} [options] - Collection options
78
 * @returns {SkinCollection} Collection instance
79
 */
80
collection(name, options);
81

82
/**
83
 * Bind a collection to the database instance as a property
84
 * @param {string} name - Collection name
85
 * @param {object} [options] - Collection options  
86
 * @returns {SkinCollection} The bound collection
87
 */
88
bind(name, options);
89

90
/**
91
 * Open database connection explicitly
92
 * @param {function} callback - Callback function (err, db)
93
 * @returns {SkinDb} this
94
 */
95
open(callback);
96

97
/**
98
 * Close database connection
99
 * @param {function} [callback] - Optional callback function
100
 * @returns {SkinDb} this  
101
 */
102
close(callback);
103

104
/**
105
 * Check if database connection is open
106
 * @returns {boolean} true if connection is open
107
 */
108
isOpen();
109
```
110

111
**Usage Examples:**
112

113
```javascript
114
const mongoskin = require('mongoskin');
115
const db = mongoskin.db('mongodb://localhost:27017/myapp');
116

117
// Get collection
118
const users = db.collection('users');
119

120
// Bind collection for easy access
121
db.bind('posts');
122
db.posts.findOne({}, (err, post) => {
123
  console.log(post);
124
});
125

126
// Explicit connection management
127
db.open((err, database) => {
128
  if (err) throw err;
129
  console.log('Connected to:', database.databaseName);
130
  
131
  // Check connection status
132
  console.log('Is open:', db.isOpen()); // true
133
  
134
  db.close(() => {
135
    console.log('Connection closed');
136
  });
137
});
138
```
139

140
### Connection Options
141

142
Common connection options supported by mongoskin.
143

144
```javascript { .api }
145
interface ConnectionOptions {
146
  /** Use native BSON parser for better performance */
147
  native_parser?: boolean;
148
  
149
  /** Automatically reconnect on connection loss */
150
  auto_reconnect?: boolean;
151
  
152
  /** Connection pool size */
153
  poolSize?: number;
154
  
155
  /** Write concern options */
156
  w?: number | string;
157
  
158
  /** Journal write concern */
159
  j?: boolean;
160
  
161
  /** Timeout for server selection */
162
  serverSelectionTimeoutMS?: number;
163
  
164
  /** Socket timeout */
165
  socketTimeoutMS?: number;
166
  
167
  /** Connection timeout */
168
  connectTimeoutMS?: number;
169
}
170
```
171

172
### Admin Interface
173

174
Access to MongoDB administrative operations.
175

176
```javascript { .api }
177
/**
178
 * Get admin interface for database operations
179
 * @returns {SkinAdmin} Admin instance
180
 */
181
admin();
182
```
183

184
**Usage Example:**
185

186
```javascript
187
const db = mongoskin.db('mongodb://localhost:27017/myapp');
188

189
const admin = db.admin();
190
admin.listDatabases((err, dbs) => {
191
  if (err) throw err;
192
  console.log('Databases:', dbs.databases);
193
});
194
```
195

196
### GridStore Interface
197

198
Access to GridFS file storage operations.
199

200
```javascript { .api }
201
/**
202
 * Create GridStore instance for file operations
203
 * @param {...any} args - GridStore constructor arguments
204
 * @returns {SkinGridStore} GridStore instance
205
 */
206
gridStore(...args);
207
```
208

209
**Usage Example:**
210

211
```javascript
212
const db = mongoskin.db('mongodb://localhost:27017/myapp');
213

214
const gridStore = db.gridStore('myfile.txt', 'w');
215
gridStore.open((err, gs) => {
216
  if (err) throw err;
217
  gs.write('Hello World', (err, result) => {
218
    if (err) throw err;
219
    gs.close();
220
  });
221
});
222
```