Skip to main content

systemprompt_database/
lib.rs

1//! # systemprompt-database
2//!
3//! `PostgreSQL` infrastructure for systemprompt.io: a thin `SQLx`-backed pool,
4//! generic repository traits, dynamic-query primitives for admin tooling, and
5//! lifecycle helpers (schema installation, extension migrations, validation).
6//!
7//! ## Public API surface
8//!
9//! - [`Database`] / [`DbPool`] — owned pool wrapper with optional split
10//!   read/write providers.
11//! - [`DatabaseProvider`] — dyn-safe trait abstracting
12//!   query/execute/transaction primitives across providers (currently only
13//!   `PostgreSQL`).
14//! - [`PostgresProvider`] — the `PostgreSQL` implementation.
15//! - [`RepositoryError`] / [`DatabaseResult`] — canonical typed error/result
16//!   returned from non-trait public APIs.
17//! - [`MigrationService`], [`install_extension_schemas`],
18//!   [`install_extension_schemas_full`] — lifecycle helpers driving
19//!   extension-supplied DDL.
20//! - [`DatabaseAdminService`], [`QueryExecutor`], [`AdminSql`],
21//!   [`SafeIdentifier`] — admin/introspection layer used by the CLI.
22//! - [`resilience`] — domain-agnostic resilience primitives
23//!   ([`resilience::ResilienceGuard`], [`resilience::CircuitBreaker`],
24//!   [`resilience::Bulkhead`], [`resilience::retry_async`]) wrapping outbound
25//!   calls; the crate's own connection and transaction retries run on them.
26//!
27//! ## Feature flags
28//!
29//! This crate currently has no Cargo features; everything compiles
30//! unconditionally. The `[package.metadata.docs.rs]` block is in place so
31//! `--all-features` documentation builds remain stable as features are added.
32//!
33//! ## sqlx allowlist
34//!
35//! Static SQL goes through the compile-time-verified `sqlx::query!` /
36//! `query_as!` / `query_scalar!` macros. Runtime/dynamic SQL is contained to
37//! two paths whose contract is dynamic SQL by design; the `lint-sqlx` gate
38//! allows runtime `sqlx::query` only there:
39//!
40//! - `src/admin/` — admin CLI surfaces (introspection, restricted query
41//!   executor) where the SQL is the user input.
42//! - `src/services/postgres/` — the dyn-safe `DatabaseProvider` implementation,
43//!   transaction wrapper, type-erased helpers and `PostgreSQL` schema
44//!   introspection.
45//!
46//! Every other call site uses verified macros.
47//!
48//! Copyright (c) systemprompt.io — Business Source License 1.1.
49//! See <https://systemprompt.io> for licensing details.
50
51pub mod admin;
52pub mod error;
53pub mod extension;
54pub mod lifecycle;
55pub mod models;
56#[macro_use]
57pub mod repository;
58pub mod resilience;
59pub mod scope;
60pub mod services;
61
62pub use extension::DatabaseExtension;
63
64pub use models::{
65    ArtifactId, ClientId, ColumnInfo, ContentId, ContextId, DatabaseInfo, DatabaseQuery,
66    DatabaseTransaction, DbValue, ExecutionStepId, FileId, FromDatabaseRow, FromDbValue, IndexInfo,
67    JsonRow, LogId, QueryResult, QueryRow, QuerySelector, SessionId, SkillId, TableInfo, TaskId,
68    ToDbValue, TokenId, TraceId, UserId, parse_database_datetime,
69};
70
71pub use scope::{ConnectionScopeProvider, ScopeError, ScopeSetting, SharedScopeProvider};
72pub use services::{
73    BoxFuture, Database, DatabaseCliDisplay, DatabaseExt, DatabaseProvider, DatabaseProviderExt,
74    DbPool, PoolConfig, PostgresProvider, SqlExecutor, begin_scoped, with_scoped_transaction,
75    with_transaction, with_transaction_retry,
76};
77pub use systemprompt_models::RequestScope;
78
79pub use error::{DatabaseResult, RepositoryError};
80pub use lifecycle::{
81    AppliedMigration, BOOTSTRAP_ADVISORY_LOCK_KEY, BaselineStamp, BootstrapLockGuard,
82    ChecksumDrift, DeferredForeignKey, ExpensiveStatement, ExtensionMigrationStatus,
83    FkDeferralError, ForeignKeyDrift, FreshnessCheck, HOT_TABLES, MarkAppliedOutcome,
84    MigrationConfig, MigrationCost, MigrationResult, MigrationService, MigrationStatus,
85    OrphanMigrationLedger, OrphanedMigration, PendingMigration, RepairResult, ReplicaStatus,
86    SchemaInstallReport, SchemaResidue, SlotCollision, SplitCreateTable, TombstonedSlot,
87    UndeclaredTable, audit_migration_cost, audit_one, audit_schema_residue,
88    check_migration_references, install_extension_schemas, install_extension_schemas_full,
89    install_extension_schemas_with_config, is_retirement, replica_status,
90    split_create_table_foreign_keys, validate_column_exists, validate_database_connection,
91    validate_table_exists, validate_write_pool_is_primary,
92};
93pub use repository::{CreateServiceInput, PgDbPool, ServiceConfig, ServiceRepository};
94
95pub use admin::{
96    AdminSql, AdminSqlError, DEFAULT_READONLY_ROW_LIMIT, DatabaseAdminService, IdentifierError,
97    QueryExecutor, QueryExecutorError, SafeIdentifier,
98};
99pub use sqlx::types::Json;
100pub use sqlx::{PgPool, Pool, Postgres, Transaction};
101
102use systemprompt_traits::DatabaseHandle;
103
104impl DatabaseHandle for Database {
105    fn is_connected(&self) -> bool {
106        !self.pool().is_closed() && !self.write_pool().is_closed()
107    }
108
109    fn as_any(&self) -> &dyn std::any::Any {
110        self
111    }
112}