feat(persistence): add embedded seekDB support - #1293
Conversation
- manage embedded seekDB lifecycle with pylibseekdb - reuse OceanBase vector and full-text persistence logic - support default and custom seekDB data paths - add seekDB configuration and profile tests
| await create_tables(connection, tables) | ||
| yield profile | ||
| finally: | ||
| await database.close() |
There was a problem hiding this comment.
Could we make shutdown cancellation-safe here? If database.close() is cancelled while it is waiting for an active transaction, its close state is reset, but this outer finally still calls instance.close(). I reproduced this with pylibseekdb==1.3.0.post4: hold a transaction open, start __aexit__, and cancel it once the database enters _closing. The active connection then fails with OperationalError 2013 (Lost connection to MySQL server). This can abort an in-flight write during shutdown. Please shield and await the database close before closing the seekDB instance, then re-raise the cancellation. A regression test with a held transaction would be useful.
| "pyobvector>=0.2.28,<0.3", | ||
| "sqlalchemy[asyncio]>=2,<3", | ||
| ] | ||
| seekdb = [ |
There was a problem hiding this comment.
This extra also changes the root package metadata recorded in e2e/bub/uv.lock, but that lockfile was not regenerated. On this head, uvx --from uv==0.10.12 uv lock --project e2e/bub --locked exits with The lockfile needs to be updated; the same command passes on the base commit. Please regenerate and commit e2e/bub/uv.lock. It may also be worth making the E2E validation run the locked check, since the current sync step can update the file silently.
| password=None if password_value is None else str(password_value), | ||
| host=host, | ||
| port=None if port_value is None else int(cast(int | str, port_value)), | ||
| database=config.database, |
There was a problem hiding this comment.
How is a non-default database supposed to be created? With a fresh embedded path and database="custom", this connection fails with OperationalError 1049: Unknown database 'custom'. The new settings test only checks parsing, so it does not catch this. Please either create the requested database before opening the main engine, or document and restrict this setting to an existing database and cover that behavior with a real open test.
| # POWERCONTEXT_SERVER_DATABASE_KIND=oceanbase | ||
| # POWERCONTEXT_SERVER_DATABASE_URL=mysql+aoceanbase://user:password@host:2881/powercontext?charset=utf8mb4 | ||
|
|
||
| # To use embedded seekDB instead, install powercontext[server,seekdb] and replace the SQLite database values. |
There was a problem hiding this comment.
Could we add a short section to the user-facing docs showing the complete setup for embedded seekDB? This is an optional backend, and right now the only guidance is this .env.example comment. Please include the install command, supported platforms, the required environment variables, and a start/verification example. Without that, users can switch DATABASE_KIND and only discover at runtime that the seekDB extra is missing.
2 participants
Which issue or RFC does this PR close?
None
Rationale for this change
PowerContext currently supports SQLite and externally managed OceanBase deployments. This PR adds an optional embedded seekDB backend for users who need OceanBase-compatible persistence without running a separate database server.
The integration uses
pylibseekdbonly to manage the embedded database lifecycle, while reusing the existing OceanBase-compatible persistence, full-text search, and vector search paths.What changes are included in this PR?
powercontext[seekdb]extra withpylibseekdb.SeekDBConfigandSeekDBProfile.seekdbto the runtime database discriminator and persistence composition.POWERCONTEXT_SERVER_DATABASE_KIND=seekdb.seekdbsubdirectory whenDATABASE_PATHis omitted or blank..env.examplewith an opt-in embedded seekDB configuration example.uv.lockwith the optional seekDB dependency.Are there any user-facing changes?
Yes. This PR adds a new opt-in persistence backend.
Install PowerContext with embedded seekDB support:
pip install "powercontext[server,seekdb]"Configure the Server:
The seekDB database name defaults to
test.This is not a breaking change:
pylibseekdbis not installed by the default Server extra.kind=seekdbis selected.Embedded seekDB currently requires a supported Linux or macOS
pylibseekdbwheel. Windows users can continue using SQLite or OceanBase, but embedded seekDB is not currently available on Windows.How was this change tested?
uv lock --check: passed.git diff --check: passed./health/livereturned a healthy status./health/readyreported both the runtime and database as ready.Ctrl+Cshutdown exited with code 0.ConnectionResetError, SQLAlchemy close warning, or traceback.AI usage statement
OpenAI Codex (GPT-5.6) was used to assist with implementation, debugging, code review, test execution, and drafting this PR.