Service Administration

Create A User

All DocServe endpoints require an Authorization header that uses JWTs with a Bearer scheme. To obtain a JWT you must first create a user with the createuser command. Run cargo run createuser -h for instructions. Running the command without any arguments creates a default user admin with password apidocpass. Because this is a lightweight hobby project there is no way to reset a user’s password (yet), and since all passwords are stored as hashed values in the database there is no way to recover human-readable passwords. Once you create a user, supply the username and password to the login endpoint to obtain a JWT. The Quick Reference page contains some pre-built cURL requests for quick manual testing.

Telemetry

Data Persistence & Migrations

DocServe is built on SeaORM. SeaORM, as the name suggests, is an object-relational mapping (ORM) tool. The core purpose of an ORM tool is to map database tables to programming language objects (and vice versa). ORMs provide high-level, ergonomic abstractions that reduce the usage of raw SQL. Well-designed abstractions can speed up development, encourage safe query patterns to reduce SQL injection risks, and simplify data persistence.

In addition to ergonomic abstraction for raw SQL interfacing, many ORM tools provide migration management. Database migration is a structured way to manage database schemas over time. Migration allows developers to version control database changes, making it easier to evolve the database structures while keeping data intact. Migrations address creating, modifying, and dropping tables, altering columns, adding and removing constraints. Some migration tooling also support initial data seeding.

Migrations

The last step in the basic service installation and setup guide is running the check command. This command automatically checks for database connection and executes the service’s initial migration which creates all necessary tables for the service. For simple service operation, this is all you need you do. However, if you want to develop the service further, you can leverage this feature set to create and run your own database migrations with the service’s migrate command. In fact, the check command actually executes the migrate command under the hood.

Updating The Database Schema

Create a new migration with the SeaORM CLI; Visit the install page for details; Use short, descriptive names for migration scripts; The CLI prepends a timestamp, so dont get too wordy
```
sea-orm-cli migrate generate <migration_name>
```
The migration generation operation creates a new file in the /migration/src/ directory that you can edit with the updated schema. The file is named with a timestamp and the argument you supply to the operation. The file is like a script and works by altering elements that are already in place. For example, if you want to create a new table, you use Table::create(), but altering an existing table requires Table::alter(). See the SeaORM docs for more info.
After you edit the new migration file (script) you can run the migration with cargo run migrate.
Check that the migration took by logging in to the database via interactive Docker session. If you’ve forgotten the container ID run docker ps. Note that you only need the host (-h) option if you’re connecting to a remote host, otherwise the operation assumes localhost.
Terminal window
```
docker exec -it <container_id> psql -U <username> -h 127.0.0.1
```
Once you’re in the database you can run the necessary \d <PATTERN> commands to check that the particular table changes took.

Fixing Botched Migrations

If your changes didn’t take, its likely that there is a bug in your migration script. Unfortunately, you cant just re-run the cargo run migrate command after fixing the migration file. Instead you need to manually delete the last migration attempt, fix the issue, and re-run the migration. Supposing you’ve already fixed your migration script issue,

Enter the database in interactive mode. If you’ve forgotten the container ID run docker ps. Note that you only need the host (-h) option if you’re connecting to a remote host, otherwise the operation assumes localhost.
Terminal window
```
docker exec -it <container_id> psql -U <username>
```
Navigate to the correct database. If you forgot which DB you’re using, run the list (\l) command to get a list of DBs and \c <DB_NAME> into the correct one.
```
postgres=# \c apidoc
You are now connected to database "apidoc" as user "postgres".
```

Get a list of applied migrations.

SELECT * FROM seaql_migrations;

This will provide a table with all applied migrations and might look something like this:

apidoc=# SELECT * FROM seaql_migrations;
                  version                  | applied_at
-------------------------------------------+------------
 m20220101_000001_create_table             | 1742778038
 m20250324_012019_add_test_column_to_table | 1742780782
(2 rows)

After you’ve identified the migration you want to delete, run:

apidoc=# DELETE FROM seaql_migrations WHERE version = '<VERSION>';
DELETE 1

Re-run the fixed migration operation with the migrate command and repeat the check step to make sure it all took.