Skip to content

Commit efce928

Browse files
DominusKelvinDominusKelvin
committed
Merge branch 'release/1.17.0'
2 parents 8165148 + 478eb0f commit efce928

File tree

7 files changed

+374
-1
lines changed

7 files changed

+374
-1
lines changed

‎docs/.vitepress/config.mjs‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ export default {
4646
'/sails-flash/': SailsFlashGuide(),
4747
'/clearance/': SailsClearanceGuide(),
4848
'/sails-sqlite/': SailsSQLiteGuide(),
49+
'/connect-sqlite/': ConnectSQLiteGuide(),
4950
'/sails-quest/': SailsQuestGuide(),
5051
'/sentry-sails/': SentrySailsGuide(),
5152
'/pellicule/': pelliculeGuide()
@@ -481,6 +482,24 @@ function SailsClearanceGuide() {
481482
]
482483
}
483484

485+
function ConnectSQLiteGuide() {
486+
return [
487+
{
488+
text: 'Introduction',
489+
collapsed: false,
490+
items: [
491+
{ text: 'Getting started', link: 'connect-sqlite/getting-started' },
492+
{ text: 'Configuration', link: 'connect-sqlite/configuration' }
493+
]
494+
},
495+
{
496+
text: 'Reference',
497+
collapsed: false,
498+
items: [{ text: 'API', link: 'connect-sqlite/api' }]
499+
}
500+
]
501+
}
502+
484503
function SailsSQLiteGuide() {
485504
return [
486505
{

‎docs/.vitepress/data/projects.data.js‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,12 @@ export default {
9191
link: '/sails-sqlite/',
9292
github: 'https://github.com/sailscastshq/sails-sqlite'
9393
},
94+
{
95+
name: 'Connect SQLite',
96+
description: 'SQLite session store for Sails.js using better-sqlite3',
97+
link: '/connect-sqlite/',
98+
github: 'https://github.com/sailscastshq/connect-sqlite'
99+
},
94100
{
95101
name: 'Sentry Sails',
96102
description:

‎docs/connect-sqlite/api.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
---
2+
prev:
3+
text: 'Configuration'
4+
link: '/connect-sqlite/configuration'
5+
next: false
6+
---
7+
8+
# API Reference
9+
10+
Connect SQLite implements the standard Express session store interface plus additional utility methods.
11+
12+
## Required Methods
13+
14+
These methods are part of the session store interface and are called automatically by Express/Sails.
15+
16+
### get(sid, callback)
17+
18+
Retrieve session data by session ID.
19+
20+
```javascript
21+
store.get('abc123', (err, session) => {
22+
if (err) console.error(err)
23+
console.log(session) // { user: { id: 1 }, cookie: { ... } }
24+
})
25+
```
26+
27+
### set(sid, session, callback)
28+
29+
Store session data for a session ID.
30+
31+
```javascript
32+
store.set('abc123', { user: { id: 1 } }, (err) => {
33+
if (err) console.error(err)
34+
console.log('Session saved')
35+
})
36+
```
37+
38+
### destroy(sid, callback)
39+
40+
Delete a session by ID.
41+
42+
```javascript
43+
store.destroy('abc123', (err, count) => {
44+
if (err) console.error(err)
45+
console.log(`Deleted ${count} session(s)`)
46+
})
47+
```
48+
49+
### touch(sid, session, callback)
50+
51+
Refresh a session's TTL without modifying its data. Used for sliding session expiration.
52+
53+
```javascript
54+
store.touch('abc123', session, (err, result) => {
55+
if (err) console.error(err)
56+
console.log(result) // 'OK' or 'EXPIRED'
57+
})
58+
```
59+
60+
## Optional Methods
61+
62+
These methods are not required by the session store interface but are useful for session management.
63+
64+
### length(callback)
65+
66+
Get the count of all active sessions.
67+
68+
```javascript
69+
store.length((err, count) => {
70+
console.log(`Active sessions: ${count}`)
71+
})
72+
```
73+
74+
### clear(callback)
75+
76+
Delete all sessions.
77+
78+
```javascript
79+
store.clear((err, count) => {
80+
console.log(`Cleared ${count} sessions`)
81+
})
82+
```
83+
84+
### ids(callback)
85+
86+
Get all active session IDs.
87+
88+
```javascript
89+
store.ids((err, ids) => {
90+
console.log(ids) // ['abc123', 'def456', ...]
91+
})
92+
```
93+
94+
### all(callback)
95+
96+
Get all active sessions with their data.
97+
98+
```javascript
99+
store.all((err, sessions) => {
100+
sessions.forEach((session) => {
101+
console.log(session.id, session.user)
102+
})
103+
})
104+
```
105+
106+
### close()
107+
108+
Close the database connection. Call this when shutting down to clean up resources.
109+
110+
```javascript
111+
store.close()
112+
```
113+
114+
::: warning
115+
After calling `close()`, the store can no longer be used.
116+
:::
117+
118+
## TTL Behavior
119+
120+
Session TTL (time-to-live) is determined in this order:
121+
122+
1. **`cookie.expires`** - If the session has a cookie with an expires date
123+
2. **`cookie.maxAge`** - If the session has a cookie with maxAge (in milliseconds)
124+
3. **`ttl` option** - The default TTL configured when creating the store
125+
126+
```javascript
127+
// TTL from cookie.expires
128+
store.set(
129+
'abc',
130+
{
131+
cookie: { expires: new Date(Date.now() + 3600000) } // 1 hour
132+
},
133+
callback
134+
)
135+
136+
// TTL from cookie.maxAge
137+
store.set(
138+
'abc',
139+
{
140+
cookie: { maxAge: 3600000 } // 1 hour in ms
141+
},
142+
callback
143+
)
144+
145+
// Falls back to default TTL (86400 seconds = 1 day)
146+
store.set('abc', { user: { id: 1 } }, callback)
147+
```
148+
149+
## Expired Sessions
150+
151+
When a session with a negative TTL is set (i.e., it's already expired), the store will automatically destroy it instead of saving it.
152+
153+
```javascript
154+
// This will destroy the session, not save it
155+
store.set(
156+
'abc',
157+
{
158+
cookie: { expires: new Date(Date.now() - 1000) } // In the past
159+
},
160+
callback
161+
)
162+
```

‎docs/connect-sqlite/configuration.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
prev:
3+
text: 'Getting Started'
4+
link: '/connect-sqlite/getting-started'
5+
next:
6+
text: 'API Reference'
7+
link: '/connect-sqlite/api'
8+
---
9+
10+
# Configuration
11+
12+
Connect SQLite provides several configuration options to customize its behavior.
13+
14+
## Options
15+
16+
| Option | Default | Description |
17+
| -------------- | ------------ | -------------------------------------------------------------- |
18+
| `url` | - | SQLite URL (`sqlite:./path/to/db.sqlite` or `sqlite::memory:`) |
19+
| `db` | `:memory:` | Database file path (alternative to url) |
20+
| `client` | - | Existing better-sqlite3 Database instance |
21+
| `table` | `'sessions'` | Table name for sessions |
22+
| `prefix` | `'sess:'` | Key prefix for session IDs |
23+
| `ttl` | `86400` | Default TTL in seconds (1 day) |
24+
| `disableTTL` | `false` | Disable TTL expiration |
25+
| `disableTouch` | `false` | Disable touch updates |
26+
| `serializer` | `JSON` | Custom serializer with `parse`/`stringify` |
27+
| `wal` | `true` | Enable WAL mode for better concurrency |
28+
29+
## Example Configurations
30+
31+
### Production Setup
32+
33+
```javascript
34+
// config/session.js
35+
module.exports.session = {
36+
secret: process.env.SESSION_SECRET,
37+
adapter: '@sailscastshq/connect-sqlite',
38+
url: 'sqlite:./db/sessions.db',
39+
40+
// Custom TTL (7 days)
41+
ttl: 7 * 24 * 60 * 60,
42+
43+
cookie: {
44+
secure: true,
45+
maxAge: 7 * 24 * 60 * 60 * 1000
46+
}
47+
}
48+
```
49+
50+
### Development Setup
51+
52+
```javascript
53+
// config/env/development.js
54+
module.exports.session = {
55+
adapter: '@sailscastshq/connect-sqlite',
56+
url: 'sqlite::memory:', // In-memory for fast development
57+
58+
cookie: {
59+
secure: false
60+
}
61+
}
62+
```
63+
64+
### Custom Table Name
65+
66+
```javascript
67+
module.exports.session = {
68+
adapter: '@sailscastshq/connect-sqlite',
69+
url: 'sqlite:./db/sessions.db',
70+
table: 'user_sessions', // Custom table name
71+
prefix: 'myapp:' // Custom prefix
72+
}
73+
```
74+
75+
## WAL Mode
76+
77+
WAL (Write-Ahead Logging) mode is enabled by default for file-based databases. This provides better concurrent read/write performance.
78+
79+
To disable WAL mode:
80+
81+
```javascript
82+
module.exports.session = {
83+
adapter: '@sailscastshq/connect-sqlite',
84+
url: 'sqlite:./db/sessions.db',
85+
wal: false
86+
}
87+
```
88+
89+
::: tip
90+
WAL mode is automatically disabled for in-memory databases (`:memory:`).
91+
:::
92+
93+
## Session Cleanup
94+
95+
Expired sessions are automatically pruned:
96+
97+
- **On startup** - Cleans up any expired sessions from previous runs
98+
- **Hourly** - Runs a background cleanup job every hour
99+
100+
The cleanup job uses `setInterval().unref()` so it won't prevent your process from exiting.

‎docs/connect-sqlite/getting-started.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
prev: false
3+
next:
4+
text: 'Configuration'
5+
link: '/connect-sqlite/configuration'
6+
---
7+
8+
# Getting Started
9+
10+
Connect SQLite is a SQLite session store for Sails.js applications. It uses [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) for fast, synchronous database operations.
11+
12+
## Installation
13+
14+
```bash
15+
npm install @sailscastshq/connect-sqlite
16+
```
17+
18+
## Basic Setup
19+
20+
Configure your session store in `config/session.js`:
21+
22+
```javascript
23+
module.exports.session = {
24+
secret: process.env.SESSION_SECRET,
25+
adapter: '@sailscastshq/connect-sqlite',
26+
url: 'sqlite:./db/sessions.db',
27+
28+
cookie: {
29+
secure: true,
30+
maxAge: 24 * 60 * 60 * 1000 // 24 hours
31+
}
32+
}
33+
```
34+
35+
That's it! Sails will automatically use SQLite to store sessions.
36+
37+
## URL Formats
38+
39+
Connect SQLite supports multiple URL formats:
40+
41+
```javascript
42+
// File-based database (recommended for production)
43+
url: 'sqlite:./db/sessions.db'
44+
45+
// Absolute path
46+
url: 'sqlite:/var/data/sessions.db'
47+
48+
// In-memory database (for testing)
49+
url: 'sqlite::memory:'
50+
```
51+
52+
## Why SQLite for Sessions?
53+
54+
- **No external dependencies** - No Redis or Memcached server to manage
55+
- **Persistent storage** - Sessions survive server restarts
56+
- **Low memory footprint** - Perfect for single-instance deployments
57+
- **Fast** - better-sqlite3 is one of the fastest SQLite bindings for Node.js
58+
59+
## Next Steps
60+
61+
- [Configuration Options](/connect-sqlite/configuration) - Customize TTL, table name, and more
62+
- [API Reference](/connect-sqlite/api) - Available methods and their usage

‎docs/connect-sqlite/index.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
layout: home
3+
hero:
4+
name: Connect SQLite
5+
text: SQLite session store for Sails.js
6+
tagline: A fast, lightweight session store using better-sqlite3 with WAL mode, prepared statements, and automatic session cleanup.
7+
actions:
8+
- theme: brand
9+
text: Get Started
10+
link: /connect-sqlite/getting-started
11+
- theme: alt
12+
text: Star on GitHub
13+
link: https://github.com/sailscastshq/connect-sqlite
14+
features:
15+
- icon: 🚀
16+
title: Blazing Fast
17+
details: Uses better-sqlite3's synchronous API and prepared statements for maximum performance.
18+
- icon: 💾
19+
title: Production Ready
20+
details: WAL mode for concurrent access, automatic session cleanup, and comprehensive error handling.
21+
- icon: ⚙️
22+
title: Simple Configuration
23+
details: URL-based configuration similar to Redis. Just set the url and you're ready to go.
24+
---

0 commit comments

Comments
 (0)