trezy.codes
forked from
slices.network/quickslice
Auto-indexing service and GraphQL API for AT Protocol Records
chadtmiller.com
1# Quickslice Server
2
3ATProto/Bluesky data indexer and API server.
4
5## Features
6
7- Multi-database support (SQLite and PostgreSQL)
8- OAuth 2.0 authentication with ATProto
9- GraphQL API for querying indexed data
10- MCP (Model Context Protocol) support
11- Jetstream integration for real-time data sync
12
13## Quick Start
14
15### 1. Set up environment
16
17```sh
18cp .env.example .env
19# Edit .env with your configuration
20```
21
22### 2. Set up the database
23
24**SQLite (default, simplest):**
25```sh
26make db-setup-sqlite
27```
28
29**PostgreSQL:**
30```sh
31# Ensure PostgreSQL is running
32export DATABASE_URL=postgres://localhost:5432/quickslice
33make db-setup-postgres
34```
35
36### 3. Run the server
37
38```sh
39gleam run
40```
41
42## Database Configuration
43
44The server supports both SQLite and PostgreSQL via the `DATABASE_URL` environment variable:
45
46| Database | URL Format | Example |
47|------------|------------------------------------------------|---------------------------------------------|
48| SQLite | `sqlite:path/to/file.db` | `sqlite:data/quickslice.db` |
49| SQLite | `sqlite::memory:` | In-memory database (testing) |
50| PostgreSQL | `postgres://user:pass@host:port/dbname` | `postgres://localhost:5432/quickslice` |
51
52### Database Commands (via Makefile)
53
54```sh
55make db-create # Create the database
56make db-migrate # Run pending migrations
57make db-rollback # Rollback the last migration
58make db-status # Show migration status
59make db-reset # Drop and recreate (DESTRUCTIVE)
60```
61
62All commands require `DATABASE_URL` to be set and automatically use the correct migrations directory for the database type.
63
64## Development
65
66```sh
67gleam build # Build the project
68gleam test # Run the tests
69gleam run # Run the server
70```
71
72### Running PostgreSQL Integration Tests
73
74To run PostgreSQL integration tests, set the `POSTGRES_TEST_URL` environment variable:
75
76```sh
77export POSTGRES_TEST_URL=postgres://localhost:5432/quickslice_test
78gleam test
79```
80
81If `POSTGRES_TEST_URL` is not set, PostgreSQL tests are automatically skipped.
82
83## Architecture
84
85### Database Layer
86
87The database layer uses an Executor abstraction that provides a unified interface for both SQLite and PostgreSQL:
88
89```
90database/
91├── executor.gleam # Unified Executor type and operations
92├── connection.gleam # Connection factory (parses DATABASE_URL)
93├── sqlite/
94│ ├── executor.gleam # SQLite-specific implementation
95│ └── connection.gleam # SQLite connection handling
96├── postgres/
97│ ├── executor.gleam # PostgreSQL-specific implementation
98│ └── connection.gleam # PostgreSQL connection handling
99├── queries/
100│ ├── where_clause.gleam # Dialect-aware WHERE clause builder
101│ └── pagination.gleam # Pagination utilities
102└── repositories/ # Data access layer
103```
104
105### Migrations
106
107Database migrations are managed with [dbmate](https://github.com/amacneil/dbmate):
108
109- SQLite migrations: `db/migrations/`
110- PostgreSQL migrations: `db/migrations_postgres/`
111
112## License
113
114See LICENSE file.