Skip to content
Back to search

fastsqla

MarketplaceWorks with Claude CodeGitHub

Agent Skills for building FastAPI applications with FastSQLA.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/hadrien/FastSQLA with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/hadrien/FastSQLA'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hadrien--fastsqla/badge.svg)](/listings/hadrien--fastsqla)

HTML

<a href="/listings/hadrien--fastsqla"><img src="/api/listings/hadrien--fastsqla/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Using [uv](https://docs.astral.sh/uv/):

uv add fastsqla

Using [pip](https://pip.pypa.io/):

pip install fastsqla

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 26 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "fastsqla",
  4. "description": "Agent Skills for building FastAPI applications with FastSQLA.",
  5. "owner": {
  6. "name": "Hadrien David",
  7. "email": "h@driendavid.com"
  8. },
  9. "plugins": [
  10. {
  11. "name": "fastsqla",
  12. "source": "./plugin/fastsqla",
  13. "description": "Use FastSQLA's current setup, async session, and pagination APIs correctly.",
  14. "version": "1.0.0",
  15. "author": {
  16. "name": "Hadrien David",
  17. "email": "h@driendavid.com"
  18. },
  19. "homepage": "https://hadrien.github.io/FastSQLA/",
  20. "repository": "https://github.com/hadrien/FastSQLA",
  21. "license": "MIT",
  22. "keywords": ["fastapi", "sqlalchemy", "async", "pagination", "sqlmodel"],
  23. "category": "development"
  24. }
  25. ]
  26. }
README.md · README · 383 lines · 2 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # FastSQLA
  2. _Async SQLAlchemy 2.0+ for FastAPI — boilerplate, pagination, and seamless session management._
  3. [![PyPI - Version](https://img.shields.io/pypi/v/FastSQLA?color=brightgreen)](https://pypi.org/project/FastSQLA/)
  4. [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/hadrien/fastsqla/ci.yml?branch=main&logo=github&label=CI)](https://github.com/hadrien/FastSQLA/actions?query=branch%3Amain+event%3Apush)
  5. [![Codecov](https://img.shields.io/codecov/c/github/hadrien/fastsqla?token=XK3YT60MWK&logo=codecov)](https://codecov.io/gh/hadrien/FastSQLA)
  6. [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-brightgreen.svg)](https://conventionalcommits.org)
  7. [![GitHub License](https://img.shields.io/github/license/hadrien/fastsqla)](https://github.com/hadrien/FastSQLA/blob/main/LICENSE)
  8. [![🍁 With love from Canada](https://img.shields.io/badge/With%20love%20from%20Canada-ffffff?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSI2MDAiIGhlaWdodD0iNjAwIiB2aWV3Qm94PSItMjAxNSAtMjAwMCA0MDMwIDQwMzAiPjxwYXRoIGZpbGw9IiNmMDAiIGQ9Im0tOTAgMjAzMCA0NS04NjNhOTUgOTUgMCAwIDAtMTExLTk4bC04NTkgMTUxIDExNi0zMjBhNjUgNjUgMCAwIDAtMjAtNzNsLTk0MS03NjIgMjEyLTk5YTY1IDY1IDAgMCAwIDM0LTc5bC0xODYtNTcyIDU0MiAxMTVhNjUgNjUgMCAwIDAgNzMtMzhsMTA1LTI0NyA0MjMgNDU0YTY1IDY1IDAgMCAwIDExMS01N2wtMjA0LTEwNTIgMzI3IDE4OWE2NSA2NSAwIDAgMCA5MS0yN2wzMzItNjUyIDMzMiA2NTJhNjUgNjUgMCAwIDAgOTEgMjdsMzI3LTE4OS0yMDQgMTA1MmE2NSA2NSAwIDAgMCAxMTEgNTdsNDIzLTQ1NCAxMDUgMjQ3YTY1IDY1IDAgMCAwIDczIDM4bDU0Mi0xMTUtMTg2IDU3MmE2NSA2NSAwIDAgMCAzNCA3OWwyMTIgOTktOTQxIDc2MmE2NSA2NSAwIDAgMC0yMCA3M2wxMTYgMzIwLTg1OS0xNTFhOTUgOTUgMCAwIDAtMTExIDk4bDQ1IDg2M3oiLz48L3N2Zz4K)](https://montrealpython.org)
  9. **Documentation**: [https://hadrien.github.io/FastSQLA/](https://hadrien.github.io/FastSQLA/)
  10. **Github Repo:** [https://github.com/hadrien/fastsqla](https://github.com/hadrien/fastsqla)
  11. -----------------------------------------------------------------------------------------
  12. `FastSQLA` is an async [`SQLAlchemy 2.0+`](https://docs.sqlalchemy.org/en/20/)
  13. extension for [`FastAPI`](https://fastapi.tiangolo.com/) with built-in pagination,
  14. [`SQLModel`](http://sqlmodel.tiangolo.com/) support and more.
  15. It streamlines the configuration and asynchronous connection to relational databases by
  16. providing boilerplate and intuitive helpers. Additionally, it offers built-in
  17. customizable pagination and automatically manages the `SQLAlchemy` session lifecycle
  18. following [`SQLAlchemy`'s best practices](https://docs.sqlalchemy.org/en/20/orm/session_basics.html#when-do-i-construct-a-session-when-do-i-commit-it-and-when-do-i-close-it).
  19. ## Features
  20. * Easy setup at app startup using
  21. [`FastAPI` Lifespan](https://fastapi.tiangolo.com/advanced/events/#lifespan):
  22. ```python
  23. from fastapi import FastAPI
  24. from fastsqla import lifespan
  25. app = FastAPI(lifespan=lifespan)
  26. ```
  27. * `SQLAlchemy` async session dependency:
  28. ```python
  29. ...
  30. from fastsqla import Session
  31. from sqlalchemy import select
  32. ...
  33. @app.get("/heros")
  34. async def get_heros(session:Session):
  35. stmt = select(...)
  36. result = await session.execute(stmt)
  37. ...
  38. ```
  39. * `SQLAlchemy` async session with an async context manager:
  40. ```python
  41. from fastsqla import open_session
  42. async def background_job():
  43. async with open_session() as session:
  44. stmt = select(...)
  45. result = await session.execute(stmt)
  46. ...
  47. ```
  48. * Built-in pagination with offset/limit:
  49. ```python
  50. ...
  51. from fastsqla import Page, Paginate
  52. from sqlalchemy import select
  53. ...
  54. @app.get("/heros", response_model=Page[HeroModel])
  55. async def get_heros(paginate:Paginate):
  56. return await paginate(select(Hero))
  57. ```
  58. <center>
  59. 👇 `/heros?offset=10&limit=10` 👇
  60. </center>
  61. ```json
  62. {
  63. "data": [
  64. {
  65. "name": "The Flash",
  66. "secret_identity": "Barry Allen",
  67. "id": 11
  68. },
  69. {
  70. "name": "Green Lantern",
  71. "secret_identity": "Hal Jordan",
  72. "id": 12
  73. }
  74. ],
  75. "meta": {
  76. "offset": 10,
  77. "total_items": 12,
  78. "total_pages": 2,
  79. "page_number": 2
  80. }
  81. }
  82. ```
  83. * Forward cursor pagination for "Load more" lists:
  84. ```python
  85. from fastsqla.cursor import Page, Paginate
  86. @app.get("/heros")
  87. async def get_heros(paginate: Paginate[Hero]) -> Page[HeroModel]:
  88. return await paginate(select(Hero).order_by(Hero.id))
  89. ```
  90. <center>
  91. 👇 `/heros?limit=2&next_cursor=eyJ2IjoxLCJvcmRlciI6W1siaGVybyIsImlkIixmYWxzZSwiaW50Il1dLCJ2YWx1ZXMiOlsyXX0` 👇
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 119 on GitHub
  92. </center>
  93. ```json
  94. {
  95. "data": [
  96. {
  97. "name": "Superman",
  98. "secret_identity": "Clark Kent",
  99. "id": 3
  100. },
  101. {
  102. "name": "Batman",
  103. "secret_identity": "Bruce Wayne",
  104. "id": 4
  105. }
  106. ],
  107. "meta": {
  108. "next_cursor": "eyJ2IjoxLCJvcmRlciI6W1siaGVybyIsImlkIixmYWxzZSwiaW50Il1dLCJ2YWx1ZXMiOls0XX0"
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 138 on GitHub
  109. }
  110. }
  111. ```
  112. Pass `meta.next_cursor` as `next_cursor` in the next query string. A `null` cursor
  113. means the end of the results.
  114. * Pagination customization:
  115. ```python
  116. from typing import Annotated
  117. from fastapi import Depends
  118. from fastsqla import Page, PaginateType, new_pagination
  119. CustomPaginate = Annotated[
  120. PaginateType[HeroModel],
  121. Depends(new_pagination(default_page_size=5, max_page_size=500)),
  122. ]
  123. @app.get("/heroes", response_model=Page[HeroModel])
  124. async def get_heroes(paginate: CustomPaginate):
  125. return await paginate(select(Hero))
  126. ```
  127. * Session lifecycle management: session is commited on request success or rollback on
  128. failure.
  129. * [`SQLModel`](http://sqlmodel.tiangolo.com/) support:
  130. ```python
  131. ...
  132. from fastsqla import Item, Page, Paginate, Session
  133. from sqlmodel import Field, SQLModel
  134. ...
  135. class Hero(SQLModel, table=True):
  136. id: int | None = Field(default=None, primary_key=True)
  137. name: str
  138. secret_identity: str
  139. age: int
  140. @app.get("/heroes", response_model=Page[Hero])
  141. async def get_heroes(paginate: Paginate):
  142. return await paginate(select(Hero))
  143. @app.get("/heroes/{hero_id}", response_model=Item[Hero])
  144. async def get_hero(session: Session, hero_id: int):
  145. hero = await session.get(Hero, hero_id)
  146. if hero is None:
  147. raise HTTPException(status_code=HTTPStatus.NOT_FOUND)
  148. return {"data": hero}
  149. ```
  150. ## Installing
  151. Using [uv](https://docs.astral.sh/uv/):
  152. ```bash
  153. uv add fastsqla
  154. ```
  155. Using [pip](https://pip.pypa.io/):
  156. ```
  157. pip install fastsqla
  158. ```
  159. ## Quick Example
  160. ### `example.py`
  161. Let's write some tiny app in `example.py`:
  162. ```python
  163. # example.py
  164. from http import HTTPStatus
  165. from fastapi import FastAPI, HTTPException
  166. from fastsqla import Base, Item, Page, Paginate, Session, lifespan
  167. from pydantic import BaseModel, ConfigDict
  168. from sqlalchemy import select
  169. from sqlalchemy.exc import IntegrityError
  170. from sqlalchemy.orm import Mapped, mapped_column
  171. app = FastAPI(lifespan=lifespan)
  172. class Hero(Base):
  173. __tablename__ = "hero"
  174. id: Mapped[int] = mapped_column(primary_key=True)
  175. name: Mapped[str] = mapped_column(unique=True)
  176. secret_identity: Mapped[str]
  177. age: Mapped[int]
  178. class HeroBase(BaseModel):
  179. name: str
  180. secret_identity: str
  181. age: int
  182. class HeroModel(HeroBase):
  183. model_config = ConfigDict(from_attributes=True)
  184. id: int
  185. @app.get("/heros", response_model=Page[HeroModel])
  186. async def list_heros(paginate: Paginate):
  187. stmt = select(Hero)
  188. return await paginate(stmt)
  189. @app.get("/heros/{hero_id}", response_model=Item[HeroModel])
  190. async def get_hero(hero_id: int, session: Session):
  191. hero = await session.get(Hero, hero_id)
  192. if hero is None:
  193. raise HTTPException(HTTPStatus.NOT_FOUND, "Hero not found")
  194. return {"data": hero}
  195. @app.post("/heros", response_model=Item[HeroModel])
  196. async def create_hero(new_hero: HeroBase, session: Session):
  197. hero = Hero(**new_hero.model_dump())
  198. session.add(hero)
  199. try:
  200. await session.flush()
  201. except IntegrityError:
  202. raise HTTPException(HTTPStatus.CONFLICT, "Duplicate hero name")
  203. return {"data": hero}
  204. ```
  205. ### Database
  206. 💡 This example uses an `SQLite` database for simplicity: `FastSQLA` is compatible with
  207. all asynchronous db drivers that `SQLAlchemy` is compatible with.
  208. Let's create an `SQLite` database using `sqlite3` and insert 12 rows in the `hero` table:
  209. ```bash
  210. sqlite3 db.sqlite <<EOF
  211. -- Create Table hero
  212. CREATE TABLE hero (
  213. id INTEGER PRIMARY KEY AUTOINCREMENT,
  214. name TEXT NOT NULL UNIQUE, -- Unique hero name (e.g., Superman)
  215. secret_identity TEXT NOT NULL, -- Secret identity (e.g., Clark Kent)
  216. age INTEGER NOT NULL -- Age of the hero (e.g., 30)
  217. );
  218. -- Insert heroes with their name, secret identity, and age
  219. INSERT INTO hero (name, secret_identity, age) VALUES ('Superman', 'Clark Kent', 30);
  220. INSERT INTO hero (name, secret_identity, age) VALUES ('Batman', 'Bruce Wayne', 35);
  221. INSERT INTO hero (name, secret_identity, age) VALUES ('Wonder Woman', 'Diana Prince', 30);
  222. INSERT INTO hero (name, secret_identity, age) VALUES ('Iron Man', 'Tony Stark', 45);
  223. INSERT INTO hero (name, secret_identity, age) VALUES ('Spider-Man', 'Peter Parker', 25);
  224. INSERT INTO hero (name, secret_identity, age) VALUES ('Captain America', 'Steve Rogers', 100);
  225. INSERT INTO hero (name, secret_identity, age) VALUES ('Black Widow', 'Natasha Romanoff', 35);
  226. INSERT INTO hero (name, secret_identity, age) VALUES ('Thor', 'Thor Odinson', 1500);
  227. INSERT INTO hero (name, secret_identity, age) VALUES ('Scarlet Witch', 'Wanda Maximoff', 30);
  228. INSERT INTO hero (name, secret_identity, age) VALUES ('Doctor Strange', 'Stephen Strange', 40);
  229. INSERT INTO hero (name, secret_identity, age) VALUES ('The Flash', 'Barry Allen', 28);
  230. INSERT INTO hero (name, secret_identity, age) VALUES ('Green Lantern', 'Hal Jordan', 35);
  231. EOF
  232. ```
  233. ### Run the app
  234. Let's install required dependencies:
  235. ```bash
  236. pip install uvicorn aiosqlite fastsqla
  237. ```
  238. Let's run the app:
  239. ```
  240. sqlalchemy_url=sqlite+aiosqlite:///db.sqlite?check_same_thread=false \
  241. uvicorn example:app
  242. ```
  243. ### Check the result
  244. Execute `GET /heros?offset=10&limit=10` using `curl`:
  245. ```bash
  246. curl -X 'GET' -H 'accept: application/json' 'http://127.0.0.1:8000/heros?offset=10&limit=10'
  247. ```
  248. Returns:
  249. ```json
  250. {
  251. "data": [
  252. {
  253. "name": "The Flash",
  254. "secret_identity": "Barry Allen",
  255. "id": 11
  256. },
  257. {
  258. "name": "Green Lantern",
  259. "secret_identity": "Hal Jordan",
  260. "id": 12
  261. }
  262. ],
  263. "meta": {
  264. "offset": 10,
  265. "total_items": 12,
  266. "total_pages": 2,
  267. "page_number": 2
  268. }
  269. }
  270. ```
  271. You can also check the generated openapi doc by opening your browser to
  272. [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs).
  273. ![OpenAPI generated documentation of the example API](https://raw.githubusercontent.com/hadrien/FastSQLA/refs/heads/main/docs/images/example-openapi-generated-doc.png)
  274. ## License
  275. This project is licensed under the terms of the [MIT license](https://github.com/hadrien/FastSQLA/blob/main/LICENSE).
  276. ## For coding agents and LLMs
  277. FastSQLA publishes agent-readable documentation alongside the website:
  278. - [`llms.txt`](https://hadrien.github.io/FastSQLA/llms.txt) is the concise documentation
  279. index.
  280. - [`llms-full.txt`](https://hadrien.github.io/FastSQLA/llms-full.txt) contains the
  281. complete documentation in one file.
  282. - Every indexed page has a Markdown twin, such as
  283. [`setup/index.md`](https://hadrien.github.io/FastSQLA/setup/index.md).
  284. - [Context7](https://context7.com/hadrien/fastsqla) serves the current documentation and
  285. FastSQLA-specific usage rules.
  286. The repository also bundles Agent Skills for setup, session management, and pagination.
  287. Install all three as one plugin:
  288. ### Claude Code
  289. ```bash
  290. claude plugin marketplace add hadrien/FastSQLA
  291. claude plugin install fastsqla@fastsqla
  292. ```
  293. ### Codex
  294. ```bash
  295. codex plugin marketplace add hadrien/FastSQLA
  296. codex plugin add fastsqla@fastsqla
  297. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.