Separate database connections from file-backed host information and document handoff
Verify databases and deploy Aster VM / verify-and-deploy (push) Successful in 7m25s

This commit is contained in:
2026-10-19 02:07:36 +08:00
parent 18cd24a203
commit e52d2e1e4b
50 changed files with 935 additions and 442 deletions
+4 -7
View File
@@ -1,10 +1,7 @@
# Storage 源码导航
# 数据库连接源码导航
| 文件 | 职责 |
| --- | --- |
| [lib.rs](lib.rs) | StorageConfig::from_values/from_env、StorageError、SQLite/PostgreSQL 连接池、schema 初始化、ping/put/get/close |
| [schema.sql](schema.sql) | 当前 aster_metadata 文本 key/value 表,幂等建表 |
[lib.rs](lib.rs) 是唯一实现文件:DatabaseConfig 显式选择 SQLite 文件/内存或 PostgreSQL;DatabaseConnection 提供 connect、sqlite_pool/postgres_pool、backend_name、ping 和 close;DatabaseError 对公开错误脱敏。
配置改动同步 [配置表](../../../docs/operations/configuration.md) 与 storage 测试。schema 改动须考虑已有数据库,当前没有版本化迁移;不得将 CREATE IF NOT EXISTS 当作已有结构升级。Storage 克隆共享连接池,close 影响所有克隆。
connect 只建立连接池,不执行应用 DDL,不保存基础信息。没有 schema.sql、初始化表、put/get 或 from_env。业务表和查询由未来的数据库特殊类决定;本层不替它定义数据模型。
连接与持久化契约见 [运行指南](../../../docs/operations/README.md),测试定位见 [tests](../tests/README.md)。返回 [storage](../README.md)。
克隆共享连接池,close 会关闭所有克隆;具体生命周期及限制见 [数据库对象](../../../docs/runtime/database-objects.md)。配置变动同步 [配置](../../../docs/operations/configuration.md) 和 [tests](../tests/README.md)。返回 [storage](../README.md)。
+41 -109
View File
@@ -1,4 +1,5 @@
//! Host metadata storage; deliberately has no dependency on core.
//! Explicit database connections for database-backed objects.
//! Connecting never creates application tables or stores VM/host metadata.
use std::fmt;
use std::path::PathBuf;
use std::str::FromStr;
@@ -8,17 +9,15 @@ use sqlx::postgres::{PgConnectOptions, PgPoolOptions};
use sqlx::sqlite::{SqliteConnectOptions, SqliteJournalMode, SqlitePoolOptions};
use sqlx::{PgPool, SqlitePool};
const SCHEMA: &str = include_str!("schema.sql");
/// An explicit PostgreSQL configuration never falls back to SQLite.
#[derive(Clone)]
pub enum StorageConfig {
pub enum DatabaseConfig {
SqliteFile(PathBuf),
SqliteMemory,
Postgres(String),
}
impl fmt::Debug for StorageConfig {
impl fmt::Debug for DatabaseConfig {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::SqliteFile(path) => f.debug_tuple("SqliteFile").field(path).finish(),
@@ -28,57 +27,14 @@ impl fmt::Debug for StorageConfig {
}
}
impl StorageConfig {
/// DATABASE_URL accepts PostgreSQL only; SQLITE_PATH selects file or :memory:.
/// Empty/invalid explicit values are errors rather than default selection.
pub fn from_values(
database_url: Option<&str>,
sqlite_path: Option<&str>,
) -> Result<Self, StorageError> {
if let Some(url) = database_url {
if !(url.starts_with("postgres://") || url.starts_with("postgresql://")) {
return Err(StorageError::Config(
"DATABASE_URL must be a PostgreSQL URL",
));
}
return Ok(Self::Postgres(url.into()));
}
match sqlite_path.unwrap_or("data/aster.db") {
"" => Err(StorageError::Config("SQLITE_PATH cannot be empty")),
":memory:" => Ok(Self::SqliteMemory),
path => Ok(Self::SqliteFile(path.into())),
}
}
pub fn from_env() -> Result<Self, StorageError> {
let database_url = read_env("DATABASE_URL")?;
// Irrelevant SQLite settings must not prevent PostgreSQL configuration.
if database_url.is_some() {
return Self::from_values(database_url.as_deref(), None);
}
let sqlite_path = read_env("SQLITE_PATH")?;
Self::from_values(None, sqlite_path.as_deref())
}
}
fn read_env(name: &str) -> Result<Option<String>, StorageError> {
match std::env::var(name) {
Ok(value) => Ok(Some(value)),
Err(std::env::VarError::NotPresent) => Ok(None),
Err(std::env::VarError::NotUnicode(_)) => Err(StorageError::Config(
"storage environment must be valid Unicode",
)),
}
}
#[derive(Debug)]
pub enum StorageError {
pub enum DatabaseError {
Config(&'static str),
Directory(std::io::Error),
Database(sqlx::Error),
}
impl fmt::Display for StorageError {
impl fmt::Display for DatabaseError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Config(message) => f.write_str(message),
@@ -91,7 +47,7 @@ impl fmt::Display for StorageError {
}
}
impl std::error::Error for StorageError {
impl std::error::Error for DatabaseError {
fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
match self {
Self::Config(_) => None,
@@ -101,7 +57,7 @@ impl std::error::Error for StorageError {
}
}
impl From<sqlx::Error> for StorageError {
impl From<sqlx::Error> for DatabaseError {
fn from(error: sqlx::Error) -> Self {
Self::Database(error)
}
@@ -113,20 +69,26 @@ enum Backend {
Postgres(PgPool),
}
/// Clones share a pool. A memory SQLite store uses exactly one connection, so
/// initialization and every operation see the same database for its lifetime.
/// Created only on explicit request by an object or host adapter. Clones share
/// a pool; close() closes it for all users. There is no automatic schema or data.
/// In-memory SQLite uses one connection to preserve its database lifetime.
#[derive(Clone)]
pub struct Storage {
pub struct DatabaseConnection {
backend: Backend,
}
impl Storage {
/// Connects eagerly and initializes the v1 metadata schema before returning.
pub async fn connect(config: &StorageConfig) -> Result<Self, StorageError> {
impl DatabaseConnection {
/// Connects eagerly to the explicit backend without executing application DDL.
pub async fn connect(config: &DatabaseConfig) -> Result<Self, DatabaseError> {
let backend = match config {
StorageConfig::Postgres(url) => {
DatabaseConfig::Postgres(url) => {
if !(url.starts_with("postgres://") || url.starts_with("postgresql://")) {
return Err(DatabaseError::Config(
"expected a PostgreSQL connection URL",
));
}
let options = PgConnectOptions::from_str(url)
.map_err(|_| StorageError::Config("invalid PostgreSQL connection URL"))?;
.map_err(|_| DatabaseError::Config("invalid PostgreSQL connection URL"))?;
Backend::Postgres(
PgPoolOptions::new()
.max_connections(5)
@@ -135,16 +97,16 @@ impl Storage {
.await?,
)
}
StorageConfig::SqliteFile(path) => {
DatabaseConfig::SqliteFile(path) => {
if path.as_os_str().is_empty() || path == std::path::Path::new(":memory:") {
return Err(StorageError::Config(
"use SqliteMemory for an in-memory database",
return Err(DatabaseError::Config(
"expected a nonempty file path; use SqliteMemory for :memory:",
));
}
if let Some(parent) = path.parent().filter(|p| !p.as_os_str().is_empty()) {
tokio::fs::create_dir_all(parent)
.await
.map_err(StorageError::Directory)?;
.map_err(DatabaseError::Directory)?;
}
let options = SqliteConnectOptions::new()
.filename(path)
@@ -159,7 +121,7 @@ impl Storage {
.await?,
)
}
StorageConfig::SqliteMemory => {
DatabaseConfig::SqliteMemory => {
let options = SqliteConnectOptions::new().in_memory(true);
Backend::Sqlite(
SqlitePoolOptions::new()
@@ -172,21 +134,22 @@ impl Storage {
)
}
};
let storage = Self { backend };
storage.initialize().await?;
Ok(storage)
Ok(Self { backend })
}
async fn initialize(&self) -> Result<(), StorageError> {
/// Backend-specific access for the database-backed object implementation.
pub fn sqlite_pool(&self) -> Option<&SqlitePool> {
match &self.backend {
Backend::Sqlite(pool) => {
sqlx::query(SCHEMA).execute(pool).await?;
}
Backend::Postgres(pool) => {
sqlx::query(SCHEMA).execute(pool).await?;
}
Backend::Sqlite(pool) => Some(pool),
Backend::Postgres(_) => None,
}
}
pub fn postgres_pool(&self) -> Option<&PgPool> {
match &self.backend {
Backend::Postgres(pool) => Some(pool),
Backend::Sqlite(_) => None,
}
Ok(())
}
pub fn backend_name(&self) -> &'static str {
@@ -196,7 +159,7 @@ impl Storage {
}
}
pub async fn ping(&self) -> Result<(), StorageError> {
pub async fn ping(&self) -> Result<(), DatabaseError> {
match &self.backend {
Backend::Sqlite(pool) => {
sqlx::query("SELECT 1").execute(pool).await?;
@@ -208,38 +171,7 @@ impl Storage {
Ok(())
}
pub async fn put(&self, key: &str, value: &str) -> Result<(), StorageError> {
match &self.backend {
Backend::Sqlite(pool) => {
sqlx::query("INSERT INTO aster_metadata (key, value) VALUES (?1, ?2) ON CONFLICT (key) DO UPDATE SET value = excluded.value")
.bind(key).bind(value).execute(pool).await?;
}
Backend::Postgres(pool) => {
sqlx::query("INSERT INTO aster_metadata (key, value) VALUES ($1, $2) ON CONFLICT (key) DO UPDATE SET value = excluded.value")
.bind(key).bind(value).execute(pool).await?;
}
}
Ok(())
}
pub async fn get(&self, key: &str) -> Result<Option<String>, StorageError> {
Ok(match &self.backend {
Backend::Sqlite(pool) => {
sqlx::query_scalar("SELECT value FROM aster_metadata WHERE key = ?1")
.bind(key)
.fetch_optional(pool)
.await?
}
Backend::Postgres(pool) => {
sqlx::query_scalar("SELECT value FROM aster_metadata WHERE key = $1")
.bind(key)
.fetch_optional(pool)
.await?
}
})
}
/// Explicitly closes the shared pool, including all Storage clones.
/// Explicitly closes the shared pool, including all DatabaseConnection clones.
pub async fn close(&self) {
match &self.backend {
Backend::Sqlite(pool) => pool.close().await,
-4
View File
@@ -1,4 +0,0 @@
CREATE TABLE IF NOT EXISTS aster_metadata (
key TEXT PRIMARY KEY NOT NULL,
value TEXT NOT NULL
)