prax_query/
lib.rs

1//! # prax-query
2//!
3//! Type-safe query builder for the Prax ORM.
4//!
5//! This crate provides the core query building functionality, including:
6//! - Fluent API for building queries (`find_many`, `find_unique`, `create`, `update`, `delete`)
7//! - Type-safe filtering with `where` clauses
8//! - Sorting and pagination
9//! - Relation loading (`include`, `select`)
10//! - Transaction support
11//! - Raw SQL escape hatch
12//! - Middleware system
13//! - Multi-tenant support
14//!
15//! ## Filters
16//!
17//! Build type-safe filters for queries:
18//!
19//! ```rust
20//! use prax_query::{Filter, FilterValue};
21//!
22//! // Equality filter
23//! let filter = Filter::Equals("email".into(), FilterValue::String("test@example.com".into()));
24//!
25//! // Greater than filter
26//! let filter = Filter::Gt("age".into(), FilterValue::Int(18));
27//!
28//! // Contains filter (for strings)
29//! let filter = Filter::Contains("name".into(), FilterValue::String("john".into()));
30//!
31//! // Combine filters with AND/OR
32//! let combined = Filter::and([
33//!     Filter::Equals("active".into(), FilterValue::Bool(true)),
34//!     Filter::Gt("age".into(), FilterValue::Int(18)),
35//! ]);
36//!
37//! let either = Filter::or([
38//!     Filter::Equals("role".into(), FilterValue::String("admin".into())),
39//!     Filter::Equals("role".into(), FilterValue::String("moderator".into())),
40//! ]);
41//! ```
42//!
43//! ## Filter Values
44//!
45//! Convert Rust types to filter values:
46//!
47//! ```rust
48//! use prax_query::FilterValue;
49//!
50//! // Integer values
51//! let val: FilterValue = 42.into();
52//! assert!(matches!(val, FilterValue::Int(42)));
53//!
54//! // String values
55//! let val: FilterValue = "hello".into();
56//! assert!(matches!(val, FilterValue::String(_)));
57//!
58//! // Boolean values
59//! let val: FilterValue = true.into();
60//! assert!(matches!(val, FilterValue::Bool(true)));
61//!
62//! // Float values
63//! let val: FilterValue = 3.14f64.into();
64//! assert!(matches!(val, FilterValue::Float(_)));
65//!
66//! // Null values
67//! let val = FilterValue::Null;
68//! ```
69//!
70//! ## Sorting
71//!
72//! Build sort specifications:
73//!
74//! ```rust
75//! use prax_query::{OrderBy, OrderByField, NullsOrder};
76//!
77//! // Ascending order
78//! let order = OrderByField::asc("created_at");
79//!
80//! // Descending order
81//! let order = OrderByField::desc("updated_at");
82//!
83//! // With NULLS FIRST/LAST
84//! let order = OrderByField::asc("name").nulls(NullsOrder::First);
85//! let order = OrderByField::desc("score").nulls(NullsOrder::Last);
86//!
87//! // Combine multiple orderings
88//! let orders = OrderBy::Field(OrderByField::asc("name"))
89//!     .then(OrderByField::desc("created_at"));
90//! ```
91//!
92//! ## Raw SQL
93//!
94//! Build raw SQL queries with parameter binding:
95//!
96//! ```rust
97//! use prax_query::Sql;
98//!
99//! // Simple query
100//! let sql = Sql::new("SELECT * FROM users");
101//! assert_eq!(sql.sql(), "SELECT * FROM users");
102//!
103//! // Query with parameter - bind appends placeholder
104//! let sql = Sql::new("SELECT * FROM users WHERE id = ")
105//!     .bind(42);
106//! assert_eq!(sql.params().len(), 1);
107//! ```
108//!
109//! ## Connection Strings
110//!
111//! Parse database connection strings:
112//!
113//! ```rust
114//! use prax_query::ConnectionString;
115//!
116//! // PostgreSQL
117//! let conn = ConnectionString::parse("postgres://user:pass@localhost:5432/mydb").unwrap();
118//! assert_eq!(conn.host(), Some("localhost"));
119//! assert_eq!(conn.port(), Some(5432));
120//! assert_eq!(conn.database(), Some("mydb"));
121//!
122//! // MySQL
123//! let conn = ConnectionString::parse("mysql://user:pass@localhost:3306/mydb").unwrap();
124//! ```
125//!
126//! ## Transaction Config
127//!
128//! Configure transaction behavior:
129//!
130//! ```rust
131//! use prax_query::IsolationLevel;
132//!
133//! let level = IsolationLevel::Serializable;
134//! assert_eq!(level.as_sql(), "SERIALIZABLE");
135//! ```
136//!
137//! ## Error Handling
138//!
139//! Work with query errors:
140//!
141//! ```rust
142//! use prax_query::{QueryError, ErrorCode};
143//!
144//! // Create errors
145//! let err = QueryError::not_found("User");
146//! assert_eq!(err.code, ErrorCode::RecordNotFound);
147//! ```
148
149pub mod advanced;
150pub mod async_optimize;
151pub mod batch;
152pub mod builder;
153pub mod cache;
154pub mod connection;
155pub mod cte;
156pub mod data;
157#[allow(dead_code, unused_imports)]
158pub mod data_cache;
159pub mod db_optimize;
160pub mod error;
161pub mod extension;
162pub mod filter;
163pub mod intern;
164pub mod introspection;
165pub mod json;
166pub mod lazy;
167pub mod logging;
168#[macro_use]
169pub mod macros;
170pub mod mem_optimize;
171pub mod memory;
172pub mod middleware;
173pub mod nested;
174pub mod operations;
175pub mod pagination;
176pub mod partition;
177pub mod pool;
178pub mod procedure;
179pub mod profiling;
180pub mod query;
181pub mod raw;
182pub mod relations;
183pub mod replication;
184pub mod row;
185pub mod search;
186pub mod security;
187pub mod sequence;
188pub mod sql;
189pub mod static_filter;
190pub mod tenant;
191pub mod traits;
192pub mod transaction;
193pub mod trigger;
194pub mod typed_filter;
195pub mod types;
196pub mod upsert;
197pub mod window;
198pub mod zero_copy;
199
200pub use error::{ErrorCode, ErrorContext, QueryError, QueryResult, Suggestion};
201pub use extension::{Extension, ExtensionBuilder, Point, Polygon};
202pub use filter::{
203    AndFilterBuilder, FieldName, Filter, FilterValue, FluentFilterBuilder, LargeValueList,
204    OrFilterBuilder, ScalarFilter, SmallValueList, ValueList,
205};
206pub use json::{JsonAgg, JsonFilter, JsonIndex, JsonIndexBuilder, JsonOp, JsonPath, PathSegment};
207pub use nested::{NestedWrite, NestedWriteBuilder, NestedWriteOperations};
208pub use operations::{
209    CreateOperation,
210    CreateManyOperation,
211    DeleteOperation,
212    DeleteManyOperation,
213    FindManyOperation,
214    FindFirstOperation,
215    FindUniqueOperation,
216    CountOperation,
217    AggregateOperation,
218    AggregateField,
219    AggregateResult,
220    GroupByOperation,
221    GroupByResult,
222    HavingCondition,
223    HavingOp,
224    having,
225    // View operations
226    MaterializedViewAccessor,
227    RefreshMaterializedViewOperation,
228    UpdateOperation,
229    UpdateManyOperation,
230    UpsertOperation,
231    ViewAccessor,
232    ViewCountOperation,
233    ViewFindFirstOperation,
234    ViewFindManyOperation,
235    ViewQueryBuilder,
236};
237pub use pagination::{Cursor, CursorDirection, Pagination};
238pub use partition::{
239    HashPartitionDef, ListPartitionDef, Partition, PartitionBuilder, PartitionDef, PartitionType,
240    RangeBound, RangePartitionDef,
241};
242pub use procedure::{
243    Parameter, ParameterMode, ProcedureCall, ProcedureCallOperation, ProcedureEngine,
244    ProcedureResult,
245};
246pub use query::QueryBuilder;
247pub use raw::{RawExecuteOperation, RawQueryOperation, Sql};
248pub use relations::{Include, IncludeSpec, RelationLoader, RelationSpec, SelectSpec};
249pub use search::{
250    FullTextIndex, FullTextIndexBuilder, FuzzyOptions, HighlightOptions, RankingOptions,
251    SearchLanguage, SearchMode, SearchQuery, SearchQueryBuilder, SearchSql,
252};
253pub use security::{
254    ConnectionProfile, ConnectionProfileBuilder, DataMask, Grant, GrantBuilder, GrantObject,
255    MaskFunction, PolicyCommand, Privilege, RlsPolicy, RlsPolicyBuilder, Role, RoleBuilder,
256    TenantPolicy, TenantSource,
257};
258pub use sequence::{OwnedBy, Sequence, SequenceBuilder};
259pub use traits::{
260    Executable, IntoFilter, MaterializedView, Model, QueryEngine, View, ViewQueryEngine,
261};
262pub use transaction::{IsolationLevel, Transaction, TransactionConfig};
263pub use trigger::{
264    Trigger, TriggerAction, TriggerBuilder, TriggerCondition, TriggerEvent, TriggerLevel,
265    TriggerTiming, UpdateOf,
266};
267pub use types::{
268    NullsOrder, OrderBy, OrderByBuilder, OrderByField, Select, SortOrder, order_patterns,
269};
270pub use upsert::{
271    Assignment, AssignmentValue, ConflictAction, ConflictTarget, UpdateSpec, Upsert, UpsertBuilder,
272};
273pub use window::{
274    FrameBound, FrameClause, FrameExclude, FrameType, NamedWindow, NullsPosition, OrderSpec,
275    WindowFn, WindowFunction, WindowFunctionBuilder, WindowSpec,
276};
277
278// Re-export middleware types
279pub use middleware::{
280    LoggingMiddleware, MetricsMiddleware, Middleware, MiddlewareBuilder, MiddlewareChain,
281    MiddlewareStack, QueryContext, QueryMetadata, QueryMetrics, QueryType, RetryMiddleware,
282    TimingMiddleware,
283};
284
285// Re-export connection types
286pub use connection::{
287    ConnectionError, ConnectionOptions, ConnectionString, DatabaseConfig, Driver, EnvExpander,
288    MultiDatabaseConfig, PoolConfig, PoolOptions, SslConfig, SslMode,
289};
290pub use cte::{
291    Cte, CteBuilder, CycleClause, Materialized, SearchClause, SearchMethod, WithClause,
292    WithQueryBuilder,
293};
294
295// Re-export advanced query types
296pub use advanced::{
297    BulkOperation, DistinctOn, LateralJoin, LateralJoinBuilder, LateralJoinType, LockStrength,
298    LockWait, ReturnOperation, Returning, ReturningColumn, RowLock, RowLockBuilder, SampleMethod,
299    SampleSize, TableSample, TableSampleBuilder,
300};
301
302// Re-export data types
303pub use data::{
304    BatchCreate, ConnectData, CreateData, DataBuilder, FieldValue, IntoData, UpdateData,
305};
306
307// Re-export introspection types
308pub use introspection::{
309    CheckConstraint, ColumnInfo, DatabaseSchema, EnumInfo, ForeignKeyInfo, IndexColumn, IndexInfo,
310    NormalizedType, ReferentialAction, SequenceInfo, TableInfo, UniqueConstraint, ViewInfo,
311    generate_prax_schema, normalize_type,
312};
313
314// Re-export tenant types
315pub use tenant::{
316    DynamicResolver, IsolationStrategy, RowLevelConfig, SchemaConfig, StaticResolver, TenantConfig,
317    TenantConfigBuilder, TenantContext, TenantId, TenantInfo, TenantMiddleware, TenantResolver,
318};
319
320// Re-export intern types
321pub use intern::{clear_interned, fields, intern, intern_cow, interned_count};
322
323// Re-export pool types
324pub use pool::{FilterBuilder, FilterPool, IntoPooledValue, PooledFilter, PooledValue};
325
326// Re-export SQL builder types
327pub use sql::{
328    AdvancedQueryCapacity, CachedSql, DatabaseType, FastSqlBuilder, LazySql, QueryCapacity,
329    SqlBuilder, SqlTemplateCache as SqlCache, global_sql_cache, keywords, templates,
330};
331
332// Re-export optimized builder types
333pub use builder::{
334    BuilderPool,
335    ColumnList,
336    ColumnNameList,
337    CowColumnList,
338    CowIdentifier,
339    ExprList,
340    // Note: FrameBound and FrameType are also defined in window module
341    FrameBound as BuilderFrameBound,
342    FrameType as BuilderFrameType,
343    Identifier,
344    OptimizedWindowSpec,
345    OrderByList,
346    PartitionByList,
347    ReusableBuilder,
348    WindowFrame,
349};
350
351// Re-export database optimization types
352pub use db_optimize::{
353    BatchConfig, CachedStatement, IndexHint, IndexHintType, JoinHint, JoinMethod,
354    MongoPipelineBuilder, PipelineStage, PreparedStatementCache, PreparedStatementStats,
355    QueryHints, global_statement_cache,
356};
357
358// Re-export zero-copy types
359pub use zero_copy::{
360    CteRef, FrameBoundRef, FrameRef, FrameTypeRef, JsonPathRef, PathSegmentRef, WindowSpecRef,
361    WithClauseRef,
362};
363
364// Re-export cache types
365pub use cache::{
366    CacheStats, CachedQuery, ExecutionPlan, ExecutionPlanCache, PlanHint, QueryCache, QueryHash,
367    QueryKey, SqlTemplate, SqlTemplateCache, get_global_template, global_template_cache,
368    patterns as cache_patterns, precompute_query_hash, register_global_template,
369};
370
371// Re-export batch types
372pub use batch::{
373    Batch, BatchBuilder, BatchOperation, BatchResult, OperationResult, Pipeline, PipelineBuilder,
374    PipelineQuery, PipelineResult, QueryResult as PipelineQueryResult,
375};
376
377// Re-export row deserialization types
378pub use row::{FromColumn, FromRow, FromRowRef, RowData, RowError, RowRef, RowRefIter};
379
380// Re-export lazy loading types
381pub use lazy::{Lazy, LazyRelation, ManyToOneLoader, OneToManyLoader};
382
383// Re-export static filter utilities
384pub use static_filter::{
385    CompactValue, StaticFilter, and2, and3, and4, and5, contains, ends_with, eq,
386    fields as static_fields, gt, gte, in_list, is_not_null, is_null, lt, lte, ne, not, not_in_list,
387    or2, or3, or4, or5, starts_with,
388};
389
390// Re-export typed filter utilities
391pub use typed_filter::{
392    And, AndN, Contains, DirectSql, EndsWith, Eq, Gt, Gte, InI64, InI64Slice, InStr, InStrSlice,
393    IsNotNull, IsNull, LazyFilter, Lt, Lte, Maybe, Ne, Not as TypedNot, NotInI64Slice, Or, OrN,
394    StartsWith, TypedFilter, and_n, eq as typed_eq, gt as typed_gt, gte as typed_gte,
395    in_i64 as typed_in_i64, in_i64_slice, in_str as typed_in_str, in_str_slice,
396    is_not_null as typed_is_not_null, is_null as typed_is_null, lazy, lt as typed_lt,
397    lte as typed_lte, ne as typed_ne, not_in_i64_slice, or_n,
398};
399
400// Re-export memory optimization utilities
401pub use memory::{
402    BufferPool, CompactFilter, GLOBAL_BUFFER_POOL, GLOBAL_STRING_POOL, MemoryStats, PoolStats,
403    PooledBuffer, StringPool, get_buffer, intern as memory_intern,
404};
405
406// Re-export logging utilities
407pub use logging::{
408    get_log_format, get_log_level, init as init_logging, init_debug, init_with_level,
409    is_debug_enabled,
410};
411
412// Re-export replication types
413pub use replication::{
414    ConnectionRouter, HealthStatus, LagMeasurement, LagMonitor, ReadPreference, ReplicaConfig,
415    ReplicaHealth, ReplicaRole, ReplicaSetBuilder, ReplicaSetConfig,
416};
417
418// Re-export async optimization types
419pub use async_optimize::{
420    ConcurrencyConfig, ConcurrentExecutor, ExecutionStats, IntrospectionConfig,
421    IntrospectionResult, PipelineConfig, PipelineError, PipelineResult as AsyncPipelineResult,
422    QueryPipeline, TaskError, TaskResult,
423    concurrent::execute_batch as async_execute_batch,
424    concurrent::execute_chunked as async_execute_chunked,
425    introspect::{
426        BatchIntrospector, ColumnMetadata, ConcurrentIntrospector, ForeignKeyMetadata,
427        IndexMetadata, IntrospectionError, IntrospectionPhase, IntrospectorBuilder, TableMetadata,
428    },
429    pipeline::{BulkInsertPipeline, BulkUpdatePipeline, SimulatedExecutor},
430};
431
432// Re-export memory optimization types
433pub use mem_optimize::{
434    GlobalInterner, IdentifierCache, InternedStr, ScopedInterner,
435    arena::{ArenaScope, ArenaStats, QueryArena, ScopedFilter, ScopedQuery, ScopedValue},
436    interning::{get_interned, intern as global_intern, intern_component, intern_qualified},
437    lazy::{LazyColumn, LazyForeignKey, LazyIndex, LazySchema, LazySchemaStats, LazyTable},
438};
439
440// Re-export profiling types
441pub use profiling::{
442    AllocationRecord, AllocationStats, AllocationTracker, HeapProfiler, HeapReport, HeapStats,
443    LeakDetector, LeakReport, LeakSeverity, MemoryProfiler, MemoryReport, MemorySnapshot,
444    PotentialLeak, SnapshotDiff, TrackedAllocator, disable_profiling, enable_profiling,
445    is_profiling_enabled, with_profiling,
446};
447
448// Re-export smallvec for macros
449pub use smallvec;
450
451/// Prelude module for convenient imports.
452pub mod prelude {
453    pub use crate::advanced::{LateralJoin, Returning, RowLock, TableSample};
454    pub use crate::cte::{Cte, CteBuilder, WithClause};
455    pub use crate::error::{QueryError, QueryResult};
456    pub use crate::extension::{Extension, Point, Polygon};
457    pub use crate::filter::{Filter, FilterValue, ScalarFilter};
458    pub use crate::introspection::{DatabaseSchema, TableInfo, generate_prax_schema};
459    pub use crate::json::{JsonFilter, JsonOp, JsonPath};
460    pub use crate::nested::{NestedWrite, NestedWriteBuilder, NestedWriteOperations};
461    pub use crate::operations::*;
462    pub use crate::pagination::{Cursor, CursorDirection, Pagination};
463    pub use crate::partition::{Partition, PartitionBuilder, PartitionType, RangeBound};
464    pub use crate::procedure::{
465        Parameter, ParameterMode, ProcedureCall, ProcedureEngine, ProcedureResult,
466    };
467    pub use crate::query::QueryBuilder;
468    pub use crate::raw::{RawExecuteOperation, RawQueryOperation, Sql};
469    pub use crate::raw_query;
470    pub use crate::relations::{Include, IncludeSpec, RelationSpec, SelectSpec};
471    pub use crate::replication::{ConnectionRouter, ReadPreference, ReplicaSetConfig};
472    pub use crate::search::{FullTextIndex, SearchMode, SearchQuery, SearchQueryBuilder};
473    pub use crate::security::{Grant, GrantBuilder, RlsPolicy, Role, RoleBuilder};
474    pub use crate::sequence::{Sequence, SequenceBuilder};
475    pub use crate::traits::{
476        Executable, IntoFilter, MaterializedView, Model, QueryEngine, View, ViewQueryEngine,
477    };
478    pub use crate::transaction::{IsolationLevel, Transaction, TransactionConfig};
479    pub use crate::trigger::{
480        Trigger, TriggerAction, TriggerBuilder, TriggerCondition, TriggerEvent, TriggerLevel,
481        TriggerTiming,
482    };
483    pub use crate::types::{OrderBy, Select, SortOrder};
484    pub use crate::upsert::{ConflictAction, ConflictTarget, Upsert, UpsertBuilder};
485    pub use crate::window::{WindowFn, WindowFunction, WindowSpec};
486
487    // Tenant types
488    pub use crate::tenant::{IsolationStrategy, TenantConfig, TenantContext, TenantMiddleware};
489
490    // Async optimization types
491    pub use crate::async_optimize::{
492        ConcurrencyConfig, ConcurrentExecutor, IntrospectionConfig, PipelineConfig, QueryPipeline,
493    };
494
495    // Memory optimization types
496    pub use crate::mem_optimize::{GlobalInterner, InternedStr, LazySchema, QueryArena};
497
498    // Profiling types
499    pub use crate::profiling::{
500        LeakDetector, MemoryProfiler, MemorySnapshot, enable_profiling, with_profiling,
501    };
502}
prax_query/lib.rs

prax_query/
lib.rs
