# free-stockdb: A Local A-Share K-Line Data Engine for Quant Research

> free-stockdb packages A-share daily, minute and ETF data into a local C++ time-series service with incremental sync, adjustment factors, 39 indicators and five calling methods. It is aimed at researchers who need full-market backtests without hammering a remote API.

**hello245m/free-stockdb** — 面向 A 股日K、分钟K与ETF分钟数据的本地量化引擎，集成增量同步、本地缓存、复权、批量查询、回测与指标计算。

- Repository: https://github.com/hello245m/free-stockdb
- Stars: 2,726 · Forks: 407
- Language: HTML
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/hello245m-free-stockdb

## What free-stockdb Actually Replaces

The README frames the problem as data engineering rather than strategy code. Its own worked example is a full-market backtest over 7000+ stocks on minute bars, and it lists the steps a remote-API workflow forces you to own: token and rate-limit management, IP blocking, resumable downloads, suspension and delisting handling, ticker renames, time sorting, dividend and split data, adjustment factor derivation, database schema design, index building, and per-language integration glue. The README's estimate is that this takes at least 10 to 15 working days before the first full-market strategy runs, and it claims free-stockdb compresses that to 30 minutes from zero to runnable. That number is the project's own marketing, not a measurement I can confirm, but the list of chores it enumerates is real and familiar to anyone who has built this pipeline by hand.

The intended user is narrow. This is for someone doing A-share research who wants daily, weekly, monthly, 1/5/15/30-minute and on-demand tick data sitting on local disk, queryable in bulk, with adjustment handled at read time. It is not a trading terminal, not a broker connection, and not a market data vendor. The README is explicit that data copyright and redistribution terms belong to each data source and its rights holders, and that the user must confirm those terms. free-stockdb ships the engine; you supply the feed.

## The Sync, Storage and Query Path

The architecture is a single local service with several front doors. A sync tool reads a source address from sync_url.txt, transfers history with Zstd compression, and then only processes changed data on later runs, with resumable transfer and manifest checks. Files land under ./data by default. From there a C++ time-series service handles reads, and five clients talk to it: a Python SDK, an HTTP API on 127.0.0.1:7899, Excel/WPS macros, an HTML page, and an MCP endpoint for AI tools. The README states the MCP protocol is self-implemented, so no separate MCP SDK install is needed.

The query layer splits into three entry points with different jobs. rd.get_data() is the bulk reader: codes, start, end, frequency, fq for forward/backward/no adjustment, fields, and an as_df switch that returns a list, dict or DataFrame. zb.get() is the indicator engine, taking a comma-separated name list, per-indicator parameters, and a cross option that returns raw values, golden-cross signals, or both. bk.get() maps between stocks and board classifications, with category 0 through 3 covering concept boards and Shenwan level one, two and three industries. The README says the database itself supports arbitrary custom storage, so lower-frequency data such as financials, macro or fund flows can be attached to the same query and compute layer.

Storage is deliberately layered. Market history is compressed and, per the README, occupies more than three times less space than CSV or MySQL for the same records. Separately, there is a private store under ./mydb for your own data, written through an async pipeline with mset for bulk and set for single records, plus a WAL for durability. A second mount mechanism, ./dataN, lets sync_url.txt list multiple sources with their own types and target paths, and rd.get() with no arguments auto-reads all of them. That is the part of the design that makes the engine more than a fixed dataset: you can add your own tables and your own sync nodes without changing the query code.

## Installing free-stockdb and Running a First Query

Windows users are pointed at the Releases page, where a prebuilt package is published. The README's two-minute path is four steps: run the data update tool, let data sync to ./data, start stockdb (the README gives its size as 2.2 MB), then query through Python, HTTP, Excel/WPS, the web page or MCP. The release notes list Windows, macOS, Alpine and manylinux builds as published, with macOS and Linux described as having passed several rounds of stress testing before release.

If you build from source instead, the C++ components live in cpp/ and need CMake 3.14 or newer, a C++17 compiler, libcurl and the OpenSSL development packages. The README gives exactly two commands:

```bash
cmake -S cpp -B cpp/build
cmake --build cpp/build --config Release
```

Before the first sync, point the engine at a source. The README describes sync_url.txt as the configuration file for the data source, and notes that when it is empty the synchronizer makes no requests at all. It also supports file:// URLs or local directories for syncing archived snapshots offline. Once data is on disk, a bulk read looks like the README's example:

```python
result = rd.get_data(
    code=7000_codes,
    start=any_start,
    end=any_end,
    frequency=any_frequency,
    fq=any_fq,
    fields=any_fields,
    as_df=False
)
```

The four keywords to watch are frequency (minute, daily, weekly, monthly), fq (forward-adjusted, backward-adjusted or raw), fields (any single or multiple columns) and as_df, which decides whether you get a list, a dict or a DataFrame back. For indicators, the README's zb.get() example passes a comma-separated name string, a code list, a time range, the same frequency and fq arguments, an n list holding one parameter string per indicator, and cross="with_value" to get both the raw indicator and its cross signal. If you only want to confirm the service is up, the HTTP form is a GET against http://127.0.0.1:7899/?cmd=get&t=... as shown in the README's calling-methods table; the exact parameter string beyond cmd and t is not spelled out there, so read the examples under 调用方式/ before writing your own client.

## Where free-stockdb Is the Wrong Tool

The README's own hardware table is the first honest constraint. Minimum disk is about 5 GB for daily bars alone and about 20 GB with the full minute dataset; memory minimum is 2 GB, recommended 8 GB or more; the listed operating systems are Windows 7 and up, with Windows 10 or newer recommended. That table names Windows only, even though the release notes mention macOS, Alpine and manylinux builds. Anyone on macOS or Linux should treat the release notes as the authority and check whether the published package covers their platform, because the README's stated requirements do not.

The bigger limitation is the data source. free-stockdb is an engine, and the README says plainly that the data source is an input rather than the product's only dependency. That cuts both ways: you still need a lawful feed to populate sync_url.txt, and the project does not ship one. The README tells you to verify data quality yourself, suggesting you sample adjustment factors, prices, volumes and corporate action dates through the local interface, or generate and validate the local data from a source you trust. If you have no such source, the engine has nothing to run on.

Real-time use is out of scope. The README describes tick data as on-demand, and the whole design assumes sync first, query later, with queries served from local disk. If your strategy needs live quotes, this is not the layer for it. There is also an operational assumption that you are comfortable with a local daemon plus a sync step; the README notes a LAN service can be configured for multi-person collaboration and distributed backtesting, but it does not document rollback of a bad sync, and the release notes for 0.3.5 describe it as a test version, which is worth weighing if you plan to depend on it.

## How It Differs from pandas Plus a Remote API

The obvious alternative is the one most A-share researchers already have: a vendor API or a scraping script feeding pandas DataFrames, with adjustment and indicators computed in Python at analysis time. The difference is where the work happens. In the pandas approach, every backtest run pulls or reloads data, concatenates frames, and rolls indicators across the full market, and the README argues this is slow enough to be a bottleneck, claiming its Rust compute core is three times faster than pandas and that full-market indicators finish in seconds rather than hours. I cannot verify that ratio, but the structural difference is not in dispute: free-stockdb precomputes nothing and instead keeps data resident in a local time-series service, so the query returns only the fields and range you asked for, and indicator computation happens next to the storage rather than after a round trip.

The second difference is adjustment. The README states the local data keeps raw prices plus adjustment factors, and applies forward or backward adjustment at query time. A pandas workflow typically stores an adjusted series and has to re-derive it whenever a new corporate action arrives. Read-time adjustment means the stored history does not need rewriting, at the cost of the engine owning the factor logic, which is exactly the code you should audit against a second source.

The third difference is the interface surface. A pandas pipeline needs separate glue for notebooks, spreadsheets, a web view and an AI assistant. free-stockdb exposes one local protocol through Python, HTTP, Excel/WPS, HTML and MCP, and the README's point is that swapping the data source does not require rewriting the query and compute layer. If you only ever work in one notebook on a few hundred symbols, that uniformity buys you little.

## Licence, Maintenance and Upgrade Cost

The repository is MIT licensed, and the README points to the LICENSE file in the repository. MIT is permissive, so the software itself is straightforward to use, modify and redistribute. That says nothing about the data. The README separates the two explicitly: data copyright, usage authorization and redistribution conditions are decided by each data source and its rights holders, and the user must confirm those terms. A permissive code licence does not grant you any rights to the market data flowing through sync_url.txt, and the disclaimer states the project is for software learning, data management and quantitative research and is not investment advice. I am not a lawyer and this is not legal advice; if you plan to redistribute derived datasets, that question sits with your source, not with this repository.

On maintenance, the last push to the default branch was on 2026-09-08, and the repository is not archived. The most recent release listed is 测试版本0.3.5, published on 2026-07-19, described in the release notes as the more-power version of the local A-share daily and minute K-line engine. The README carries dated changelog markers, including an 08-10 note that Windows, macOS, Alpine and manylinux builds are published, an 08-04 note on macOS and Linux completion, and 08-05 upgrades to the private store and multi-mount features. That pattern suggests ongoing work, but the release is labelled a test version, so pin the version you deploy and keep the previous package.

Upgrade cost is mostly data, not code. If sync_url.txt points at a node whose layout changes, the sync step is where you will feel it; the query and compute layer is described as independent of the source. Budget for the SHA-256 check the README asks for on every release download, and expect the disk footprint to grow as you add minute and tick ranges, since the 5 GB and 20 GB figures in the README cover daily-only and full-minute cases respectively.

## Conclusion

free-stockdb suits quant researchers and small teams who run full-market A-share backtests and want the data layer on their own disk instead of behind a rate-limited API. It is the wrong choice if you need real-time streaming quotes, if you cannot obtain a lawful data source to point sync_url.txt at, or if you only need a handful of symbols and a few years of daily bars, where a single pandas download is simpler. Before adopting it, verify three things on your own machine: that the release package you download matches the SHA-256 published with that version, that the sync node in sync_url.txt is one you are permitted to use, and that the adjusted prices returned by rd.get_data() line up with an independent source around a known dividend or split date.

## FAQ

### What does the name free-stockdb mean?

The project is a local quantitative data engine for A-share daily K-line, minute K-line and ETF minute data, distributed under the MIT licence. The README describes it as a local-first engine that syncs, cleans, adjusts and organizes data for batch query and research.

### How can I get free-stockdb?

The README points Windows users to the Releases page, and the release notes list Windows, macOS, Alpine and manylinux builds as published. The 0.3.5 release is linked from the README as 测试版本0.3.5.

### What does stock data mean in free-stockdb?

The README covers daily, weekly and monthly bars plus 1, 5, 15 and 30-minute K-lines and on-demand tick data, with fields such as price, volume, turnover, valuation, market cap and ST status. It also stores raw prices with adjustment factors and applies forward or backward adjustment at query time.

### What does "no stock" mean for free-stockdb when no data source is configured?

The README states that the synchronizer only accesses the address given in sync_url.txt or by --source, and that when the configuration is empty it does not initiate any sync request. Data already written to ./data remains queryable offline.

## Sources

- [hello245m/free-stockdb on GitHub](https://github.com/hello245m/free-stockdb)
- [Issues](https://github.com/hello245m/free-stockdb/issues)
- [License: MIT](https://github.com/hello245m/free-stockdb/blob/main/LICENSE)
- [README](https://github.com/hello245m/free-stockdb/blob/main/README.md)
- [Releases](https://github.com/hello245m/free-stockdb/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hello245m-free-stockdb