SQL profiler middleware for FastAPI
Project description
FastAPI-Silk
Lightweight SQL profiling middleware for FastAPI + SQLAlchemy
Track query count, database time, and total request time per request.
Installation | Quick Start | How It Works | Development
Why FastAPI-Silk
| Capability | Details |
|---|---|
| SQL instrumentation | setup_sql_profiler(engine) hooks into SQLAlchemy engine events (before_cursor_execute / after_cursor_execute) so SQL executed through that engine is captured per request. |
| Request-level metrics | Adds X-DB-Queries, X-DB-Time, and X-Total-Time response headers. |
| Slow query visibility | Logs queries slower than 0.1s to stdout for quick diagnostics. |
| Context isolation | Uses contextvars for per-request query storage. |
| Minimal setup | One profiler setup call + one middleware registration. |
Installation
pip install fastapi-silk
PyPI: https://pypi.tw.martin98.com/project/fastapi-silk/
Quick Start
from fastapi import FastAPI
from sqlalchemy import create_engine, text
from fastapi_silk import SQLDebugMiddleware, setup_sql_profiler, silk_router
app = FastAPI()
engine = create_engine("sqlite:///./app.db")
# Profiles SQL that goes through this engine
setup_sql_profiler(engine)
app.add_middleware(SQLDebugMiddleware)
# For the UI use
app.include_router(silk_router)
@app.get("/health")
def health() -> dict[str, bool]:
with engine.connect() as conn:
conn.execute(text("SELECT 1"))
return {"ok": True}
Example response headers:
X-DB-Queries: 1
X-DB-Time: 0.0012s
X-Total-Time: 0.0049s
Docs
- Use /_silk link to move for docs where you can find all profiling requests with detailed data
How It Works
flowchart TD
A[Incoming request] --> B[SQLDebugMiddleware starts request timer]
B --> C[Endpoint runs SQL through profiled SQLAlchemy Engine]
C --> D[setup_sql_profiler listeners capture query start/end]
D --> E[Query data stored in request-local context]
E --> F[Middleware sets X-DB-Queries, X-DB-Time, X-Total-Time]
Requirements
| Item | Requirement |
|---|---|
| Python | >=3.10 (CI runs 3.10 through 3.14) |
| Framework | FastAPI (CI validates minimum + latest) |
| Database layer | SQLAlchemy Engine (CI validates minimum + latest) |
Code Convention / Style
- Use Ruff for linting and formatting.
- Use MyPy (strict mode) for type checks.
- Keep changes small and typed where possible.
Development
Install dev dependencies and run checks:
uv sync --locked --all-extras --dev
make ci
python -m pytest
make ci runs:
- Ruff lint/format checks
- MyPy strict type checks
Contributing
- Create a branch from
development(for example,feature/<name>orfix/<name>). - Keep the pull request focused on a single change.
- Add or update tests when behavior changes.
- Run checks locally (
make ciandpython -m pytest). - Open a PR with a clear summary of what changed, why, and how it was tested.
Scope
FastAPI-Silk focuses on SQL profiling and request timing headers. It does not provide a built-in dashboard UI.
License
GNU General Public License v3.0 (GPL-3.0). See LICENSE.
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file fastapi_silk-1.0.6.tar.gz.
File metadata
- Download URL: fastapi_silk-1.0.6.tar.gz
- Upload date:
- Size: 98.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
477b36a226604b222bace5441da86ecc7cdd16bd85f71cc391d77e913fb86cad
|
|
| MD5 |
ffac0d5bd00b793bc7928db0f34ba7c1
|
|
| BLAKE2b-256 |
562a3a3202036581213616a9501e86c0d23abd57e42af3e3156b7d377e9a4282
|
Provenance
The following attestation bundles were made for fastapi_silk-1.0.6.tar.gz:
Publisher:
publish.yml on Nikolaev3Artem/fastapi-silk
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
fastapi_silk-1.0.6.tar.gz -
Subject digest:
477b36a226604b222bace5441da86ecc7cdd16bd85f71cc391d77e913fb86cad - Sigstore transparency entry: 1154997743
- Sigstore integration time:
-
Permalink:
Nikolaev3Artem/fastapi-silk@7bf506e3acf2ddbc0363e42427b13a6048ba3758 -
Branch / Tag:
refs/tags/v1.0.6 - Owner: https://github.com/Nikolaev3Artem
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@7bf506e3acf2ddbc0363e42427b13a6048ba3758 -
Trigger Event:
push
-
Statement type:
File details
Details for the file fastapi_silk-1.0.6-py3-none-any.whl.
File metadata
- Download URL: fastapi_silk-1.0.6-py3-none-any.whl
- Upload date:
- Size: 21.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
70f6e4ec5e14b303a72f0177b9b98f13aec6031ae29721a16d25f7f475e07c0d
|
|
| MD5 |
3fb78f5ca12dc731681588fc100caff4
|
|
| BLAKE2b-256 |
5eaf12f32cb89707d9da463b0db818231ccda896d31c6b8ac819e007c2c08e8a
|
Provenance
The following attestation bundles were made for fastapi_silk-1.0.6-py3-none-any.whl:
Publisher:
publish.yml on Nikolaev3Artem/fastapi-silk
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
fastapi_silk-1.0.6-py3-none-any.whl -
Subject digest:
70f6e4ec5e14b303a72f0177b9b98f13aec6031ae29721a16d25f7f475e07c0d - Sigstore transparency entry: 1154997745
- Sigstore integration time:
-
Permalink:
Nikolaev3Artem/fastapi-silk@7bf506e3acf2ddbc0363e42427b13a6048ba3758 -
Branch / Tag:
refs/tags/v1.0.6 - Owner: https://github.com/Nikolaev3Artem
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@7bf506e3acf2ddbc0363e42427b13a6048ba3758 -
Trigger Event:
push
-
Statement type:
