configuration

Database

MySQL 8 backing every Glyph install - backups, restores, migrations.

Glyph runs on MySQL 8, packaged as a Docker container alongside the backend. The schema is managed by Alembic migrations.

What's stored

Entity	Purpose
`users`	Account credentials (hashed password), profile
`workspaces`	Top-level grouping
`workspace_members`	User-to-workspace mapping with role
`invitations`	Pending invites with token and expiry
`projects`	Per-project metadata (source, default branch)
`commits`	Synced commit history
`documents`	Documentation entries `(file_path, commit_sha, content)`
`code_references`	Labeled line ranges
`comments`	Threaded comments per `(file, commit)`
`connected_accounts`	Encrypted Personal Access Tokens

The actual file contents and Git history live in volumes/data/<project_id>/.git/ - the database only stores documentation and metadata.

Container details

	Value
Image	`mysql:8.0`
Container name	`glyph-db`
Database name	`glyph`
Application user	`glyph`
Volume	`./volumes/mysql` (bind mount on host)
Internal port	`3306` (not exposed by default)

Migrations

The backend runs alembic upgrade head automatically on startup. New migrations ship with each release and apply themselves on the next docker compose pull && up -d.

To run migrations manually (rare):

docker compose exec backend alembic upgrade head

To check current revision:

docker compose exec backend alembic current

Backups

Run mysqldump from the host:

docker exec glyph-db \
  mysqldump -u glyph -p"$MYSQL_PASSWORD" glyph \
  > glyph-backup-$(date +%F).sql

For a compressed backup:

docker exec glyph-db \
  mysqldump -u glyph -p"$MYSQL_PASSWORD" glyph \
  | gzip > glyph-backup-$(date +%F).sql.gz

See Backups for a complete strategy including the file volumes.

Restore

Stop the backend so it doesn't write during restore:

docker compose stop backend

Restore the dump:

docker exec -i glyph-db \
  mysql -u glyph -p"$MYSQL_PASSWORD" glyph \
  < glyph-backup-2026-05-14.sql

Restart:

docker compose start backend

A restore replaces the current database completely. Make a fresh dump of the current state first if you might want to roll back the restore.

Direct SQL access

For ad-hoc queries (e.g. promoting a user to admin):

docker exec -it glyph-db mysql -u glyph -p"$MYSQL_PASSWORD" glyph

-- Promote a user to admin in their default workspace
UPDATE workspace_members
SET role = 'admin'
WHERE user_id = (SELECT id FROM users WHERE email = 'me@example.com');

Direct SQL bypasses application logic. Always backup before destructive queries.

Sizing

A workspace with hundreds of projects and active documentation typically uses < 1 GB of MySQL data. The bulk of storage usage comes from volumes/data (cloned repos), not the database.

Replacing MySQL with another database

Not supported. Alembic migrations and a couple of queries use MySQL-specific syntax. PostgreSQL would require porting work. Stick with MySQL 8.

Email Providers

Search Engine